# unimakers/espresso architecture

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

- Interactive diagram: https://gitdiagram.com/unimakers/espresso
- Repository: https://github.com/unimakers/espresso

## Overview

##### Project type and purpose
- This is an embedded‐focused robotics toolkit (“Espresso Toolkit”) targeted at ESP32 microcontrollers.
- It provides decoupled C/C++ libraries for common robotics functions (LiDAR, steppers, EQL, vision), vendored TensorFlow Lite Micro for on‐device ML inference, plus Python ML scripts, data assets, documentation, and PlatformIO build configuration.

##### File structure
- Top level
- platformio.ini – defines the embedded build (ESP32) and dependencies.
- src/main.cpp – the entry point for firmware.
- lib/… – contains subfolders for eql, lidar, stepper, vision, and a vendored TensorFlow Lite Micro tree.
- ml/… – Python scripts and data for training and testing ML models (YOLOv8, pickle).
- dataset/… – raw and processed image data for ML training.
- tools/… – helper Python scripts (eql.py, robovision UI).
- docs/… – MkDocs site for user and developer documentation.
- Patterns
- Each robotics capability is its own library folder (lib/lidar, lib/stepper, lib/vision, lib/eql).
- Vendored third‐party code under lib/vendors/tensorflow includes the full TFLite Micro engine and examples.
- ML pipeline separated into its own directory; scripts generate .pt/.pkl models outside of embedded build.
- PlatformIO orchestrates firmware build and linking of all C/C++ source.

##### README for additional insights
- Purpose: a lightweight robotics toolkit specialized for ESP32.
- Not yet stable for external package use; modules are decoupled, built into your code via copy/paste.

##### Main components
a. Development Environment
- Host PC
– IDE/CLI running PlatformIO
– Python environment for ML (training.py, processing.py)
– Documentation builder (MkDocs)
b. Firmware Build System
- PlatformIO
- CMakeLists and header/source files under lib/ and src/
- Vendored TensorFlow Lite Micro
c. Embedded Target
- ESP32 Module (dual‐core microcontroller)
- Sensor Interfaces
– LiDAR (via UART/SPI/I2C to lib/lidar)
- Actuators
– Stepper motors (via lib/stepper)
– Servos (if added in future)
- In‐device ML Inference
– TensorFlow Lite Micro interpreter linking a compiled .tflite or model data blob
- Custom EQL Protocol Module (lib/eql)
d. ML Pipeline (Host‐side)
- Dataset (dataset/raw, dataset/blobs)
- Training Script (ml/training.py) → generates ml/yolov8n.pt, ml/model.pkl
- Processing Script (ml/processing.py) → converts/optimizes model for embedded inference
e. Tools & Utilities
- EQL code generator (tools/eql.py)
- Robovision host UI (tools/robovision/main.py + components)
- Script.eql domain language file

##### Relationships and data flows
- On the host:
1. Collect images (dataset/) → run ml/training.py → produce model files.
2. Run ml/processing.py → embed converted model into firmware resources.
3. Run PlatformIO build → links lib/* (including TensorFlow, EQL, LIDAR, stepper, vision).
4. Flash firmware onto ESP32.
- On the device:
1. Sensors feed data into library modules (e.g., LiDAR → lib/lidar, camera → lib/vision).
2. Vision/EQL modules process raw sensor data.
3. If ML inference is enabled, data passes into TFLite Micro interpreter.
4. Control commands output to actuators via lib/stepper or future servo library.
5. Optionally, send telemetry back over Wi-Fi/Bluetooth to host or Robovision tool.

##### Architectural patterns and design principles
- Modular, decoupled libraries: each domain (LiDAR, vision, stepper, EQL) stands alone.
- Single‐binary firmware: all modules and vendored TF‐Lite Micro link into one ESP32 executable.
- Well‐separated host vs. device responsibilities: ML training and model conversion on host; inference on device.
- Use of PlatformIO for cross‐platform embedded build management.
- Python scripts organized under ml/ and tools/ for extensibility and maintainability.

##### Be detailed but focused
- External/vendor code (TensorFlow Lite) as a separate component.
- ML assets (model files) flowing into the firmware.

Layer 1: Host (ML pipeline, tools, docs)
Layer 2: Build system (PlatformIO, resource embedding)
Layer 3: Embedded firmware modules
Layer 4: Hardware (sensors/actuators)

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Host PC Environment"
    A_HOST("Host PC"):::host
    A_DATA_RAW("Raw Dataset"):::host
    A_DATA_BLOBS("Processed Dataset"):::host
    A_TRAIN("Training Script"):::host
    A_MODELS_PT("yolov8n.pt"):::host
    A_MODELS_PKL("model.pkl"):::host
    A_PROCESS("Processing Script"):::host
    A_DOCS("Docs Builder (MkDocs)"):::host
    A_TOOL_EQL("EQL Code Generator"):::host
    A_TOOL_ROBO("Robovision Host UI"):::host
    A_TOOL_COMP("RV UI Components"):::host
    A_TOOL_SCRIPT("Domain Language File"):::host
  end

  subgraph "Build System"
    B_PIO("PlatformIO Build System"):::build
    B_VENDOR_TF("Vendored TFLite Micro"):::build
    B_ENTRY_SRC("Firmware Entry Point"):::build
  end

  subgraph "Firmware Binary"
    F_BIN("ESP32 Firmware Binary"):::firmware
    subgraph Modules
      F_LIDAR("LiDAR Module"):::firmware
      F_VISION("Vision Module"):::firmware
      F_STEPPER("Stepper Module"):::firmware
      F_EQL("EQL Module"):::firmware
      F_TF("TFLite Micro Engine"):::firmware
    end
  end

  subgraph "Hardware"
    H_ESP("ESP32 Module"):::hardware
    H_LIDAR_SENSOR("LiDAR Sensor"):::hardware
    H_CAMERA("Camera Sensor"):::hardware
    H_STEPPER_ACT("Stepper Motor"):::hardware
  end

  A_DATA_RAW -->|feeds| A_TRAIN
  A_DATA_BLOBS -->|feeds| A_TRAIN
  A_TRAIN -->|produces| A_MODELS_PT
  A_TRAIN -->|produces| A_MODELS_PKL
  A_MODELS_PT -->|input| A_PROCESS
  A_MODELS_PKL -->|input| A_PROCESS
  A_PROCESS -->|embeds model| B_PIO
  A_DOCS -->|generates docs| A_HOST
  A_TOOL_SCRIPT -->|used by| A_TOOL_EQL
  A_TOOL_EQL -->|generates code| B_PIO
  A_TOOL_ROBO -->|telemetry/UI| H_ESP
  A_TOOL_COMP -->|UI libs| A_TOOL_ROBO

  B_VENDOR_TF -->|includes| B_PIO
  B_ENTRY_SRC -->|included| B_PIO
  B_PIO -->|builds| F_BIN

  F_BIN -->|runs on| H_ESP
  H_ESP -->|links| F_LIDAR
  H_ESP -->|links| F_VISION
  H_ESP -->|links| F_STEPPER
  H_ESP -->|links| F_EQL
  H_ESP -->|links| F_TF

  H_LIDAR_SENSOR -->|UART/SPI/I2C| F_LIDAR
  H_CAMERA -->|data| F_VISION
  F_STEPPER -->|GPIO pulses| H_STEPPER_ACT
  
  classDef host fill:#cce5ff,stroke:#004085;
  classDef build fill:#d4edda,stroke:#155724;
  classDef firmware fill:#fff3cd,stroke:#856404;
  classDef hardware fill:#e2e3e5,stroke:#6c757d;

  click A_DATA_RAW "https://github.com/unimakers/espresso/tree/master/dataset/raw/"
  click A_DATA_BLOBS "https://github.com/unimakers/espresso/tree/master/dataset/blobs/"
  click A_TRAIN "https://github.com/unimakers/espresso/blob/master/ml/training.py"
  click A_PROCESS "https://github.com/unimakers/espresso/blob/master/ml/processing.py"
  click A_MODELS_PT "https://github.com/unimakers/espresso/blob/master/ml/yolov8n.pt"
  click A_MODELS_PKL "https://github.com/unimakers/espresso/blob/master/ml/model.pkl"
  click A_DOCS "https://github.com/unimakers/espresso/blob/master/docs/mkdocs.yml"
  click A_TOOL_EQL "https://github.com/unimakers/espresso/blob/master/tools/eql.py"
  click A_TOOL_ROBO "https://github.com/unimakers/espresso/blob/master/tools/robovision/main.py"
  click A_TOOL_COMP "https://github.com/unimakers/espresso/tree/master/tools/robovision/components/"
  click A_TOOL_SCRIPT "https://github.com/unimakers/espresso/blob/master/tools/script.eql"
  click B_PIO "https://github.com/unimakers/espresso/blob/master/platformio.ini"
  click B_VENDOR_TF "https://github.com/unimakers/espresso/tree/master/lib/vendors/tensorflow/"
  click B_ENTRY_SRC "https://github.com/unimakers/espresso/blob/master/src/main.cpp"
  click F_LIDAR "https://github.com/unimakers/espresso/tree/master/lib/lidar/"
  click F_VISION "https://github.com/unimakers/espresso/tree/master/lib/vision/"
  click F_STEPPER "https://github.com/unimakers/espresso/tree/master/lib/stepper/"
  click F_EQL "https://github.com/unimakers/espresso/tree/master/lib/eql/"
```
