EverTag Station Gateway -- Web UI Specification¶
| Product | EverTag Station WiFi / LTE Gateway (CargoBeacon) |
| Target MCU | ESP32-C5 (WiFi 6 dual-band) + nRF54L15 (Wirepas mesh) |
| Gateway Boards | 232202, 232203, 232204 |
| Status | Phase 1 (WiFi) -- active development |
Purpose of This Document
This is the authoritative firmware specification for the EverTag Station gateway web-based configuration UI. The Web UI is served by the ESP32-C5 and provides on-site configuration of WiFi connectivity, Wirepas sink parameters, MQTT broker settings, and system diagnostics -- without requiring cloud access.
The specification is organized into three development phases:
- Phase 1 -- WiFi Gateway (current project): Core WiFi connectivity, Sink, MQTT, NTP, Device status, Nodes viewer
- Phase 2 -- Remote Firmware Update (next priority): OTA for ESP32 + nRF54, remote management via custom MQTT
- Phase 3 -- LTE Gateway (future reference): Full LTE modem configuration for 232210/232211 extension boards
A shared TLV Configuration Parameter Registry underpins all configuration entry points (Web UI, NFC multi-tap, CLI, remote MQTT push).
1. Architecture Overview¶
The EverTag Station gateway uses a dual-MCU architecture:
- nRF54L15 -- Wirepas mesh sink, BLE, NFC (ST25DV04K), coexistence arbiter, configuration master (flash storage)
- ESP32-C5 -- WiFi radio (2.4 GHz + 5 GHz), web server, MQTT client, LTE modem control (Phase 3)
The ESP32-C5 serves a single-page application (SPA) web UI accessible via:
- WiFi AP mode (commissioning): connect to the gateway's SSID
ETGW-<serial>, browse to192.168.4.1 - WiFi Station mode (production): browse to the DHCP-assigned IP or
ETGW-<serial>.local(mDNS)
Authentication is a single password prompt on the login page. The default password is evertag.
After login, the UI presents top-level tabs in a left sidebar:
| Tab | Purpose | Phase |
|---|---|---|
| Device | Read-only device information, service status, diagnostics, network interfaces | 1 |
| Configuration | All configurable settings (WiFi, Sink, MQTT, NTP) | 1 |
| Nodes | Live Wirepas mesh packet viewer | 1 |
| Firmware Update | OTA firmware and UI update | 2 |
| Remote Management | Fleet management via secondary MQTT broker | 2 |
| LTE | LTE modem configuration (when extension board detected) | 3 |
The header bar shows the product name ("EverTag Station") and the gateway hostname (e.g. ETGW-00a1b2c3d4e5f6).
graph LR
BROWSER["Browser"] -->|"WiFi"| ESP32["ESP32-C5<br/>Web UI + MQTT"]
ESP32 -->|"UART1: Dual-MCU API"| NRF54["nRF54L15<br/>Config Master"]
NRF54 -->|"Wirepas Mesh"| MESH["Tags / Anchors"]
NRF54 -->|"I2C"| NFC["ST25DV04K<br/>NFC Config"]
ESP32 -->|"WiFi / LTE"| CLOUD["MQTT Broker"]
ESP32 -->|"UART2 + GPIO"| LTE["SIM7672x<br/>LTE Modem"]2. Phase 1 -- WiFi Gateway¶
2.1 Device Tab (Status & Diagnostics)¶
The Device tab is the landing page after login. It provides read-only status information in card sections.
Information¶
| Field | Example Value | Description |
|---|---|---|
| Hostname | ETGW-00a1b2c3d4e5f6 |
Derived from ESP32-C5 MAC address |
| Model | wifi / wifi-bat / full |
Board variant (232202 / 232203 / 232204) |
| ESP32 FW Version | 1.0.0.100 (release) |
ESP32-C5 application firmware |
| nRF54 FW Version | 1.0.0.50 |
nRF54L15 firmware (received via UART1) |
| UI Version | 1.0.0.1 |
Web UI build version |
| Wirepas Stack | 5.x.y.z |
Wirepas mesh stack version (from nRF54) |
| OS Version | 5.5.x |
ESP-IDF version |
| System time | 2026-02-16 21:57:13 |
Current date/time (NTP-synced) |
| Uptime | 24 days, 5 hours, 34 min |
Time since last boot |
| Timezone | UTC |
System timezone |
Status¶
Shows the operational state of the gateway's core services with colour-coded indicators:
| Status Indicator | Meaning |
|---|---|
| Sink service running | Wirepas sink service active on nRF54 |
| Sink configured | Sink has valid config (network address, channel, keys) |
| Sink stack running / not running | Wirepas stack state |
| Transport service (MQTT) running / not running | MQTT client connection state |
| Coexistence active | 2.4 GHz coexistence arbitration enabled |
When MQTT is in error state, additional detail is shown:
- Error type: e.g.
MQTT_ERROR_TYPE_TCP_TRANSPORT - TLS Error: e.g.
ESP_ERR_ESP_TLS_CANNOT_RESOLVE_HOSTNAME - Socket Error: e.g.
EINPROGRESS
Diagnostics (expandable)¶
A "Show diagnostics" button expands additional timing and queue metrics:
| Field | Description |
|---|---|
| Last Network Down | Timestamp of last network loss |
| Last Network Up | Timestamp of last network gain |
| Mesh Last packet received | Last Wirepas mesh packet timestamp |
| MQTT Last connection attempt | Last MQTT connect attempt |
| MQTT Last successful connection | Last successful MQTT session |
| MQTT Last disconnection | Last MQTT disconnect |
| MQTT Last topic subscription | Last successful subscription |
| MQTT Last received request | Last downlink request from broker |
| MQTT Last successful publishing | Last successful uplink publish |
| State | Internal state machine state |
| MQTT Mesh packets queue usage | Uplink queue fill level (%) |
| MQTT Requests queue usage | Downlink request queue fill level (%) |
| MQTT Responses queue usage | Downlink response queue fill level (%) |
Network Interfaces¶
| Name | Enabled | Mode | MAC Address | IP Address | Netmask | Gateway IP | DNS |
|---|---|---|---|---|---|---|---|
| wlan | true | AP / STA | xx:xx:xx:xx:xx:xx |
192.168.4.1 |
255.255.255.0 |
-- | -- |
| lte | (Phase 3) | -- | -- | -- | -- | -- | -- |
A "Check internet connection" button tests outbound connectivity.
Identifiers¶
| Field | Example Value | Description |
|---|---|---|
| ESP32 Model | ESP32-C5 |
SoC model |
| ESP32 Revision | 0 |
Silicon revision |
| ESP32 Serial | 00a1b2c3d4e5f6 |
Unique chip ID (MAC-derived) |
| nRF54 Serial | (from UART1) | nRF54L15 device ID |
| Gateway ID | ETGW-00a1b2c3d4e5f6 |
Wirepas gateway identifier (used in MQTT topics) |
| Sink ID | sink0 |
Wirepas sink identifier |
| Board Article | 232202 |
Detected board variant (from V_SAMPLE ADC) |
| Extension | None / 232210 / 232211 |
Detected extension board (from EXT_DETECT ADC) |
2.2 Configuration Tab¶
The Configuration tab contains sub-sections accessible via a chip menu: WiFi, Sink, MQTT, NTP. Phase 2 adds Remote Management. Phase 3 adds LTE. Each section has a Save button.
2.2.1 WiFi Configuration¶
| Setting | Type | Default / Example | Description |
|---|---|---|---|
| Enabled | Toggle | On | Enable/disable WiFi interface |
| Mode | Dropdown | Access Point | WiFi operating mode (see table) |
| Band preference | Dropdown | Auto | WiFi band selection (see table) |
| SSID | Text | ETGW-<serial> |
Network name (AP: broadcast; Station: target) |
| AP Hidden | Toggle | Off | Hide SSID in AP mode |
| AP Timeout (min) | Number | 0 | Auto-disable AP after timeout (0 = never) |
| Password | Text | evertag |
WiFi password (WPA2/WPA3) |
| Password confirm | Text | -- | Confirmation field |
| DHCP | Toggle | On | DHCP client (Station) / server (AP) |
| Country code | Dropdown | Auto | Regulatory domain (affects channel availability) |
WiFi Mode options:
| Mode | Description |
|---|---|
| Access Point | Gateway creates its own WiFi network. Default for commissioning. |
| Station | Gateway joins an existing WiFi network. Used for production deployment. |
Band Preference options:
| Option | wifi_band_mode_t |
Description |
|---|---|---|
| Auto | WIFI_BAND_MODE_AUTO |
Dual-band, auto-select. Preferred default. |
| 5 GHz only | WIFI_BAND_MODE_5G_ONLY |
Avoids 2.4 GHz Wirepas interference. Best for production. |
| 2.4 GHz only | WIFI_BAND_MODE_2G_ONLY |
Legacy compatibility. Not recommended (coex overhead). |
5 GHz Preferred for Production
When the gateway operates near Wirepas mesh nodes (2.4 GHz), selecting 5 GHz only or Auto (which prefers 5 GHz when available) eliminates the need for time-domain coexistence arbitration between WiFi and Wirepas. The nRF54 coexistence arbiter (3-wire MPSL) is still active as a fallback when 2.4 GHz WiFi is in use.
2.2.2 Sink Configuration (Wirepas Mesh)¶
This is the most critical configuration section. It controls the Wirepas mesh sink behaviour on the nRF54. All changes are sent to nRF54 via UART1 Dual-MCU API.
Configurable Properties:
| Setting | Type | Default / Example | Options / Range | Description |
|---|---|---|---|---|
| Stack mode | Dropdown | Sink enabled on network up | See table below | Controls when the Wirepas stack starts |
| Node address | Number | 70001 |
1--4294967295 | Unique Wirepas node address for this sink |
| Node Role | Dropdown | CSMA-CA Sink (Low Latency) | See table below | Wirepas node role |
| Network address | Number | 70000 |
1--16777215 | Wirepas mesh network identifier |
| Network channel | Number | 5 |
1--40 | RF channel for the mesh network |
| Sink cost | Number | 0 |
0--254 | Routing cost metric (0 = preferred sink) |
| CipherKey | Key editor | Not set | 128-bit hex | Wirepas network encryption key |
| AuthenticationKey | Key editor | Not set | 128-bit hex | Wirepas network authentication key |
Stack Mode options:
| Option | Description |
|---|---|
| Sink enabled on network up | Start Wirepas stack when WiFi (or LTE) becomes available. Stop when all interfaces go down. |
| Sink permanently enabled | Start immediately on boot. Mesh data is buffered locally if MQTT is unavailable. |
| Sink permanently disabled | Do not start the Wirepas stack. Gateway operates as a configuration portal only. |
| Sink enabled on active MQTT Connection | Start only when MQTT connection is confirmed. Most conservative -- avoids data loss. |
Node Role options:
| Option | Description |
|---|---|
| CSMA-CA Sink (Low Latency) | Gateway acts as a Wirepas sink with low-latency routing. Default for gateways. |
| CSMA-CA Router Node (Low Latency) | Gateway acts as a relay/router only (does not consume mesh data). Useful for range extension. |
Stored AppConfig (read-only):
| Field | Description |
|---|---|
| Sequence number | AppConfig sequence (increments on change; nodes accept only higher sequences) |
| Diagnostics interval | Seconds between diagnostic reports from mesh nodes |
| AppConfig | Raw application configuration payload (hex) broadcast to the mesh |
Readonly Properties (from Wirepas stack on nRF54):
| Property | Description |
|---|---|
| StackProfile | Wirepas stack profile identifier |
| HwMagic | Hardware platform identifier |
| MaxMtu | Maximum transmission unit (bytes) |
| ChRangeMin / ChRangeMax | Supported channel range |
| ACRangeMin / ACRangeMax | Access cycle range (microseconds) |
| PDUBufferSize | Protocol data unit buffer depth |
| AppConfigMaxSize | Maximum AppConfig payload size (bytes) |
| FirmwareVersion | Wirepas stack firmware version |
| CurrentAC | Current access cycle |
| StackStatus | Stack state code |
2.2.3 MQTT Configuration¶
Basic Settings:
| Setting | Type | Default / Example | Description |
|---|---|---|---|
| Enabled | Toggle | On | Enable/disable MQTT transport |
| Protocol | Dropdown | mqtts:// |
Connection protocol (see table) |
| URI (hostname) | Text | mqtt.cargobeacon.com |
MQTT broker hostname |
| Port | Number | 8883 |
Broker port |
| Keep alive (sec) | Number | 60 | MQTT keep-alive interval |
Advanced Settings (hidden by default):
| Setting | Type | Default | Description |
|---|---|---|---|
| Data encoding | Dropdown | Protobuffer | Wirepas data encoding on MQTT topics |
| Network timeout (sec) | Number | 30 | TCP connection timeout |
| Message retransmit timeout (sec) | Number | 10 | MQTT QoS retransmit interval |
| Reconnect timeout (sec) | Number | 5 | Delay before reconnection attempt |
Credentials:
| Setting | Type | Default | Description |
|---|---|---|---|
| Use credentials | Toggle | Off | Enable username/password authentication |
| Username | Text | (empty) | MQTT username |
| Password | Text | (empty) | MQTT password |
| Password confirm | Text | (empty) | Confirmation field |
TLS / Certificate Management:
| Setting | Type | Description |
|---|---|---|
| CA Certificate | PEM upload + cloud download | Server CA certificate for TLS validation |
| Use client certificate | Toggle | Enable mutual TLS (mTLS) |
| Client Certificate | PEM file upload | Client certificate for mTLS |
| Client private key | PEM file upload | Client private key |
| Use certificate password | Toggle | Enable password-protected private key |
| Client key password | Text | Private key passphrase |
MQTT Protocol options:
| Protocol | URI Scheme | TLS | Description |
|---|---|---|---|
| mqtts | mqtts:// |
Yes | MQTT over TLS (port 8883). Recommended for production. |
| mqtt | mqtt:// |
No | Plain MQTT (port 1883). Local/testing only. |
| wss | wss:// |
Yes | MQTT over WebSocket with TLS. For firewall-restricted environments. |
| ws | ws:// |
No | MQTT over WebSocket. Testing only. |
Data encoding options:
| Option | Description |
|---|---|
| Protobuffer | Standard Wirepas Protobuf encoding. Most efficient, lowest bandwidth. Default. |
| JSON | Human-readable JSON. Useful for debugging and non-Wirepas-native platforms. |
| Protobuffer + JSON | Dual encoding on separate topics. Useful during migration. |
2.2.4 NTP Configuration¶
| Setting | Type | Default / Example | Description |
|---|---|---|---|
| Enabled | Toggle | On | Enable NTP time synchronization |
| NTP Server | Text | pool.ntp.org |
NTP server hostname |
| Synchronization interval | Slider | 24 hours | Sync frequency (5 min -- 24 hours) |
2.2.5 EverTag-Specific Settings¶
Settings not found on the reference design that the EverTag gateway adds:
| Setting | Section | Description |
|---|---|---|
| WiFi band preference | WiFi | 2.4 GHz / 5 GHz / Auto (minimize Wirepas coex interference) |
| Country code | WiFi | Regulatory domain for channel/power compliance |
| Coexistence mode | Device | Display 2.4 GHz coexistence state (nRF54 MPSL arbiter) |
| Battery status | Device | Battery voltage, charge state (232203/232204 only) |
| LED behaviour | Configuration | LED1 (system) and LED2 (gateway) brightness, patterns |
| NFC commissioning status | Device | ST25DV04K tag content, last NFC config event |
| nRF54 firmware info | Device | Firmware + Wirepas stack version (via UART1) |
| Board variant | Device | Detected article number + extension board |
| Debug log level | Configuration | ESP-IDF / application log verbosity |
| Factory reset | Configuration | Button to erase all config, return to defaults |
2.3 Nodes Tab (Mesh Packet Viewer)¶
A live table of Wirepas mesh packets received by the gateway sink, pushed via WebSocket. A "Clear received messages" button resets the table.
| Column | Description |
|---|---|
| Date/time | Timestamp when the packet was received |
| Source address | Wirepas node address of the sender |
| Destination address | Wirepas destination address |
| Source EP | Source endpoint number |
| Destination EP | Destination endpoint number |
| Hop count | Number of mesh hops from source to sink |
| Travel time | Time from transmission to reception |
| Data | Raw payload (hex) |
When no messages are available: "No message received".
Planned Enhancements
Consider adding filtering by source address, endpoint, or time range. Add a packet count summary and rate indicator (packets/sec).
3. Phase 2 -- Remote Firmware Update & Management¶
3.1 Firmware Update Tab¶
The Firmware Update tab supports three independent OTA channels:
| Channel | Target | Source | Method |
|---|---|---|---|
| ESP32 Firmware | ESP32-C5 application | CargoBeacon cloud or local file | esp_https_ota -- HTTPS download, A/B partition, rollback |
| ESP32 UI Assets | Web UI (SPIFFS/LittleFS) | CargoBeacon cloud or local file | Partition write from downloaded archive |
| nRF54 Firmware | nRF54L15 application + Wirepas stack | CargoBeacon cloud or local file | ESP32 downloads, relays via UART1 bridge to nRF54 DFU |
Each channel displays:
| Field | Description |
|---|---|
| Current version | Installed firmware version |
| Available version | Latest version from update source |
| Release date | Build date |
| Size | Download size |
| Change log | Release notes (expandable) |
An Update button triggers download and installation. A Upload file button allows local file upload for offline environments.
3.2 Remote Management¶
A dual-broker MQTT architecture separates Wirepas data transport from fleet management. The management broker handles configuration push, OTA triggers, remote reboot, and diagnostics collection.
Basic Settings:
| Setting | Type | Default | Description |
|---|---|---|---|
| Enabled | Toggle | Off | Enable remote management channel |
| Protocol | Dropdown | mqtts:// |
Connection protocol (same options as data MQTT) |
| URI (hostname) | Text | (empty) | Management MQTT broker hostname |
| Port | Number | 8883 |
Broker port |
| Keep alive (sec) | Number | 60 | MQTT keep-alive interval |
Advanced Settings (hidden by default):
| Setting | Type | Default | Description |
|---|---|---|---|
| Network timeout (sec) | Number | 30 | TCP connection timeout |
| Message retransmit timeout (sec) | Number | 10 | MQTT QoS retransmit interval |
| Reconnect timeout (sec) | Number | 5 | Delay before reconnection attempt |
Credentials and TLS -- identical structure to primary MQTT (username/password, CA cert, client cert, mTLS, key password).
Management MQTT Topics (custom schema):
| Topic Pattern | Direction | Purpose |
|---|---|---|
etgw/<gw-id>/cmd/config |
Cloud -> Gateway | Push configuration changes |
etgw/<gw-id>/cmd/ota |
Cloud -> Gateway | Trigger OTA update (target + URL) |
etgw/<gw-id>/cmd/reboot |
Cloud -> Gateway | Remote reboot |
etgw/<gw-id>/cmd/diag |
Cloud -> Gateway | Request diagnostic dump |
etgw/<gw-id>/status |
Gateway -> Cloud | Status report (versions, uptime, connectivity) |
etgw/<gw-id>/diag |
Gateway -> Cloud | Diagnostic data response |
etgw/<gw-id>/ota/progress |
Gateway -> Cloud | OTA progress and result |
4. Phase 3 -- LTE Gateway (Future Reference)¶
Future Phase
LTE is not part of the current WiFi gateway project. This section is included as a future reference for the 232210/232211 extension boards. LTE UI elements are hidden unless an extension board is detected via the EXT_DETECT ADC pin (P1.12).
4.1 LTE Modem Architecture¶
Per ADR #12, ESP32 manages the LTE modem directly (not nRF54):
- ESP32 communicates with the SIM7672E/NA via UART2 (AT commands) and GPIO (POWER_KEY, RESET, STATUS, NETLIGHT, TX_BLANK)
- All signals route through the Harwin M20 B2B connector to the extension board, where 1.8V/3.3V level shifting occurs
- nRF54 has zero direct connection to the LTE modem
- Data flow:
Wirepas mesh -> nRF54 -> UART1 -> ESP32 -> WiFi or LTE (ESP32 decides routing) - ESP32 manages WiFi/LTE coexistence via TX_BLANK GPIO with sub-millisecond latency
The esp_modem component (Espressif managed component, esp-protocols repo) provides AT command abstraction, PPP data mode, and CMUX multiplexing. SIM7672 support is added by subclassing GenericModule.
4.2 LTE Configuration¶
When LTE is disabled, shows "Disabled" only. When enabled:
Basic Settings:
| Setting | Type | Default | Description |
|---|---|---|---|
| Enabled | Toggle | Off | Enable/disable LTE modem |
| APN | Text | (empty) | Access Point Name for the mobile operator |
| PIN | Text | (empty) | SIM card PIN code (if PIN-locked) |
Advanced Settings (hidden by default):
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Network Scan Mode | Dropdown | -- | GSM and LTE, GSM Only, LTE Only | Radio access technologies to scan |
| IoT Operation Mode | Dropdown | -- | LTE-M Only, NB-IoT Only, LTE-M and NB-IoT | IoT network mode preference |
| Network Scan Sequence | Dropdown | Auto | Auto, GSM First, LTE-M First, NB-IoT First | RAT scan order during registration |
| GSM Bands | Multi-choice | (from modem) | Band list from modem query | Allowed GSM frequency bands |
| LTE Bands | Multi-choice | (from modem) | Band list from modem query | Allowed LTE frequency bands |
| NB-IoT Bands | Multi-choice | (from modem) | Band list from modem query | Allowed NB-IoT frequency bands |
APN Credentials (optional):
| Setting | Type | Default | Options | Description |
|---|---|---|---|---|
| Use credentials | Toggle | Off | -- | Enable APN authentication |
| Authentication type | Dropdown | PAP | PAP, CHAP, MSCHAP, MSCHAP V2 | APN auth protocol |
| Username | Text | (empty) | -- | APN username |
| Password | Text | (empty) | -- | APN password |
DNS Configuration:
| Setting | Type | Default | Description |
|---|---|---|---|
| DNS 1 | Text | (empty) | Primary DNS (overrides operator DNS) |
| DNS 2 | Text | (empty) | Secondary DNS |
4.3 LTE Status on Device Tab¶
When the LTE extension is detected, the Device tab shows additional sections:
Modem Information:
| Field | Description |
|---|---|
| Model | Modem model string (SIM7672E / SIM7672NA) |
| IMEI | International Mobile Equipment Identity |
| IMSI | International Mobile Subscriber Identity |
| Firmware Version | Modem firmware revision |
| Error | Error string if modem not detected |
Mobile Network Status:
| Field | Description |
|---|---|
| Registration status | Network registration state |
| Packet Domain Status | Data service attach state |
| Operator | Carrier name |
| Access Technology | LTE, NB-IoT, etc. |
| Signal Strength (RSSI) | Received signal strength |
| RSRP | Reference Signal Received Power |
| RSRQ | Reference Signal Received Quality |
| SINR | Signal-to-Interference-plus-Noise Ratio |
| Data | Upload / download byte counters |
5. NFC Multi-Tap Configuration¶
NFC configuration is an nRF54-only feature -- it does not depend on the ESP32 or Web UI. The ST25DV04K NFC tag is present on every Station board (even non-gateway 232200/232201).
5.1 Advantages Over Web UI¶
| Advantage | Detail |
|---|---|
| No WiFi needed | Works without powering up the ESP32 or joining a network |
| Works on all boards | Available on 232200/232201 (non-gateway) for anchor configuration |
| Factory provisioning | Configure devices before ESP32 firmware is loaded |
| Fast field deployment | Tap-and-go workflow: select preset on phone, tap gateway, done |
| Offline capable | Phone app stores configuration presets locally |
5.2 NFC Multi-Tap Flow¶
sequenceDiagram
participant Tech as Technician Phone
participant NFC as ST25DV04K
participant nRF54 as nRF54L15
participant ESP32 as ESP32-C5
Tech->>Tech: Select network preset in app
Tech->>NFC: Tap 1: Write TLV config records
NFC-->>nRF54: GPO interrupt (RF activity)
nRF54->>NFC: I2C read new config TLV
nRF54->>nRF54: Validate and store in flash
nRF54->>nRF54: Apply nRF54-local config (Wirepas, BLE)
nRF54->>ESP32: UART1: CONFIG_APPLY (WiFi, MQTT, NTP records)
ESP32->>ESP32: Apply config, restart WiFi/MQTT
Tech->>NFC: Tap 2 (optional): Read back status
NFC-->>Tech: Confirm config applied successfully5.3 Conflict Resolution¶
When NFC config arrives while the Web UI has unsaved changes:
- nRF54 flash is the single source of truth (ADR #18)
- NFC write wins -- nRF54 stores the new config and pushes it to ESP32
- ESP32 RAM cache is overwritten with the new config from nRF54
- Web UI reflects the updated values on next page refresh
5.4 Development Timeline¶
NFC multi-tap and Web UI Phase 1 share the same TLV config parameter set. The TLV registry definition is the shared prerequisite.
Timeline: ─────────────────────────────────────────────────────────>
nRF54 FW: [TLV config registry]──[NFC multi-tap]──[gateway sink]──[LTE AT cmds]
ESP32 FW: [Web UI Phase 1: WiFi+Sink+MQTT]──[Phase 2: OTA]──[Phase 3: LTE]
Phone App: [NFC config app]
6. TLV Configuration Parameter Registry¶
All configuration entry points (Web UI, NFC, CLI, remote MQTT push) use a shared TLV (Type-Length-Value) format. The nRF54 flash stores the canonical copy. When forwarding to ESP32, nRF54 sends only the records relevant to WiFi, MQTT, NTP, and gateway operation.
6.1 Phase 1 Parameters (WiFi Gateway)¶
| Type ID | Name | Length | Encoding | Description |
|---|---|---|---|---|
0x01 |
WIFI_ENABLED |
1 | bool | WiFi interface enabled |
0x02 |
WIFI_MODE |
1 | enum: 0=AP, 1=STA | WiFi operating mode |
0x03 |
WIFI_SSID |
1--32 | UTF-8 string | SSID (AP broadcast or STA target) |
0x04 |
WIFI_PASSWORD |
1--63 | UTF-8 string | WiFi password (WPA2/WPA3) |
0x05 |
WIFI_BAND |
1 | enum: 0=Auto, 1=2.4G, 2=5G | Band preference |
0x06 |
WIFI_HIDDEN |
1 | bool | Hide SSID in AP mode |
0x07 |
WIFI_AP_TIMEOUT |
2 | uint16, minutes | AP auto-disable timeout (0=never) |
0x08 |
WIFI_DHCP |
1 | bool | DHCP enabled |
0x09 |
WIFI_COUNTRY |
2 | ISO 3166-1 alpha-2 | Regulatory domain |
0x10 |
SINK_STACK_MODE |
1 | enum: 0--3 | Wirepas stack start mode |
0x11 |
SINK_NODE_ADDR |
4 | uint32 | Wirepas node address |
0x12 |
SINK_NODE_ROLE |
1 | enum: 0=Sink, 1=Router | Wirepas node role |
0x13 |
SINK_NET_ADDR |
3 | uint24 | Wirepas network address |
0x14 |
SINK_NET_CHANNEL |
1 | uint8 (1--40) | Wirepas RF channel |
0x15 |
SINK_COST |
1 | uint8 (0--254) | Routing cost metric |
0x16 |
SINK_CIPHER_KEY |
16 | 128-bit raw | Wirepas encryption key |
0x17 |
SINK_AUTH_KEY |
16 | 128-bit raw | Wirepas authentication key |
0x20 |
MQTT_ENABLED |
1 | bool | MQTT transport enabled |
0x21 |
MQTT_PROTOCOL |
1 | enum: 0=mqtts, 1=mqtt, 2=wss, 3=ws | Connection protocol |
0x22 |
MQTT_HOST |
1--128 | UTF-8 string | Broker hostname |
0x23 |
MQTT_PORT |
2 | uint16 | Broker port |
0x24 |
MQTT_KEEPALIVE |
2 | uint16, seconds | Keep-alive interval |
0x25 |
MQTT_USERNAME |
0--128 | UTF-8 string | MQTT username |
0x26 |
MQTT_PASSWORD |
0--128 | UTF-8 string | MQTT password |
0x27 |
MQTT_DATA_ENC |
1 | enum: 0=Protobuf, 1=JSON, 2=Both | Data encoding format |
0x28 |
MQTT_CA_CERT |
0--4096 | PEM blob | CA certificate |
0x29 |
MQTT_CLIENT_CERT |
0--4096 | PEM blob | Client certificate (mTLS) |
0x2A |
MQTT_CLIENT_KEY |
0--4096 | PEM blob | Client private key |
0x30 |
NTP_ENABLED |
1 | bool | NTP sync enabled |
0x31 |
NTP_SERVER |
1--128 | UTF-8 string | NTP server hostname |
0x32 |
NTP_INTERVAL |
2 | uint16, minutes | Sync interval |
6.2 Phase 3 Parameters (LTE -- Future Reference)¶
| Type ID | Name | Length | Encoding | Description |
|---|---|---|---|---|
0x40 |
LTE_ENABLED |
1 | bool | LTE modem enabled |
0x41 |
LTE_APN |
1--64 | UTF-8 string | Access Point Name |
0x42 |
LTE_PIN |
0--8 | UTF-8 string | SIM PIN code |
0x43 |
LTE_SCAN_MODE |
1 | enum: 0=GSM+LTE, 1=GSM, 2=LTE | Network scan mode |
0x44 |
LTE_IOT_MODE |
1 | enum: 0=LTE-M, 1=NB-IoT, 2=Both | IoT operation mode |
0x45 |
LTE_SCAN_SEQ |
1 | enum: 0=Auto, 1=GSM, 2=LTE-M, 3=NB-IoT | Scan sequence |
0x46 |
LTE_BANDS_GSM |
var | bitmask | Allowed GSM bands |
0x47 |
LTE_BANDS_LTE |
var | bitmask | Allowed LTE bands |
0x48 |
LTE_BANDS_NBIOT |
var | bitmask | Allowed NB-IoT bands |
0x49 |
LTE_AUTH_TYPE |
1 | enum: 0=PAP, 1=CHAP, 2=MSCHAP, 3=MSCHAPv2 | APN auth protocol |
0x4A |
LTE_USERNAME |
0--64 | UTF-8 string | APN username |
0x4B |
LTE_PASSWORD |
0--64 | UTF-8 string | APN password |
0x4C |
LTE_DNS1 |
0--45 | UTF-8 string | Primary DNS |
0x4D |
LTE_DNS2 |
0--45 | UTF-8 string | Secondary DNS |
6.3 Remote Management Parameters (Phase 2)¶
| Type ID | Name | Length | Encoding | Description |
|---|---|---|---|---|
0x50 |
RMGMT_ENABLED |
1 | bool | Remote management enabled |
0x51 |
RMGMT_PROTOCOL |
1 | enum | Management broker protocol |
0x52 |
RMGMT_HOST |
1--128 | UTF-8 string | Management broker hostname |
0x53 |
RMGMT_PORT |
2 | uint16 | Management broker port |
0x54 |
RMGMT_USERNAME |
0--128 | UTF-8 string | Management broker username |
0x55 |
RMGMT_PASSWORD |
0--128 | UTF-8 string | Management broker password |
0x56 |
RMGMT_CA_CERT |
0--4096 | PEM blob | Management broker CA cert |
7. ESP-IDF Component Map¶
This section maps each Web UI feature to the ESP-IDF v5.5.x component or API that implements it. This serves as the implementation reference for firmware developers.
7.1 Direct Reuse (no custom code)¶
| Feature | ESP-IDF Component | Key APIs | Notes |
|---|---|---|---|
| WiFi band selection | esp_wifi |
esp_wifi_set_band_mode(wifi_band_mode_t) |
WIFI_BAND_MODE_AUTO, _2G_ONLY, _5G_ONLY |
| WiFi protocol | esp_wifi |
esp_wifi_set_protocol(), esp_wifi_set_protocols() |
Per-band: b/g/n/ax (2.4G), a/n/ac/ax (5G) |
| WiFi bandwidth | esp_wifi |
esp_wifi_set_bandwidth(), esp_wifi_set_bandwidths() |
HT20 / HT40 per interface |
| WiFi channel | esp_wifi |
esp_wifi_set_channel() |
5 GHz secondary auto-determined |
| WiFi country/regulatory | esp_wifi |
esp_wifi_set_country_code() |
wifi_country_t: cc, schan, nchan, max_tx_power |
| WiFi power save | esp_wifi |
esp_wifi_set_ps() |
NONE, MIN_MODEM, MAX_MODEM |
| WiFi mode (AP/STA) | esp_wifi |
esp_wifi_set_mode(), esp_wifi_set_config() |
STA, AP, STA+AP; SSID, password, auth, retry |
| WiFi security | esp_wifi |
Built-in | WPA2, WPA3, WPA⅔-Enterprise, WPS, DPP |
| WiFi scanning | esp_wifi |
esp_wifi_scan_start(), esp_wifi_scan_get_ap_records() |
RSSI, auth mode, channel, band per result |
| HTTP server | esp_http_server |
httpd_start(), httpd_register_uri_handler() |
GET/POST/PUT/WebSocket, persistent connections |
| Static file serving | esp_http_server + SPIFFS/LittleFS |
Partition-based | HTML/JS/CSS assets compiled into partition |
| Persistent settings | nvs_flash |
nvs_set_*(), nvs_get_*() |
Key-value, typed, survives OTA |
| MQTT client | esp_mqtt |
esp_mqtt_client_init(), esp_mqtt_client_start() |
MQTT 3.1.⅕.0, TLS/mTLS, QoS 0/½, dual connections |
| NTP sync | esp_sntp |
esp_sntp_setservername(), esp_sntp_init() |
Configurable server and interval |
| mDNS | mdns |
mdns_hostname_set() |
ETGW-<serial>.local resolution |
| OTA (ESP32) | esp_https_ota |
esp_https_ota_begin(), esp_https_ota_perform() |
HTTPS download, A/B partition, rollback |
| WiFi provisioning | wifi_prov_mgr |
wifi_prov_mgr_start_provisioning() |
SoftAP or BLE, QR code support |
| LTE modem (Phase 3) | esp_modem |
esp_modem_new(), esp_modem_set_mode() |
AT abstraction, PPP, CMUX; subclass GenericModule for SIM7672 |
7.2 Custom Development Required¶
| Feature | What's Custom | ESP-IDF Base |
|---|---|---|
| Web UI frontend (HTML/JS/CSS) | All UI pages, forms, layout | esp_http_server serves files |
| Dual-MCU UART protocol | nRF54 <-> ESP32 config sync, Wirepas data relay | driver/uart.h |
| TLV config registry | Schema definition, encode/decode library | NVS for storage |
| Wirepas packet viewer | Parse/display mesh data from nRF54 | WebSocket for real-time push |
| 2.4 GHz coexistence | nRF54-driven PTA via 3-wire MPSL | esp_coex hooks |
| NFC multi-tap config | ST25DV I2C read, TLV decode, config apply | N/A (nRF54 side) |
| Remote management topics | Custom MQTT topic schema, command handling | esp_mqtt client |
| nRF54 OTA via UART bridge | Firmware relay ESP32 -> nRF54 via UART1 | esp_https_ota for download |
| LTE modem extensions | SIM7672 AT commands, band/IoT config, failover | esp_modem GenericModule subclass |
| NETLIGHT decode | Blink-pattern timing decode for LED2 | GPIO + timer |
7.3 ESP-IDF Coverage Summary¶
| Web UI Section | Reuse % | Notes |
|---|---|---|
| WiFi Configuration | 95% | Band, protocol, scan, country, security built-in; only HTML form is custom |
| Sink Configuration | 0% | Wirepas-specific, custom Dual-MCU protocol to nRF54 |
| MQTT Configuration | 80% | esp_mqtt handles connections, TLS, credentials; custom: topic schema |
| NTP Configuration | 95% | esp_sntp handles everything; only HTML form is custom |
| Device Status | 30% | ESP32 system APIs for MAC/IP/uptime; nRF54 info via UART |
| Firmware Update | 70% | esp_https_ota for ESP32; custom: nRF54 UART bridge |
| Remote Management | 60% | esp_mqtt dual-connection; custom: topic schema, commands |
| LTE (Phase 3) | 60% | esp_modem for AT/PPP; custom: SIM7672 extensions, failover |
8. Architecture Mapping (Dual-MCU)¶
| Function | ESP32-C5 | nRF54L15 |
|---|---|---|
| Web server | Hosts SPA, serves HTML/JS/CSS | -- |
| WiFi radio | 2.4 GHz + 5 GHz WiFi 6 | -- |
| Wirepas mesh | -- | Sink / anchor role |
| MQTT client | Data uplink + management | -- |
| Config storage | RAM cache (volatile) | Flash (single source of truth) |
| Config entry: Web UI | Receives form data, sends to nRF54 via UART1 | Stores in flash, ACKs |
| Config entry: NFC | -- | Reads ST25DV via I2C, stores in flash, forwards to ESP32 |
| Config entry: CLI | -- | Parses UART0, stores in flash, forwards to ESP32 |
| Coexistence | Requests 2.4 GHz airtime | Arbiter (MPSL), grants/denies |
| LTE modem (Phase 3) | AT commands via UART2, GPIO control | -- |
| OTA: ESP32 | Downloads + applies | -- |
| OTA: nRF54 | Downloads, relays via UART1 | Receives, applies DFU |
Appendix A: Reference Device Data (BlueUp TinyGateway LTE)
This appendix preserves the original reference device details for traceability. The EverTag gateway specification was initially informed by analysis of this commercial Wirepas gateway.
| Property | Value |
|---|---|
| Manufacturer | BlueUp Srl |
| Product | TinyGateway LTE Wirepas |
| CPU | ESP32-S3 rev 0 |
| Gateway ID | BTGW-000048ca439ddcdc |
| Access URL | http://10.0.20.219/ (Ethernet) or http://192.168.4.1/ (WiFi AP) |
| Default password | blueup |
| WiFi AP SSID | tinygateway-dcdd |
| WiFi AP password | tinygateway |
| FW Version | 1.7.0.398 (release) |
| UI Version | 2.1.1.123 |
| Wirepas Stack | 5.3.0.89 |
| MQTT Broker | mqtts://prod-1.tagfinder.com:8883 |
| NTP Server | pool.ntp.org |
Key differences from EverTag:
| BlueUp (ESP32-S3) | EverTag (ESP32-C5 + nRF54L15) |
|---|---|
| Single MCU runs web server + Wirepas sink | Dual-MCU: ESP32-C5 (web/WiFi/MQTT) + nRF54 (Wirepas/BLE/NFC) |
| Direct Wirepas stack access | ESP32 proxies config to nRF54 via Dual-MCU API UART |
| Includes Ethernet interface | No Ethernet on EverTag hardware |
| LTE modem controlled directly by ESP32 | LTE modem controlled by ESP32 via B2B connector (same approach) |
| No NFC configuration | NFC multi-tap config via ST25DV04K on nRF54 |
| No dual-band WiFi | WiFi 6 dual-band (2.4 + 5 GHz) with band preference setting |
| Single firmware target | Three OTA targets (ESP32 FW, ESP32 UI, nRF54 FW) |
Related Documents¶
- 232202 Base WiFi -- ESP32-C5 WiFi gateway hardware
- 232204 Base Full -- Full platform with LTE connector
- 232210 Ext LTE EU -- LTE extension board
- Firmware Compatibility -- Cross-board firmware reference, Dual-MCU API, coexistence
- Architecture Decisions (
ARCHITECTURE_DECISIONS.mdin repo root) -- ADR #12 (ESP32 manages LTE), ADR #18 (nRF54 config master) - Station Firmware Overview -- Firmware section landing page