> For the complete documentation index, see [llms.txt](https://docs.bituo-technik.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/udp-report.md).

# UDP Report

{% hint style="info" %}
**Status:** Active | **Applies to:** all SPM / SDM Open Wi-Fi branches (for who gets the AES-encrypted datagram see Section 4) | **Updated:** 2026-10-16&#x20;
{% endhint %}

UDP report is **pushed by the device**: you give the meter an IP and a port, and it sends the telemetry JSON there as a UDP datagram at a fixed period. There is no connection and no handshake, so latency is low and implementation is simple. It fits scenarios that need power readings quickly, such as PV export limiting and dynamic load balancing.

### 1. Introduction

<table><thead><tr><th width="179">Item</th><th>Description</th></tr></thead><tbody><tr><td>Direction</td><td>Device → your host, <strong>one-way</strong>; the device does not accept commands here</td></tr><tr><td>Content</td><td>Telemetry JSON, same as MQTT <code>/data</code>, see Telemetry Payload; on Pro it can be switched to AES-CCM ciphertext, see Section 4</td></tr><tr><td>Targets</td><td>Up to <strong>5</strong> targets (IP + port); one datagram per target each period</td></tr><tr><td>Period</td><td>Default 5 s, <strong>one period shared by all targets</strong>, minimum 100 ms</td></tr><tr><td>Switch</td><td>Function bit 13; turned on automatically when a target is added, and deleting a target does <strong>not</strong> turn it off</td></tr><tr><td>Source port</td><td>The device always sends from local port <strong>2390</strong> (shared with time sync); use it if a firewall needs it</td></tr><tr><td>Reliability</td><td>UDP guarantees no delivery, order or retransmission. To detect loss, use the <code>Post</code> counter in the telemetry</td></tr></tbody></table>

### 2. Configuring targets

Use the `udp`, `deleteudp` and `udpdata` commands from the Business Command Reference; they work over BLE, HTTP, MQTT and WebSocket.

```json
{"cmd":"udp","IpAddress":"192.168.1.100","localUdpPort":9000,"Frequency":5}
```

<table><thead><tr><th width="185.6666259765625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>IpAddress</code></td><td>Target IP (at most 19 characters, dotted IPv4)</td></tr><tr><td><code>localUdpPort</code></td><td>Target port. "local" is in the name but it is the port on <strong>your</strong> side</td></tr><tr><td><code>Frequency</code></td><td>Optional period in <strong>seconds</strong>. If omitted the current period is kept. The device converts it to milliseconds, minimum 100 ms</td></tr></tbody></table>

* Success: `UDP successfully`. Adding the same IP + port again only updates the period.
* When the IP is empty or the port invalid, the device also returns `UDP full` (subcode 24); do not read it literally as "full".
* A sixth target also returns `UDP full`.
* Delete: `{"cmd":"deleteudp","IpAddress":"192.168.1.100","localUdpPort":9000}`, success `UDP deleted`; if absent `UDP not found` (subcode 25).
* List: `{"cmd":"udpdata"}`; targets are in `d.udp_data`, for example `[{"ip":"192.168.1.100","port":"9000"}]`.
* The configuration is stored on the device and survives reboot.
* Targets and period also show up in the `model` response: the period is `UI` (milliseconds); in HTTP `/model` they are `udpInterval` and `UDP`.

Notes:

* Give the target a fixed IP (or a DHCP reservation on the router), otherwise the datagrams stop arriving when your computer's address changes.
* The firmware simply sends to the configured address. To reach a whole subnet you may try the subnet broadcast address (such as `192.168.1.255`), but that is not a firmware specification and you have to verify it yourself.

### 3. Datagram format

#### 3.1 Plaintext datagram

Each UDP datagram is **one complete JSON text** (UTF-8), with no header, no newline delimiter and no fragmentation, at most 1024 bytes. Fields are on the Telemetry Payload page.

```json
{"Post":927,"Time":1782313081,"IP":"192.168.1.50","Rssi":-68,"FWVersion":"5.1.16","SerialNumber":"AABBCCDDEEFF","ProductModel":"SPM01","TP":1,"Voltage":"227.6","Current":"0.000","ActivePower":"0.000"}
```

The example shows only some fields for layout; the real datagram is the full packet. Just `JSON.parse` it, and use `SerialNumber` to tell devices apart.

With `commonmode` on, the datagram follows the generic format; see Section 6 of the telemetry page.

#### 3.2 When it is sent

* It is sent when the period elapses, Wi-Fi is connected and function bit 13 is 1.
* What goes out is the packet the device "last generated". The firmware decides how often it refreshes internally; a period faster than that delivers duplicates, so deduplicate with `Post`.
* With no target configured, nothing is sent.

### 4. AES-CCM encrypted datagram

> Scope: the encrypted datagram is sent only on Pro, and only while HTTPS (`enablehttps`) is on. Basic and Lite always send plaintext. Published notes that say Lite supports it do not match Pro `3.1.19` and Lite `5.1.16`. See the CHANGELOG.

When it is on, the datagram is no longer the telemetry JSON but a ciphertext JSON:

```json
{"ct":"<ciphertext base64>","tag":"<tag base64>","counter":12}
```

<table><thead><tr><th width="171.22216796875">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>ct</code></td><td>AES-128-CCM ciphertext of the telemetry JSON, Base64</td></tr><tr><td><code>tag</code></td><td>Authentication tag, <strong>8 bytes</strong>, Base64</td></tr><tr><td><code>counter</code></td><td>32-bit unsigned integer, <strong>incremented every report period</strong> (every target gets the same datagram in a period). It <strong>restarts from 1</strong> after a reboot</td></tr></tbody></table>

Encryption parameters:

<table><thead><tr><th width="169">Item</th><th>Value</th></tr></thead><tbody><tr><td>Algorithm</td><td>AES-128-CCM</td></tr><tr><td>Key</td><td>The <strong>broadcast key</strong> (16 bytes), the same one used by BLE encrypted advertising, derived from the J-PAKE result during BLE provisioning; see Crypto Protocol 3.5</td></tr><tr><td>Nonce (12 bytes)</td><td>First 8 bytes all <code>00</code>, last 4 bytes are <code>counter</code> in <strong>big-endian</strong></td></tr><tr><td>Tag length</td><td>8 bytes (BLE long advertising uses 4 bytes; do not mix them up)</td></tr><tr><td>Additional data (AAD)</td><td>none</td></tr><tr><td>Plaintext</td><td>The complete telemetry JSON text (UTF-8)</td></tr></tbody></table>

Decryption steps:

1. Parse the datagram to get `ct`, `tag`, `counter`, and Base64-decode the first two.
2. Build the nonce from `counter`: 8 `00` bytes + 4 bytes of big-endian `counter`.
3. Concatenate `ct` and `tag` as `ct || tag` and run AES-CCM decryption with the broadcast key and nonce (tag length 8).
4. On success you have the plaintext JSON; if the tag check fails, discard the datagram.

Python (`cryptography` library):

```python
import base64, json
from cryptography.hazmat.primitives.ciphers.aead import AESCCM

def decrypt_udp(datagram: bytes, broadcast_key: bytes) -> dict:
    env = json.loads(datagram)
    ct = base64.b64decode(env["ct"])
    tag = base64.b64decode(env["tag"])
    nonce = b"\x00" * 8 + int(env["counter"]).to_bytes(4, "big")
    plain = AESCCM(broadcast_key, tag_length=8).decrypt(nonce, ct + tag, None)
    return json.loads(plain)
```

Notes:

* **Test vector**: `spec/udp-aes-test-vector.json` has a key, a counter, a plaintext and the expected datagram for checking your implementation. It was generated from the parameters above, not captured from a device.
* **Replay protection**: `counter` resets after a device reboot, so ordering by it alone is not reliable; `Post` inside the plaintext resets too. For replay protection, use `Time` (Unix time) in the plaintext with a window check.
* When the device has no broadcast key (for example secured provisioning was never completed), it sends an **empty datagram**. A datagram of length 0 can simply be ignored.
* After `enablehttps` is turned off, datagrams go back to plaintext. The receiver should handle both: run `JSON.parse` first and decrypt if a `ct` field exists.
* How to get the broadcast key out of the BLE provisioning result: the BLE secured tools in this repository cache it locally, and the UDP listener tool can read it directly.

### 5. Receiver example

The simplest listener (Python, plaintext):

```python
import json, socket

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.bind(("0.0.0.0", 9000))
while True:
    data, addr = s.recvfrom(2048)
    if not data:
        continue
    msg = json.loads(data)
    print(addr[0], msg.get("SerialNumber"), msg.get("Post"))
```

The UDP listener tool in this repository handles both plaintext and AES-CCM datagrams and detects loss.

### 6. Troubleshooting

<table><thead><tr><th width="280.1112060546875">Symptom</th><th>Cause</th></tr></thead><tbody><tr><td>Nothing arrives</td><td>No target is configured; function bit 13 is off; the computer's firewall blocks inbound UDP; the device and the computer are on different subnets</td></tr><tr><td>Occasional loss</td><td>Normal for UDP; count it with <code>Post</code></td></tr><tr><td>You receive <code>{"ct":...}</code></td><td>The device has AES on; decrypt with the broadcast key</td></tr><tr><td>You receive an empty datagram</td><td>The device has no broadcast key; redo BLE secured provisioning</td></tr><tr><td>Decryption fails</td><td>The key belongs to another device, or the device was reset after provisioning and the key changed</td></tr><tr><td>Wrong period</td><td>The period is written in <strong>seconds</strong> and converted to milliseconds; minimum 100 ms</td></tr></tbody></table>
