# quecpython/solution-sensorhub architecture

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

- Interactive diagram: https://gitdiagram.com/quecpython/solution-sensorhub
- Repository: https://github.com/quecpython/solution-sensorhub

## Overview

##### Project type and purpose
- This is an IoT “sensor-hub” firmware project written in QuecPython, targeting the Quectel EC200U LTE module.
- Its purpose is to read data from multiple onboard and external sensors, detect significant changes, and upload updates over the cellular network to a cloud backend (which in turn feeds a mobile/web app).

##### File structure
- Top-level “code” folder holds everything that lives on the module’s filesystem:
- Qth/ – Quectel platform modules (bus, file, OTA, protocol, config, DMP)
- drivers/ – Python drivers for IC sensors (ICM20948, LPS22HB, SHTC3, TCS34725)
- libs/ – utility libraries (I2C abstraction, logging, threading, pub-sub)
- extensions/ – high-level services: sensor_service, gnss_service, lbs_service, qth_client
- _main.py – entry point orchestrating initialization, sensor polling, change detection, and upload
- config.json / config2.json – runtime parameters and thresholds
- Outside code/ you have documentation, hardware schematics, and PC-side tools for flashing and log retrieval.

##### README for additional insights
- Describes hardware setup (EC200U dev-board + sensors + SIM card)
- Instructs on flashing firmware via QPYcom, transferring “code/” directory to module
- Explains runtime behavior: dial-up, periodic sensor prints, change detection >1 unit (or 150 RGB units) triggers upload, GNSS/LBS location updates when moved >50 m

##### Main components and their relationships
a. Hardware layer
- EC200U module (LTE modem + Python interpreter)
- SIM card + LTE antenna
b. Firmware layers on the module
1) Core/Platform (Qth)
- qth_bus: event/message bus
- qth_file: file I/O
- qth_ota: firmware update
- qth_protocal: network protocol abstractions
2) Drivers (one per sensor)
- Wrap I2C transactions & raw data parsing
3) Libs/utilities
- I2C wrapper, logging, threading, pub-sub event hub, common helpers
4) Extensions/services
- sensor_service: periodically polls drivers, publishes sensor readings
- gnss_service & lbs_service: location services from module’s GNSS/LBS APIs
- qth_client: network client that dials up, sends JSON payloads to cloud
5) Application (_main.py)
- Loads config, subscribes to sensor events, applies threshold logic, triggers qth_client uploads
c. Network & cloud
- EC200U LTE link over 4G network → remote API endpoint
- Cloud backend stores data, responds to “read” requests from mobile/web app
d. Mobile/Web App
- Uses cloud API to fetch latest sensor & location data; UI refreshable on demand

##### Important architectural patterns & design principles
- Layered separation: drivers ← libs ← services ← application
- Pub-sub event bus for decoupling sensors from upload logic
- Config-driven thresholds & endpoints
- Threading model: each service may run in its own thread, orchestrated via libs/threading.py

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client App
    subgraph "Client Application"
        MobileApp["Mobile/Web App"]:::external
    end

    %% Network & Cloud
    subgraph "Network & Cloud"
        CloudAPI["Cloud Backend API"]:::external
    end

    %% LTE Link
    subgraph "LTE Network"
        LTE["4G LTE"]:::external
    end

    MobileApp <-->|"API Calls"| CloudAPI
    CloudAPI <-->|"HTTPS"| LTE

    %% Module Firmware
    subgraph "EC200U Module Firmware"
        direction TB

        subgraph "Application & Services"
            MainApp["_main.py"]:::app
            SensorService["sensor_service"]:::app
            GNSSService["gnss_service"]:::app
            LBSService["lbs_service"]:::app
            QthClient["qth_client"]:::app
            Config["config.json / config2.json"]:::config
        end

        subgraph "Libs & Drivers"
            direction TB

            subgraph "Utilities"
                I2C["i2c.py"]:::lib
                Logging["logging.py"]:::lib
                Threading["threading.py"]:::lib
                PubSub["pypubsub.py"]:::lib
                Common["common.py"]:::lib
                Collections["collections.py"]:::lib
            end

            subgraph "Drivers"
                IMU["icm20948.py"]:::driver
                Baro["lps22hb.py"]:::driver
                TempHum["shtc3.py"]:::driver
                Color["tcs34725.py"]:::driver
            end
        end

        subgraph "Qth Platform"
            Bus["qth_bus"]:::platform
            File["qth_file"]:::platform
            OTA["qth_ota"]:::platform
            Protocol["qth_protocal"]:::platform
            ConfigMod["qth_config"]:::platform
            DMP["qth_dmp"]:::platform
        end

        %% Internal Flows
        I2C --> IMU
        I2C --> Baro
        I2C --> TempHum
        I2C --> Color

        IMU --> SensorService
        Baro --> SensorService
        TempHum --> SensorService
        Color --> SensorService

        SensorService --> Bus
        GNSSService --> Bus
        LBSService --> Bus
        Bus --> MainApp

        Config --> MainApp
        MainApp --> QthClient
        QthClient --> Protocol
        Protocol --> LTE
        GNSSService --> MainApp
        LBSService --> MainApp
    end

    %% Hardware Layer
    subgraph "Hardware"
        ModuleHW["EC200U Module"]:::hardware
        I2CBus["I2C Bus"]:::hardware
        IMU_Sensor["IMU (ICM20948)"]:::hardware
        Baro_Sensor["Barometer (LPS22HB)"]:::hardware
        TH_Sensor["Temp/Humidity (SHTC3)"]:::hardware
        Color_Sensor["Color (TCS34725)"]:::hardware
        SIM["SIM Card + LTE Antenna"]:::hardware
    end

    ModuleHW --> I2CBus
    I2CBus --> IMU_Sensor
    I2CBus --> Baro_Sensor
    I2CBus --> TH_Sensor
    I2CBus --> Color_Sensor
    ModuleHW --> SIM

    %% Click Events
    click QthPlatform "https://github.com/quecpython/solution-sensorhub/tree/main/code/Qth"
    click Bus "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_bus.mpy"
    click File "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_file.mpy"
    click OTA "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_ota.mpy"
    click Protocol "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_protocal.mpy"
    click ConfigMod "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_config.mpy"
    click DMP "https://github.com/quecpython/solution-sensorhub/blob/main/code/Qth/qth_dmp.mpy"
    click IMU "https://github.com/quecpython/solution-sensorhub/blob/main/code/drivers/icm20948.py"
    click Baro "https://github.com/quecpython/solution-sensorhub/blob/main/code/drivers/lps22hb.py"
    click TempHum "https://github.com/quecpython/solution-sensorhub/blob/main/code/drivers/shtc3.py"
    click Color "https://github.com/quecpython/solution-sensorhub/blob/main/code/drivers/tcs34725.py"
    click I2C "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/i2c.py"
    click Logging "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/logging.py"
    click Threading "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/threading.py"
    click PubSub "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/pypubsub.py"
    click Common "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/common.py"
    click Collections "https://github.com/quecpython/solution-sensorhub/blob/main/code/libs/collections.py"
    click SensorService "https://github.com/quecpython/solution-sensorhub/blob/main/code/extensions/sensor_service.py"
    click GNSSService "https://github.com/quecpython/solution-sensorhub/blob/main/code/extensions/gnss_service.py"
    click LBSService "https://github.com/quecpython/solution-sensorhub/blob/main/code/extensions/lbs_service.py"
    click QthClient "https://github.com/quecpython/solution-sensorhub/blob/main/code/extensions/qth_client.py"
    click MainApp "https://github.com/quecpython/solution-sensorhub/blob/main/code/_main.py"
    click Config "https://github.com/quecpython/solution-sensorhub/blob/main/code/config.json"
    click Config "https://github.com/quecpython/solution-sensorhub/blob/main/code/config2.json"

    %% Styles
    classDef hardware fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef platform fill:#cce0ff,stroke:#333,stroke-width:1px
    classDef lib fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef driver fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef app fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef external fill:#e5ccff,stroke:#333,stroke-width:1px
    classDef config fill:#fff2cc,stroke:#333,stroke-width:1px
```
