# r2axz/bluepill-serial-monster architecture

> Architecture diagram of the GitHub repository r2axz/bluepill-serial-monster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r2axz/bluepill-serial-monster
- Repository: https://github.com/r2axz/bluepill-serial-monster

## Overview

This firmware turns an STM32 Blue Pill into a three-port USB-to-serial adapter. The principal workflow carries host CDC traffic through USB endpoints to three UARTs, with configurable serial formats and control signals; a built-in shell configures and saves device settings. The graph includes the USB protocol stack, device configuration, GPIO, and system support. Some subsystems are represented from README claims and the source index; unsampled implementation details and unverified links are omitted.

Main entry points: [`usb_core.c`](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_core.c) (USB control core), [`usb_cdc.c`](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_cdc.c) (CDC serial bridge), [`main.c`](https://github.com/r2axz/bluepill-serial-monster/blob/main/main.c) (Firmware entry), [`cdc_shell.c`](https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_shell.c) (Configuration shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_usb["USB device"]
  node_usb_core["USB control core<br/>[usb_core.c]"]
  node_usb_io["USB endpoint I/O<br/>[usb_io.c]"]
  node_usb_descriptors["CDC descriptors<br/>[usb_descriptors.c]"]
  node_usb_std["USB definitions<br/>[usb_std.h]"]
  node_usb_uid["USB identity<br/>[usb_uid.c]"]
  node_usb_panic["USB fault handling<br/>[usb_panic.c]"]
end

subgraph group_serial["Serial ports"]
  node_usb_cdc["CDC serial bridge<br/>[usb_cdc.c]"]
  node_cdc_types["CDC interface types<br/>[usb_cdc.h]"]
  node_circ_buf["Circular buffers<br/>[circ_buf.h]"]
  node_uart_hardware["Three UARTs"]
end

subgraph group_config["Configuration"]
  node_shell["Configuration shell<br/>[cdc_shell.c]"]
  node_shell_api["Shell interface<br/>[cdc_shell.h]"]
  node_cdc_config["CDC pin config<br/>[cdc_config.h]"]
  node_device_config[("Device settings<br/>[device_config.c]")]
  node_device_config_api["Settings interface<br/>[device_config.h]"]
end

subgraph group_platform["Board support"]
  node_firmware["Firmware entry<br/>[main.c]"]
  node_gpio["GPIO pins<br/>[gpio.c]"]
  node_status_led["Status LED<br/>[status_led.c]"]
  node_clock["System clock<br/>[system_clock.c]"]
  node_interrupts["Interrupt setup"]
end

node_host(("USB host"))

node_host -->|"issues USB requests"| node_usb_core
node_usb_core -->|"uses endpoint I/O"| node_usb_io
node_usb_core -->|"serves descriptors"| node_usb_descriptors
node_usb_core -->|"dispatches CDC requests"| node_usb_cdc
node_usb_core -->|"gets serial identity"| node_usb_uid
node_usb_core -->|"signals fatal errors"| node_usb_panic
node_usb_descriptors -->|"defines CDC interfaces"| node_cdc_types
node_usb_cdc -->|"transfers endpoint data"| node_usb_io
node_usb_cdc -->|"buffers serial data"| node_circ_buf
node_usb_cdc -->|"configures UART DMA"| node_uart_hardware
node_usb_cdc -->|"drives control pins"| node_gpio
node_usb_cdc -->|"uses config port shell"| node_shell
node_shell -->|"saves or resets"| node_device_config
node_shell -->|"reconfigures serial ports"| node_usb_cdc
node_shell -->|"edits pin settings"| node_cdc_config
node_device_config -->|"stores pin settings"| node_gpio
node_firmware -->|"initializes"| node_clock
node_firmware -->|"initializes"| node_interrupts
node_firmware -->|"initializes"| node_device_config
node_firmware -->|"initializes"| node_status_led
node_firmware -->|"starts USB device"| node_usb_core
node_status_led -->|"controls LED pin"| node_gpio

click node_firmware "https://github.com/r2axz/bluepill-serial-monster/blob/main/main.c"
click node_usb_core "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_core.c"
click node_usb_io "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_io.c"
click node_usb_descriptors "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_descriptors.c"
click node_usb_std "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_std.h"
click node_usb_cdc "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_cdc.c"
click node_cdc_types "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_cdc.h"
click node_circ_buf "https://github.com/r2axz/bluepill-serial-monster/blob/main/circ_buf.h"
click node_gpio "https://github.com/r2axz/bluepill-serial-monster/blob/main/gpio.c"
click node_shell "https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_shell.c"
click node_shell_api "https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_shell.h"
click node_cdc_config "https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_config.h"
click node_device_config "https://github.com/r2axz/bluepill-serial-monster/blob/main/device_config.c"
click node_device_config_api "https://github.com/r2axz/bluepill-serial-monster/blob/main/device_config.h"
click node_status_led "https://github.com/r2axz/bluepill-serial-monster/blob/main/status_led.c"
click node_clock "https://github.com/r2axz/bluepill-serial-monster/blob/main/system_clock.c"
click node_interrupts "https://github.com/r2axz/bluepill-serial-monster/blob/main/system_interrupts.c"
click node_usb_uid "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_uid.c"
click node_usb_panic "https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_panic.c"

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_usb_core,node_usb_io,node_usb_descriptors,node_usb_std,node_usb_uid,node_usb_panic toneBlue
class node_usb_cdc,node_cdc_types,node_circ_buf,node_uart_hardware toneAmber
class node_shell,node_shell_api,node_cdc_config,node_device_config,node_device_config_api toneMint
class node_firmware,node_gpio,node_status_led,node_clock,node_interrupts toneRose
class node_host toneIndigo
```

## Components

### USB device

- [USB control core](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_core.c): `usb_core.c`
- [USB endpoint I/O](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_io.c): `usb_io.c`
- [CDC descriptors](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_descriptors.c): `usb_descriptors.c`
- [USB definitions](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_std.h): `usb_std.h`
- [USB identity](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_uid.c): `usb_uid.c`
- [USB fault handling](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_panic.c): `usb_panic.c`

### Serial ports

- [CDC serial bridge](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_cdc.c): `usb_cdc.c`
- [CDC interface types](https://github.com/r2axz/bluepill-serial-monster/blob/main/usb_cdc.h): `usb_cdc.h`
- [Circular buffers](https://github.com/r2axz/bluepill-serial-monster/blob/main/circ_buf.h): `circ_buf.h`
- **Three UARTs**

### Configuration

- [Configuration shell](https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_shell.c): `cdc_shell.c`
- [Shell interface](https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_shell.h): `cdc_shell.h`
- [CDC pin config](https://github.com/r2axz/bluepill-serial-monster/blob/main/cdc_config.h): `cdc_config.h`
- [Device settings](https://github.com/r2axz/bluepill-serial-monster/blob/main/device_config.c): `device_config.c`
- [Settings interface](https://github.com/r2axz/bluepill-serial-monster/blob/main/device_config.h): `device_config.h`

### Board support

- [Firmware entry](https://github.com/r2axz/bluepill-serial-monster/blob/main/main.c): `main.c`
- [GPIO pins](https://github.com/r2axz/bluepill-serial-monster/blob/main/gpio.c): `gpio.c`
- [Status LED](https://github.com/r2axz/bluepill-serial-monster/blob/main/status_led.c): `status_led.c`
- [System clock](https://github.com/r2axz/bluepill-serial-monster/blob/main/system_clock.c): `system_clock.c`
- [Interrupt setup](https://github.com/r2axz/bluepill-serial-monster/blob/main/system_interrupts.c): `system_interrupts.c`

### Other components

- **USB host**

## Connections

- USB host → USB control core: issues USB requests (evidence: `README.md`)
- USB control core → USB endpoint I/O: uses endpoint I/O (evidence: `usb_core.c`)
- USB control core → CDC descriptors: serves descriptors (evidence: `usb_core.c`)
- USB control core → CDC serial bridge: dispatches CDC requests (evidence: `usb_core.c`)
- USB control core → USB identity: gets serial identity (evidence: `usb_core.c`)
- USB control core → USB fault handling: signals fatal errors (evidence: `usb_core.c`)
- CDC descriptors → CDC interface types: defines CDC interfaces (evidence: `usb_descriptors.c`)
- CDC serial bridge → USB endpoint I/O: transfers endpoint data (evidence: `usb_cdc.c`)
- CDC serial bridge → Circular buffers: buffers serial data (evidence: `usb_cdc.c`)
- CDC serial bridge → Three UARTs: configures UART DMA (evidence: `README.md`)
- CDC serial bridge → GPIO pins: drives control pins (evidence: `usb_cdc.c`)
- CDC serial bridge → Configuration shell: uses config port shell (evidence: `usb_cdc.c`)
- Configuration shell → Device settings: saves or resets (evidence: `cdc_shell.c`)
- Configuration shell → CDC serial bridge: reconfigures serial ports (evidence: `cdc_shell.c`)
- Configuration shell → CDC pin config: edits pin settings (evidence: `cdc_shell.c`)
- Device settings → GPIO pins: stores pin settings
- Firmware entry → System clock: initializes (evidence: `main.c`)
- Firmware entry → Interrupt setup: initializes (evidence: `main.c`)
- Firmware entry → Device settings: initializes (evidence: `main.c`)
- Firmware entry → Status LED: initializes (evidence: `main.c`)
- Firmware entry → USB control core: starts USB device (evidence: `README.md`)
- Status LED → GPIO pins: controls LED pin (evidence: `status_led.c`)
