# robbertjv/poollab2.0_gateway architecture

> Architecture diagram of the GitHub repository robbertjv/poollab2.0_gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robbertjv/poollab2.0_gateway
- Repository: https://github.com/robbertjv/poollab2.0_gateway

## Overview

This firmware provisions Wi-Fi and MQTT settings, connects to an MQTT broker, discovers and synchronizes a PoolLab 2.0 over BLE, then publishes gateway/device status, sources, and measurements as JSON. MQTT commands can request synchronization or clear measurements. The main firmware excerpt shows orchestration and publication, while the README documents several capabilities whose detailed implementation is in omitted portions of that file; library call relationships are supported by its API and SOURCE INDEX references.

Main entry points: [`src/main.cpp`](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp) (Gateway orchestration), [`lib/PoolLab/src/poollab/commands`](https://github.com/robbertjv/poollab2.0_gateway/tree/main/lib/PoolLab/src/poollab/commands) (Device commands), [`lib/PoolLab/src/poollab/protocol/PoolLabProtocol.cpp`](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabProtocol.cpp) (Command protocol), [`lib/PoolLab/src/PoolLab.cpp`](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/PoolLab.cpp) (PoolLab facade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway firmware"]
  node_main_firmware["Gateway orchestration<br/>[main.cpp]"]
  node_portal["Wi-Fi setup portal<br/>[main.cpp]"]
  node_preferences[("Persistent settings<br/>[main.cpp]")]
  node_network_time["NTP time sync<br/>[main.cpp]"]
  node_mqtt_pub["MQTT JSON publications<br/>[main.cpp]"]
  node_mqtt_commands["MQTT remote commands<br/>[main.cpp]"]
end

subgraph group_poollab_api["PoolLab API"]
  node_pool_api["PoolLab facade<br/>[PoolLab.cpp]"]
  node_device_commands["Device commands"]
end

subgraph group_ble_protocol["BLE and protocol"]
  node_transport["BLE transport"]
  node_protocol["Command protocol"]
  node_command_defs["Command definitions"]
  node_response_types["Protocol responses<br/>[PoolLabResponse.h]"]
end

subgraph group_interpretation["Parsing and domain"]
  node_measurement_parser["Measurement parser"]
  node_source_parser["Source parser<br/>[SourceParser.cpp]"]
  node_quick_parser["Quick-info parser"]
  node_datetime_parser["Date-time parser<br/>[DateTimeParser.h]"]
  node_parameter_registry["Parameter registry"]
  node_parameter_data["Parameter catalog"]
  node_time_utils["Time utilities<br/>[TimeUtils.cpp]"]
end

node_operator(("Installer / operator"))
node_broker(("MQTT broker"))
node_pool_device(("PoolLab 2.0"))

node_operator -->|"configures"| node_portal
node_portal -->|"stores settings"| node_preferences
node_main_firmware -->|"starts portal"| node_portal
node_main_firmware -.->|"synchronizes time"| node_network_time
node_main_firmware -->|"connects MQTT"| node_broker
node_broker -->|"delivers commands"| node_mqtt_commands
node_mqtt_commands -.->|"requests sync"| node_main_firmware
node_main_firmware -->|"synchronizes device"| node_pool_api
node_main_firmware -->|"publishes records"| node_mqtt_pub
node_mqtt_pub -->|"publishes JSON"| node_broker
node_main_firmware -->|"rediscovers device"| node_pool_device
node_pool_api -->|"dispatches operations"| node_device_commands
node_device_commands -->|"executes commands"| node_protocol
node_protocol -->|"transfers frames"| node_transport
node_transport -->|"communicates BLE"| node_pool_device
node_device_commands -->|"parses records"| node_measurement_parser
node_device_commands -->|"parses sources"| node_source_parser
node_device_commands -.->|"parses quick info"| node_quick_parser
node_device_commands -->|"parses timestamps"| node_datetime_parser
node_device_commands -.->|"enriches readings"| node_parameter_registry
node_parameter_registry -->|"loads catalog"| node_parameter_data
node_main_firmware -->|"uses time helpers"| node_time_utils
node_protocol -->|"validates commands"| node_command_defs
node_protocol -->|"builds responses"| node_response_types

click node_main_firmware "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_portal "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_preferences "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_network_time "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_mqtt_pub "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_mqtt_commands "https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp"
click node_pool_api "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/PoolLab.cpp"
click node_device_commands "https://github.com/robbertjv/poollab2.0_gateway/tree/main/lib/PoolLab/src/poollab/commands"
click node_transport "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/transport/PoolLabBLETransport.cpp"
click node_protocol "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabProtocol.cpp"
click node_command_defs "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabCommandDef.h"
click node_response_types "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabResponse.h"
click node_measurement_parser "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/MeasurementParser.cpp"
click node_source_parser "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/SourceParser.cpp"
click node_quick_parser "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/QuickInfoParser.cpp"
click node_datetime_parser "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/DateTimeParser.h"
click node_parameter_registry "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parameters/PoolLabParameterRegistry.cpp"
click node_parameter_data "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parameters/PoolLabParameterData.h"
click node_time_utils "https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/util/TimeUtils.cpp"

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_main_firmware,node_portal,node_preferences,node_network_time,node_mqtt_pub,node_mqtt_commands toneBlue
class node_pool_api,node_device_commands toneAmber
class node_transport,node_protocol,node_command_defs,node_response_types toneMint
class node_measurement_parser,node_source_parser,node_quick_parser,node_datetime_parser,node_parameter_registry,node_parameter_data,node_time_utils toneRose
class node_operator,node_broker,node_pool_device toneIndigo
```

## Components

### Gateway firmware

- [Gateway orchestration](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`
- [Wi-Fi setup portal](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`
- [Persistent settings](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`
- [NTP time sync](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`
- [MQTT JSON publications](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`
- [MQTT remote commands](https://github.com/robbertjv/poollab2.0_gateway/blob/main/src/main.cpp): `src/main.cpp`

### PoolLab API

- [PoolLab facade](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/PoolLab.cpp): `lib/PoolLab/src/PoolLab.cpp`
- [Device commands](https://github.com/robbertjv/poollab2.0_gateway/tree/main/lib/PoolLab/src/poollab/commands): `lib/PoolLab/src/poollab/commands`

### BLE and protocol

- [BLE transport](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/transport/PoolLabBLETransport.cpp): `lib/PoolLab/src/poollab/transport/PoolLabBLETransport.cpp`
- [Command protocol](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabProtocol.cpp): `lib/PoolLab/src/poollab/protocol/PoolLabProtocol.cpp`
- [Command definitions](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabCommandDef.h): `lib/PoolLab/src/poollab/protocol/PoolLabCommandDef.h`
- [Protocol responses](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/protocol/PoolLabResponse.h): `lib/PoolLab/src/poollab/protocol/PoolLabResponse.h`

### Parsing and domain

- [Measurement parser](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/MeasurementParser.cpp): `lib/PoolLab/src/poollab/parsers/MeasurementParser.cpp`
- [Source parser](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/SourceParser.cpp): `lib/PoolLab/src/poollab/parsers/SourceParser.cpp`
- [Quick-info parser](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/QuickInfoParser.cpp): `lib/PoolLab/src/poollab/parsers/QuickInfoParser.cpp`
- [Date-time parser](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parsers/DateTimeParser.h): `lib/PoolLab/src/poollab/parsers/DateTimeParser.h`
- [Parameter registry](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parameters/PoolLabParameterRegistry.cpp): `lib/PoolLab/src/poollab/parameters/PoolLabParameterRegistry.cpp`
- [Parameter catalog](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/parameters/PoolLabParameterData.h): `lib/PoolLab/src/poollab/parameters/PoolLabParameterData.h`
- [Time utilities](https://github.com/robbertjv/poollab2.0_gateway/blob/main/lib/PoolLab/src/poollab/util/TimeUtils.cpp): `lib/PoolLab/src/poollab/util/TimeUtils.cpp`

### Other components

- **Installer / operator**
- **MQTT broker**
- **PoolLab 2.0**

## Connections

- Installer / operator → Wi-Fi setup portal: configures (evidence: `README.md`)
- Wi-Fi setup portal → Persistent settings: stores settings (evidence: `README.md`)
- Gateway orchestration → Wi-Fi setup portal: starts portal (evidence: `src/main.cpp`)
- Gateway orchestration → NTP time sync: synchronizes time (evidence: `src/main.cpp`)
- Gateway orchestration → MQTT broker: connects MQTT (evidence: `README.md`)
- MQTT broker → MQTT remote commands: delivers commands (evidence: `README.md`)
- MQTT remote commands → Gateway orchestration: requests sync (evidence: `src/main.cpp`)
- Gateway orchestration → PoolLab facade: synchronizes device (evidence: `src/main.cpp`)
- Gateway orchestration → MQTT JSON publications: publishes records (evidence: `src/main.cpp`)
- MQTT JSON publications → MQTT broker: publishes JSON (evidence: `src/main.cpp`)
- Gateway orchestration → PoolLab 2.0: rediscovers device (evidence: `README.md`)
- PoolLab facade → Device commands: dispatches operations
- Device commands → Command protocol: executes commands (evidence: `lib/PoolLab/src/poollab/commands/MeasurementsCommand.cpp`)
- Command protocol → BLE transport: transfers frames
- BLE transport → PoolLab 2.0: communicates BLE (evidence: `README.md`)
- Device commands → Measurement parser: parses records (evidence: `lib/PoolLab/src/poollab/commands/MeasurementsCommand.cpp`)
- Device commands → Source parser: parses sources (evidence: `lib/PoolLab/src/poollab/commands/SourcesCommand.cpp`)
- Device commands → Quick-info parser: parses quick info
- Device commands → Date-time parser: parses timestamps (evidence: `lib/PoolLab/src/poollab/commands/DateTimeCommand.cpp`)
- Device commands → Parameter registry: enriches readings
- Parameter registry → Parameter catalog: loads catalog (evidence: `lib/PoolLab/src/poollab/parameters/PoolLabParameterRegistry.cpp`)
- Gateway orchestration → Time utilities: uses time helpers (evidence: `src/main.cpp`)
- Command protocol → Command definitions: validates commands
- Command protocol → Protocol responses: builds responses
