Internet Control Message Protocol (ICMP)

Table of Contents

• Asynchronous Event Notification Callback
• Code examples
  • Ping remote using link-local address
  • Sending router solicitation to all router addresses
  • Sending neighbor solicitation with ARO option to router node
• Configuration parameters

The ICMPv6 module provides functionality for handling Internet Control Message Protocol messages. Depending on the configuration, it will forward packets to the application handler (if declared). The module also implements minimal functionality for neighbor discovery such as generating and sending registration messages (neighbor solicitation with ARO option), and for router solicitation for finding routers. It also implements minimal processing of Router Advertisement messages by getting the 6LoWPAN context option, which is needed for correct compression and decompression. This feature is therefore implemented internally.

Neighbor discovery parameters and data structures such as the routing table, neighbor cache, or prefix cache can easily be managed in the application layer.

Echo request messages are handled by the IPv6 stack internally whenever ICMP6_ENABLE_HANDLE_ECHO_REQUEST_TO_APPLICATION is not set.

Note

The architecture of the module provides only the most essential functionality that is required to start a 6LoWPAN network connection, and therefore it fits well for constrained nodes. Any other functionality contained in full IPv6 stacks can be added in the application layer.

Asynchronous Event Notification Callback

Asynchronous callback is used to notify the application of ICMP packets that are received. By default, the application does not receive notifications of echo requests or errors when using ICMP. However, these notifications can be enabled with ICMP6_ENABLE_ALL_MESSAGES_TO_APPLICATION if the application needs to handle them. You can also enable only neighbor discovery messages by setting ICMP6_ENABLE_ND6_MESSAGES_TO_APPLICATION.

The application can also handle echo request itself and disable the internal echo response procedure by using the ICMP6_ENABLE_HANDLE_ECHO_REQUEST_TO_APPLICATION flag.

ICMPv6 callback also informs about the internal process result, which can be either NRF_SUCCESS or one of the following errors:

Process result	Description
ICMP6_UNHANDLED_PACKET_TYPE	ICMPv6 packet type is unknown.
ICMP6_BAD_CHECKSUM	Calculated checksum does not match.
ICMP6_MALFORMED_PACKET	ICMPv6 packet is malformed.
ICMP6_INVALID_PACKET_DATA	Data inside ICMPv6 packet is incorrect.

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

Ping remote using link-local address

This code example shows how to send an echo request message to a remote node on a specific interface (mp_interface). The application must allocate a packet buffer for it and optionally fill the payload. In the example below, 10 bytes of byte 0xA5 will be sent as additional data.

uint32_t                   err_code;
ipv6_addr_t                src_addr;
ipv6_addr_t                dest_addr;
iot_pbuffer_alloc_param_t  pbuff_param;
iot_pbuffer_t            * p_buffer;

// Create the link-local address of local node.
IPV6_CREATE_LINK_LOCAL_FROM_EUI64(&src_addr, mp_interface->local_addr.identifier);

// Create the link-local address of remote node.
IPV6_CREATE_LINK_LOCAL_FROM_EUI64(&dest_addr, mp_interface->remote_addr.identifier);

// Allocate a packet buffer.
pbuff_param.flags  = PBUFFER_FLAG_DEFAULT;
pbuff_param.type   = ICMP6_PACKET_TYPE;
pbuff_param.length = ICMP6_ECHO_REQUEST_PAYLOAD_OFFSET + 10;

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

// Set a payload.
memset(p_buffer->p_payload + ICMP6_ECHO_REQUEST_PAYLOAD_OFFSET, 0xA5, 10);
p_request->length = ICMP6_ECHO_REQUEST_PAYLOAD_OFFSET + 10;

// Send an echo request to all nodes.
err_code = icmp6_echo_request(mp_interface, &src_addr, &dest_addr, p_buffer);
APP_ERROR_CHECK(err_code);

Sending router solicitation to all router addresses

This code example shows how to find routers on the link using a router solicitation message. All buffers are allocated inside a function. If a router is available on the link, it should send a router advertisement message.

uint32_t          err_code;
ipv6_addr_t       src_addr;
const ipv6_addr_t all_router_multicast_addr = {{0xff,0x02,0x00,0x00,0x00,00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x02}};

// Create the link-local address of local node.
IPV6_CREATE_LINK_LOCAL_FROM_EUI64(&src_addr, mp_interface->local_addr.identifier);

// Send router solicitation to all nodes.
err_code = icmp6_rs_send(mp_interface, &src_addr, &all_router_multicast_addr);
APP_ERROR_CHECK(err_code);

Sending neighbor solicitation with ARO option to router node

This code example shows how to register an IPv6 address (source address in the request) in the default router (m_router_addr). The following example tries to register its global address for one hour (60 minutes).

uint32_t           err_code;
icmp6_ns_param_t   ns_param;
const ipv6_addr_t  src_addr = {{0x20,0x01,0x0d,0xb8,0x00,0x00,0x00,0x00,0x02,0x11,0x22,0xff,0xfe,0x33,0x44,0x55}};

// Add ARO option.
ns_param.add_aro      = true;
ns_param.aro_lifetime = 1000;

// Unicast address.
IPV6_CREATE_LINK_LOCAL_FROM_EUI64(&ns_param.target_addr,
                                  mp_interface->peer_addr.identifier);

// Send neighbor solicitation to peer.
err_code = icmp6_ns_send(mp_interface,
                         &src_addr,
                         &ns_param.target_addr,
                         &ns_param);
APP_ERROR_CHECK(err_code);

Configuration parameters

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

ICMP6_DISABLE_LOGS

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

ICMP6_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

ICMP6_ENABLE_ND6_MESSAGES_TO_APPLICATION

Enables calls to the ICMPv6 event handler when a neighbor discovery message is received.

Description	Value
Enable	1
Disable	0
Dependencies	None

ICMP6_ENABLE_ALL_MESSAGES_TO_APPLICATION

Enables calls to the ICMPv6 event handler when an ICMPv6 message is received.

Description	Value
Enable	1
Disable	0
Dependencies	None

ICMP6_ENABLE_HANDLE_ECHO_REQUEST_TO_APPLICATION

Enables the handling of echo requests by the application. Set this parameter to 1 to disable the internal sending of echo responses after processing ICMP packets in the application (if ICMP6_ENABLE_ALL_MESSAGES_TO_APPLICATION is set). Set it to 0 to make sure that echo requests are handled internally and the ICMPv6 module sends automatic replies after processing ICMP packets in the application.

If this parameter is set to 1, the application is responsible for processing echo requests, and it should also generate echo responses.

Description	Value
Enable	1
Disable	0
Dependencies	None