# leandrosly/s16-companion architecture

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

- Interactive diagram: https://gitdiagram.com/leandrosly/s16-companion
- Repository: https://github.com/leandrosly/s16-companion

## Overview

S16 Companion is an ESP32-S3 wrist display and Bluetooth bridge for a KingSong KS-S16. The main flow connects to the wheel, presents a matching BLE identity and GATT services to phone apps, and relays wheel data and app interactions while providing live display, controls, logging, and peripheral features. The README documents substantial features, but the firmware sketches implementing them were not sampled, so those links are documented rather than source-verified; the sampled NimBLE files show supporting BLE stack changes.

Main entry points: [`ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino) (Companion Firmware), [`patch_nimble_2.5.1/nimconfig.h`](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/nimconfig.h) (NimBLE Configuration), [`patch_nimble_2.5.1/ble_gap.c`](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_gap.c) (GAP Procedures), [`patch_nimble_2.5.1/ble_hs_hci_evt.c`](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_hs_hci_evt.c) (HCI Event Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bridge["BLE Bridge"]
  node_ble_client["Wheel BLE Client"]
  node_ble_server["App BLE Server"]
  node_media["Media Controls"]
end

subgraph group_display["Display and Controls"]
  node_companion["Companion Firmware"]
  node_ui["Live Display"]
  node_settings["Settings and Sleep"]
  node_logs[("SD Logs and Prints")]
end

subgraph group_peripherals["Peripherals"]
  node_dream["Dream Backpack"]
  node_mpu["MPU-6050"]
  node_audio["Audio and Horn"]
  node_signals["433 MHz Signals"]
  node_brake["Brake Lighting"]
end

subgraph group_platform["BLE Platform"]
  node_nimble_gap["GAP Procedures<br/>[ble_gap.c]"]
  node_hci_events["HCI Event Dispatch<br/>[ble_hs_hci_evt.c]"]
  node_gap_service["GAP Service<br/>[ble_svc_gap.c]"]
  node_gatt_service["GATT Service<br/>[ble_svc_gatt.c]"]
  node_nimble_config["NimBLE Configuration<br/>[nimconfig.h]"]
end

node_rider(("Rider"))
node_wheel(("KS-S16 Wheel"))
node_phone(("Phone Apps"))

node_rider -->|"views status"| node_ui
node_wheel -->|"sends telemetry"| node_ble_client
node_ble_client -->|"connects and controls"| node_wheel
node_ble_client -->|"provides wheel data"| node_companion
node_companion -->|"hosts wheel identity"| node_ble_server
node_phone -->|"connects as app"| node_ble_server
node_ble_server -->|"relays wheel services"| node_phone
node_phone -->|"pairs separately"| node_media
node_media -->|"controls playback"| node_phone
node_companion -.->|"updates display"| node_ui
node_rider -->|"configures device"| node_settings
node_settings -.->|"saves settings"| node_logs
node_companion -->|"records events"| node_logs
node_rider -->|"sets lighting"| node_dream
node_dream -->|"connects as client"| node_ble_client
node_mpu -->|"drives auto display"| node_ui
node_rider -->|"triggers horn"| node_audio
node_rider -->|"sets indicators"| node_signals
node_companion -->|"detects regen current"| node_brake
node_brake -->|"sets red lighting"| node_dream
node_brake -->|"sets red lamps"| node_signals
node_nimble_config -.->|"configures stack"| node_nimble_gap
node_nimble_config -.->|"configures stack"| node_hci_events
node_nimble_gap -.->|"handles connection events"| node_hci_events
node_ble_server -.->|"uses GAP service"| node_gap_service
node_ble_server -.->|"uses GATT service"| node_gatt_service

click node_companion "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_ble_client "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_ble_server "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_media "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_ui "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_settings "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_logs "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_dream "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_mpu "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_audio "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_signals "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_brake "https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino"
click node_nimble_gap "https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_gap.c"
click node_hci_events "https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_hs_hci_evt.c"
click node_gap_service "https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_svc_gap.c"
click node_gatt_service "https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_svc_gatt.c"
click node_nimble_config "https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/nimconfig.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_ble_client,node_ble_server,node_media toneBlue
class node_companion,node_ui,node_settings,node_logs toneAmber
class node_dream,node_mpu,node_audio,node_signals,node_brake toneMint
class node_nimble_gap,node_hci_events,node_gap_service,node_gatt_service,node_nimble_config toneRose
class node_rider,node_wheel,node_phone toneIndigo
```

## Components

### BLE Bridge

- [Wheel BLE Client](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [App BLE Server](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [Media Controls](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`

### Display and Controls

- [Companion Firmware](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [Live Display](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [Settings and Sleep](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [SD Logs and Prints](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`

### Peripherals

- [Dream Backpack](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [MPU-6050](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [Audio and Horn](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [433 MHz Signals](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`
- [Brake Lighting](https://github.com/leandrosly/s16-companion/blob/main/ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino): `ks_s16_ponte_v5_midia/ks_s16_ponte_v5_midia.ino`

### BLE Platform

- [GAP Procedures](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_gap.c): `patch_nimble_2.5.1/ble_gap.c`
- [HCI Event Dispatch](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_hs_hci_evt.c): `patch_nimble_2.5.1/ble_hs_hci_evt.c`
- [GAP Service](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_svc_gap.c): `patch_nimble_2.5.1/ble_svc_gap.c`
- [GATT Service](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/ble_svc_gatt.c): `patch_nimble_2.5.1/ble_svc_gatt.c`
- [NimBLE Configuration](https://github.com/leandrosly/s16-companion/blob/main/patch_nimble_2.5.1/nimconfig.h): `patch_nimble_2.5.1/nimconfig.h`

### Other components

- **Rider**
- **KS-S16 Wheel**
- **Phone Apps**

## Connections

- Rider → Live Display: views status (evidence: `README.md`)
- KS-S16 Wheel → Wheel BLE Client: sends telemetry (evidence: `README.md`)
- Wheel BLE Client → KS-S16 Wheel: connects and controls (evidence: `README.md`)
- Wheel BLE Client → Companion Firmware: provides wheel data (evidence: `README.md`)
- Companion Firmware → App BLE Server: hosts wheel identity (evidence: `README.md`)
- Phone Apps → App BLE Server: connects as app (evidence: `README.md`)
- App BLE Server → Phone Apps: relays wheel services (evidence: `README.md`)
- Phone Apps → Media Controls: pairs separately (evidence: `README.md`)
- Media Controls → Phone Apps: controls playback (evidence: `README.md`)
- Companion Firmware → Live Display: updates display
- Rider → Settings and Sleep: configures device (evidence: `README.md`)
- Settings and Sleep → SD Logs and Prints: saves settings
- Companion Firmware → SD Logs and Prints: records events (evidence: `README.md`)
- Rider → Dream Backpack: sets lighting (evidence: `README.md`)
- Dream Backpack → Wheel BLE Client: connects as client (evidence: `README.md`)
- MPU-6050 → Live Display: drives auto display (evidence: `README.md`)
- Rider → Audio and Horn: triggers horn (evidence: `README.md`)
- Rider → 433 MHz Signals: sets indicators (evidence: `README.md`)
- Companion Firmware → Brake Lighting: detects regen current (evidence: `README.md`)
- Brake Lighting → Dream Backpack: sets red lighting (evidence: `README.md`)
- Brake Lighting → 433 MHz Signals: sets red lamps (evidence: `README.md`)
- NimBLE Configuration → GAP Procedures: configures stack
- NimBLE Configuration → HCI Event Dispatch: configures stack
- GAP Procedures → HCI Event Dispatch: handles connection events
- App BLE Server → GAP Service: uses GAP service
- App BLE Server → GATT Service: uses GATT service
