# adamvotocek/open-tube-light architecture

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

- Interactive diagram: https://gitdiagram.com/adamvotocek/open-tube-light
- Repository: https://github.com/adamvotocek/open-tube-light

## Overview

1. This repository is split into two major halves: embedded firmware in `Code/Open-Tube-Light` and hardware design files in `PCB`. The firmware targets an STM32H723-based controller board, and the PCB directory contains the KiCad design for the fixture/controller hardware and a second board set for XLR-related connectors.

2. The firmware is a bare-metal-plus-RTOS embedded application built with STM32Cube-style structure. Core runtime pieces are `main.c`, interrupt handlers, the STM32 HAL/CMSIS layers under `Drivers`, and FreeRTOS under `Middlewares/Third_Party/FreeRTOS`. Build and toolchain support is via CMake/CMakePresets, not a desktop application stack.

3. The main system boundary is networking versus lighting output. Ethernet is handled by `LWIP` plus the STM32 Ethernet HAL and LAN8742 PHY driver. That network path exists to receive Art-Net packets, implemented under `Core/Src/Art-Net`, which is the primary remote-control protocol for lighting data.

4. A second input path exists for DMX512 over UART. The `DMX512/dmx512_uart.*` and `dmx_input.*` modules indicate the device can consume local DMX data directly, likely as an alternative or fallback to Art-Net. Both input paths converge into shared device state rather than driving LEDs independently.

5. The shared control/data plane appears to be centered on `pixel_render.*`. This is the application-layer subsystem that turns incoming lighting values into a renderable pixel buffer or channel set. It is the bridge between protocol inputs and the physical LED output driver.

6. Physical LED output is handled by `SK9822/sk9822.*`, which is the low-level driver for the LED chain. Architecturally, this is the final sink in the lighting pipeline: protocol input → render/state normalization → SK9822 transport → LEDs.

7. The system includes an OLED status/display subsystem under `OLED/ssd1306.*`. This is separate from the lighting output path and is used for local UI/status feedback. The presence of `displayAndButtons.kicad_sch` in the PCB tree suggests the hardware also supports local buttons or controls that feed into the firmware.

8. `device_config.*` is the configuration boundary between hardware-specific constants and application logic. It likely holds board/fixture parameters such as channel counts, network identifiers, LED layout, or default modes. This keeps the protocol handlers and render path from hardcoding physical details.

9. FreeRTOS is the execution model that ties the subsystems together. The firmware is likely structured as tasks/queues/timers around network reception, DMX processing, rendering, and display updates, with interrupt/DMA-driven peripheral support underneath. `freertos.c` is the main coordination point for that concurrency model.

10. The HAL and BSP layers are not just boilerplate here; they define the hardware integration boundaries. SPI, UART, I2C, Ethernet, timers, DMA, GPIO, and the LAN8742 PHY driver are all present because the fixture depends on multiple real-time peripherals simultaneously.

11. The PCB files matter architecturally because they define the physical system around the firmware. The `ledTubeFixture` board includes schematics for MCU, power, DMX, Ethernet, and display/buttons, which mirrors the firmware subsystems. `xlrConBoards` is a separate board family focused on connector/interface hardware, likely for signal routing or termination.

12. Net effect: this is an embedded lighting controller, not a general-purpose app. Its core data flow is network/DMX ingestion on the STM32, internal state/render processing, then real-time LED driving, with OLED/UI and configuration as supporting subsystems. An accurate diagram should show Ethernet/Art-Net and DMX as parallel inputs feeding a shared render pipeline, with FreeRTOS and HAL as the orchestration/driver layers, and the PCB as the hardware realization of those boundaries.

Main entry points: [`PCB/ledTubeFixture/ledTubeFixture.kicad_sch`](https://github.com/adamvotocek/open-tube-light/blob/main/PCB/ledTubeFixture/ledTubeFixture.kicad_sch) (Fixture PCB), [`Code/Open-Tube-Light/Core/Src/freertos.c`](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/freertos.c) (RTOS coord), [`Code/Open-Tube-Light/Core/Src/pixel_render.c`](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/pixel_render.c) (Render core), [`Code/Open-Tube-Light/Core/Src/main.c`](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/main.c) (Main app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware"]
  node_main["Main app<br/>entrypoint<br/>[main.c]"]
  node_freertos["RTOS coord<br/>scheduler<br/>[freertos.c]"]
  node_hal_msp["HAL MSP<br/>board init"]
  node_interrupts["Interrupts<br/>irq handlers<br/>[stm32h7xx_it.c]"]
  node_board_firmware["Firmware tree<br/>embedded repo"]
end

subgraph group_network["Network input"]
  node_ethernetif["Ethernet IF<br/>net port<br/>[ethernetif.c]"]
  node_lwip_app["LwIP stack<br/>tcp/ip stack<br/>[lwip.c]"]
  node_lan8742["LAN8742<br/>phy driver<br/>[lan8742.c]"]
  node_artnet["Art-Net<br/>lighting protocol<br/>[artnet.c]"]
end

subgraph group_lighting["Lighting pipeline"]
  node_dmx_uart["DMX UART<br/>dmx input<br/>[dmx512_uart.c]"]
  node_dmx_input["DMX input<br/>input merge<br/>[dmx_input.c]"]
  node_device_config["Config<br/>[device_config.c]"]
  node_pixel_render["Render core<br/>state/render<br/>[pixel_render.c]"]
  node_sk9822["SK9822 out<br/>led driver<br/>[sk9822.c]"]
end

subgraph group_ui["Local UI"]
  node_oled["OLED status<br/>ui display<br/>[ssd1306.c]"]
end

subgraph group_hardware["Hardware design"]
  node_pcb_fixture["Fixture PCB<br/>kicad board"]
  node_pcb_xlr["XLR boards<br/>kicad board"]
end

node_main -->|"starts"| node_freertos
node_main -->|"inits"| node_hal_msp
node_main -->|"uses"| node_interrupts
node_main -->|"brings up"| node_lwip_app
node_lwip_app -->|"binds"| node_ethernetif
node_ethernetif -->|"drives"| node_lan8742
node_ethernetif -->|"carries"| node_artnet
node_artnet -->|"updates"| node_pixel_render
node_dmx_uart -->|"feeds"| node_dmx_input
node_dmx_input -->|"converges"| node_pixel_render
node_device_config -->|"configures"| node_artnet
node_device_config -->|"configures"| node_dmx_input
node_device_config -->|"parameterizes"| node_pixel_render
node_pixel_render -->|"drives"| node_sk9822
node_freertos -->|"schedules"| node_artnet
node_freertos -->|"schedules"| node_dmx_input
node_freertos -->|"coordinates"| node_pixel_render
node_freertos -->|"updates"| node_oled
node_oled -->|"shows"| node_device_config
node_pcb_fixture -->|"implements"| node_board_firmware
node_pcb_fixture -->|"hosts"| node_oled
node_pcb_fixture -->|"hosts"| node_ethernetif
node_pcb_fixture -->|"hosts"| node_dmx_uart
node_pcb_fixture -->|"drives"| node_sk9822
node_pcb_xlr -->|"supports"| node_board_firmware

click node_main "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/main.c"
click node_freertos "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/freertos.c"
click node_hal_msp "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/stm32h7xx_hal_msp.c"
click node_interrupts "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/stm32h7xx_it.c"
click node_ethernetif "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/LWIP/Target/ethernetif.c"
click node_lwip_app "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/LWIP/App/lwip.c"
click node_lan8742 "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Drivers/BSP/Components/lan8742/lan8742.c"
click node_artnet "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/Art-Net/artnet.c"
click node_dmx_uart "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/DMX512/dmx512_uart.c"
click node_dmx_input "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/dmx_input.c"
click node_device_config "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/device_config.c"
click node_pixel_render "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/pixel_render.c"
click node_sk9822 "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/SK9822/sk9822.c"
click node_oled "https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/OLED/ssd1306.c"
click node_board_firmware "https://github.com/adamvotocek/open-tube-light/tree/main/Code/Open-Tube-Light"
click node_pcb_fixture "https://github.com/adamvotocek/open-tube-light/blob/main/PCB/ledTubeFixture/ledTubeFixture.kicad_sch"
click node_pcb_xlr "https://github.com/adamvotocek/open-tube-light/blob/main/PCB/xlrConBoards/xlrConBoards.kicad_sch"

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_main,node_freertos,node_hal_msp,node_interrupts,node_board_firmware toneBlue
class node_ethernetif,node_lwip_app,node_lan8742,node_artnet toneAmber
class node_dmx_uart,node_dmx_input,node_device_config,node_pixel_render,node_sk9822 toneMint
class node_oled toneRose
class node_pcb_fixture,node_pcb_xlr toneIndigo
```

## Components

### Firmware

STM32H723 embedded application and runtime stack

- [Main app](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/main.c): entrypoint · Bootstraps the firmware and wires peripherals, tasks, and interrupts · `Code/Open-Tube-Light/Core/Src/main.c`
- [RTOS coord](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/freertos.c): scheduler · FreeRTOS task, queue, and timer coordination layer · `Code/Open-Tube-Light/Core/Src/freertos.c`
- [HAL MSP](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/stm32h7xx_hal_msp.c): board init · Peripheral-level hardware setup hooks for STM32 HAL · `Code/Open-Tube-Light/Core/Src/stm32h7xx_hal_msp.c`
- [Interrupts](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/stm32h7xx_it.c): irq handlers · Exception and peripheral interrupt handling · `Code/Open-Tube-Light/Core/Src/stm32h7xx_it.c`
- [Firmware tree](https://github.com/adamvotocek/open-tube-light/tree/main/Code/Open-Tube-Light): embedded repo · STM32Cube-style firmware project for the lighting controller · `Code/Open-Tube-Light`

### Network input

Ethernet/LwIP path for remote lighting control

- [Ethernet IF](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/LWIP/Target/ethernetif.c): net port · LwIP-to-ETHMAC integration and PHY-facing network interface · `Code/Open-Tube-Light/LWIP/Target/ethernetif.c`
- [LwIP stack](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/LWIP/App/lwip.c): tcp/ip stack · IP stack initialization and network services foundation · `Code/Open-Tube-Light/LWIP/App/lwip.c`
- [LAN8742](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Drivers/BSP/Components/lan8742/lan8742.c): phy driver · Ethernet PHY driver used by the controller board · `Code/Open-Tube-Light/Drivers/BSP/Components/lan8742/lan8742.c`
- [Art-Net](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/Art-Net/artnet.c): lighting protocol · Receives lighting data over Ethernet · `Code/Open-Tube-Light/Core/Src/Art-Net/artnet.c`

### Lighting pipeline

Shared state, rendering, and LED output

- [DMX UART](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/DMX512/dmx512_uart.c): dmx input · DMX512 reception over UART · `Code/Open-Tube-Light/Core/Src/DMX512/dmx512_uart.c`
- [DMX input](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/dmx_input.c): input merge · Normalizes local DMX input into shared application state · `Code/Open-Tube-Light/Core/Src/dmx_input.c`
- [Config](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/device_config.c): fixture config · Hardware- and fixture-specific parameters shared across subsystems · `Code/Open-Tube-Light/Core/Src/device_config.c`
- [Render core](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/pixel_render.c): state/render · Transforms incoming lighting values into a renderable pixel/channel buffer · `Code/Open-Tube-Light/Core/Src/pixel_render.c`
- [SK9822 out](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/SK9822/sk9822.c): led driver · Low-level LED chain transport and final output sink · `Code/Open-Tube-Light/Core/Src/SK9822/sk9822.c`

### Local UI

OLED status and local controls

- [OLED status](https://github.com/adamvotocek/open-tube-light/blob/main/Code/Open-Tube-Light/Core/Src/OLED/ssd1306.c): ui display · SSD1306-based status display subsystem · `Code/Open-Tube-Light/Core/Src/OLED/ssd1306.c`

### Hardware design

KiCad schematics and board definitions

- [Fixture PCB](https://github.com/adamvotocek/open-tube-light/blob/main/PCB/ledTubeFixture/ledTubeFixture.kicad_sch): kicad board · Main controller/fixture hardware design with MCU, power, DMX, Ethernet, and UI · `PCB/ledTubeFixture/ledTubeFixture.kicad_sch`
- [XLR boards](https://github.com/adamvotocek/open-tube-light/blob/main/PCB/xlrConBoards/xlrConBoards.kicad_sch): kicad board · Separate connector/interface board family · `PCB/xlrConBoards/xlrConBoards.kicad_sch`

## Connections

- Main app → RTOS coord: starts · Main application enters RTOS-based coordination
- Main app → HAL MSP: inits · Boot-time peripheral and board initialization
- Main app → Interrupts: uses · Interrupt-driven peripheral handling
- Main app → LwIP stack: brings up · Network stack initialization path
- LwIP stack → Ethernet IF: binds · LwIP connects to the Ethernet interface implementation
- Ethernet IF → LAN8742: drives · Ethernet MAC/PHY link management
- Ethernet IF → Art-Net: carries · Network packets feed the Art-Net protocol handler
- Art-Net → Render core: updates · Art-Net lighting payloads populate shared render state
- DMX UART → DMX input: feeds · UART DMX frames enter the local input path
- DMX input → Render core: converges · DMX input is normalized into the shared render plane
- Config → Art-Net: configures · Protocol and fixture settings depend on device parameters
- Config → DMX input: configures · DMX channel and fixture behavior settings
- Config → Render core: parameterizes · Render behavior depends on fixture layout and channel counts
- Render core → SK9822 out: drives · Rendered pixel data is sent to the LED output driver
- RTOS coord → Art-Net: schedules · Network processing is coordinated as RTOS work
- RTOS coord → DMX input: schedules · DMX processing and normalization run under RTOS coordination
- RTOS coord → Render core: coordinates · Render updates are synchronized with other runtime work
- RTOS coord → OLED status: updates · Status/display refresh is managed as a concurrent subsystem
- OLED status → Config: shows · Display may reflect configuration and device state
- Fixture PCB → Firmware tree: implements · Main fixture hardware mirrors the firmware subsystem boundaries
- Fixture PCB → OLED status: hosts · Display and button hardware support the local UI path
- Fixture PCB → Ethernet IF: hosts · Ethernet hardware realization for the network input path
- Fixture PCB → DMX UART: hosts · DMX circuitry maps to the firmware DMX input path
- Fixture PCB → SK9822 out: drives · LED output hardware corresponds to the final sink
- XLR boards → Firmware tree: supports · Connector/interface hardware complements the main system
