How aleksandrab83/dps_sim works
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: server.py Server · main.c MCU main · docker-compose.yml Docker stack · CH9120.c CH9120 link
Components 20
Control plane
Browser and Python server that accept frequency commands and fan them out to boards.
- Client UI · Lightweight human-facing control surface for the server.
src/client/index.html - Server · Main HTTP control-plane runtime and fan-out coordinator.
src/server/server.py - Server tests · Validation for the Python control API and command flow.
src/server/tests/test_server.py - API state · Shared current frequency and request handling for GET/POST /frequency.
src/server/server.py - Fan-out · Pushes JSON command updates to all connected RP2040-ETH boards.
src/server/server.py - TCP JSON · 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 · Firmware entry point for the board runtime.
src/mcu/main.c - PIO wavegen · Hardware-assisted waveform generation for four continuous channels.
src/mcu/square_4ch.pio - Board I/O · Fixed pin assignment and board-specific signal wiring.
src/mcu/main.c - CH9120 link · TCP-to-UART bridge used for board command ingress.
src/mcu/lib/CH9120/CH9120.c - Ethernet HW · RP2040-ETH networking and SPI-connected Ethernet hardware.
src/mcu/main.c - CH9120 lib · Support code for the CH9120 network bridge.
src/mcu/lib/CH9120/CH9120.c
Deployment
Containerization and process supervision for running the system.
- Docker stack · Containerization and supervisor-based runtime packaging.
etc/docker/docker-compose.yml - Image build · Build definition for the packaged environment.
etc/docker/Dockerfile - Nginx · HTTP front end or proxy configuration for the packaged system.
etc/docker/nginx.conf - Supervisor · 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 · CI pipeline for Python server validation.
.github/workflows/server-tests.yml - MCU CI · CI pipeline for firmware build or validation.
.github/workflows/mcu.yml - Docker CI · CI pipeline for container artifact validation.
.github/workflows/docker.yml - Hardware docs · Setup, wiring, and board behavior documentation.
doc/Принцип работы устройста.md
Connections 23
- 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.