BSD UDP Serial Sample

Introduction

This sample demonstrates how to write a UDP serial application using the Berkeley Software Distribution (BSD) standard socket APIs to communicate with a device server.

For the purpose of this demonstration, the sample application creates a networking socket it uses to send and receive serial data encapsulated in UDP datagrams from the device server. The device server uses its UDP Client and Server features, and a loopback plug to relay data received on its first port back to the sample application.

Device Server Setup

This sample was designed to operate with the first port on the device server, and requires that the port be configured with UDP Client and Server information. After the device server is configured properly, the port must also have a loopback plug attached to it.

Configure the device server

1. Access the web interface by entering the module’s IP address in a browser’s URL window.
2. Choose Serial Ports from the Configuration menu.
3. Configure the module as a UDP server by doing the following:
   1. Click the UDP tab.
   2. Check Enable UDP Server.
   3. Specify 2101 as the Raw UDP port.
   4. Click Save.
4. Configure the module as a UDP client by doing the following:
   1. Click Enable UDP Client.
   2. Configure a destination by doing the following (1) Supplying the IP address of the PC on which the sample application is installed. (2) Supplying a UDP port of 7777. (3) Ensuring that the Enabled field is checked.
   3. Click Save.
5. Connect the loopback plug to port 1.

How To Build

This sample has been compiled and tested using GCC 3.2 on Red Hat Linux 8.0. It contains a Makefile that is used for building the application.

To build this sample

1. Change directory to where the sample source files reside.
2. Type make.

Step-by-Step

1.  Create a local socket

The call to create a socket looks like this:

int Socket = socket(AF_INET, Type, Protocol);

Where Type is SOCK_DGRAM and Protocol is IPPROTO_UDP for a blocking, connectionless datagram socket.

2.  Bind to a local port

To bind the socket to a local port, call the following function:

bind(Socket, &SockAddr, sizeof(SockAddr));

Binding to a local port must be done before using the socket to calls like sendto, and is used to associate the currently unnamed socket with a local name.

The SockAddr parameter is the struct sockaddr representation of the local name to bind to. This name consists of an address family (for UDP, always AF_INET), a host address, and a port number.

In this sample, the calls to socket and bind are both done in the function MySocketOpen. Since this sample demonstrates a UDP application, a well-known port (7777) is supplied to the call to MySocketOpen. The same well-known port is also used by the device server as part of its UDP Client destination address information.

3.  Transmit data

Transmitting data is done by calling sendto.

sendto(Socket, Data, Length, 0,
       &SockAddr, sizeof(SockAddr));

To simplify transmitting data this sample uses its own function named MySocketSendTo.

MySocketSendTo(MySocket, SendData, sizeof(SendData),
               AddressToSendTo, PortToSendTo);

The parameters needed for MySocketSend are: MySocket which is the socket returned from MySocketOpen, SendData which is a pointer to the buffer holding the data to send, sizeof(SendData) which is the number of bytes SendData points to, and AddressToSendTo and PortToSendTo which provide the IP address and port number of the device server to send the data to. For Digi device servers, the UDP port number for Port 1 is 2101

4.  Receive data

To retrieve data received at the local address, call recvfrom.

recvfrom(Socket, Data, Length, 0,
         &SockAddr, &SockAddrLength);

With the device server setup with the loopback plug, the data transmitted in the step above will be sent directly back to the sample application.

Like sendto, the sample provides an alternative function, MySocketRecvFrom that is somewhat easier to use.

MySocketRecvFrom(MySocket, RecvData, sizeof(RecvData),
                 AddressReceivedFrom,
                 &AddressReceivedFromLength)

The caller to MySocketRecv need only supply the prerequisite MySocket, a buffer RecvData to hold the received data, sizeof(RecvData) which specifies the length of RecvData, AddressReceivedFrom which provides space to return a string representation of the IP address and port number of the device server that sent the data, and &AddressReceivedFromLength which specifies the length of AddressReceivedFrom.

5.  Close the socket

Accomplish this task by calling the following two functions:

shutdown(Socket, SHUT_RDWR);
close(Socket);

When the sample application is done using the socket, the connection it represents must be terminated properly (shutdown) and any resources it may be using should be released (close).

File List

hexdumpdata.cpp

hexdumpdata.h

Makefile

mysocket.cpp

mysocket.h

udpserial.cpp

Keywords

socket; sendto; recvfrom; shutdown; close