How adamvotocek/open-tube-light works
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: ledTubeFixture.kicad_sch Fixture PCB · freertos.c RTOS coord · pixel_render.c Render core · main.c Main app
Components 17
Firmware
STM32H723 embedded application and runtime stack
- Main app · Bootstraps the firmware and wires peripherals, tasks, and interrupts
Code/Open-Tube-Light/Core/Src/main.c - RTOS coord · FreeRTOS task, queue, and timer coordination layer
Code/Open-Tube-Light/Core/Src/freertos.c - HAL MSP · Peripheral-level hardware setup hooks for STM32 HAL
Code/Open-Tube-Light/Core/Src/stm32h7xx_hal_msp.c - Interrupts · Exception and peripheral interrupt handling
Code/Open-Tube-Light/Core/Src/stm32h7xx_it.c - Firmware tree · STM32Cube-style firmware project for the lighting controller
Code/Open-Tube-Light
Network input
Ethernet/LwIP path for remote lighting control
- Ethernet IF · LwIP-to-ETHMAC integration and PHY-facing network interface
Code/Open-Tube-Light/LWIP/Target/ethernetif.c - LwIP stack · IP stack initialization and network services foundation
Code/Open-Tube-Light/LWIP/App/lwip.c - LAN8742 · Ethernet PHY driver used by the controller board
Code/Open-Tube-Light/Drivers/BSP/Components/lan8742/lan8742.c - Art-Net · 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 · DMX512 reception over UART
Code/Open-Tube-Light/Core/Src/DMX512/dmx512_uart.c - DMX input · Normalizes local DMX input into shared application state
Code/Open-Tube-Light/Core/Src/dmx_input.c - Config · Hardware- and fixture-specific parameters shared across subsystems
Code/Open-Tube-Light/Core/Src/device_config.c - Render core · Transforms incoming lighting values into a renderable pixel/channel buffer
Code/Open-Tube-Light/Core/Src/pixel_render.c - SK9822 out · 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 · SSD1306-based status display subsystem
Code/Open-Tube-Light/Core/Src/OLED/ssd1306.c
Hardware design
KiCad schematics and board definitions
- Fixture PCB · Main controller/fixture hardware design with MCU, power, DMX, Ethernet, and UI
PCB/ledTubeFixture/ledTubeFixture.kicad_sch - XLR boards · Separate connector/interface board family
PCB/xlrConBoards/xlrConBoards.kicad_sch
Connections 25
- 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