# atc1441/atc_mithermometer architecture

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

- Interactive diagram: https://gitdiagram.com/atc1441/atc_mithermometer
- Repository: https://github.com/atc1441/atc_mithermometer

## Overview

##### Project Type and Purpose
- The repository provides custom firmware (found in the “ATC_Thermometer” folder) for a Xiaomi thermometer that uses a Telink TLSR8251 MCU. It includes mechanisms for both OTA flashing via a custom Web Flasher tool and direct USB-to-UART flashing through a Python tool.
- The README highlights two primary functions: flashing the custom firmware (or reverting to stock) and building the firmware using a provided Makefile. In addition, it explains how the firmware integrates with third-party systems such as ESPHome, OpenMQTTGateway, and Home Assistant.
- The existence of auxiliary directories (like “contrib/nodejs” and “contrib/python”) further indicates that external scripts are provided to scan or interface with the thermometer.

##### File Structure
- Top-level files: You have two binary firmware images (ATC_Exploit.bin, ATC_Thermometer.bin), flashing tools (ATCtelink.py, ATCtelink_one_way.py, flash.py), and build-related files (Makefile, project.mk).
- The “ATC_Thermometer” folder contains source files (e.g., main.c, app.c, battery.c, ble.c, flash.c, lcd.c, sensor.c, etc.) and header files that show a modular design: each module (battery, BLE, I2C, command parser) is separated into its own C file.
- The “.github” folder with workflows indicates that CI/CD for building and testing may be in place.
- The “contrib” folder includes additional tooling with separate folders for nodejs and python implementations of scanner utilities.

##### Identifying the Main Components
- Embedded Firmware:
– The “ATC_Thermometer” core module that integrates various functionalities such as:
▪ Application Logic (app.c / app_att.c)
▪ Hardware interfacing: battery management (battery.c), sensor readout (sensor.c), and LCD display (lcd.c)
▪ Communication interfaces: BLE module (ble.c) and I2C communication (i2c.c)
▪ Firmware management: flash operations (flash.c) and command parsing (cmd_parser.c)
– Build configuration files (Makefile, project.mk) providing instructions to compile the firmware.

- Flashing and Upgrade Mechanisms:
– OTA Flashing: The README details a Web-based flasher (hosted externally at atc1441.github.io/TelinkFlasher.html) allowing OTA firmware upgrades.
– USB-to-UART Flashing: Tools like ATCtelink.py facilitate programming/unbricking the device via USB to serial converters.
- Auxiliary Integration Layers:
– External tools provided in “contrib/python” and “contrib/nodejs” for scanning the device and possibly handling advertisement data.
– Integration with third-party ecosystems (ESPHome and OpenMQTTGateway) is supported by the firmware’s advertising structure.

##### Specific Elements
▪ The compilation flow (source files → firmware binary).
▪ The flashing/update process from the flashing tools to the device.
▪ Data churn from sensor modules feeding into the BLE advertising, then to integrating systems like ESPHome.
▪ Another for external utilities (OTA, USB flasher),
▪ And a third for integration points (MQTT, ESPHome).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Deployment"
        BE("Build Environment (Makefile & project.mk)"):::build
        CICD("CI/CD Pipeline (GitHub Actions)"):::cicd
        BE -->|"compile"| FW
        CICD --- BE
        subgraph "Flashing/Update"
            OTA("OTA Flashing (Web Tool)"):::flasher
            subgraph "USB-to-UART Flasher"
                USB1("ATCtelink.py"):::flasher
                USB2("ATCtelink_one_way.py"):::flasher
                USB3("flash.py"):::flasher
            end
            OTA -->|"flashes"| FW
            USB1 -->|"flashes"| FW
            USB2 -->|"flashes"| FW
            USB3 -->|"flashes"| FW
        end
    end

    subgraph "Embedded Firmware"
        FW("Firmware (ATC_Thermometer)"):::firmware
        App("Application Logic (app.c, cmd_parser.c)"):::firmware
        Battery("Battery Management (battery.c)"):::firmware
        Sensor("Sensor Module (sensor.c)"):::firmware
        LCD("LCD Display (lcd.c)"):::firmware
        BLE("BLE Module (ble.c)"):::firmware
        I2C("I2C Communication (i2c.c)"):::firmware
        FlashOp("Flash Management (flash.c)"):::firmware
        FW --- App
        FW --- Battery
        FW --- Sensor
        FW --- LCD
        FW --- BLE
        FW --- I2C
        FW --- FlashOp
        FW -->|"BLEAdvertising"| EXT
    end

    subgraph "External & Auxiliary"
        EXT("External Integration (ESPHome, OpenMQTTGateway, HomeAssistant)"):::external
        ScannerNode("Node.js Scanner"):::scanner
        ScannerPy("Python Scanner"):::scanner
        EXT -->|"feedsData"| ScannerNode
        EXT -->|"feedsData"| ScannerPy
    end

    click FW "https://github.com/atc1441/atc_mithermometer/tree/master/ATC_Thermometer/"
    click BE "https://github.com/atc1441/atc_mithermometer/tree/master/ATC_Thermometer/makefile"
    click CICD "https://github.com/atc1441/atc_mithermometer/blob/master/.github/workflows/build_thermometer.yml"
    click USB1 "https://github.com/atc1441/atc_mithermometer/blob/master/ATCtelink.py"
    click USB2 "https://github.com/atc1441/atc_mithermometer/blob/master/ATCtelink_one_way.py"
    click USB3 "https://github.com/atc1441/atc_mithermometer/blob/master/flash.py"
    click ScannerNode "https://github.com/atc1441/atc_mithermometer/blob/master/contrib/nodejs/scan-thermometer.js"
    click ScannerPy "https://github.com/atc1441/atc_mithermometer/blob/master/contrib/python/scan-thermometer.py"

    classDef firmware fill:#FFCCCB,stroke:#B22222,stroke-width:2px;
    classDef build fill:#C6E2FF,stroke:#4682B4,stroke-width:2px;
    classDef flasher fill:#D3FFCE,stroke:#228B22,stroke-width:2px;
    classDef external fill:#FFFACD,stroke:#B8860B,stroke-width:2px;
    classDef scanner fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px;
    classDef cicd fill:#FFD700,stroke:#DAA520,stroke-width:2px;
```
