# morgendagen/riden-dongle architecture

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

- Interactive diagram: https://gitdiagram.com/morgendagen/riden-dongle
- Repository: https://github.com/morgendagen/riden-dongle

## Overview

#### Purpose and deployment
Riden Dongle is ESP-12F/ESP8266 firmware replacing the stock Riden WiFi-module software. It bridges a Riden DC power supply’s UART Modbus RTU interface to LAN protocols: Modbus TCP, SCPI raw socket/VXI-11, and an embedded control/configuration web UI. PlatformIO builds the device firmware; the application entry point is `src/main.cpp`, with target configuration in `platformio.ini`.

#### Bootstrap and orchestration
`src/main.cpp` owns firmware lifecycle: hardware/network initialization, service startup, and periodic device-facing work. It composes the protocol, configuration, HTTP, and discovery/time capabilities rather than exposing a separate host application. Public component contracts are under `include/`, including `include/riden_config/riden_config.h` and `include/riden_modbus/riden_modbus.h`.

#### Device bus and canonical PSU access
`src/riden_modbus/riden_modbus.cpp` implements the Modbus RTU client that communicates with the physical Riden PSU over UART. Register definitions and device-model semantics are centralized in `include/riden_modbus/riden_modbus_registers.h`. This is the core hardware boundary: all remote protocols ultimately read/write PSU state through this layer, constrained by UART baud rate, Modbus address, and the PSU firmware’s register behavior.

#### Modbus TCP bridge
`src/riden_modbus_bridge/riden_modbus_bridge.cpp` translates inbound Modbus TCP requests into the local RTU/register operations. Its interface is `include/riden_modbus_bridge/riden_modbus_bridge.h`. This path preserves standard Modbus client compatibility while isolating network request handling from serial-device access.

#### SCPI and instrument transports
`src/riden_scpi/riden_scpi.cpp` maps SCPI commands and queries to PSU operations, with its public API in `include/riden_scpi/riden_scpi.h`; supported command surface is documented in `SCPI_COMMANDS.md`. `src/scpi_bridge/scpi_bridge.h` adapts transport input to that SCPI engine. Raw SCPI socket service and VXI-11 are mutually constrained at runtime: VXI-11 provides synchronous RPC-style instrument access, while raw socket supplies TCP port-5025 VISA compatibility.

#### VXI-11 RPC server
`src/vxi11_server/vxi_server.cpp` implements the VXI-11 instrument server, with RPC framing in `src/vxi11_server/rpc_packets.cpp` and port-mapper/binder behavior in `src/vxi11_server/rpc_bind_server.cpp`. This boundary exposes SCPI to VISA clients using `TCPIP::<host>::INSTR`, and participates in mDNS-based LAN discovery. The subsystem’s local design notes are in `src/vxi11_server/README.md`.

#### HTTP UI, configuration, and operations
`src/riden_http_server/riden_http_server.cpp` serves the embedded web interface for PSU status/control, graphs, device configuration, reboot actions, and OTA update flow. Static browser content is compiled into `src/riden_http_server/http_static.h`; source/mock UI artifacts live in `src/riden_http_server/html_content/`. HTTP routes invoke the same PSU/configuration services as the machine protocols, making the UI another client boundary rather than a separate control plane.

#### Persistent configuration and external services
`src/riden_config/riden_config.cpp` manages dongle settings such as timezone and UART configuration; timezone data is in `src/riden_config/timezones.h`. Runtime infrastructure includes ESP Wi-Fi provisioning via WiFiManager, IPv4 LAN connectivity, mDNS service advertising, NTP synchronization against `pool.ntp.org`, and OTA firmware delivery through the HTTP interface. The resulting clock/time configuration is propagated to the PSU through the Modbus access layer.

Main entry points: [`src/main.cpp`](https://github.com/morgendagen/riden-dongle/blob/main/src/main.cpp) (Firmware lifecycle), [`src/riden_modbus/riden_modbus.cpp`](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_modbus/riden_modbus.cpp) (Modbus RTU client), [`src/riden_http_server/riden_http_server.cpp`](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_http_server/riden_http_server.cpp) (HTTP control server), [`src/vxi11_server/vxi_server.cpp`](https://github.com/morgendagen/riden-dongle/blob/main/src/vxi11_server/vxi_server.cpp) (VXI-11 server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware core"]
  node_build["PlatformIO build<br/>build config<br/>[platformio.ini]"]
  node_main["Firmware lifecycle<br/>ESP8266 entry point<br/>[main.cpp]"]
  node_config["Persistent configuration<br/>settings service<br/>[riden_config.cpp]"]
end

subgraph group_device["PSU access"]
  node_modbus["Modbus RTU client<br/>UART device client<br/>[riden_modbus.cpp]"]
  node_registers["PSU register model<br/>register definitions"]
  node_psu{{"Riden DC power supply<br/>physical UART device"}}
end

subgraph group_protocols["LAN protocols"]
  node_modbus_tcp["Modbus TCP bridge<br/>TCP-to-RTU bridge"]
  node_modbus_clients(("Modbus TCP clients<br/>LAN clients"))
  node_scpi["SCPI command engine<br/>instrument command mapper<br/>[riden_scpi.cpp]"]
  node_raw_scpi["Raw SCPI socket<br/>TCP 5025 transport<br/>[scpi_bridge.h]"]
  node_vxi11["VXI-11 server<br/>RPC instrument server<br/>[vxi_server.cpp]"]
  node_vxi_rpc["VXI-11 RPC framing<br/>RPC protocol layer<br/>[rpc_packets.cpp]"]
  node_visa_clients(("VISA clients<br/>LAN instrument clients"))
end

subgraph group_operations["Web and infrastructure"]
  node_http["HTTP control server<br/>embedded web server"]
  node_web_ui["Embedded web UI<br/>compiled browser assets<br/>[http_static.h]"]
  node_browser(("Browser clients<br/>LAN clients"))
  node_lan_services["Wi-Fi, mDNS and NTP<br/>network infrastructure"]
end

node_build -->|"builds"| node_main
node_main -->|"initializes"| node_config
node_main -->|"runs"| node_modbus
node_main -->|"starts"| node_modbus_tcp
node_main -->|"starts"| node_raw_scpi
node_main -->|"starts"| node_vxi11
node_main -->|"starts"| node_http
node_main -->|"initializes"| node_lan_services
node_config -->|"applies UART/time settings"| node_modbus
node_modbus -->|"uses"| node_registers
node_modbus -->|"Modbus RTU over UART"| node_psu
node_modbus_clients -->|"Modbus TCP"| node_modbus_tcp
node_modbus_tcp -->|"register operations"| node_modbus
node_raw_scpi -->|"SCPI commands"| node_scpi
node_vxi11 -->|"uses"| node_vxi_rpc
node_vxi_rpc -->|"VXI-11 RPC"| node_visa_clients
node_vxi11 -->|"SCPI commands"| node_scpi
node_scpi -->|"PSU operations"| node_modbus
node_browser -->|"HTTP"| node_http
node_http -->|"serves"| node_web_ui
node_http -->|"configures"| node_config
node_http -->|"status and control"| node_modbus
node_lan_services -.->|"mDNS discovery"| node_vxi11
node_lan_services -.->|"propagates synchronized time"| node_modbus

click node_build "https://github.com/morgendagen/riden-dongle/blob/main/platformio.ini"
click node_main "https://github.com/morgendagen/riden-dongle/blob/main/src/main.cpp"
click node_config "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_config/riden_config.cpp"
click node_modbus "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_modbus/riden_modbus.cpp"
click node_registers "https://github.com/morgendagen/riden-dongle/blob/main/include/riden_modbus/riden_modbus_registers.h"
click node_modbus_tcp "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_modbus_bridge/riden_modbus_bridge.cpp"
click node_scpi "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_scpi/riden_scpi.cpp"
click node_raw_scpi "https://github.com/morgendagen/riden-dongle/blob/main/src/scpi_bridge/scpi_bridge.h"
click node_vxi11 "https://github.com/morgendagen/riden-dongle/blob/main/src/vxi11_server/vxi_server.cpp"
click node_vxi_rpc "https://github.com/morgendagen/riden-dongle/blob/main/src/vxi11_server/rpc_packets.cpp"
click node_http "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_http_server/riden_http_server.cpp"
click node_web_ui "https://github.com/morgendagen/riden-dongle/blob/main/src/riden_http_server/http_static.h"

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_build,node_main,node_config toneBlue
class node_modbus,node_registers,node_psu toneAmber
class node_modbus_tcp,node_modbus_clients,node_scpi,node_raw_scpi,node_vxi11,node_vxi_rpc,node_visa_clients toneMint
class node_http,node_web_ui,node_browser,node_lan_services toneRose
```

## Components

### Firmware core

- [PlatformIO build](https://github.com/morgendagen/riden-dongle/blob/main/platformio.ini): build config · Build target configuration. · `platformio.ini`
- [Firmware lifecycle](https://github.com/morgendagen/riden-dongle/blob/main/src/main.cpp): ESP8266 entry point · Initializes hardware/network services and runs periodic work. · `src/main.cpp`
- [Persistent configuration](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_config/riden_config.cpp): settings service · Stores timezone and UART settings. · `src/riden_config/riden_config.cpp`

### PSU access

- [Modbus RTU client](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_modbus/riden_modbus.cpp): UART device client · Canonical read/write access to the Riden PSU. · `src/riden_modbus/riden_modbus.cpp`
- [PSU register model](https://github.com/morgendagen/riden-dongle/blob/main/include/riden_modbus/riden_modbus_registers.h): register definitions · Centralizes register and device-model semantics. · `include/riden_modbus/riden_modbus_registers.h`
- **Riden DC power supply**: physical UART device

### LAN protocols

- [Modbus TCP bridge](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_modbus_bridge/riden_modbus_bridge.cpp): TCP-to-RTU bridge · Translates Modbus TCP requests into local register operations. · `src/riden_modbus_bridge/riden_modbus_bridge.cpp`
- **Modbus TCP clients**: LAN clients
- [SCPI command engine](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_scpi/riden_scpi.cpp): instrument command mapper · Maps SCPI commands and queries to PSU operations. · `src/riden_scpi/riden_scpi.cpp`
- [Raw SCPI socket](https://github.com/morgendagen/riden-dongle/blob/main/src/scpi_bridge/scpi_bridge.h): TCP 5025 transport · Provides VISA-compatible raw SCPI access. · `src/scpi_bridge/scpi_bridge.h`
- [VXI-11 server](https://github.com/morgendagen/riden-dongle/blob/main/src/vxi11_server/vxi_server.cpp): RPC instrument server · Exposes synchronous SCPI instrument access for VISA clients. · `src/vxi11_server/vxi_server.cpp`
- [VXI-11 RPC framing](https://github.com/morgendagen/riden-dongle/blob/main/src/vxi11_server/rpc_packets.cpp): RPC protocol layer · Handles RPC packets and port-mapper binding. · `src/vxi11_server/rpc_packets.cpp`
- **VISA clients**: LAN instrument clients

### Web and infrastructure

- [HTTP control server](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_http_server/riden_http_server.cpp): embedded web server · Serves status, control, configuration, reboot, and OTA routes. · `src/riden_http_server/riden_http_server.cpp`
- [Embedded web UI](https://github.com/morgendagen/riden-dongle/blob/main/src/riden_http_server/http_static.h): compiled browser assets · `src/riden_http_server/http_static.h`
- **Browser clients**: LAN clients
- **Wi-Fi, mDNS and NTP**: network infrastructure · Provides provisioning, LAN discovery, and clock synchronization.

## Connections

- PlatformIO build → Firmware lifecycle: builds
- Firmware lifecycle → Persistent configuration: initializes
- Firmware lifecycle → Modbus RTU client: runs
- Firmware lifecycle → Modbus TCP bridge: starts
- Firmware lifecycle → Raw SCPI socket: starts
- Firmware lifecycle → VXI-11 server: starts
- Firmware lifecycle → HTTP control server: starts
- Firmware lifecycle → Wi-Fi, mDNS and NTP: initializes
- Persistent configuration → Modbus RTU client: applies UART/time settings
- Modbus RTU client → PSU register model: uses
- Modbus RTU client → Riden DC power supply: Modbus RTU over UART
- Modbus TCP clients → Modbus TCP bridge: Modbus TCP
- Modbus TCP bridge → Modbus RTU client: register operations
- Raw SCPI socket → SCPI command engine: SCPI commands
- VXI-11 server → VXI-11 RPC framing: uses
- VXI-11 RPC framing → VISA clients: VXI-11 RPC
- VXI-11 server → SCPI command engine: SCPI commands
- SCPI command engine → Modbus RTU client: PSU operations
- Browser clients → HTTP control server: HTTP
- HTTP control server → Embedded web UI: serves
- HTTP control server → Persistent configuration: configures
- HTTP control server → Modbus RTU client: status and control
- Wi-Fi, mDNS and NTP → VXI-11 server: mDNS discovery
- Wi-Fi, mDNS and NTP → Modbus RTU client: propagates synchronized time