OXRecorder::OXLEDManager

Overview

OXLEDManager drives a single WS2812 (NeoPixel) RGB LED to show what the device is doing. You set a high-level SystemStatus from anywhere in the firmware, pump animate() from loop(), and the LED shows a distinct color + animation for that state — so a glance tells you whether the device is pairing, recording, streaming, faulted, and so on.

• Drives the LED through the ESP32 core's neopixelWrite() — no external library.
• Default data pin is GPIO4 (the ESP32-S3 DI line); overridable in begin().
• Patterns: solid, blink (slow/normal/fast), smooth pulse, and a heartbeat double-blink.
• Designed to be shared project-wide: one instance, setStatus() from any subsystem.

Declared in include/OXLEDManager.h; portable core in src/OXLEDManager.cpp; the WS2812 backend in src/led/Ws2812Device.cpp.

Wiring

System states & their indications

Each SystemStatus maps to one color + pattern. The colors are chosen to be unambiguous at a glance: blue = Bluetooth, yellow = Wi-Fi link, green = connected / operational, purple = recording, cyan = active data transfer, orange = power/battery, magenta = firmware update, white = startup/reset, red = fault.

Startup

Bluetooth provisioning

Wi-Fi connectivity

Recording

Data transfer

Maintenance & power

Faults

The states above refine and extend the original request: the Bluetooth, Wi-Fi, server, and recording modes you listed are all present, split into precise sub-states (e.g. "Wi-Fi available but no server" vs "server connected"), plus added states for boot, idle, OTA update, charging, low battery, factory reset, SD fault, and generic error.

Patterns

API reference

Examples

1. Reflect application status

Create one manager, set the status as the app changes state, and pump animate() every loop.

#include <Arduino.h>
#include "OXLEDManager.h"

using namespace OXRecorder;

OXLEDManager statusLed;

void setup() {
  statusLed.begin();                 // GPIO4, starts in Boot (white solid)
  // ... bring up subsystems ...
  statusLed.setStatus(SystemStatus::BluetoothPairing);  // blue blink
}

void loop() {
  statusLed.animate(millis());     // drives the blink/pulse animation
  // ... rest of your loop; keep it non-blocking ...
}

2. Drive status from real events

Wherever your connection / recording state changes, call setStatus(). It's a cheap no-op when unchanged.

void onWifiConnected()    { statusLed.setStatus(SystemStatus::WifiConnectedNoServer); }
void onServerConnected()  { statusLed.setStatus(SystemStatus::ServerConnected); }
void onRecordingStart(bool streaming) {
  statusLed.setStatus(streaming ? SystemStatus::RecordingAndStreaming
                            : SystemStatus::Recording);
}
void onSdFault()          { statusLed.setStatus(SystemStatus::SdError); }   // red heartbeat
void onLowBattery()       { statusLed.setStatus(SystemStatus::LowBattery); }

3. Derive status from flags

A small helper keeps the mapping in one place when several conditions combine:

SystemStatus deriveStatus(bool wifi, bool server, bool recording) {
  if (recording && server)        return SystemStatus::RecordingAndStreaming;
  if (recording && wifi)          return SystemStatus::RecordingWifiNoServer;
  if (recording)                  return SystemStatus::Recording;
  if (server)                     return SystemStatus::ServerConnected;
  if (wifi)                       return SystemStatus::WifiConnectedNoServer;
  return SystemStatus::Idle;
}

// each loop:
statusLed.setStatus(deriveStatus(wifiUp, serverUp, isRecording));
statusLed.animate(millis());

4. Custom one-off indication

statusLed.setStyle({Colors::Magenta, Pattern::Pulse});  // e.g. OTA
// ... later, return to status-driven behavior:
statusLed.setStatus(SystemStatus::Idle);

5. Override the pin

statusLed.begin(6, SystemStatus::Idle);   // WS2812 DI on a custom GPIO6

Notes

• Pump animate() regularly. Blink and pulse timing come from the millis() you pass; if the loop stalls, animations freeze. Keep loop() non-blocking.
• Cheap to over-call. setStatus() with the current status does nothing, and animate() only writes the LED when the color actually changes — so calling both every loop is fine.
• One LED. This manager drives a single status LED. For an addressable strip, drive multiple pixels behind a custom ILedDevice.