NetBurner 3.3.8a
PDF Version
UDP Class

The NetBurner API provides two mechanisms to implement UDP: sockets and a C++ class. The choice of which to use is Dependent of which method you find most comfortable using. There is not a performance difference.

Receiving UDP Packets Using the UDP Class

To receive UDP Packets:

  • Create an OS_FIFO to hold incoming UDP packets
  • Register a UDP FIFO with RegisterUDPFifo() to listen for and store incoming packets. If listening on more than one port number, a separate OS_FIFO can be used for each port, or one OS_FIFO can be used to listen on multiple ports by calling RegisterUDPFifo() for each port number and specifying the same OS_FIFO.
  • Call a UDP constructor such as: UDPPacket upkt(&fifo, timeout), which will block until a packet is received, then accept and store the packet.
  • Call the Validate() member function to verify the packet
  • Call the GetDataBuffer() member function to obtain the data in the packet

Sending a UDP Packet Using the UDP Class

To send a UDP packet:

  • Declare an instance of a UDP object
  • Specify the source and destination port numbers
  • Add data to the packet using the class member functions
  • Call the Send() member function to send the packet
Unlike TCP, there is no connection between the client and sever, so I/O functions such as read() and write() cannot be used. When sending, a UDP packet must be created for each transmission.

UDP Send/Receive Example with UDP Class

You can use the NetBurner UDPTerminal utility on Windows platforms to send/receive UDP packets on your PC.

* This example program will receive a UDP packet from another device or
* host computer, and then send a response. To run the example, connect a serial
* port from your PC to the debug serial port on your NetBurner device and run a
* terminal program such as MTTTY. On the PC, run the NetBurner UDP Terminal
* (be sure to set the IP address and port numbers to match). You will then
* be able to type characters in the UDP Terminal and see them in MTTTY,
* and vice versa.
* You will be prompted for the port number to send/receive data and the
* destination IP address of the other device or host. Note that the application
* uses the same port number to send and receive data, but you can use any other
* port number you wish.
* The application will create a thread to receive packets and display them
* on the debug port, while the main task will take any data you type in
* to the MTTTY terminal and send it as a UDP packet to the destination IP
* address.
#include <init.h>
#include <stdlib.h>
#include <system.h>
#include <udp.h>
#include <utils.h>
const char *AppName = "UDP Send/Receive Example";
// Allocate stack space for the listen task
uint32_t UdpReceiveTaskStack[USER_TASK_STK_SIZE];
* This UDP task will wait for incoming packets on the specified port number,
* which is passed as a OSTaskCreate() void * parameter.
void UdpReceiveTask(void *pd)
static OS_FIFO fifo; // Create a FIFO for the UDP packet and initialize it
int listenPort = (int)pd;
iprintf("Listening on UDP port: %d\r\n", listenPort);
// Register the OS_FIFO. Received packets will be stored in the OS_FIFO.
RegisterUDPFifo(listenPort, &fifo);
while (1)
// Construct a UDP packet object using the previously declared FIFO.
// The UDP constructor will block until a packet has been received.
// The second parameter is a timeout value (time in ticks). A value of 0 will
// wait forever.
UDPPacket upkt(&fifo, 0 * TICKS_PER_SECOND);
// Did we get a valid packet, or just time out?
if (upkt.Validate())
uint16_t len = upkt.GetDataSize();
iprintf("Received UDP packet with %d bytes from: %I\r\n", (int)len, upkt.GetSourceAddress());
ShowData(upkt.GetDataBuffer(), len); // hex dump function
* UserMain
void UserMain(void *pd)
int portNumber;
IPADDR destIpAddress;
char buffer[80];
init(); // Initialize network stack
WaitForActiveNetwork(TICKS_PER_SECOND * 5); // Wait for DHCP address
iprintf("Application: %s\r\nNNDK Revision: %s\r\n", AppName, GetReleaseTag());
iprintf("Enter the UDP port number (will be used for send & receive): ");
portNumber = atoi(buffer);
iprintf("\r\nEnter the destination IP Address: ");
destIpAddress = AsciiToIp(buffer);
iprintf("Listening/Sending on UDP Port %d, Sending to IP address: %I\r\n", portNumber, destIpAddress);
// Create UDP listen task
OSTaskCreatewName( UdpReceiveTask,
(void *)portNumber,
&UdpReceiveTaskStack[USER_TASK_STK_SIZE] ,
MAIN_PRIO - 1, // higher priority than UserMain
"UDP Receive" );
// while loop to process user input and send as a UDP packet
iprintf("Enter data and hit return to send.\r\n");
while (1)
UDPPacket pkt;
iprintf("Sent \"%s\" to %I:%d\r\n", buffer, destIpAddress, portNumber);
Used to hold and manipulate IPv4 and IPv6 addresses in dual stack mode.
Definition: ipv6_addr.h:40
UDP Packet Class.
Definition: udp.h:78
void Send(const IPADDR &to, uint8_t ttl=0)
Send the UDP Packet and free the pool buffer.
Definition: udp.h:443
void SetDestinationPort(uint16_t port)
Set the destination port number of a UDP Packet object.
Definition: udp.cpp:762
void SetSourcePort(uint16_t port)
Set the source port number of a UDP Packet object.
Definition: udp.cpp:721
void AddData(puint8_t pData, uint16_t len)
Add a number of data bytes to a UDP Packet object.
Definition: udp.cpp:830
void AddDataByte(uint8_t b)
Add an 8-bit unsigned integer to a UDP Packet object.
Definition: udp.cpp:860
uint8_t OSTaskCreatewName(void(*task)(void *dptr), void *data, void *pstktop, void *pstkbot, uint8_t prio, const char *name)
This function creates a new task.
const char * GetReleaseTag()
Returns the NNDK release tag information.
Definition: release_tag.cpp:8
void RegisterUDPFifo(uint16_t listenPort, OS_FIFO *pFifo)
Register a FIFO to receive incoming UDP packets.
Definition: udp.cpp:1153
void init()
System initialization. Normally called at the beginning of all applications.
Definition: init.cpp:27
bool WaitForActiveNetwork(uint32_t ticks_to_wait=120 *TICKS_PER_SECOND, int interface=-1)
Wait for an active network connection on at least one interface.
Definition: dhcpc.cpp:1554
NetBurner System Initialization Header File.
A FIFO is used to pass structures from one task to another. Note: Structures to be passed must have a...
Definition: nbrtos.h:764
NetBurner System Functions.
NetBurner User Datagram Protocol Header File.

Sending Packets

In the while loop of UserMain() you can see that a UDPPacket object named "pkt" is created. Member functions are then called to specify the source port number, destination port number, add the message data, add a null string terminator, and finally to send the packet. In practice it is a good idea to choose random source port numbers.

Receiving Packets

UserMain() creates a task named UdpReceiveTask(). The task declares an OS_FIFO to use to store incoming packets. Note that it is static so the FIFO is located in global variable space. A UDPPacket object constructor is then called for upkt. It will block until a packet is received. When one does arrive it is verified with the Validate() member function. If it is a valid packet the ShowData() utility function is used to display the data in hex format to the debug serial port.