UDP socket routines enable simple IP communication using the user datagram protocol (UDP). More...

Functions
int32_t	udp_get_socket (uint8_t tos, uint8_t opt, net_udp_cb_t cb_func)
	Allocate a free UDP socket.

netStatus	udp_release_socket (int32_t socket)
	Release UDP socket and free resources.

netStatus	udp_open (int32_t socket, uint16_t port)
	Open UDP socket for communication.

netStatus	udp_close (int32_t socket)
	Stop UDP communication and close socket.

netStatus	udp_multicast_ttl (int32_t socket, uint8_t ttl)
	Set Time To Live value for multicast packets.

uint8_t *	udp_get_buf (uint32_t size)
	Allocate memory for UDP send buffer.

netStatus	udp_send (int32_t socket, const uint8_t ip_addr, uint16_t port, uint8_t buf, uint32_t len)
	Send data to a remote node.

typedef uint32_t(*	net_udp_cb_t )(int32_t socket, const uint8_t ip_addr, uint16_t port, const uint8_t buf, uint32_t len)
	UDP Event callback function.

Description

UDP socket routines enable simple IP communication using the user datagram protocol (UDP).

The User Datagram Protocol (UDP) runs on top of the Internet Protocol (IP) and was developed for application that do not require reliability, acknowledgement, or flow control features at the transport layer. This simple protocol provides transport layer addressing in the form of UDP ports and an optional checksum capability.

Note: More information on the usage of UDP and how to work with the functions is available at UDP Socket.

Typedef Documentation

uint32_t(* net_udp_cb_t)(int32_t socket, const uint8_t *ip_addr, uint16_t port, const uint8_t *buf, uint32_t len)

UDP Event callback function.

Parameters

[in]	socket	UDP socket handle of the local machine.
[in]	ip_addr	Pointer to the IP address of the remote machine.
[in]	port	UDP port number on the remote machine.
[in]	buf	Pointer to buffer containing the received data.
[in]	len	Number of bytes in the received packet.

Returns: Currently not used. Reserved for future use.

Is the type definition for the UDP callback function. The Network Core calls the callback function whenever a UDP data packet is received. Users must provide the function.

Parameter for:

udp_get_socket

Function Documentation

netStatus udp_close ( int32_t socket )

Stop UDP communication and close socket.

Parameters

[in] socket socket handle obtained with udp_get_socket.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The udp_close function closes the UDP socket identified in the function argument. After calling the udp_close function, the UDP socket cannot send or receive any data packet.

Note

After closing the UDP socket, you can reopen it using the udp_open function.
The UDP socket still reserves memory after calling the udp_close function. Hence, if you do not need the socket, you must release the memory using the udp_release_socket function after calling udp_close.

Code Example

#include "rl_net.h"
 
void disconnect_udp (int32_t udp_soc) {
   ..
  // This UDP connection is no longer needed 
  udp_close (udp_soc);
  udp_release_socket (udp_soc);
}

uint8_t * udp_get_buf ( uint32_t size )

Allocate memory for UDP send buffer.

Parameters

[in] size number of bytes to allocate.

Returns: pointer to the allocated memory.

The function udp_get_buf allocates memory for the UDP send buffer into which your application can write the outgoing data packet.

The argument size specifies the number of data bytes that the application wants to send. When the UDP frame has been sent, the Network Core automatically de-allocates the memory used by the send buffer.

Note

Your application must call the udp_get_buf function each time it wants to send a UDP data packet.
The total size of the allocated memory must not exceed the UDP Maximum Packet Size (1472 bytes).
Writing more data than the allocated size of the data buffer overwrites the Memory Manager Block links and causes the Network Core to crash.

Code Example

#include "rl_net.h"
#include <string.h>
 
void send_data () {
  char udp_msg[] = {"Hello World!"};
  const uint8_t remip[4] = {192,168,1,100};
  uint8_t *sendbuf;
  uint32_t len;
 
  len = strlen (udp_msg);
  sendbuf = udp_get_buf (len);
  strcpy (sendbuf, udp_msg);
  // Send 'Hello World!' to remote peer 
  udp_send (udp_soc, remip, 1000, sendbuf, len);
}

int32_t udp_get_socket	(	uint8_t	tos,
		uint8_t	opt,
		net_udp_cb_t	cb_func
	)

Allocate a free UDP socket.

Parameters

[in]	tos	IP type of service: 0 = default value.
[in]	opt	Checksum calculation option: UDP_OPT_SEND_CHECKSUM = Calculate transmit checksum. UDP_OPT_VERIFY_CHECKSUM = Verify receive checksum. 0 = No checksum calculation.
[in]	cb_func	event listening callback function.

Returns

socket handle number or execution status:

value >= 0: socket handle number
value < 0: error occurred, -value is execution status as defined with netStatus

The function udp_get_socket allocates a free UDP socket. It initializes all state variables of the UDP socket to the default state.

The argument tos specifies the IP Type Of Service. The most common value for tos is 0.

The argument opt specifies the checksum option as shown in the following table:

Option Value	Description
UDP_OPT_SEND_CHECKSUM	Calculate transmit checksum
UDP_OPT_VERIFY_CHECKSUM	Verify receive checksum
0	No checksum calculation

You can also set opt to UDP_OPT_SEND_CHECKSUM|UDP_OPT_VERIFY_CHECKSUM to enable both options. This is recommended for a more secure UDP connection. You can also disable both options by setting opt to 0 for fast system reaction time.

The argument cb_func is the event callback function of the UDP socket. Users must provide this function. Refer to net_udp_cb_t.

Note

You must call the udp_get_socket function before any other function calls to the UDP socket.
Ethernet packets are also protected by the Ethernet CRC.
Packets can be modified when passing through routers, proxy servers, gateways, etc.
You must define the listener function to use with the UDP socket.

Code Example

#include "rl_net.h"
 
int32_t udp_soc;
 
uint32_t udp_callback (int32_t socket, const uint8_t *ip_addr, uint16_t port, const uint8_t *buf, uint32_t len) {
  // This function is called when UDP data is received 
 
  // Process received data from 'buf' 
   ..
  return (0);
}
 
void main (void) {
 
  init ();
  // Initialize the Network Core 
  net_initialize ();
  udp_soc = udp_get_socket (0, UDP_OPT_SEND_CHECKSUM | UDP_OPT_VERIFY_CHECKSUM, udp_callback);
  if (udp_soc >= 0) {
    // Open UDP port 1000 for communication 
    udp_open (udp_soc, 1000);
  }
 
  while (1);
    // Run main Network Core 'thread' 
    net_main ();
     ..
  }
}

netStatus udp_multicast_ttl	(	int32_t	socket,
		uint8_t	ttl
	)

Set Time To Live value for multicast packets.

Parameters

[in]	socket	socket handle obtained with udp_get_socket.
[in]	ttl	number of routers the packet can cross before being expired.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function udp_multicast_ttl sets the time to live (TTL) value for multicast packets of an UDP socket identified with a parameter socket. The argument ttl specifies the TTL value for the UDP socket (default value is 1). A TTL value controls the number of routers the packet can cross before being expired. If this function is not called, a default TTL value of 1 is assumed for all transmitted Multicast UDP datagrams.

Note: This TTL value is not used for unicast UDP datagrams.

Code Example

 ..
udp_soc = udp_get_socket (0, UDP_OPT_SEND_CHECKSUM | UDP_OPT_VERIFY_CHECKSUM, udp_callback);
if (udp_soc >= 0) {
  // Open UDP port 1000 for communication 
  udp_open (udp_soc, 1000);
  // Let UDP Multicast datagrams cross a router. 
  udp_multicast_ttl (udp_soc, 2);
}

netStatus udp_open	(	int32_t	socket,
		uint16_t	port
	)

Open UDP socket for communication.

Parameters

[in]	socket	socket handle obtained with udp_get_socket.
[in]	port	local port number or 0 for system assigned local port.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The udp_open function opens the UDP socket identified by the argument socket for communication.

The argument port specifies the local port for sending and receiving data packets.

Note: If you specify 0 for port, the Network Core automatically allocates the first free UDP port for communication.

Code Example

#include "rl_net.h"
 
int32_t udp_soc;
 
uint32_t udp_callback (int32_t socket, const uint8_t *ip_addr, uint16_t port, const uint8_t *buf, uint32_t len) {
  // This function is called when UDP data is received 
  // Process received data from 'buf' 
   ..
  return (0);
}
 
void main (void) {
 
  init ();
  // Initialize the Network Core
  net_initialize ();
  udp_soc = udp_get_socket (0, UDP_OPT_SEND_CHECKSUM | UDP_OPT_VERIFY_CHECKSUM, udp_callback);
  if (udp_soc >= 0) {
    // Open UDP port 1000 for communication 
    udp_open (udp_soc, 1000);
  }
 
  while (1);
    // Run main Network Core 'thread' 
    net_main ();
     ..
  }
}

netStatus udp_release_socket ( int32_t socket )

Release UDP socket and free resources.

Parameters

[in] socket socket handle obtained with udp_get_socket.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function udp_release_socket releases the socket and de-allocates its memory.

Note

Once the socket is released, the Network Core can allocate the socket to another process.
You must call the udp_release_socket function when you do not need the UDP socket any longer.

Code Example

#include "rl_net.h"
 
void disconnect_udp (int32_t udp_soc) {
   ..
  // This UDP connection is no longer needed 
  udp_close (udp_soc);
  udp_release_socket (udp_soc);
}

netStatus udp_send	(	int32_t	socket,
		const uint8_t *	ip_addr,
		uint16_t	port,
		uint8_t *	buf,
		uint32_t	len
	)

Send data to a remote node.

Parameters

[in]	socket	socket handle obtained with udp_get_socket.
[in]	ip_addr	IP address of the remote node.
[in]	port	port number of the remote node to send data to.
[in]	buf	buffer containing the data.
[in]	len	length of data in bytes.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function udp_send sends the data packet to a remote machine. The argument socket specifies the socket handle to use for communication on the local machine. The argument ip_addr points to a buffer containing the four octets that make up the IP address of the remote machine. The argument port specifies the remote machine port to which to send the data packet. The argument buf points to the constructed UDP data packet. The argument dlen specifies the number of bytes in the data packet.

Note

You must allocate the memory using udp_get_buf before calling udp_send.
The socket must already be open for communication before you can send data.
The same UDP socket, using the same local port, can communicate with several remote machines using UDP ports. The user application must handle proper multiplexing of outgoing packets and demultiplexing of received packets.

Code Example

#include "rl_net.h"
#include <string.h>
 
void send_data () {
  char udp_msg[] = {"Hello World!"};
  const uint8_t remip[4] = {192,168,1,100};
  uint8_t *sendbuf;
  uint32_t len;
 
  len = strlen (udp_msg);
  sendbuf = udp_get_buf (len);
  strcpy (sendbuf, udp_msg);
  // Send 'Hello World!' to remote peer 
  udp_send (udp_soc, remip, 1000, sendbuf, len);
}

Functions

Description

Typedef Documentation

Function Documentation