UDP Report
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
Direction
Device → your host, one-way; the device does not accept commands here
Content
Telemetry JSON, same as MQTT /data, see Telemetry Payload; on Pro it can be switched to AES-CCM ciphertext, see Section 4
Targets
Up to 5 targets (IP + port); one datagram per target each period
Period
Default 5 s, one period shared by all targets, minimum 100 ms
Switch
Function bit 13; turned on automatically when a target is added, and deleting a target does not turn it off
Source port
The device always sends from local port 2390 (shared with time sync); use it if a firewall needs it
Reliability
UDP guarantees no delivery, order or retransmission. To detect loss, use the Post counter in the telemetry
2. Configuring targets
Use the udp, deleteudp and udpdata commands from the Business Command Reference; they work over BLE, HTTP, MQTT and WebSocket.
{"cmd":"udp","IpAddress":"192.168.1.100","localUdpPort":9000,"Frequency":5}IpAddress
Target IP (at most 19 characters, dotted IPv4)
localUdpPort
Target port. "local" is in the name but it is the port on your side
Frequency
Optional period in seconds. If omitted the current period is kept. The device converts it to milliseconds, minimum 100 ms
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}, successUDP deleted; if absentUDP not found(subcode 25).List:
{"cmd":"udpdata"}; targets are ind.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
modelresponse: the period isUI(milliseconds); in HTTP/modelthey areudpIntervalandUDP.
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.
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 Pro3.1.19and Lite5.1.16. See the CHANGELOG.
When it is on, the datagram is no longer the telemetry JSON but a ciphertext JSON:
ct
AES-128-CCM ciphertext of the telemetry JSON, Base64
tag
Authentication tag, 8 bytes, Base64
counter
32-bit unsigned integer, incremented every report period (every target gets the same datagram in a period). It restarts from 1 after a reboot
Encryption parameters:
Algorithm
AES-128-CCM
Key
The broadcast key (16 bytes), the same one used by BLE encrypted advertising, derived from the J-PAKE result during BLE provisioning; see Crypto Protocol 3.5
Nonce (12 bytes)
First 8 bytes all 00, last 4 bytes are counter in big-endian
Tag length
8 bytes (BLE long advertising uses 4 bytes; do not mix them up)
Additional data (AAD)
none
Plaintext
The complete telemetry JSON text (UTF-8)
Decryption steps:
Parse the datagram to get
ct,tag,counter, and Base64-decode the first two.Build the nonce from
counter: 800bytes + 4 bytes of big-endiancounter.Concatenate
ctandtagasct || tagand run AES-CCM decryption with the broadcast key and nonce (tag length 8).On success you have the plaintext JSON; if the tag check fails, discard the datagram.
Python (cryptography library):
Notes:
Test vector:
spec/udp-aes-test-vector.jsonhas 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:
counterresets after a device reboot, so ordering by it alone is not reliable;Postinside the plaintext resets too. For replay protection, useTime(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
enablehttpsis turned off, datagrams go back to plaintext. The receiver should handle both: runJSON.parsefirst and decrypt if actfield 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):
The UDP listener tool in this repository handles both plaintext and AES-CCM datagrams and detects loss.
6. Troubleshooting
Nothing arrives
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
Occasional loss
Normal for UDP; count it with Post
You receive {"ct":...}
The device has AES on; decrypt with the broadcast key
You receive an empty datagram
The device has no broadcast key; redo BLE secured provisioning
Decryption fails
The key belongs to another device, or the device was reset after provisioning and the key changed
Wrong period
The period is written in seconds and converted to milliseconds; minimum 100 ms
Last updated