# jlab-sensing/ents-tock architecture

> Architecture diagram of the GitHub repository jlab-sensing/ents-tock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlab-sensing/ents-tock
- Repository: https://github.com/jlab-sensing/ents-tock

## Overview

ENTS-tock is presented as a userspace ENTS implementation for Tock, with embedded sensor firmware, an ESP32 companion, protobuf-based messages, and Python utilities. The principal embedded path is measurement buffering on the STM32 followed by batched LoRaWAN upload; the ESP32 provides command-driven modules over I²C. Python tools encode/decode data, simulate uploads, and support calibration. The README is sparse and sampled source is incomplete, so links are limited to relationships shown in excerpts or the source index.

Main entry points: [`embedded/esp32/src/main.cpp`](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/src/main.cpp) (ESP32 Startup), [`python/src/ents/cli.py`](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/cli.py) (ENTS CLI), [`embedded/stm32/apps/core/main.cc`](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/stm32/apps/core/main.cc) (Core App), [`python/src/ents/simulator/node.py`](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/simulator/node.py) (Node Simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stm32["STM32 Firmware"]
  node_sensor_drivers["Sensor Drivers"]
  node_fifo[("Measurement FIFO<br/>[fifo.c]")]
  node_core_app["Core App<br/>[main.cc]"]
  node_lorawan["LoRaWAN<br/>[lorawan.cc]"]
  node_controller["ESP32 Controller<br/>[controller.c]"]
  node_communication["Controller Communication<br/>[communication.c]"]
end

subgraph group_esp32["ESP32 Companion"]
  node_esp_main["ESP32 Startup<br/>[main.cpp]"]
  node_module_handler["Module Dispatcher<br/>[module_handler.cpp]"]
  node_wifi_module["WiFi Module<br/>[wifi.cpp]"]
  node_microsd_module["microSD Module<br/>[microsd.cpp]"]
  node_user_config_module["User Config Module"]
  node_irrigation_module["Irrigation Module<br/>[irrigation.cpp]"]
  node_power_module["Power Module<br/>[power.cpp]"]
end

subgraph group_protocol["Message Protocol"]
  node_protobuf_messages["Protobuf Messages"]
end

subgraph group_python["Python Utilities"]
  node_cli["ENTS CLI<br/>[cli.py]"]
  node_encoder["Measurement Encoder<br/>[encode.py]"]
  node_sensor_protocol["Sensor Protocol<br/>[sensor.py]"]
  node_simulator["Node Simulator<br/>[node.py]"]
  node_calibration["Calibration Recorder<br/>[recorder.py]"]
  node_plots["Calibration Plots<br/>[plots.py]"]
end

node_operator(("Operator"))
node_sensors(("Physical Sensors"))
node_dirtviz(("Dirtviz Service"))
node_smu(("Source Measurement Unit"))

node_operator -->|"runs firmware"| node_core_app
node_core_app -->|"reads batches"| node_fifo
node_core_app -->|"uploads data"| node_lorawan
node_sensors -.->|"provide readings"| node_sensor_drivers
node_core_app -->|"uses interface"| node_controller
node_controller -->|"uses buffers"| node_communication
node_esp_main -->|"registers modules"| node_module_handler
node_esp_main -->|"routes I²C callbacks"| node_module_handler
node_esp_main -->|"registers"| node_wifi_module
node_esp_main -->|"registers"| node_microsd_module
node_esp_main -->|"registers"| node_user_config_module
node_esp_main -->|"registers"| node_power_module
node_esp_main -.->|"optional module"| node_irrigation_module
node_operator -->|"invokes commands"| node_cli
node_cli -->|"encodes messages"| node_encoder
node_cli -->|"handles sensor data"| node_sensor_protocol
node_cli -->|"runs simulation"| node_simulator
node_simulator -->|"encodes readings"| node_encoder
node_simulator -->|"posts uploads"| node_dirtviz
node_cli -->|"records calibration"| node_calibration
node_cli -->|"creates plots"| node_plots
node_calibration -->|"controls instrument"| node_smu
node_encoder -.->|"serializes messages"| node_protobuf_messages

click node_sensor_drivers "https://github.com/jlab-sensing/ents-tock/tree/main/embedded/libents/src/libents/sensors"
click node_fifo "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/storage/fifo.c"
click node_core_app "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/stm32/apps/core/main.cc"
click node_lorawan "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/stm32/apps/core/lorawan.cc"
click node_controller "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/controller/controller.c"
click node_communication "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/controller/communication.c"
click node_esp_main "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/src/main.cpp"
click node_module_handler "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/module_handler.cpp"
click node_wifi_module "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/wifi.cpp"
click node_microsd_module "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/microsd.cpp"
click node_user_config_module "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/wifi_userconfig.cpp"
click node_irrigation_module "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/irrigation.cpp"
click node_power_module "https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/power.cpp"
click node_protobuf_messages "https://github.com/jlab-sensing/ents-tock/tree/main/proto"
click node_cli "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/cli.py"
click node_encoder "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/proto/encode.py"
click node_sensor_protocol "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/proto/sensor.py"
click node_simulator "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/simulator/node.py"
click node_calibration "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/calibrate/recorder.py"
click node_plots "https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/calibrate/plots.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sensor_drivers,node_fifo,node_core_app,node_lorawan,node_controller,node_communication toneBlue
class node_esp_main,node_module_handler,node_wifi_module,node_microsd_module,node_user_config_module,node_irrigation_module,node_power_module toneAmber
class node_protobuf_messages toneMint
class node_cli,node_encoder,node_sensor_protocol,node_simulator,node_calibration,node_plots toneRose
class node_operator,node_sensors,node_dirtviz,node_smu toneIndigo
```

## Components

### STM32 Firmware

- [Sensor Drivers](https://github.com/jlab-sensing/ents-tock/tree/main/embedded/libents/src/libents/sensors): `embedded/libents/src/libents/sensors`
- [Measurement FIFO](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/storage/fifo.c): `embedded/libents/src/libents/storage/fifo.c`
- [Core App](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/stm32/apps/core/main.cc): `embedded/stm32/apps/core/main.cc`
- [LoRaWAN](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/stm32/apps/core/lorawan.cc): `embedded/stm32/apps/core/lorawan.cc`
- [ESP32 Controller](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/controller/controller.c): `embedded/libents/src/libents/controller/controller.c`
- [Controller Communication](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/libents/src/libents/controller/communication.c): `embedded/libents/src/libents/controller/communication.c`

### ESP32 Companion

- [ESP32 Startup](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/src/main.cpp): `embedded/esp32/src/main.cpp`
- [Module Dispatcher](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/module_handler.cpp): `embedded/esp32/lib/module_handler/src/module_handler.cpp`
- [WiFi Module](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/wifi.cpp): `embedded/esp32/lib/module_handler/src/modules/wifi.cpp`
- [microSD Module](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/microsd.cpp): `embedded/esp32/lib/module_handler/src/modules/microsd.cpp`
- [User Config Module](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/wifi_userconfig.cpp): `embedded/esp32/lib/module_handler/src/modules/wifi_userconfig.cpp`
- [Irrigation Module](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/irrigation.cpp): `embedded/esp32/lib/module_handler/src/modules/irrigation.cpp`
- [Power Module](https://github.com/jlab-sensing/ents-tock/blob/main/embedded/esp32/lib/module_handler/src/modules/power.cpp): `embedded/esp32/lib/module_handler/src/modules/power.cpp`

### Message Protocol

- [Protobuf Messages](https://github.com/jlab-sensing/ents-tock/tree/main/proto): `proto`

### Python Utilities

- [ENTS CLI](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/cli.py): `python/src/ents/cli.py`
- [Measurement Encoder](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/proto/encode.py): `python/src/ents/proto/encode.py`
- [Sensor Protocol](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/proto/sensor.py): `python/src/ents/proto/sensor.py`
- [Node Simulator](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/simulator/node.py): `python/src/ents/simulator/node.py`
- [Calibration Recorder](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/calibrate/recorder.py): `python/src/ents/calibrate/recorder.py`
- [Calibration Plots](https://github.com/jlab-sensing/ents-tock/blob/main/python/src/ents/calibrate/plots.py): `python/src/ents/calibrate/plots.py`

### Other components

- **Operator**
- **Physical Sensors**
- **Dirtviz Service**
- **Source Measurement Unit**

## Connections

- Operator → Core App: runs firmware (evidence: `embedded/stm32/apps/core/main.cc`)
- Core App → Measurement FIFO: reads batches (evidence: `embedded/stm32/apps/core/main.cc`)
- Core App → LoRaWAN: uploads data (evidence: `embedded/stm32/apps/core/main.cc`)
- Physical Sensors → Sensor Drivers: provide readings
- Core App → ESP32 Controller: uses interface (evidence: `embedded/stm32/apps/core/main.cc`)
- ESP32 Controller → Controller Communication: uses buffers (evidence: `embedded/libents/src/libents/controller/controller.c`)
- ESP32 Startup → Module Dispatcher: registers modules (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → Module Dispatcher: routes I²C callbacks (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → WiFi Module: registers (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → microSD Module: registers (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → User Config Module: registers (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → Power Module: registers (evidence: `embedded/esp32/src/main.cpp`)
- ESP32 Startup → Irrigation Module: optional module (evidence: `embedded/esp32/src/main.cpp`)
- Operator → ENTS CLI: invokes commands (evidence: `python/src/ents/cli.py`)
- ENTS CLI → Measurement Encoder: encodes messages (evidence: `python/src/ents/cli.py`)
- ENTS CLI → Sensor Protocol: handles sensor data (evidence: `python/src/ents/cli.py`)
- ENTS CLI → Node Simulator: runs simulation (evidence: `python/src/ents/cli.py`)
- Node Simulator → Measurement Encoder: encodes readings (evidence: `python/src/ents/simulator/node.py`)
- Node Simulator → Dirtviz Service: posts uploads (evidence: `python/src/ents/simulator/node.py`)
- ENTS CLI → Calibration Recorder: records calibration (evidence: `python/src/ents/cli.py`)
- ENTS CLI → Calibration Plots: creates plots (evidence: `python/src/ents/cli.py`)
- Calibration Recorder → Source Measurement Unit: controls instrument (evidence: `python/src/ents/calibrate/recorder.py`)
- Measurement Encoder → Protobuf Messages: serializes messages
