# augmentos-community/opensourcesmartglasses architecture

> Architecture diagram of the GitHub repository augmentos-community/opensourcesmartglasses, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/augmentos-community/opensourcesmartglasses
- Repository: https://github.com/augmentos-community/opensourcesmartglasses

## Overview

Based on an analysis of the full file tree and the README information, this project is clearly a multi-disciplinary “full‐system” design that includes hardware (mechanical CAD files, PCB/firmware designs), firmware for multiple microcontrollers (for audio processing, display and control, communication, etc.), and even a dedicated Python-based server for handling websockets communications. In other words, you’re working with a full stack of smart glasses development where the physical design, embedded firmware (for both a Pico‑based microphone interface and an ESP32‑based main MCU), and external software/web services all interact.

##### Start by breaking the system into high-level components
- Hardware/Mechanical Layer: This includes the physical structure, 3D models/stl and step files in the “mechanical” folder, lenses, frames, and support structures.
- Electronics / PCB Layer: Multiple sub-projects under “electronics_and_firmware” and “endpiece_mic_board” contain KiCad projects, BOMs, PCB schematics, gerbers, and revisions (v0p1 through v0p5, plus various endpiece boards). This layer encapsulates sensor boards, audio capture circuitry, buttons, power management, etc.
- Firmware Layer: There are distinct firmware projects – one for the Pico (microphone-library-for-pico-main) and another directory for the ESP32 (“esp32_firmware_v0p3” with structured folders such as comms, display, gui, and utilities). These firmware modules follow a modular design (e.g., UI with LVGL, comms for WiFi/websocket connectivity, microphone handling). They communicate with the electronics layer by interfacing directly with the custom PCBs.
- Software / Communication Layer: The “python_websocket_server” folder shows that there’s an external server component using websockets. This likely acts as a bridge between the wearable device and external applications or the Wearable Intelligence System.
- External Interfaces / Services: Include integration points with external systems (such as the Wearable Intelligence System and an eventual AugmentOS app store and SDK).

##### Relationships and interactions
- The mechanical hardware encloses the electronics (PCBs mounted on frames) and provides mechanical connectivity for sensors, speakers, displays, and microphones.
- The PCBs (and their firmware) form the “brains” of the glasses; the Pico-based modules handle audio (microphone capture, signal processing) while the ESP32 firmware handles display, general control, communications (WiFi/Bluetooth) and UI.
- The firmware modules (widget libraries, message types, comms modules) interact within the embedded system via well-defined interfaces (comm APIs, LVGL for UI, I2C/SPI for sensor data).
- The Python WebSocket server serves as an external entry point for remote control, configuration, or live data feeds (as part of integration with the Wearable Intelligence System).

##### Architectural patterns/design principles
- Modularity: Each component (hardware, firmware, software) is split into multiple sub-projects for iterative versioning.
- Layered design: Clear separation between physical design (mechanical and PCB), firmware (real-time control, UI, sensor data processing) and external software/services.
- Reusability and extensibility: The firmware components (e.g., the LVGL-based display UI and the microphone libraries) are separate and extensible, and the mechanical designs are provided in neutral formats (STL, STEP) to allow rapid prototyping and redesign.
- Iterative revisions: Different folders (OSSG_v0p1, v0p2, v0p3, …) indicate evolutionary design of the PCBs and firmware and should be documented as iterative improvements.

##### Relevant technologies and frameworks
- Firmware build tools (CMake, Kconfig, SDKs for Raspberry Pi Pico and ESP32)
- KiCad for PCB design and associated file formats (schematics, gerbers, BOMs)
- Mechanical CAD tools using STL/STEP (e.g., CATIA or similar)
- Python with a websockets library (possibly asyncio or similar) in the python_websocket_server
- LVGL for UI development on embedded devices
- Communication protocols (WiFi, Bluetooth, possibly USB interfaces on boards)

- Start your drawing with the high-level blocks:
▪ “Mechanical System” (frame, lenses, battery enclosure, etc.)
▪ Within that, “PCB / Electronics” block – further subdivided if needed into “Audio/Mic Interface” and “Main Control Board”
▪ “Firmware” block – with two sub-blocks: one for Pico-based audio/microphone firmware and one for ESP32-based display, UI, and communications firmware.
▪ “External Software/Services” block – representing the Python WebSocket Server and the Wearable Intelligence System.
▪ Power and sensor/control signals from the Electronics block to the Firmware blocks.
▪ Data/control signals from the Firmware to the External Services.
▪ How the Mechanical system physically encapsulates (or mounts) the electronics.

Remember that clarity and detail are key – as many relationships as possible should be explicitly represented so that every important technical element is visible at a glance. This helps in future discussions about potential modifications or integration challenges.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mechanical / Hardware Layer
    subgraph "Mechanical / Hardware"
        MECH("OSSG Mechanical CAD"):::mechanical
    end

    %% Electronics / PCB Layer
    subgraph "Electronics / PCB"
        PCB("PCBs & KiCad Designs"):::electronics
    end

    %% Firmware Layer
    subgraph "Firmware"
        PICO("Pico Microphone Firmware"):::firmware
        ESP32("ESP32 Display/UI Firmware"):::firmware
    end

    %% External Software/Services
    subgraph "External Software/Services"
        PYTHON("Python Websocket Server"):::external
        WIS("Wearable Intelligence System"):::external
    end

    %% Relationships
    MECH -->|"houses"| PCB
    PCB -->|"interfaces_with"| PICO
    PCB -->|"interfaces_with"| ESP32
    ESP32 -->|"communicates_with"| PYTHON
    PYTHON -->|"integrates_with"| WIS

    %% Click Events
    click MECH "https://github.com/augmentos-community/opensourcesmartglasses/tree/main/mechanical"
    click PCB "https://github.com/augmentos-community/opensourcesmartglasses/tree/main/electronics_and_firmware/OSSG_v0p1_and_v0p2/pcb"
    click PICO "https://github.com/augmentos-community/opensourcesmartglasses/tree/main/electronics_and_firmware/OSSG_v0p1_and_v0p2/code/microphone-library-for-pico-main"
    click ESP32 "https://github.com/augmentos-community/opensourcesmartglasses/tree/main/electronics_and_firmware/esp32_firmware_v0p3/ossg_firmware_mcu"
    click PYTHON "https://github.com/augmentos-community/opensourcesmartglasses/blob/main/python_websocket_server/server.py"

    %% Styles
    classDef mechanical fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef electronics fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef firmware fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
