Stacklight

Stacklight Monitor

An ESP32-based physical status monitor that polls New Relic alert statuses and Azure DevOps deployment states, driving a 4-segment stacklight to provide an at-a-glance view of system health.

Overview

The ESP32 polls two data sources every 60 seconds:

• New Relic — queries alertSeverity across multiple APM entity GUIDs via NerdGraph (GraphQL). The worst-case severity across all entities determines the main light colour.
• Azure DevOps — polls in-progress release deployments across configured production environment IDs. A deployment in progress illuminates the blue light; one running past a configurable timeout causes it to flash.

Hardware

Components

Stacklight Wiring

Each segment draws approximately 46mA. Total current draw across all four channels is ~181mA.

Pins are active high. GPIO12 is a strapping pin on the ESP32-WROOM-32D — it may briefly pulse during boot, which does not affect normal operation.

Circuit Design

Each output channel uses a complementary BC547/BC557 transistor pair to level-shift the ESP32's 3.3V GPIO logic to the 12V stacklight supply. The MP1584 buck converter steps 12V down to 5V to power the ESP32. All grounds are common.

The PCB was designed in KiCad 10 and manufactured by JLCPCB. KiCad project files are in stacklight PCB/.

Front	Back

Enclosure

The enclosure was modelled in Autodesk Fusion and sliced with OrcaSlicer. STL files are in enclosure model/.

Software

Built with PlatformIO using the Arduino framework for ESP32.

Dependencies

• ArduinoJson v7 (bblanchon/ArduinoJson@^7.2.2)
• ESP32 platform (platform-espressif32 via git)

Architecture

The firmware is split into focused modules, each with a corresponding unit test suite:

Hardware dependencies are isolated behind IGpioHal and IHttpClient interfaces, making all modules unit testable without hardware.

Configuration

Configuration is split into two categories:

Build-time constants (entity GUIDs, ADO org/project/pipeline IDs, pins, timeout) live in src/config.h, which is gitignored. Copy src/config.h.example to src/config.h and fill in your values before building.

Runtime credentials (WiFi SSID/password, New Relic API key, Azure DevOps PAT) are stored in ESP32 NVS flash and set via serial commands at any time after flashing:

ssid=YourNetwork
password=YourPassword
nr_key=NRAK-xxxxxxxxxxxx
ado_pat=your_ado_personal_access_token

Connect at 115200 baud using the PlatformIO serial monitor or any terminal.

Behaviour

• Polls New Relic and Azure DevOps every 60 seconds
• New Relic: queries alertSeverity for each configured entity GUID — NOT_ALERTING, WARNING, or CRITICAL. Worst case across all entities drives the light colour.
• Azure DevOps: polls in-progress deployments for each configured production environment ID. Deployments running longer than DEPLOY_TIMEOUT_MINUTES cause the blue light to flash.
• On WiFi loss or API error — all lights turn off and yellow flashes. Blue light state is restored on the next successful poll.
• Serial debug output at 115200 baud.

New Relic Setup

1. Create a dedicated New Relic user with a Restricted Read Only role, scoped to the relevant accounts
2. Generate a User API key under that user (type must be "User" — NRAK- prefix for US, eu01xx- prefix for EU)
3. Obtain entity GUIDs for your monitored APM services via the NerdGraph Explorer or the entity URL in the New Relic UI
4. Set the entity GUIDs and entity count in src/config.h and set the API key via serial (nr_key=your_key)

Azure DevOps Setup

1. Generate a Personal Access Token (PAT) with Read permission on Release
2. Note the release definition ID (visible in the ADO URL when viewing a release pipeline)
3. Note the environment IDs for your production stages (visible in the ADO URL when viewing a stage, or from the deployments API response)
4. Set these values in src/config.h and set the PAT via serial (ado_pat=your_pat)

Security

Runtime credentials are stored in ESP32 NVS (non-volatile storage) flash, not in firmware. This means:

• Credentials survive reboots without being visible in source code or build artefacts
• src/config.h (build-time constants) is gitignored — commit src/config.h.example instead
• The New Relic API key is scoped read-only — a compromised key cannot modify any New Relic configuration or access infrastructure credentials
• The ADO PAT should be scoped to Release read only

If the device is decommissioned, revoke the New Relic API key and ADO PAT.

Testing

Unit tests run on-device using the Unity test framework via PlatformIO.

pio test -e test_esp32

To run a single suite:

pio test -e test_esp32 --filter test_polling_timer

Available suites: test_polling_timer, test_serial_parser, test_ado_monitor, test_nr_monitor, test_stacklight, test_config_store.