Skip to content

nRF54 Gateway — Firmware Spec
Product Family EverTag Station
Firmware Build nRF54 Gateway
MCU Module Panasonic PAN611 (nRF54L15) + ESP32-C5 (WiFi/MQTT co-processor)
Target Boards 232202 (Station WiFi), 232203 (Station Battery+WiFi)
Application Role Wirepas Mesh Sink, Dual-MCU Bridge, NFC Configuration Master, Battery Hold-Up
OTAP Area ID 0x9A06C300 (native, OEM 0x3)

1. Platform Overview & Shared Codebase

The nRF54 Gateway firmware targets EverTag Station boards equipped with an ESP32-C5 WiFi co-processor. It shares the same hardware platform and PCB design as the nRF54 Tag/Anchor build, but fundamentally changes the Wirepas application role from Anchor (relay-only) to Sink (mesh terminator that forwards data to IP networks).

The nRF54 is the system master. It runs the Wirepas Mesh stack, manages all persistent configuration in flash, and drives the ESP32-C5 as a peripheral via the Wirepas Dual-MCU API over UART1. The ESP32 handles WiFi, MQTT, and the web UI but has no independent configuration store — it receives all settings from the nRF54 at boot.

1.1 Firmware Binary Compatibility

A single Gateway binary handles all three gateway-capable boards. The firmware detects the underlying hardware at startup using the V_SAMPLE ADC reading (P1.07) and conditionally initializes peripherals.

1.2 Board Variant Detection (V_SAMPLE — P1.07)

Same resistor divider circuit as the Tag/Anchor build: R_top = 100k (1%), board-specific R_bottom in 16.5k steps. The Gateway firmware accepts only ADC values in the gateway range (1200+).

Board Article Product R_bottom 12-bit ADC ADC Window This Build?
230220 Tag nRF54 Base 0 ohm 0 0--200 No (Tag/Anchor build)
232200 Station Base Std 16.5k 580 400--750 No (Tag/Anchor build)
232201 Station Base Battery 33k 1016 850--1200 No (Tag/Anchor build)
232202 Station Base WiFi 49.9k 1363 1200--1550 Yes
232203 Station Bat+WiFi 66.5k 1634 1500--1800 Yes
232204 Station Bat+Radar 82.5k 1851 1750--2050 No (Anchor build)

232204 Runs Anchor Firmware

The 232204 (Base Bat+Radar) runs Anchor firmware, not Gateway. It has no ESP32. See Tag/Anchor for 232204 behaviour.

If V_SAMPLE reads below 1200 (non-gateway ADC values), the firmware must halt and signal a firmware/board mismatch via UART0 and LED1 red fast-flash. See Firmware Compatibility for the full detection circuit, tolerance analysis, and extension board detection (P1.12).

1.3 Initialization Sequence

  1. Boot and read 12-bit ADC on P1.07 (V_SAMPLE).
  2. Identify the board variant from the ADC window table above.
  3. If value < 1200, abort (firmware/board mismatch — Tag/Anchor board detected). 3b. If value ≥ 1750 (232204 Bat+Radar range), abort with "Wrong firmware — 232204 requires Anchor build".
  4. Apply the common GPIO mux (directions are identical across all nRF54 variants).
  5. Initialize the ST25DV04K NFC interface via I2C.
  6. Initialize UART1 (P0.03 TX, P0.04 RX) for Dual-MCU API.
  7. Reset ESP32-C5 via P1.10 (ESP32_RESET).
  8. Wait for ESP32_READY signal on P2.08 (timeout: 10 seconds).
  9. Initialize the Wirepas Dual-MCU library (Dualmcu_lib_init).
  10. Initialize 3-wire coexistence GPIOs (firmware TBD — MPSL not available in Wirepas).
  11. Push stored configuration to ESP32 via UART1 (WiFi, MQTT, NTP settings from nRF54 flash).
  12. Conditionally initialize battery management (232203 only).
Peripheral 232202 (WiFi) 232203 (Bat+WiFi)
I2C NFC (ST25DV04K) Init Init
UART1 Dual-MCU API (ESP32-C5) Init Init
ESP32_RESET (P1.10) Init Init
ESP32_READY (P2.08) Init Init
Coexistence (COEX_REQUEST/PRIORITY/GRANT) Init Init
LED1 + LED2 (SK6812MINI daisy-chain, P0.01) Init Init
Service Button (P2.06) Init Init
Battery Mgmt (P1.06, P2.03--P2.05) Skip Init
SPI Accelerometer Skip Skip

2. Wirepas Mesh Network Configuration

The Gateway firmware incorporates the Wirepas Mesh protocol stack (5.x) in Sink mode. The nRF54 terminates the mesh and forwards received data to the ESP32-C5 via the Dual-MCU API.

2.1 Addressing & Identification

Parameter Value (Hex) Value (Dec) Description
Default Network ID 0x0000DE8E 56974 Default mesh network address.
Default Channel 0x05 5 Default RF channel.
Source Endpoint 0xA000 - MSB of the ETSI-assigned endpoint.
Destination Endpoint 0x006B - LSB of the ETSI-assigned endpoint.
Endpoint Value 0xA06B - Full CargoBeacon messaging endpoint.

2.2 OTAP Area IDs

The Gateway firmware uses OEM 0x3 to separate it from the Tag/Anchor fleet in OTAP updates. This prevents accidental cross-flashing between anchor and gateway builds on the shared Station PCB.

Area ID Format Firmware Build Description
0x12A205 Legacy Tag/Anchor (nRF52) Original OTAP ID for the nRF52 tag fleet.
0x9A06C100 Native Tag/Anchor (nRF52) Native-format equivalent. OEM 0x1.
0x9A06C200 Native Tag/Anchor (nRF54) OEM 0x2 = nRF54 Tag/Anchor.
0x9A06C300 Native Gateway (nRF54) This build. OEM 0x3 = nRF54 Gateway.

Native Area ID structure (32-bit):

Field Bits Value Description
Prefix [31:28] 0x9 DECT/proprietary marker.
Endpoint [27:12] 0xA06C CargoBeacon ETSI-assigned endpoint.
OEM [11:8] 0x3 OEM range. 0x3 = nRF54 Gateway.
Reserved [7:0] 0x00 HW variant byte (populated by build system per board).

OTAP Separation

OEM 0x3 ensures that a gateway firmware update does not reprogram Tag/Anchor devices (OEM 0x2) or legacy nRF52 tags (OEM 0x1), and vice versa. The Wirepas dualmcu_app reference uses 0x846B74 — we replace that with our native 0x9A06C300.

2.3 Role & Class Definitions

The Gateway firmware defaults to Sink mode. The Sink terminates the mesh and is responsible for forwarding all received data upstream.

  • Default Role: Sink - CSMA-CA (Low Latency)
  • Default Class: 249
  • Open Joining: Disabled by default.
  • Key Management: Enabled for Sink role (required by Wirepas security model).

2.4 Network Keys

  • Authentication Key: Default 0xFFFFFFFF_FFFFFFFF_FFFFFFFF_FFFFFFFF (16 bytes, 128-bit)
  • Encryption Key: Default 0xFFFFFFFF_FFFFFFFF_FFFFFFFF_FFFFFFFF (16 bytes, 128-bit)

3. Dual-MCU Architecture

The Gateway firmware is based on the Wirepas dualmcu_app reference application. The nRF54 runs the Wirepas stack and exposes its services to the ESP32-C5 via the Wirepas Dual-MCU API over UART1.

3.1 UART1 Configuration

Parameter Value Notes
TX Pin P0.03 Reassigned from SPI CLK (no accelerometer on gateway boards)
RX Pin P0.04 Reassigned from SPI MISO
Baud Rate 125000 Default from dualmcu_app; upgradable to 921600
DMA Enabled DMA UART by default (from dualmcu_app makefile)
Flow Control Disabled No HW flow control pins available

3.2 Dual-MCU API Protocol

The Wirepas Dual-MCU API multiplexes data and control on a single UART link. Three Service Access Points (SAPs) provide the interface:

SAP Purpose Key Operations
DSAP Data transfer to/from the Wirepas mesh DATA_TX (send to mesh), DATA_RX (receive from mesh)
MSAP Stack management and runtime attributes STACK_START/STOP, STACK_STATE, APP_CONFIG, SINK_COST, SCRATCHPAD, GET_NBORS
CSAP Configuration attributes (stack must be stopped) Node address, network address, channel, keys, role

Frame format:

| Octet 0 | Octet 1 | Octet 2–3    | Octet 4..N    | Octet N+1..N+2 |
|---------|---------|--------------|---------------|-----------------|
| SAP ID  | Prim ID | Payload Len  | Payload       | CRC-16-CCITT    |
  • CRC-16-CCITT (polynomial 0x1021, init 0xFFFF) over the entire frame excluding the CRC field.
  • All multi-byte fields are little-endian.

3.3 Boot Handshake Sequence

sequenceDiagram
    participant nRF54
    participant ESP32

    nRF54->>ESP32: Assert ESP32_RESET (P1.10 LOW)
    Note over nRF54: Hold reset 100ms
    nRF54->>ESP32: Release ESP32_RESET (P1.10 HIGH)
    Note over ESP32: ESP32 boots (1-3 seconds)
    ESP32->>nRF54: ESP32_READY (P2.08 HIGH)
    nRF54->>nRF54: Init Dualmcu_lib_init(125000, false)
    nRF54->>ESP32: CSAP: Push stored config (WiFi, MQTT, NTP)
    nRF54->>ESP32: MSAP: STACK_START
    Note over nRF54,ESP32: Coexistence arbiter active

If ESP32_READY does not go HIGH within 10 seconds, the nRF54 logs an error on UART0 and retries the reset sequence. After 3 failed attempts, the nRF54 continues in degraded mode (Sink operational, no IP uplink; LED2 shows RED fast-blink).

3.4 Key Management (Sink Role)

The dualmcu_app reference enables key management for Sink-role devices. When the node role is SINK_LE or SINK_LL, the firmware enables app_key_management_supported and app_key_management_configured flags. This allows the Sink to participate in Wirepas network-level key rotation.

For non-Sink roles, local provisioning from flash storage is used instead.

3.5 Coexistence Architecture

The nRF54 and ESP32-C5 share the 2.4 GHz band. A 3-wire coexistence interface is routed on the PCB for optional firmware-based arbitration (MPSL is not available in Wirepas — see note below):

Pin Signal Direction Description
P2.00 COEX_REQUEST ESP32 → nRF54 ESP32 requests 2.4 GHz airtime
P2.01 COEX_PRIORITY ESP32 → nRF54 ESP32 indicates priority level
P2.02 COEX_GRANT nRF54 → ESP32 nRF54 grants ESP32 airtime

Coexistence — Firmware TBD (Wirepas) / MPSL-Ready (nRF Connect SDK)

Nordic MPSL is not available in the Wirepas stack (Wirepas uses its own radio scheduler). When running Wirepas firmware, coexistence relies on: (1) Wirepas built-in Adaptive Frequency Avoidance (AFA), (2) <0.1% duty cycle, and (3) 5 GHz WiFi preference. A custom firmware arbiter can be implemented later if needed.

BLE / nRF Connect SDK builds: If the gateway hardware is used with a non-Wirepas firmware (e.g., BLE-only gateway using nRF Connect SDK + Zephyr), MPSL is available and the 3-wire PTA traces can be driven directly by Nordic's built-in coexistence driver. This dual-use compatibility is a key reason the traces are routed.

4. NFC Configuration (Flash Storage for Gateway)

The nRF54 is the configuration master for the entire gateway. All persistent settings — including WiFi, MQTT, and NTP parameters destined for the ESP32 — are stored in the nRF54 internal flash using TLV format. The ST25DV04K NFC EEPROM is the primary user-facing configuration interface.

4.1 NFC Interface

Same hardware as the Tag/Anchor build:

  1. I2C Interface: ST25DV04K on P1.04 (SCL) and P1.05 (SDA).
  2. Interrupts: GPO interrupt on P1.09 triggers configuration sync.
  3. TLV Format: Type-Length-Value parser reads/writes config records between NFC memory and nRF54 flash.
  4. Security: 8-character NFC PIN (default: 12345678). Each character must be printable ASCII 33–126 (no spaces, no control characters).

4.2 Configuration Flow

The nRF54 acts as a bridge between NFC and the ESP32:

graph LR
    NFC["Smartphone<br/>(CB Admin)"] -->|"NFC tap"| ST25DV["ST25DV04K<br/>EEPROM"]
    ST25DV -->|"I2C + GPO IRQ"| nRF54["nRF54L15<br/>Flash (TLV)"]
    nRF54 -->|"UART1 Dual-MCU"| ESP32["ESP32-C5"]
    ESP32 -->|"Apply config"| WIFI["WiFi / MQTT / NTP"]
    WEB["Web UI"] -->|"HTTP"| ESP32
    ESP32 -->|"UART1 config write"| nRF54

Write path (NFC → ESP32):

  1. User taps smartphone to configure WiFi SSID, MQTT broker, etc.
  2. ST25DV04K fires GPO interrupt.
  3. nRF54 reads TLV records from NFC EEPROM, validates, and writes to internal flash.
  4. nRF54 pushes updated config to ESP32 via UART1 (CSAP attribute write).
  5. ESP32 applies new settings (reconnect WiFi, restart MQTT client, etc.).

Write path (Web UI → nRF54):

  1. User configures settings via the ESP32 web UI.
  2. ESP32 sends config to nRF54 via UART1 (CSAP attribute write).
  3. nRF54 validates and persists to internal flash (single source of truth).
  4. nRF54 optionally updates NFC EEPROM so the next NFC read reflects the current state.

4.3 Flash as Single Source of Truth

The nRF54 internal flash is authoritative for all gateway configuration. The ESP32 has no persistent config store — on every boot, it receives its full configuration from the nRF54. This ensures:

  • NFC, Web UI, and CLI all converge on the same flash store.
  • Factory reset on the nRF54 (config factory-reset) also resets ESP32 settings.
  • OTAP firmware updates on the ESP32 do not lose gateway configuration.

5. Hardware Abstraction & Drivers

5.1 Visual Indication & Service Button

LED and button behavior are defined in the UI Behavior specification. Gateway boards have both LED1 and LED2 populated:

  • LED1 (SK6812MINI, index 0): System/Wirepas status — same state machine as the Tag/Anchor build (booting → no network → joined → operational).
  • LED2 (SK6812MINI, index 1): Gateway backhaul status — WiFi/MQTT connection state, ESP32 OTA indication.
  • Service button (P2.06): Same behavior as Tag/Anchor (short press = status check, 3 s hold = reboot, factory reset on power-plug-hold).
  • 0x0A LED pattern: Inherited from Tag/Anchor. PURPLE on LED1, same encoding format.

5.2 Battery Management (232203)

Identical to the Tag/Anchor build Section 4. Battery hold-up keeps the Sink operational during temporary AC power loss, maintaining mesh connectivity for downstream anchors and tags.

  • P2.03 (DC_PRESENT): LOW = DC power present, HIGH = running on battery. Source: BSS138 MOSFET sensing 5V rail.
  • P2.04 (CHARGE_STATUS): LOW = charging in progress. Source: MCP73123 STAT pin 7.
  • P2.05 (CHARGE_ENABLE): Output. Drive LOW to enable charging.

On AC loss: continue Sink operation → monitor BAT_VOLTAGE (P1.06) → when below ~2.5V, issue Wirepas leave → deep sleep.

5.3 Presence Detection (232204 — Anchor Firmware)

The 232204 (Base Bat+Radar) runs Anchor firmware, not Gateway. Presence/radar detection is handled by the Anchor build. The Gateway firmware does not apply to 232204.

The 232204 board uses SAADC-capable pins for the occupancy sensor:

Pin Channel Assignment
P1.11 AIN4 Sensor data / available
P1.13 AIN6 Sensor data / available
P1.14 AIN7 Sensor data / available
P1.08 — GPIO (ex-SPI CS)
P2.09 — GPIO (ex-ACC INT2)

The certification roadmap lists "60 GHz Radar" on 232204 as Phase 2 (C2PC). Interface type (SPI, UART, analog) and data format are TBD.

6. Configuration Data Dictionary

All persistent configuration is stored in the nRF54 internal flash using the TLV format. The Gateway build inherits the system/security and Wirepas keys from the Tag/Anchor spec and adds gateway-specific keys for WiFi, MQTT, NTP, and web UI.

6.1 System & Security

Inherited from Tag/Anchor. Same defaults and update paths.

Parameter ID Description Default Value Updatable Via
ADMIN_PIN 8-character PIN to unlock NFC writes (ASCII 33–126, no spaces) 12345678 NFC, CLI
PWR_EN Power enable/disable (virtual software switch) Enabled NFC
BTN_SHUTOFF_TO Button hold duration to shut off (0 = disabled) 0 (Disabled) NFC
BAT_HOLDUP_LATENCY Hold-up latency on AC loss before leave 300 seconds NFC, CLI

6.2 Wirepas Network

Inherited from Tag/Anchor, with role default changed to Sink.

Parameter ID Description Default Value Updatable Via
NET_ID Wirepas network address (up to 3 bytes) 56974 NFC, CLI, Web
NET_CH Wirepas RF channel 5 NFC, CLI, Web
TAG_ROLE Wirepas node role Sink - CSMA-CA LL NFC, CLI, Web
TAG_CLASS Wirepas grouping class 249 NFC, CLI, Web
TAG_ID Mesh node identifier (up to 4 bytes) 3 LSB of BT-address NFC, CLI, Web
AUTH_KEY Mesh authentication key (16 bytes) 0xFFFF... NFC, CLI, Web
ENC_KEY Mesh encryption key (16 bytes) 0xFFFF... NFC, CLI, Web
SINK_COST Sink routing cost metric (0 = preferred) 0 NFC, CLI, Web

6.3 WiFi Configuration

Stored in nRF54 flash. Pushed to ESP32 at boot and on change.

Parameter ID Description Default Value Updatable Via
GW_WIFI_EN WiFi interface enable Enabled NFC, CLI, Web
GW_WIFI_MODE WiFi mode (AP / Station) AP NFC, CLI, Web
GW_WIFI_SSID WiFi SSID ETGW-<serial> NFC, CLI, Web
GW_WIFI_PASS WiFi password (WPA2/WPA3) evertag NFC, CLI, Web
GW_WIFI_BAND Band preference (Auto / 5G / 2.4G) Auto NFC, CLI, Web
GW_WIFI_COUNTRY Regulatory country code Auto NFC, Web

6.4 MQTT Configuration

Parameter ID Description Default Value Updatable Via
GW_MQTT_BROKER MQTT broker hostname or IP (empty) NFC, CLI, Web
GW_MQTT_PORT MQTT broker port 8883 NFC, CLI, Web
GW_MQTT_USER MQTT username (empty) NFC, CLI, Web
GW_MQTT_PASS MQTT password (empty) NFC, CLI, Web
GW_MQTT_TLS MQTT TLS enable Enabled NFC, CLI, Web

6.5 NTP & System

Parameter ID Description Default Value Updatable Via
GW_NTP_SERVER NTP server hostname pool.ntp.org NFC, CLI, Web
GW_NTP_TZ Timezone string (POSIX format) UTC NFC, Web
GW_WEB_PASS Web UI login password evertag NFC, CLI, Web
GW_COEX_EN 2.4 GHz coexistence arbiter enable Enabled NFC, CLI

7. Production Debug Interface

UART0 on the TC2030 J1 connector (P0.02 TX, P2.07 RX) at 115200 baud, 8N1. The CLI provides system diagnostics and configuration access only during the initial bring-up window. After that, UART0 is disabled to reduce the risk of customers tampering with production devices.

UART0 Auto-Disables After 5 Minutes

The Gateway build follows the same policy as the Tag/Anchor firmware: UART0 and the CLI are available for approximately 5 minutes after flashing or power-on. After the 5-minute window expires, the firmware disables the UART0 peripheral and stops accepting CLI commands. This keeps production devices locked down in the field while still allowing engineering and manufacturing to run self-test and configuration during bring-up.

RF Certification Tests

Radio test commands (radio cw, radio txmod, radio rx) and peripheral test commands are not included in the production Gateway firmware. RF certification and deep diagnostics use a dedicated lab/test firmware build that keeps UART0 permanently enabled; this avoids exposing powerful radio controls in customer-facing software. See Firmware Compatibility for the test build.

7.1 Available CLI Commands

Command Purpose
variant Report detected board variant (e.g., "232202").
status Full system status (board, radio, ESP32 link, WiFi, MQTT).
version Firmware version, build date, board article.
config get <key> / config set <key> <value> Read/write config in nRF54 flash.
config dump Print all current TLV configuration settings.
config factory-reset Erase all config (including gateway settings), return to defaults.
reset System reset (nRF54 + ESP32).
esp32 status Query ESP32 link state, WiFi/MQTT connection status.
esp32 reset Reset ESP32-C5 only.
esp32 version Query ESP32 firmware version.
sink status Wirepas Sink state, neighbor count, routing info.
sink cost <value> Set Sink routing cost (0--254).
nfc read Dump NFC EEPROM content (TLV records).
adc read Read V_SAMPLE, BAT_VOLTAGE, EXT_DETECT ADC values.