UI Behavior — LED & Button Specification¶
Authoritative specification for the EverTag Station user interface: two RGB LEDs and one service button. This document is the single source of truth for firmware developers. Customer-facing summaries in the product manuals reference this spec.
Hardware Summary¶
| Component | Part | GPIO | Notes |
|---|---|---|---|
| LED1 (System) | SK6812MINI (addressable RGB, top-emitting) | P0.01 (LED_DATA) | All variants. First LED in daisy-chain. |
| LED2 (Gateway) | SK6812MINI (addressable RGB, top-emitting) | P0.01 (LED_DATA) | Gateway variants only (232202+). Second LED in daisy-chain. |
| Service button | Recessed tactile switch (right-angle, side-actuated) | P2.06 (SWITCH, active-low, internal pull-up) | All variants. Accessed via pinhole on enclosure side. |
Both LEDs share a single data line (SK6812 daisy-chain protocol). LED2 is not populated on non-gateway variants (232200, 232201).
LED Operating Modes¶
stateDiagram-v2
[*] --> Off: Device off
Off --> Active: Power-on (5s hold)
Active --> Dormant: 5-min timeout
Dormant --> Active: Short press
Dormant --> Active: NFC interaction
Active --> Active: Short press (reset timer)
Active --> Active: NFC interaction (reset timer)
Dormant --> UserOverride: 0x0A command received
Active --> UserOverride: 0x0A command received
UserOverride --> Dormant: Pattern complete
UserOverride --> Active: Pattern complete (if active timer still running)
Active --> Off: Shutdown
Dormant --> Off: ShutdownActive Mode¶
LEDs display real-time status indicators (see LED1 and LED2 tables below). Triggered by:
- Power-on: LEDs active for 5 minutes after the device is powered on via button hold.
- Short button press: LEDs active for 5 minutes. Timer resets on each subsequent short press.
- NFC interaction: Any NFC read or write (via CB Admin) activates LEDs for 5 minutes. Timer resets on each tap.
After the 5-minute timeout, LEDs transition to dormant mode.
Dormant Mode (default)¶
All LEDs are off. The device is discreet when installed. This is the steady-state after the 5-minute active window expires.
- Faults do not force LEDs on in dormant mode. A button press is required to inspect status.
- Dormant mode is the expected operating state for deployed devices.
User-Controlled Override¶
LED patterns commanded via the Wirepas network (0x0A command) activate immediately, even when the device is in dormant mode. This supports:
- Pick-by-light: finding a specific anchor among many
- Remote diagnostics: confirming a specific device is reachable
After the commanded pattern completes (repeat count expires), the LED returns to whatever mode was active before (dormant or active).
Button Behavior¶
Action Matrix¶
| Action | Trigger | LED Feedback | Result |
|---|---|---|---|
| Power on | Hold 5 s (from off state) | LED1 blinks WHITE once at 5 s to confirm | Device powers on; LEDs enter active mode (5 min) |
| Status check | Short press (< 1 s) | LEDs activate immediately | LEDs show status for 5 minutes |
| Reboot | Hold ~3 s (release after feedback) | LED1 blinks RED twice at 3 s | System reboot; device restarts; LEDs enter active mode |
| Factory reset | Hold button while plugging in power; keep holding for 10 s | LED1 fast-blinks RED at 10 s | All configuration erased; factory defaults restored |
Button Timing Diagram¶
Press duration: 0s 1s 2s 3s 4s 5s ... 10s
|---------|---------|---------|---------|---------|---------|------|
Short press: |<-release here
→ Status check (LEDs active 5 min)
Reboot: |--hold---|--hold---|--hold---|
↑ LED1 blinks RED ×2 → release → reboot
Power on (off→on): |--hold---|--hold---|--hold---|--hold---|--hold---|
↑ LED1 blinks WHITE → powered on
Factory reset: [plug in power while holding]--hold--hold--hold--hold--hold--|
0s 10s
↑ LED1 fast RED → reset
Design Notes¶
- The device ships powered off. A 5-second button hold is required to power on. This prevents battery drain on battery-backup variants (232201, 232203) — when "off and plugged in", the battery charges but the device does not run.
- NFC power-on via CB Admin remains as an alternative for first-time activation.
- Factory reset requires physically plugging in power while holding the button, then continuing to hold for 10 seconds. This two-step physical action prevents accidental resets. Works regardless of whether the device was previously on or off.
- Button debounce: 50 ms minimum (hardware RC filter + software debounce).
LED1 — System & Wirepas Status¶
Applies to all variants (232200–232203). Displayed only during active mode or when a user-controlled pattern is active.
State Priority Table¶
States are listed in priority order. The highest-priority active state is displayed. Only one state is shown at a time.
| Priority | State | Color | Pattern | Description |
|---|---|---|---|---|
| 1 | Self-test fault | RED / AMBER | Diagnostic blink (counted) | Error code blink pattern -- see Boot Self-Test. RED = error, AMBER = warning. Blink count identifies the specific fault. |
| 2 | User-controlled | PURPLE | Per 0x0A command | Commanded via Wirepas backend; overrides dormant mode |
| 3 | Booting | WHITE | Breathing (1 s cycle) | Device is initializing after power-on |
| 4 | Powered, no Wirepas | YELLOW | Solid | Powered but not joined to any Wirepas network |
| 5 | Wirepas joined, no sink | BLUE | Solid | Joined Wirepas network but no sink route available |
| 6 | Wirepas operational | GREEN | Solid | Wirepas sink connected — fully operational |
Color Reference¶
| Color | RGB Value | Description |
|---|---|---|
| RED | (255, 0, 0) | Fault / error (self-test diagnostic) |
| AMBER | (255, 160, 0) | Warning (self-test diagnostic -- non-critical) |
| PURPLE | (128, 0, 128) | User-controlled action |
| WHITE | (255, 255, 255) | Boot / neutral |
| YELLOW | (255, 255, 0) | Warning / no network |
| BLUE | (0, 0, 255) | Partial connectivity |
| GREEN | (0, 255, 0) | Fully operational |
Self-Test Diagnostic Blinks
When the boot self-test detects errors or warnings, LED1 enters diagnostic blink mode during the 5-minute active window. Each error code is displayed as a counted blink sequence (e.g., 3 RED long blinks = E03 Battery Missing). The blink timing inherits the EverTag tag firmware format: short = 100 ms ON / 400 ms OFF, long = 250 ms ON / 250 ms OFF, in 4-second cycles. See the Boot Self-Test & Traceability specification for the full error code registry, blink mapping, and UART0 output format. The self-test is diagnostic only -- the device always continues to boot and join the Wirepas network regardless of test results.
No DFU Indication
LED1 does not indicate firmware update (DFU) status because the nRF54 cannot reliably drive the LED data line during a DFU operation. ESP32 OTA updates are indicated on LED2 (gateway variants only).
LED2 — Gateway Backhaul Status¶
Applies to gateway variants only (232202, 232203). LED2 is not populated on 232200 and 232201. Displayed only during active mode.
State Priority Table¶
| Priority | State | Color | Pattern | Description |
|---|---|---|---|---|
| 1 | Gateway fault | RED | Fast blink (2 Hz) | ESP32 crash, UART comm failure, or gateway subsystem error |
| 2 | ESP32 OTA update | WHITE | Breathing (1 s cycle) | ESP32 firmware update in progress |
| 3 | WiFi connecting | BLUE | Breathing (2 s cycle) | Attempting WiFi association |
| 4 | WiFi connected, no MQTT | BLUE | Solid | WiFi associated but MQTT broker not reached |
| 5 | WiFi + MQTT connected | GREEN | Solid | Fully connected to cloud backend |
| 6 | LTE connecting | CYAN | Breathing (2 s cycle) | LTE modem registering to network (future — 232210/232211) |
| 7 | LTE connected, no MQTT | CYAN | Solid | LTE up but MQTT broker not reached (future) |
| 8 | LTE + MQTT connected | GREEN | Solid | Fully connected via LTE (future) |
| 9 | No backhaul configured | YELLOW | Solid | No WiFi or LTE configured |
Notes¶
- LTE states are reserved for future extension boards (232210/232211). WiFi and LTE are mutually exclusive (one active transport at a time).
- CYAN (light blue, RGB 0, 255, 255) distinguishes LTE from WiFi (BLUE). This can be revisited when LTE hardware is developed.
- ESP32 OTA: DFU indication is feasible on LED2 because the nRF54 can drive the LED chain while the ESP32 is updating.
User-Controlled LED Pattern (0x0A Command)¶
The Station inherits the LED pattern encoding from the existing EverTag tag firmware. LED patterns are commanded via the Wirepas configuration-over-network protocol using command ID 0x0A (4 bytes).
Encoding Format¶
0xNNABCDEF
NN = repeat count (number of times the 4-second sequence repeats)
ABCDEF = six blink codes, one per 500 ms slot within the first 3 seconds
(the 4th second is always OFF — acts as a separator)
Blink codes:
| Code | Meaning |
|---|---|
| 0 | Off (no blink) |
| 1 | Short blink: 100 ms ON / 400 ms OFF |
| 2 | Long blink: 250 ms ON / 250 ms OFF |
Behavior¶
- Color: PURPLE (fixed). Distinct from all status indication colors.
- Dormant override: Pattern activates immediately, even in dormant mode.
- Priority: Below self-test fault (priority 2 in LED1 table). A fault blink overrides a user-controlled pattern.
- Completion: After the repeat count expires, the LED returns to its previous mode (dormant or active status display).
Example¶
0x05211221:
05→ repeat 5 times (5 × 4 s = 20 seconds total)2 1 1 2 2 1→ long, short, short, long, long, short
Wirepas Configuration Inheritance¶
The EverTag Station will inherit suitable configuration parameters from the EverTag configuration-over-Wirepas-network protocol. The following command IDs are applicable to the Station:
| ID | Bytes | Description | Station Applicability |
|---|---|---|---|
| 0x0A | 4 | LED Pattern | Yes — PURPLE on LED1, same encoding |
| 0x0B | 0 | Deactivate (power down) | Yes — powers off device |
| 0x0C | 0 | Reset Config (factory defaults) | Yes — same as button factory reset |
| 0x0F | 0 | Get Hardware Info | Yes |
| 0x10 | 0 | Get Firmware Info | Yes |
| 0x19 | 0 | Enable Anchor Tampering | Yes — Station supports accelerometer |
| 0x1A | 0 | Disable Anchor Tampering | Yes |
Commands not applicable to the Station (tag-only features such as beaconing intervals, movement thresholds, iBeacon configuration, etc.) are silently ignored.
Protocol Details
For the full packet structure (CONFIG_ID, SEQ, LENGTH, MSG_TYPE, address arrays), see the EverTag User Guide — Application Configuration.
Variant Applicability¶
| Feature | 232200 | 232201 | 232202 | 232203 |
|---|---|---|---|---|
| LED1 (System/Wirepas) | Yes | Yes | Yes | Yes |
| LED2 (Gateway) | — | — | Yes | Yes |
| Service button | Yes | Yes | Yes | Yes |
| Battery backup | — | Yes | — | Yes |
| WiFi gateway | — | — | Yes | Yes |
Pattern Definitions¶
Breathing Pattern¶
Smooth sine-wave fade: 0 % → 100 % → 0 % over the specified cycle time. Used for transitional states (booting, connecting, OTA).
Fast Blink (2 Hz)¶
250 ms ON / 250 ms OFF. Used for fault indication.
Solid¶
Continuous on at configured brightness. Used for steady-state status.
Revision History¶
| Revision | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2026-02-23 | CargoBeacon | Initial specification |