# facebookresearch/digit360 architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/digit360
- Repository: https://github.com/facebookresearch/digit360

## Overview

##### Main Components
- Hardware & Mechanical Design:
- Physical components such as the printed circuit board (PCB) stack (hardware design files in design/hardware), the custom hyperfisheye lens (design/lens), and the compliant, artificial fingertip (design/fingertip).
- Mechanical design elements (design/mechanical) that house or support these electronic and optical components.
- Firmware:
- Firmwares for different parts, such as the MCU, ICS controllers, and USB interface (firmware folders for ICS, MCU, and USB).
- Software Interface:
- Standalone Python API: Show the digit360/interface module which provides a python interface to access sensor modalities (like audio, image, LED, and USB examples under digit360/interface/examples).
- Udev and Setup Scripts: Include components like udev rules (digit360/udev) that help in device recognition, and setup scripts (install_digit360_venv.sh, setup.py) for environment setup.
- Data Processing & Training:
- Train directory which contains multimodal classification code and a training pipeline (train/multimodal). This shows how sensor data is used for machine learning and inference.
- Simulation & Visualization:

- From the hardware to firmware – show how sensor data from the physical modules is captured.
- From firmware to both the standalone Python interface and ROS2 middleware – indicate how the sensor’s multi-modal data is processed and published.
- For ROS2, show how sensor data flows into ROS nodes (publishers/subscribers) and is packaged using custom messages (d360_msgs).
- Within the training module, link the interface with data processing pipelines and the multimodal classifiers.
- Configuration and dependency relationships:
- Configuration files and setup tools should be noted as supporting the software components.
- Udev rules facilitate hardware communication with the OS.

##### Architectural Patterns & Design Principles
- Modularity: Emphasize how the project is divided into hardware (design, firmware), middleware (software interfaces), and application layers (training and simulation).
- Separation of Concerns: Illustrate clear separation between standalone package functionality versus ROS2 integration.
- Extensibility: Note that there are examples and proto message definitions to facilitate further development of sensor data handling.
- Integration Focus: Clearly show the integration points between hardware design documents, firmware images, software libraries, and simulation environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware & Mechanical Design Subgraph
    subgraph "Hardware & Mechanical Design"
        H1("PCB Stack"):::hardware
        H2("Custom Hyperfisheye Lens"):::hardware
        H3("Lens Elements"):::hardware
        H4("Artificial Fingertip"):::hardware
        H5("Mechanical Housing"):::hardware
    end

    %% Firmware Subgraph
    subgraph "Firmware"
        F1("ICS Firmware"):::firmware
        F2("MCU Firmware"):::firmware
        F3("USB Firmware"):::firmware
    end

    %% Software Interface Subgraph
    subgraph "Software Interface"
        S1("Standalone Python API"):::software
        S2("ROS2 Package (with d360_msgs)"):::software
        S3("Udev Rules"):::software
        S4("Setup Script (venv)"):::software
        S5("Setup Script (setup.py)"):::software
    end

    %% Data Processing & Training Subgraph
    subgraph "Data Processing & Training"
        T1("Multimodal Training Pipeline"):::training
    end

    %% Simulation & Visualization Subgraph
    subgraph "Simulation & Visualization"
        M1("3D Meshes & URDF Files"):::simulation
    end

    %% Relationships
    %% Hardware to Firmware: Sensor data captured from hardware flows into firmware processing
    H1 -->|"captures_data"| F1
    H1 -->|"captures_data"| F2
    H1 -->|"captures_data"| F3
    H2 -->|"contains"| H3

    %% Firmware to Software Interfaces: Processed sensor data is forwarded into software layers for access & integration
    F1 -->|"forwards_data"| S1
    F1 -->|"forwards_data"| S2
    F2 -->|"forwards_data"| S1
    F2 -->|"forwards_data"| S2
    F3 -->|"forwards_data"| S1
    F3 -->|"forwards_data"| S2

    %% Support Components: Udev and Setup Scripts aiding system integration
    S3 -->|"enables_device_recognition"| F1
    S3 -->|"enables_device_recognition"| F2
    S3 -->|"enables_device_recognition"| F3
    S4 -->|"configures_environment"| S1
    S5 -->|"configures_environment"| S1

    %% Software Interfaces leading to Data Processing & Training
    S1 -->|"supplies_data"| T1
    S2 -->|"supplies_data"| T1

    %% ROS2 Data utilized for simulation environments
    S2 -->|"informs_simulation"| M1

    %% Class Definitions with Colors
    classDef hardware fill:#FFCCCB,stroke:#B22222,stroke-width:2px;
    classDef firmware fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef software fill:#FFFFCC,stroke:#DAA520,stroke-width:2px;
    classDef training fill:#CCFFCC,stroke:#228B22,stroke-width:2px;
    classDef simulation fill:#E6E6FA,stroke:#4B0082,stroke-width:2px;

    %% Click Events for Hardware/Mechanical Design
    click H1 "https://github.com/facebookresearch/digit360/tree/main/design/hardware"
    click H2 "https://github.com/facebookresearch/digit360/tree/main/design/lens"
    click H3 "https://github.com/facebookresearch/digit360/tree/main/design/lens/elements"
    click H4 "https://github.com/facebookresearch/digit360/tree/main/design/fingertip"
    click H5 "https://github.com/facebookresearch/digit360/tree/main/design/mechanical"

    %% Click Events for Firmware
    click F1 "https://github.com/facebookresearch/digit360/tree/main/firmware/ics"
    click F2 "https://github.com/facebookresearch/digit360/tree/main/firmware/mcu"
    click F3 "https://github.com/facebookresearch/digit360/tree/main/firmware/usb"

    %% Click Events for Software Interface
    click S1 "https://github.com/facebookresearch/digit360/tree/main/digit360/interface"
    click S2 "https://github.com/facebookresearch/digit360/tree/main/digit360/ros2"
    click S3 "https://github.com/facebookresearch/digit360/tree/main/digit360/udev"
    click S4 "https://github.com/facebookresearch/digit360/blob/main/digit360/install_digit360_venv.sh"
    click S5 "https://github.com/facebookresearch/digit360/blob/main/setup.py"

    %% Click Event for Data Processing & Training
    click T1 "https://github.com/facebookresearch/digit360/tree/main/train/multimodal"

    %% Click Event for Simulation & Visualization
    click M1 "https://github.com/facebookresearch/digit360/tree/main/meshes"
```
