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

Note

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

Note

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
            iprintf("\r\n");
        }
    }
}
 
/*
 *  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): ");
    gets(buffer);
    portNumber = atoi(buffer);
 
    iprintf("\r\nEnter the destination IP Address: ");
    gets(buffer);
    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] ,
                       UdpReceiveTaskStack,
                       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)
    {
        gets(buffer);
 
        UDPPacket pkt;
        pkt.SetSourcePort(portNumber);
        pkt.SetDestinationPort(portNumber);
        pkt.AddData(buffer);
        pkt.AddDataByte(0);
        pkt.Send(destIpAddress);
        iprintf("\r\n");
 
        iprintf("Sent \"%s\" to %I:%d\r\n", buffer, destIpAddress, portNumber);
    }
}

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.