# treehopper-electronics/treehopper-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/treehopper-electronics/treehopper-sdk
- Repository: https://github.com/treehopper-electronics/treehopper-sdk

## Overview

##### High-level components
- Hardware/Board (Treehopper PCB with EFM8 microcontroller)
- On-board firmware (EFM8 C code, USB descriptors, peripheral drivers)
- Host communication layer (USB stacks: WinUSB, libusb, Mac IOKit)
- Core API layer (shared C/C++ “Treehopper” core code)
- Language-specific SDKs and wrappers (C++, .NET, Java, Python, MATLAB, PowerShell)
- Code-generation tool (RegisterGenerator)
- Sample applications and demos (for each language)
- Documentation system (Doxygen, Sandcastle)

##### Relationships and data flows
– Drivers for each peripheral (gpio.c, i2c.c, spi.c, uart.c, softPwm.c…)
– USB device descriptors and firmware logic (descriptors.c, callback.c)
– FirmwareConnectionService (handles incoming commands)
– Windows: WinUSBConnectionService
– Linux: LibUsbConnectionService
– macOS: MacUsbConnectionService
– UWP/UWP wrappers, PowerShell shim
- From the Core API block, branch out to each language SDK:
– C++: API/ folder (HardwareI2c, Pin, Utility, Libraries…)
– .NET: NET/API (ConnectionService.cs, UsbConnection.cs, Treehopper.csproj…)
– Java: Java/api/treehopper (ConnectionService.java, TreehopperUsb.java…)
– Python: Python/treehopper/api (find_boards.py, i2c.py, treehopper_usb.py…)
– MATLAB: Demos folder (init.m, blink.m…)
– PowerShell: PowerShell cmdlets (GetTreehopper.cs, SetTreehopper.cs…)

##### Architectural patterns and principles
- Layered architecture: Hardware → Firmware → USB transport → Core API → Language wrappers → Demos
- Adapter/Factory pattern: ConnectionService abstracts platform-specific USB layers
- Code generation: RegisterGenerator produces register bindings for each language
- Modular drivers: each peripheral (ADC, SPI, I2C, sensor libraries) lives in its own folder
- Cross-platform partitioning: separate src/linux, src/win, src/mac for C++

##### Technologies & frameworks
- Firmware: Silicon Labs EFM8 SDK, ANSI C, USB 2.0
- C++: CMake, libusb, WinUSB, Doxygen
- .NET: C#/.NET Framework / Xamarin (Android, UWP), Sandcastle
- Java: Gradle, Android SDK, javax.usb, Javadoc
- Python: setuptools, PyPI packaging
- MATLAB: .m scripts
- PowerShell: .NET Core modules

##### Final checklist
- Every major folder in the repo (Firmware-EFM8, C++/API, NET/API, Java/api, Python/treehopper, RegisterGenerator, Demos) appears as a component.
- Clear grouping of platform-specific adapters and language wrappers.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Layer
    Hardware["Hardware/Board<br/>(Treehopper PCB with EFM8 MCU)"]:::hardware
    click Hardware "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Firmware-EFM8"

    %% Firmware Layer
    subgraph "On-board Firmware" 
        direction TB
        Drivers["Peripheral Drivers<br/>(gpio.c, i2c.c, spi.c, uart.c, softPwm.c)"]:::firmware
        USBDesc["USB Descriptors & Logic<br/>(descriptors.c, callback.c)"]:::firmware
        FWService["FirmwareConnectionService"]:::firmware
    end
    click Drivers "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Firmware-EFM8/src"
    click USBDesc "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Firmware-EFM8/inc"
    click FWService "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Firmware-EFM8/lib"

    %% Host Communication Layer
    subgraph "Host Communication Layer" 
        direction TB
        %% C++ Adapters
        subgraph "C++ USB Adapters"
            direction TB
            WinUsbCpp["WinUsbConnection.cpp"]:::transport
            WinSvcCpp["WinConnectionService.cpp"]:::transport
            LibUsbCpp["LibUsbConnection.cpp"]:::transport
            LibSvcCpp["ConnectionService.cpp"]:::transport
            MacUsbCpp["MacUsbConnection.cpp"]:::transport
            MacSvcCpp["MacConnectionService.cpp"]:::transport
        end
        %% .NET Adapters
        subgraph ".NET USB Adapters"
            direction TB
            WinUsbCs["WinUsbConnectionService.cs"]:::transport
            LibUsbCs["LibUsbConnectionService.cs"]:::transport
            MacUsbCs["MacConnectionService.cs"]:::transport
            UwpSvcCs["ConnectionService.cs"]:::transport
            UsbCs["UsbConnection.cs"]:::transport
        end
        %% Java Adapters
        subgraph "Java USB Adapters"
            direction TB
            JaUsbSvcAndroid["ConnectionService.java"]:::transport
            JaUsbConnAndroid["UsbConnection.java"]:::transport
            JaUsbSvcDesktop["ConnectionService.java"]:::transport
            JaUsbConnDesktop["UsbConnection.java"]:::transport
        end
        %% Python Adapter
        PyUsb["treehopper_usb.py"]:::transport
    end
    click WinUsbCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/win/WinUsbConnection.cpp"
    click WinSvcCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/win/WinConnectionService.cpp"
    click LibUsbCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/linux/LibUsbConnection.cpp"
    click LibSvcCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/linux/ConnectionService.cpp"
    click MacUsbCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/mac/MacUsbConnection.cpp"
    click MacSvcCpp "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/C++/API/src/mac/MacConnectionService.cpp"
    click WinUsbCs "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/NET/API/Treehopper.Desktop/WinUsb/WinUsbConnectionService.cs"
    click LibUsbCs "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/NET/API/Treehopper.Desktop/LibUsbConnectionService.cs"
    click MacUsbCs "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/NET/API/Treehopper.Desktop/MacUsb/MacConnectionService.cs"
    click UwpSvcCs "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/NET/API/Treehopper.UWP/ConnectionService.cs"
    click UsbCs "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/NET/API/Treehopper.UWP/UsbConnection.cs"
    click JaUsbSvcAndroid "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/Java/api/treehopper.android/src/main/java/io/treehopper/ConnectionService.java"
    click JaUsbConnAndroid "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/Java/api/treehopper.android/src/main/java/io/treehopper/UsbConnection.java"
    click JaUsbSvcDesktop "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/Java/api/treehopper.desktop/src/main/java/io/treehopper/ConnectionService.java"
    click JaUsbConnDesktop "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/Java/api/treehopper.desktop/src/main/java/io/treehopper/UsbConnection.java"
    click PyUsb "https://github.com/treehopper-electronics/treehopper-sdk/blob/master/Python/treehopper/api/treehopper_usb.py"

    %% Core API Layer
    subgraph "Core API Layer" 
        direction TB
        CppCore["C++ Core API<br/>(inc/*.h, src/*.cpp)"]:::core
        NetCore[".NET Core API<br/>(*.cs)"]:::core
        JavaCore["Java Core API<br/>(*.java)"]:::core
        PyCore["Python Core API<br/>(*.py)"]:::core
    end
    click CppCore "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/C++/API"
    click NetCore "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/NET/API/Treehopper"
    click JavaCore "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Java/api/treehopper"
    click PyCore "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Python/treehopper/api"

    %% RegisterGenerator Tool
    RegisterGen["RegisterGenerator<br/>(code-gen tool)"]:::tool
    click RegisterGen "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/RegisterGenerator/"

    %% SDK Layer
    subgraph "Language SDKs" 
        direction TB
        CppSDK["C++ SDK/API"]:::sdk
        NetSDK[".NET SDK"]:::sdk
        JavaSDK["Java SDK"]:::sdk
        PySDK["Python SDK"]:::sdk
        MatlabSDK["MATLAB SDK"]:::sdk
        PsSDK["PowerShell SDK"]:::sdk
    end
    click CppSDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/C++/API"
    click NetSDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/NET/API/Treehopper"
    click JavaSDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Java/api/treehopper"
    click PySDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Python/treehopper/api"
    click MatlabSDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/MATLAB/Demos"
    click PsSDK "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/PowerShell/"

    %% Demos Layer
    subgraph "Sample Applications & Demos" 
        direction TB
        CppDemos["C++ Demos"]:::demo
        JavaDemos["Java Demos"]:::demo
        PyDemos["Python Examples"]:::demo
        NetDemos[".NET Demos"]:::demo
    end
    click CppDemos "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/C++/Demos"
    click JavaDemos "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Java/demos/android"
    click PyDemos "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Python/examples"
    click NetDemos "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/NET/Demos"

    %% Documentation Layer
    subgraph "Documentation" 
        direction TB
        Doxy["C++ Doxygen"]:::doc
        MD["Markdown Docs"]:::doc
        Sand[".NET Sandcastle"]:::doc
    end
    click Doxy "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/C++/Documentation/Doxyfile"
    click MD "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/Documentation/"
    click Sand "https://github.com/treehopper-electronics/treehopper-sdk/tree/master/NET/Documentation/"

    %% Connections
    Hardware -->|"powered by"| Firmware
    Firmware -->|"USB"| WinUsbCpp
    Firmware -->|"USB"| LibUsbCpp
    Firmware -->|"USB"| MacUsbCpp
    Firmware -->|"USB"| PyUsb

    WinUsbCpp -->|"calls"| CppCore
    LibUsbCpp -->|"calls"| CppCore
    MacUsbCpp -->|"calls"| CppCore
    PyUsb -->|"calls"| PyCore
    WinUsbCs -->|"calls"| NetCore
    LibUsbCs -->|"calls"| NetCore
    MacUsbCs -->|"calls"| NetCore
    UwpSvcCs -->|"calls"| NetCore
    JaUsbSvcAndroid -->|"calls"| JavaCore
    JaUsbSvcDesktop -->|"calls"| JavaCore

    CppCore -->|"provides API"| CppSDK
    NetCore -->|"provides API"| NetSDK
    JavaCore -->|"provides API"| JavaSDK
    PyCore -->|"provides API"| PySDK

    CppSDK -->|"samples"| CppDemos
    NetSDK -->|"samples"| NetDemos
    JavaSDK -->|"samples"| JavaDemos
    PySDK -->|"samples"| PyDemos
    MatlabSDK -->|"samples"| PyDemos
    PsSDK -->|"samples"| NetDemos

    RegisterGen -.->|"gen registers"| CppCore
    RegisterGen -.->|"gen registers"| NetCore
    RegisterGen -.->|"gen registers"| JavaCore
    RegisterGen -.->|"gen registers"| PyCore
    RegisterGen -.->|"gen registers"| CppSDK
    RegisterGen -.->|"gen registers"| NetSDK
    RegisterGen -.->|"gen registers"| JavaSDK
    RegisterGen -.->|"gen registers"| PySDK

    Doxy -->|"docs for"| CppCore
    MD -->|"docs for"| PySDK
    Sand -->|"docs for"| NetCore

    %% Styles
    classDef hardware fill:#DDDDDD,stroke:#666;
    classDef firmware fill:#AED6F1,stroke:#21618C;
    classDef transport fill:#F9E79F,stroke:#B7950B;
    classDef core fill:#ABEBC6,stroke:#239B56;
    classDef sdk fill:#D2B4DE,stroke:#884EA0;
    classDef demo fill:#F5CBA7,stroke:#A04000;
    classDef tool fill:#FAD7A0,stroke:#B9770E;
    classDef doc fill:#D5DBDB,stroke:#566573;
```
