User Datagram Protocol (UDP)

Table of Contents

• Asynchronous Event Notification Callback on socket
• Code examples
  • UDP Echo application on port 7 and any address
  • Creating socket with specific peer addresses and port
• Configuration parameters

The UDP module provides functionality for handling User Datagram Protocol messages. The application can communicate with remote nodes through sockets, creating a client-server architecture. You can allocate a maximum of UDP6_MAX_SOCKET_COUNT sockets, with the functionality of bind (udp6_socket_bind) and connect (udp6_socket_connect). Each socket must declare an application handler, where the user will be informed about received messages.

The destination port and destination address of incoming packets are compared with the parameters of existing sockets. If no proper socket is found, the packet is dropped.

Asynchronous Event Notification Callback on socket

The UDP socket callback informs about the internal process result, which can be either NRF_SUCCESS or one of the following errors:

Process result	Description
UDP_BAD_CHECKSUM	Calculated checksum does not match.
UDP_TRUNCATED_PACKET	UDP packet is truncated.
UDP_MALFORMED_PACKET	UDP packet is malformed.

Note

The application may take ownership of the received packet by returning IOT_IPV6_ERR_PENDING, in which case the application must take care to free it using iot_pbuffer_free.

Code examples

UDP Echo application on port 7 and any address

static udp6_socket_t m_socket;

uint32_t udp_app_handler(const udp6_socket_t * p_socket,
                         const ipv6_header_t * p_ip_header,
                         const udp6_header_t * p_udp_header,
                         uint32_t              process_result,
                         iot_pbuffer_t       * p_rx_packet)
{
    uint32_t                    err_code;
    iot_pbuffer_alloc_param_t   pbuff_param;
    iot_pbuffer_t             * p_buffer;
    
    APPL_LOG("[APPL]: Got UDP6 data on socket 0x%08x\r\n", p_socket->socket_id);

    // Check internal process result.
    APP_ERROR_CHECK(process_result);
    
    // Allocate packet buffer for responding.
    pbuff_param.flags  = PBUFFER_FLAG_DEFAULT;
    pbuff_param.type   = UDP6_PACKET_TYPE;
    pbuff_param.length = p_rx_packet->length;

    err_code = iot_pbuffer_allocate(&pbuff_param, &p_buffer);
    APP_ERROR_CHECK(err_code);
    
    // Copy payload.
    memcpy(p_buffer->p_payload, p_rx_packet->p_payload, p_rx_packet->length);
    p_buffer->length = p_rx_packet->length;
    
    // Resend message.
    err_code = udp6_socket_sendto(p_socket, &p_ip_header->srcaddr, p_udp_header->srcport, p_buffer);   
    APP_ERROR_CHECK(err_code);
}

void udp_socket_init(void)
{
    uint32_t err_code;

    err_code = udp6_socket_allocate(&m_socket);
    APP_ERROR_CHECK(err_code);

    err_code = udp6_socket_bind(&m_socket, IPV6_ADDR_ANY, 7);
    APP_ERROR_CHECK(err_code);

    err_code = udp6_socket_recv(&m_socket, udp_app_handler);
    APP_ERROR_CHECK(err_code);
}

Creating socket with specific peer addresses and port

This code example shows how to create a socket to receive messages only on port 1000 and address 2001:db8::1, from port 2000 and peer address 2001:db8::2. In this situation, you can use udp6_socket_send instead of udp6_socket_sendto.

uint32_t udp_app_handler(const udp6_socket_t * p_socket,
                         const ipv6_header_t * p_ip_header,
                         const udp6_header_t * p_udp_header,
                         uint32_t              process_result,
                         iot_pbuffer_t       * p_rx_packet)
{
    uint32_t                    err_code;
    iot_pbuffer_alloc_param_t   pbuff_param;
    iot_pbuffer_t             * p_buffer;

    APPL_LOG("[APPL]: Got UDP6 data on socket 0x%08x\r\n", p_socket->socket_id);

    // Check internal process result.
    APP_ERROR_CHECK(process_result);

    // Allocate packet buffer for responding.
    pbuff_param.flags  = PBUFFER_FLAG_DEFAULT;
    pbuff_param.type   = UDP6_PACKET_TYPE;
    pbuff_param.length = p_rx_packet->length;

    err_code = iot_pbuffer_allocate(&pbuff_param, &p_buffer);
    APP_ERROR_CHECK(err_code);

    // Copy payload.
    memcpy(p_buffer->p_payload, p_rx_packet->p_payload, p_rx_packet->length);
    p_buffer->length = p_rx_packet->length;

    // Resend message.
    err_code = udp6_socket_send(p_socket, p_buffer);   
    APP_ERROR_CHECK(err_code);
}

void udp_socket_init(void)
{
    uint32_t          err_code;
    const ipv6_addr_t src_addr  = {{0x20,0x01,0x0d,0xb8,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01}};
    const ipv6_addr_t dest_addr = {{0x20,0x01,0x0d,0xb8,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x02}};

    err_code = udp6_socket_allocate(&m_socket);
    APP_ERROR_CHECK(err_code);

    err_code = udp6_socket_bind(&m_socket, &src_addr, 1000);
    APP_ERROR_CHECK(err_code);

    err_code = udp6_socket_connect(&m_socket, &dest_addr, 2000);
    APP_ERROR_CHECK(err_code);

    err_code = udp6_socket_recv(&m_socket, udp_app_handler);
    APP_ERROR_CHECK(err_code);
}

Configuration parameters

The following configuration parameters should be defined in sdk_config.h.

UDP6_DISABLE_LOG

Disables debug tracing in the module. To enable tracing, this flag must be set to 0 and ENABLE_DEBUG_LOG_SUPPORT must be set to 1.

Description	Value
Enable debug trace	0
Disable debug trace	1
Dependencies	ENABLE_DEBUG_LOG_SUPPORT

UDP6_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description	Value
Enable API parameters check	0
Disable API parameters check	1
Dependencies	None

UDP6_MAX_SOCKET_COUNT

Maximum UDP sockets managed by the module.

Description	Value
Minimum	0
Maximum	255
Dependencies	None