CoAP#

The Wi-SUN CoAP component provides an application layer implementation on top of the Wi-SUN stack and its socket API. The CoAP protocol is designed as a specialized Internet Application Protocol for constrained devices in lossy networks (see RFC 7252 for additional information). Wi-SUN FAN networks fit this definition. The CoAP implementation relies on the UDP transport layer to send and receive packets.

A number of helper functions are part of the component to help build CoAP payloads, parse CoAP packets, free CoAP packets, and more.

The CoAP Resource Handler service handles registered resources. Resource Discovery request provides an interface to get information about available resources. Resource has more attributes over URI (Uniform Resource Identifier) path, which can be filtered by particular Resource Discovery request.

The CoAP Notification service provides an interface to create and schedule notifications to the remote host. Schedule time and send condition can be customized depending on the application.

To use the CoAP component in your application, add it to your project and initialize it with sl_wisun_coap_init().

The Wi-SUN CoAP component offers an application layer implementation built on top of the Wi-SUN stack and its socket API. The CoAP protocol is specifically designed as an Internet Application Protocol for constrained devices operating in lossy networks (as defined in RFC 7252). Wi-SUN FAN networks precisely fit this definition.

The CoAP implementation relies on the UDP transport layer for sending and receiving packets. Within the component, you'll find a set of helper functions that assist in building CoAP payloads, parsing CoAP packets, and freeing CoAP packets. Additionally, the CoAP Resource Handler service manages registered resources.

For resource discovery, the Resource Discovery request provides an interface to retrieve information about available resources. These resources have additional attributes beyond the URI (Uniform Resource Identifier) path, which can be selectively filtered using specific Resource Discovery requests.

Furthermore, the CoAP Notification service allows you to create and schedule notifications for the remote host. You can customize the schedule time and send conditions based on your application requirements. To incorporate the CoAP component into your application, simply add it to your project and initialize it using sl_wisun_coap_init().

Modules#

CoAP type definitions

Functions#

sl_wisun_coap_packet_t *

sl_wisun_coap_build_response(const sl_wisun_coap_packet_t *req, sl_wisun_coap_message_code_t msg_code)

Build generic response for request wrapper function.

int16_t

sl_wisun_coap_builder(uint8_t *dest_buff, const sl_wisun_coap_packet_t *message)

CoAP message builder Wi-SUN.

uint16_t

sl_wisun_coap_builder_calc_size(const sl_wisun_coap_packet_t *message)

CoAP packet calc size wrapper.

void

sl_wisun_coap_destroy_packet(sl_wisun_coap_packet_t *packet)

Destroy packet.

__STATIC_INLINE void

sl_wisun_coap_destroy_payload_str(char *str)

Destroy payload string.

__STATIC_INLINE void

sl_wisun_coap_destroy_uri_path_str(char *uri_str)

Destroy URI path string.

void

sl_wisun_coap_free(void *addr)

Free Wi-SUN CoAP.

const sl_wisun_coap_handle_t *

sl_wisun_coap_get_lib_handler(void)

Get the library handler pointer from the internal handler structure.

char *

sl_wisun_coap_get_payload_str(const sl_wisun_coap_packet_t *const packet)

Prepare payload string.

char *

sl_wisun_coap_get_uri_path_str(const sl_wisun_coap_packet_t *const packet)

Prepare URI path string.

void

sl_wisun_coap_init(const sl_wisun_coap_tx_callback tx_callback, const sl_wisun_coap_rx_callback rx_callback, const sl_wisun_coap_version_t version)

Initialize Wi-SUN CoAP.

__STATIC_INLINE void

sl_wisun_coap_init_default(void)

Initialize Wi-SUN CoAP default.

void *

sl_wisun_coap_malloc(uint16_t size)

Implement malloc.

sl_wisun_coap_packet_t *

sl_wisun_coap_parser(uint16_t packet_data_len, uint8_t *packet_data)

CoAP parser wrapper function.

void

sl_wisun_coap_print_packet(const sl_wisun_coap_packet_t *packet, const bool hex_format)

Print CoAP packets and all of attached buffer, payload, token, uri_path.

Macros#

#define

SL_COAP_SERVICE_LOOP ()

CoAP Service loop.

Function Documentation#

sl_wisun_coap_build_response#

sl_wisun_coap_packet_t * sl_wisun_coap_build_response (const sl_wisun_coap_packet_t * req, sl_wisun_coap_message_code_t msg_code)

Build generic response for request wrapper function.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	[in]	req	request
sl_wisun_coap_message_code_t	[in]	msg_code	message code to build

Used sn_coap_build_response. Returns

sl_wisun_coap_header_t* built packet ptr on the heap

sl_wisun_coap_builder#

int16_t sl_wisun_coap_builder (uint8_t * dest_buff, const sl_wisun_coap_packet_t * message)

CoAP message builder Wi-SUN.

Parameters

Type	Direction	Argument Name	Description
uint8_t *	[out]	dest_buff	destination buffer for raw message
const sl_wisun_coap_packet_t *	[in]	message	message structure

Used sl_wisun_coap_builder. Returns

int16_t On success bytes of built message, on failure -1 if CoAP header structure is wrong -2 if NULL ptr set as argument

sl_wisun_coap_builder_calc_size#

uint16_t sl_wisun_coap_builder_calc_size (const sl_wisun_coap_packet_t * message)

CoAP packet calc size wrapper.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	[in]	message	message ptr

Used sn_coap_builder_calc_needed_packet_data_size. Returns

uint16_t size

sl_wisun_coap_destroy_packet#

void sl_wisun_coap_destroy_packet (sl_wisun_coap_packet_t * packet)

Destroy packet.

Parameters

Type	Direction	Argument Name	Description
sl_wisun_coap_packet_t *	N/A	packet	packet

It must be used to avoid memory leaks! Free the all of allocated buffer for packet

sl_wisun_coap_destroy_payload_str#

__STATIC_INLINE void sl_wisun_coap_destroy_payload_str (char * str)

Destroy payload string.

Parameters

Type	Direction	Argument Name	Description
char *	[in]	str	String

'\0' terminated string in the heap, it must be freed

sl_wisun_coap_destroy_uri_path_str#

__STATIC_INLINE void sl_wisun_coap_destroy_uri_path_str (char * uri_str)

Destroy URI path string.

Parameters

Type	Direction	Argument Name	Description
char *	[in]	uri_str	URI string ptr

Call free on allocated pointer

sl_wisun_coap_free#

void sl_wisun_coap_free (void * addr)

Free Wi-SUN CoAP.

Parameters

Type	Direction	Argument Name	Description
void *	N/A	addr	address ptr

OS-dependent thread-safe implementation.

Referenced by sl_wisun_coap_destroy_payload_str , and sl_wisun_coap_destroy_uri_path_str

sl_wisun_coap_get_lib_handler#

const sl_wisun_coap_handle_t * sl_wisun_coap_get_lib_handler (void )

Get the library handler pointer from the internal handler structure.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Not thread safe! It is needed only to use Pelion mbed-coap library functions Returns

const sl_wisun_coap_handle_t* pointer to the lib handler

sl_wisun_coap_get_payload_str#

char * sl_wisun_coap_get_payload_str (const sl_wisun_coap_packet_t *const packet)

Prepare payload string.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *const	[in]	packet	Packet

'\0' terminated string in the heap, it must be freed Returns

char* payload string, NULL on error

sl_wisun_coap_get_uri_path_str#

char * sl_wisun_coap_get_uri_path_str (const sl_wisun_coap_packet_t *const packet)

Prepare URI path string.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *const	[in]	packet	Packet

'\0' terminated string in the heap, it must be freed Returns

char* URI path string, NULL on error

sl_wisun_coap_init#

void sl_wisun_coap_init (const sl_wisun_coap_tx_callback tx_callback, const sl_wisun_coap_rx_callback rx_callback, const sl_wisun_coap_version_t version)

Initialize Wi-SUN CoAP.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_tx_callback	[in]	tx_callback	TX callback, if it's NULL, the default callback is applied
const sl_wisun_coap_rx_callback	[in]	rx_callback	RX callback, if it's NULL, the default callback is applied
const sl_wisun_coap_version_t	[in]	version	CoAP version

Set the Wi-SUN CoAP internal descriptor.

sl_wisun_coap_init_default#

__STATIC_INLINE void sl_wisun_coap_init_default (void )

Initialize Wi-SUN CoAP default.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Initializes the internal descriptor with default values.

sl_wisun_coap_malloc#

void * sl_wisun_coap_malloc (uint16_t size)

Implement malloc.

Parameters

Type	Direction	Argument Name	Description
uint16_t	N/A	size	size for malloc

OS-dependent thread-safe implementation. Returns

void* the memory pointer

sl_wisun_coap_parser#

sl_wisun_coap_packet_t * sl_wisun_coap_parser (uint16_t packet_data_len, uint8_t * packet_data)

CoAP parser wrapper function.

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	packet_data_len	packet data size
uint8_t *	[in]	packet_data	packet data ptr

Used sn_coap_parser Returns

sl_wisun_coap_packet_t* Parsed packet pointer

sl_wisun_coap_print_packet#

void sl_wisun_coap_print_packet (const sl_wisun_coap_packet_t * packet, const bool hex_format)

Print CoAP packets and all of attached buffer, payload, token, uri_path.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	[in]	packet	packet to print
const bool	[in]	hex_format	hex format bool to decide buffer print format

Pretty printer function, with hex format option for buffers