# aleksandrab83/dps_sim architecture

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

- Interactive diagram: https://gitdiagram.com/aleksandrab83/dps_sim
- Repository: https://github.com/aleksandrab83/dps_sim

## Overview

1. **What this repo is**
   - `dps_sim` is a two-part system for simulating a quadrature position sensor (“ДПС”).
   - One part is a **Python control server**; the other is **RP2040-ETH firmware** that generates the signals on GPIO.

2. **Primary control flow**
   - An operator or client sends `POST /frequency` to the Python server.
   - The server updates its current frequency state and broadcasts the new command to all connected MCU boards.
   - Boards apply the new settings without stopping signal generation.

3. **Server subsystem (`src/server`)**
   - `server.py` is the main runtime entry point.
   - It exposes a small HTTP API:
     - `GET /frequency` returns the current frequency.
     - `POST /frequency` updates frequency and returns how many boards were reached.
   - The server also acts as a fan-out point for multiple RP2040-ETH devices, maintaining one shared state and pushing JSON commands to each connected client.

4. **Board-to-server data exchange**
   - The server sends compact JSON messages with fields such as `frequency` and `direction`.
   - The README indicates the boards receive these over TCP, with CH9120 converting TCP to UART on the device side.
   - This makes the server the only control plane; the boards do not appear to expose a separate REST API.

5. **MCU firmware subsystem (`src/mcu`)**
   - `main.c` is the firmware entry point for RP2040-ETH.
   - `square_4ch.pio` contains the PIO program used to generate the waveforms.
   - The firmware’s role is to keep four output channels running continuously while updating frequency and direction from incoming commands.

6. **Signal-generation boundary**
   - The critical real-time work is isolated in the RP2040 PIO subsystem.
   - That boundary matters architecturally: the Python server only computes/control messages, while the MCU handles deterministic waveform timing in hardware-assisted code.
   - The generated outputs are quadrature pairs with 90° phase shift, used to emulate encoder-like A/B signals.

7. **Hardware / board integration**
   - The firmware is tied to RP2040-ETH board-specific peripherals and pin mapping.
   - The README calls out W5100S Ethernet on SPI1 and CH9120 as the network bridge.
   - GPIO allocation is fixed for the signal outputs, so the hardware mapping is part of the system architecture, not just implementation detail.

8. **Client/UI surface**
   - `src/client/index.html` is a lightweight client entry point, likely used to control or test the server from a browser.
   - The repo therefore has both a machine API surface (`/frequency`) and a simple human-facing control surface.

9. **Deployment packaging**
   - `etc/docker/` contains a Dockerfile, compose file, nginx config, and supervisord config.
   - This suggests the system can be containerized with a reverse proxy or process supervisor around the server/client components.
   - The Docker layer is a deployment boundary, not the core runtime logic.

10. **Testing and validation**
   - `src/server/tests/` contains pytest-based tests for the Python server.
   - `.github/workflows/server-tests.yml` runs server validation in CI.
   - `.github/workflows/mcu.yml` and `.github/workflows/docker.yml` indicate separate pipelines for firmware and container artifacts.

11. **Documentation and integration references**
   - `doc/` contains hardware diagrams and setup instructions, which are important because the repo couples software behavior with wiring and board-level constraints.
   - The docs are especially relevant for understanding pin mapping, power domains, and how the MCU connects to the external circuit.

12. **How to draw the architecture**
   - Model this repo as three layers:
     - **Control layer:** client/UI → Python server REST API
     - **Distribution layer:** server → multiple RP2040-ETH boards over TCP/JSON
     - **Execution layer:** MCU firmware + PIO + board/network hardware generating the 4-channel quadrature outputs
   - The main system boundary is between the server’s stateful control plane and the MCU’s real-time signal-generation plane.

Main entry points: [`src/server/server.py`](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py) (Server), [`src/mcu/main.c`](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c) (MCU main), [`etc/docker/docker-compose.yml`](https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/docker-compose.yml) (Docker stack), [`src/mcu/lib/CH9120/CH9120.c`](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/lib/CH9120/CH9120.c) (CH9120 link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_client_ui["Client UI<br/>browser client<br/>[index.html]"]
  node_server_main["Server<br/>Python app<br/>[server.py]"]
  node_server_tests["Server tests<br/>pytest suite<br/>[test_server.py]"]
  node_api_state(("API state<br/>frequency state<br/>[server.py]"))
  node_fanout["Fan-out<br/>broadcast layer<br/>[server.py]"]
  node_tcp_json["TCP JSON<br/>control protocol<br/>[server.py]"]
end

subgraph group_firmware["MCU firmware"]
  node_mcu_main["MCU main<br/>RP2040 firmware<br/>[main.c]"]
  node_pio_wave{{"PIO wavegen<br/>PIO program<br/>[square_4ch.pio]"}}
  node_board_io(("Board I/O<br/>GPIO mapping<br/>[main.c]"))
  node_net_bridge["CH9120 link<br/>uart bridge<br/>[CH9120.c]"]
  node_eth_hw["Ethernet HW<br/>board peripheral<br/>[main.c]"]
  node_ch9120_lib["CH9120 lib<br/>driver library<br/>[CH9120.c]"]
end

subgraph group_deployment["Deployment"]
  node_docker_stack["Docker stack<br/>container setup<br/>[docker-compose.yml]"]
  node_dockerfile["Image build<br/>dockerfile"]
  node_nginx_conf["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
  node_supervisord_conf["Supervisor<br/>process manager<br/>[supervisord.conf]"]
end

subgraph group_docs["Docs and CI"]
  node_workflows_server["Server CI<br/>github workflow<br/>[server-tests.yml]"]
  node_workflows_mcu["MCU CI<br/>github workflow<br/>[mcu.yml]"]
  node_workflows_docker["Docker CI<br/>github workflow<br/>[docker.yml]"]
  node_docs_hw["Hardware docs<br/>repo docs"]
end

node_client_ui -->|"HTTP control"| node_server_main
node_server_main -->|"reads/writes"| node_api_state
node_api_state -->|"triggers"| node_fanout
node_fanout -->|"encodes"| node_tcp_json
node_tcp_json -->|"TCP/UART"| node_net_bridge
node_server_main -.->|"validated by"| node_server_tests
node_server_main -->|"uses"| node_fanout
node_server_main -.->|"serves"| node_client_ui
node_mcu_main -->|"runs"| node_pio_wave
node_mcu_main -->|"maps"| node_board_io
node_mcu_main -->|"receives"| node_net_bridge
node_net_bridge -->|"implemented by"| node_ch9120_lib
node_eth_hw -->|"connects"| node_net_bridge
node_pio_wave -->|"drives"| node_board_io
node_server_main -->|"controls"| node_mcu_main
node_docker_stack -->|"builds"| node_dockerfile
node_docker_stack -->|"proxies"| node_nginx_conf
node_docker_stack -->|"supervises"| node_supervisord_conf
node_workflows_server -.->|"checks"| node_server_main
node_workflows_mcu -.->|"checks"| node_mcu_main
node_workflows_docker -.->|"checks"| node_docker_stack
node_docs_hw -.->|"documents"| node_mcu_main
node_docs_hw -.->|"documents"| node_board_io

click node_client_ui "https://github.com/aleksandrab83/dps_sim/blob/master/src/client/index.html"
click node_server_main "https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py"
click node_server_tests "https://github.com/aleksandrab83/dps_sim/blob/master/src/server/tests/test_server.py"
click node_api_state "https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py"
click node_fanout "https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py"
click node_tcp_json "https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py"
click node_mcu_main "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c"
click node_pio_wave "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/square_4ch.pio"
click node_board_io "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c"
click node_net_bridge "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/lib/CH9120/CH9120.c"
click node_eth_hw "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c"
click node_ch9120_lib "https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/lib/CH9120/CH9120.c"
click node_docker_stack "https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/docker-compose.yml"
click node_dockerfile "https://github.com/aleksandrab83/dps_sim/tree/master/etc/docker/Dockerfile"
click node_nginx_conf "https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/nginx.conf"
click node_supervisord_conf "https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/supervisord.conf"
click node_workflows_server "https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/server-tests.yml"
click node_workflows_mcu "https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/mcu.yml"
click node_workflows_docker "https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/docker.yml"
click node_docs_hw "https://github.com/aleksandrab83/dps_sim/blob/master/doc/Принцип работы устройста.md"

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_client_ui,node_server_main,node_server_tests,node_api_state,node_fanout,node_tcp_json toneBlue
class node_mcu_main,node_pio_wave,node_board_io,node_net_bridge,node_eth_hw,node_ch9120_lib toneAmber
class node_docker_stack,node_dockerfile,node_nginx_conf,node_supervisord_conf toneMint
class node_workflows_server,node_workflows_mcu,node_workflows_docker,node_docs_hw toneRose
```

## Components

### Control plane

Browser and Python server that accept frequency commands and fan them out to boards.

- [Client UI](https://github.com/aleksandrab83/dps_sim/blob/master/src/client/index.html): browser client · Lightweight human-facing control surface for the server. · `src/client/index.html`
- [Server](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py): Python app · Main HTTP control-plane runtime and fan-out coordinator. · `src/server/server.py`
- [Server tests](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/tests/test_server.py): pytest suite · Validation for the Python control API and command flow. · `src/server/tests/test_server.py`
- [API state](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py): frequency state · Shared current frequency and request handling for GET/POST /frequency. · `src/server/server.py`
- [Fan-out](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py): broadcast layer · Pushes JSON command updates to all connected RP2040-ETH boards. · `src/server/server.py`
- [TCP JSON](https://github.com/aleksandrab83/dps_sim/blob/master/src/server/server.py): control protocol · Compact command messages carrying fields like frequency and direction. · `src/server/server.py`

### MCU firmware

RP2040-ETH code that receives commands and generates quadrature outputs.

- [MCU main](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c): RP2040 firmware · Firmware entry point for the board runtime. · `src/mcu/main.c`
- [PIO wavegen](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/square_4ch.pio): PIO program · Hardware-assisted waveform generation for four continuous channels. · `src/mcu/square_4ch.pio`
- [Board I/O](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c): GPIO mapping · Fixed pin assignment and board-specific signal wiring. · `src/mcu/main.c`
- [CH9120 link](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/lib/CH9120/CH9120.c): uart bridge · TCP-to-UART bridge used for board command ingress. · `src/mcu/lib/CH9120/CH9120.c`
- [Ethernet HW](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/main.c): board peripheral · RP2040-ETH networking and SPI-connected Ethernet hardware. · `src/mcu/main.c`
- [CH9120 lib](https://github.com/aleksandrab83/dps_sim/blob/master/src/mcu/lib/CH9120/CH9120.c): driver library · Support code for the CH9120 network bridge. · `src/mcu/lib/CH9120/CH9120.c`

### Deployment

Containerization and process supervision for running the system.

- [Docker stack](https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/docker-compose.yml): container setup · Containerization and supervisor-based runtime packaging. · `etc/docker/docker-compose.yml`
- [Image build](https://github.com/aleksandrab83/dps_sim/tree/master/etc/docker/Dockerfile): dockerfile · Build definition for the packaged environment. · `etc/docker/Dockerfile`
- [Nginx](https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/nginx.conf): reverse proxy · HTTP front end or proxy configuration for the packaged system. · `etc/docker/nginx.conf`
- [Supervisor](https://github.com/aleksandrab83/dps_sim/blob/master/etc/docker/supervisord.conf): process manager · Process supervision configuration for containerized components. · `etc/docker/supervisord.conf`

### Docs and CI

Reference material and automation that validate and explain the system.

- [Server CI](https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/server-tests.yml): github workflow · CI pipeline for Python server validation. · `.github/workflows/server-tests.yml`
- [MCU CI](https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/mcu.yml): github workflow · CI pipeline for firmware build or validation. · `.github/workflows/mcu.yml`
- [Docker CI](https://github.com/aleksandrab83/dps_sim/blob/master/.github/workflows/docker.yml): github workflow · CI pipeline for container artifact validation. · `.github/workflows/docker.yml`
- [Hardware docs](https://github.com/aleksandrab83/dps_sim/blob/HEAD/doc/%D0%9F%D1%80%D0%B8%D0%BD%D1%86%D0%B8%D0%BF%20%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B%20%D1%83%D1%81%D1%82%D1%80%D0%BE%D0%B9%D1%81%D1%82%D0%B0.md): repo docs · Setup, wiring, and board behavior documentation. · `doc/Принцип работы устройста.md`

## Connections

- Client UI → Server: HTTP control · Browser client sends frequency commands to the server.
- Server → API state: reads/writes · Server exposes and updates the current frequency state.
- API state → Fan-out: triggers · Frequency updates are broadcast to connected boards.
- Fan-out → TCP JSON: encodes · Commands are sent as compact JSON messages.
- TCP JSON → CH9120 link: TCP/UART · Boards receive commands over the network bridge path.
- Server → Server tests: validated by · Server behavior is covered by pytest tests.
- Server → Fan-out: uses · Main runtime coordinates board broadcasts.
- Server → Client UI: serves · The server supports a lightweight browser client surface.
- MCU main → PIO wavegen: runs · Firmware configures the PIO waveform engine.
- MCU main → Board I/O: maps · Firmware assigns outputs to board GPIO pins.
- MCU main → CH9120 link: receives · Incoming control commands arrive through the bridge.
- CH9120 link → CH9120 lib: implemented by · Bridge behavior is supported by the CH9120 driver library.
- Ethernet HW → CH9120 link: connects · Board networking hardware provides the control ingress path.
- PIO wavegen → Board I/O: drives · PIO timing produces the quadrature outputs on fixed pins.
- Server → MCU main: controls · Python control plane drives the MCU signal-generation plane.
- Docker stack → Image build: builds · Container stack is assembled from the Docker image definition.
- Docker stack → Nginx: proxies · Nginx front end is part of the packaged deployment.
- Docker stack → Supervisor: supervises · Supervisor coordinates processes in the container layer.
- Server CI → Server: checks · CI validates the Python server subsystem.
- MCU CI → MCU main: checks · CI validates the firmware subsystem.
- Docker CI → Docker stack: checks · CI validates the containerized deployment layer.
- Hardware docs → MCU main: documents · Docs explain board wiring and firmware integration.
- Hardware docs → Board I/O: documents · Hardware docs cover GPIO mapping and signal layout.
