# djwinter29-oss/picouart architecture

> Architecture diagram of the GitHub repository djwinter29-oss/picouart, 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/djwinter29-oss/picouart
- Repository: https://github.com/djwinter29-oss/picouart

## Overview

PicoUart is RP2040/RP2350 firmware that presents six USB CDC serial ports and a HID status/control interface, bridging each CDC port to a UART channel. Startup initializes board services and UART before polling CDC and HID; UART work runs on a worker loop. The README documents two hardware-UART and four PIO-UART channels, DMA-backed paths, line-coding limits, and host monitoring. Edges reflect the startup excerpt, source-index references, or README; unsampled internals are not assumed.

Main entry points: [`firmware/src/usb/usb_hid.c`](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_hid.c) (HID monitor), [`firmware/src/main.c`](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/main.c) (Firmware loop), [`firmware/src/usb/usb_cdc.c`](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_cdc.c) (CDC ACM), [`firmware/src/uart/uart_driver.c`](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/uart_driver.c) (Logical UART ports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_usb["USB interfaces"]
  node_cdc["CDC ACM<br/>[usb_cdc.c]"]
  node_hid["HID monitor<br/>[usb_hid.c]"]
  node_descriptors["USB descriptors<br/>[usb_descriptors.c]"]
  node_python["Python HID tool<br/>[pico_uart_hid.py]"]
end

subgraph group_routing["UART routing"]
  node_uart["Logical UART ports<br/>[uart_driver.c]"]
  node_control["Control plane<br/>[plane.c]"]
  node_line["Line coding<br/>[line_coding.h]"]
  node_rings["Ring buffers<br/>[ring_buffer.c]"]
  node_worker["UART worker<br/>[worker.c]"]
end

subgraph group_backends["UART backends"]
  node_adapter["Backend adapter<br/>[adapter.c]"]
  node_hw["Hardware UART<br/>[hw_uart_driver.c]"]
  node_pio["PIO UART<br/>[pio_uart_driver.c]"]
end

subgraph group_board["Board services"]
  node_main["Firmware loop<br/>[main.c]"]
  node_topology["UART topology<br/>[uart_topology.c]"]
  node_board["Board UART setup<br/>[uart_board.c]"]
  node_system["System services<br/>[system.c]"]
  node_temperature["Temperature<br/>[temperature.c]"]
  node_led["LED service<br/>[led.c]"]
end

node_host(("Host PC"))

node_host -->|"opens ports"| node_cdc
node_host -->|"reads status"| node_hid
node_main -->|"validates topology"| node_board
node_main -->|"initializes"| node_uart
node_main -->|"initializes, polls"| node_cdc
node_main -->|"initializes, polls"| node_hid
node_main -->|"initializes"| node_system
node_main -->|"initializes"| node_temperature
node_main -->|"initializes"| node_led
node_cdc -->|"routes serial data"| node_uart
node_cdc -->|"parses requests"| node_line
node_cdc -->|"reports health"| node_hid
node_hid -->|"reads port status"| node_uart
node_hid -->|"reads status"| node_system
node_hid -->|"reads temperature"| node_temperature
node_hid -->|"uses LED status"| node_led
node_python -->|"monitors, controls"| node_hid
node_board -->|"configures ports"| node_topology
node_adapter -->|"dispatches"| node_hw
node_adapter -->|"dispatches"| node_pio
node_uart -->|"buffers port data"| node_rings
node_hw -->|"publishes DMA data"| node_rings
node_pio -->|"publishes DMA data"| node_rings
node_worker -.->|"services control"| node_control
node_worker -.->|"polls I/O"| node_uart
node_descriptors -.->|"defines interfaces"| node_host

click node_main "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/main.c"
click node_cdc "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_cdc.c"
click node_hid "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_hid.c"
click node_descriptors "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_descriptors.c"
click node_uart "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/uart_driver.c"
click node_control "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/control/plane.c"
click node_line "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/line_coding.h"
click node_rings "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/ring_buffer/ring_buffer.c"
click node_worker "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/worker.c"
click node_adapter "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/backend/adapter.c"
click node_hw "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/hw/hw_uart_driver.c"
click node_pio "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/pio/pio_uart_driver.c"
click node_topology "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/board/uart_topology.c"
click node_board "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/board/uart_board.c"
click node_system "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/system.c"
click node_temperature "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/temperature.c"
click node_led "https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/led.c"
click node_python "https://github.com/djwinter29-oss/picouart/blob/main/host/python/src/pico_uart_hid.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_cdc,node_hid,node_descriptors,node_python toneBlue
class node_uart,node_control,node_line,node_rings,node_worker toneAmber
class node_adapter,node_hw,node_pio toneMint
class node_main,node_topology,node_board,node_system,node_temperature,node_led toneRose
class node_host toneIndigo
```

## Components

### USB interfaces

- [CDC ACM](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_cdc.c): `firmware/src/usb/usb_cdc.c`
- [HID monitor](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_hid.c): `firmware/src/usb/usb_hid.c`
- [USB descriptors](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/usb/usb_descriptors.c): `firmware/src/usb/usb_descriptors.c`
- [Python HID tool](https://github.com/djwinter29-oss/picouart/blob/main/host/python/src/pico_uart_hid.py): `host/python/src/pico_uart_hid.py`

### UART routing

- [Logical UART ports](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/uart_driver.c): `firmware/src/uart/uart_driver.c`
- [Control plane](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/control/plane.c): `firmware/src/uart/control/plane.c`
- [Line coding](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/line_coding.h): `firmware/src/uart/line_coding.h`
- [Ring buffers](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/ring_buffer/ring_buffer.c): `firmware/src/uart/ring_buffer/ring_buffer.c`
- [UART worker](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/worker.c): `firmware/src/uart/worker.c`

### UART backends

- [Backend adapter](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/backend/adapter.c): `firmware/src/uart/backend/adapter.c`
- [Hardware UART](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/hw/hw_uart_driver.c): `firmware/src/uart/hw/hw_uart_driver.c`
- [PIO UART](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/uart/pio/pio_uart_driver.c): `firmware/src/uart/pio/pio_uart_driver.c`

### Board services

- [Firmware loop](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/main.c): `firmware/src/main.c`
- [UART topology](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/board/uart_topology.c): `firmware/src/board/uart_topology.c`
- [Board UART setup](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/board/uart_board.c): `firmware/src/board/uart_board.c`
- [System services](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/system.c): `firmware/src/driver/system.c`
- [Temperature](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/temperature.c): `firmware/src/driver/temperature.c`
- [LED service](https://github.com/djwinter29-oss/picouart/blob/main/firmware/src/driver/led.c): `firmware/src/driver/led.c`

### Other components

- **Host PC**

## Connections

- Host PC → CDC ACM: opens ports
- Host PC → HID monitor: reads status
- Firmware loop → Board UART setup: validates topology (evidence: `firmware/src/main.c`)
- Firmware loop → Logical UART ports: initializes (evidence: `firmware/src/main.c`)
- Firmware loop → CDC ACM: initializes, polls (evidence: `firmware/src/main.c`)
- Firmware loop → HID monitor: initializes, polls (evidence: `firmware/src/main.c`)
- Firmware loop → System services: initializes (evidence: `firmware/src/main.c`)
- Firmware loop → Temperature: initializes (evidence: `firmware/src/main.c`)
- Firmware loop → LED service: initializes (evidence: `firmware/src/main.c`)
- CDC ACM → Logical UART ports: routes serial data
- CDC ACM → Line coding: parses requests (evidence: `firmware/src/usb/usb_cdc.c`)
- CDC ACM → HID monitor: reports health (evidence: `firmware/src/usb/usb_cdc.c`)
- HID monitor → Logical UART ports: reads port status (evidence: `firmware/src/usb/usb_hid.c`)
- HID monitor → System services: reads status (evidence: `firmware/src/usb/usb_hid.c`)
- HID monitor → Temperature: reads temperature (evidence: `firmware/src/usb/usb_hid.c`)
- HID monitor → LED service: uses LED status (evidence: `firmware/src/usb/usb_hid.c`)
- Python HID tool → HID monitor: monitors, controls
- Board UART setup → UART topology: configures ports (evidence: `firmware/src/board/uart_board.c`)
- Backend adapter → Hardware UART: dispatches (evidence: `firmware/src/uart/backend/adapter.c`)
- Backend adapter → PIO UART: dispatches (evidence: `firmware/src/uart/backend/adapter.c`)
- Logical UART ports → Ring buffers: buffers port data
- Hardware UART → Ring buffers: publishes DMA data
- PIO UART → Ring buffers: publishes DMA data (evidence: `firmware/src/uart/pio/pio_uart_driver.c`)
- UART worker → Control plane: services control
- UART worker → Logical UART ports: polls I/O
- USB descriptors → Host PC: defines interfaces
