Broadcast UDP Packet

ZentriOS devices broadcast module properties in JSON format. The properties can be sent either as UDP packets to a UDP host or by a post request to an HTTP host. Properties include by default the IP address and the MAC address.

See the broadcast variables.

This application note demonstrates how to send and receive a broadcast UDP packet, and how to extract properties from the JSON format data.

This application uses a ZentriOS device and a Python Script (Python v2.7).

The ZentriOS device is programmed with the factory default configuration.

The Python script listens for UDP packets and validates any packet received as JSON data. It then extracts the IP address from the JSON data.

Setup

The following assumes that the module starts in its default state. To return it to the default state, perform a factory reset.

The python script runs on a test computer on the same Wi-Fi network as the ZentriOS device.

Copy the following python script to the test computer: broadcast_udp_packet.py

The Python script procedure is:

  1. While no IP address has been successfully parsed:
    • Wait until the server receives a broadcast UDP packet from the module
    • When a packet is received, parse the packet for the module's IP address
    • If the packet is parsed as valid JSON and the module IP address is received, return.
  2. Display the JSON packet and the IP address
  3. Repeat from step 1

To break out of the Python script loop, press Ctrl-C (Command-C on a Mac.)

Method

Open a ZentriOS Terminal to the ZentriOS device

To open a ZentriOS terminal connection to the ZentriOS device, see Getting Started.

Associate Module to Wi-Fi Network

To associate the module to a Wi-Fi network, set the values of wlan.ssid and wlan.passkey and run the network_up command. See Getting Started.

Issue the following commands to join the network automatically and reduce the broadcast interval to 2 seconds:

Module ZentriOS commandsComments

set wlan.auto_join.enabled 1
set broadcast.interval 2
save
reboot

Join network automatically on reboot
Set broadcast interval to 2 seconds
Save variables
Reboot to restart the periodic UDP broadcast service

The module automatically broadcasts UDP packets every 2 seconds after association to an AP has completed.

Run Python Script

Execute the broadcast_udp_packet.py python script. The script displays the following text:

Listening for ZentriOS device broadcast UDP packets...

Within the broadcast interval of 2 seconds, the python script prints a result similar to the following:

Broadcast UDP Packet (json format):
{
    "mac"     : "4C:55:CC:10:06:12",
    "bssid"   : "30:85:A9:E7:9C:B0",
    "channel" : 11,
    "ip"      : "192.168.1.173",
    "ssid"    : "Zentri",
    "rssi"    : -28,
    "time"    : 1416801734637,
    "version" : "ZentriOS-beta-2.0.1.5,
                 Built:2014-11-06 16:02:35 for AMW004.3,
                 Board:AMW004-E03.2",
    "remote_terminal_port" : 2000
}

IP found in broadcast UDP packet: 192.168.1.173

Change Properties in Broadcast UDP Packet

At the ZentriOS prompt, enter the following command to change the properties in the broadcast UDP packet:

Module ZentriOS CommandsComments

set broadcast.data ip,mac
save
reboot

Set broadcast properties to IP and MAC address
Save variables
Reboot to restart the periodic broadcast service

The python script now prints text similar to:

Listening for ZentriOS device broadcast UDP packets...
Broadcast UDP Packet (json format):
{
    "mac" : "4C:55:CC:10:06:12",
    "ip"  : "192.168.1.173"
}

IP found in broadcast UDP packet: 192.168.1.173

Note that only the mac (module MAC address) and ip (module IP address) properties are broadcast.

Set the IP Address to the Test Computer

The module can be configured to send the broadcast UDP packet to a fixed IP address other than the broadcast address of 255.255.255.255. At the ZentriOS prompt, enter the following command to set the target IP for the broadcast UDP packet.

Module ZentriOS CommandsComments

set broadcast.udp.ip <IP address of test computer>
save
reboot

Restrict broadcast to test computer
Save variables
Reboot to use updated IP address

The python script continues to print the same result as in the previous step.

Set IP address to Target Other than Test Computer

Set the broadcast.udp.ip variable to some address on your network other than your test computer.

Module ZentriOS commandsComments

set broadcast.udp.ip <not ip of test computer>
save
reboot

Restrict broadcast to other host
Save
Reboot

The python script stops printing results, because it never sees the broadcast UDP packet.

Now, while the script is running, follow the steps in Set the IP Address to Test Computer. Within two seconds of the ZentriOS device network coming up, the script begins to display the extracted IP address again.

Send ADC Values and GPIO Values in the Broadcast UDP Packet

Specify ADCs by ADC number, not by GPIO. See Peripherals for tables showing ADC numbers on the Wallaby/Mackerel evaluation board and the Numbat/Moray evaluation board.

On the Mackerel evaluation board, the thermistor is on ADC0 (GPIO7). On the Moray evaluation board, the thermistor is on ADC9 (GPIO20).

GPIO0 corresponds to Button 1 on both the Mackerel and Moray evaluation boards.

Module ZentriOS commandsComments

set broadcast.data ip,mac,adc0,adc9,gpio0
save
reboot

Add ADC0, ADC9, GPIO0 to broadcast properties
Save
Reboot

The python script displays a result similar to the following:

Listening for ZentriOS device broadcast UDP packets...
Broadcast UDP Packet (json format):
{
    "mac"   : "4C:55:CC:10:06:12",
    "ip"    : "192.168.1.173",
    "gpio0" : 0,
    "adc0"  : 1845,
    "adc9"  : 1513
}

IP found in broadcast UDP packet: 192.168.1.173

ADC values in the packet are in decimal. To convert to mV, see Peripherals, ADCs. If you are using a Mackerel or a Moray evaluation board, press and continue to hold Button 1. The python script displays a result similar to the following:

Listening for ZentriOS device broadcast UDP packets...
Broadcast UDP Packet (json format):
{
    "mac"   : "4C:55:CC:10:06:12",
    "ip"    : "192.168.1.173",
    "gpio0" : 1,
    "adc0"  : 1845,
    "adc9"  : 1513
}

Release Button 1 and the value for gpio0 returns to 0.

Change Log

ModifiedChangesZentriOS Version
Required
2014-11-28Created1.0+