Modules#

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, compare URI (Uniform Resource Identifier) paths, free CoAP packets, and more. The CoAP component can rely on either a static or dynamic memory pool to store CoAP packets. The dynamic implementation uses OS-dependent memory allocation and memory release APIs. The static implementation is only available when using FreeRTOS.

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

Functions#

bool

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.

bool

sl_wisun_coap_init_default(void)

Initialize Wi-SUN CoAP default.

bool

sl_wisun_coap_is_initialized(void)

Get lib state.

void *

sl_wisun_coap_malloc(uint16_t size)

Implement malloc.

void

sl_wisun_coap_free(void *addr)

Free Wi-SUN CoAP.

sl_wisun_coap_packet_t *

sl_wisun_coap_parser(uint16_t packet_data_len, uint8_t *packet_data)

CoAP parser wrapper function.

uint16_t

sl_wisun_coap_builder_calc_size(const sl_wisun_coap_packet_t *message)

CoAP packet calc size wrapper.

int16_t

sl_wisun_coap_builder(uint8_t *dest_buff, const sl_wisun_coap_packet_t *message)

CoAP message builder Wi-SUN.

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.

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.

const char *

sl_wisun_coap_get_parsed_uri_path(char *dest_buff, const uint16_t buff_length)

Get the last parsed URI path.

bool

sl_wisun_coap_get_payload(const sl_wisun_coap_packet_t *source_packet, uint8_t *dest_buff, const uint16_t buff_length)

Get payload.

void

sl_wisun_coap_set_payload(sl_wisun_coap_packet_t *dest_packet, uint8_t *source_buff, const uint16_t buff_length)

Set payload.

bool

sl_wisun_coap_get_token(const sl_wisun_coap_packet_t *source_packet, uint8_t *dest_buff, const uint16_t buff_length)

Get token.

void

sl_wisun_coap_set_token(sl_wisun_coap_packet_t *dest_packet, uint8_t *source_buff, const uint8_t buff_length)

Set token.

bool

sl_wisun_coap_get_options_list(const sl_wisun_coap_packet_t *source_packet, sl_wisun_coap_option_list_t *dest)

Get options list.

void

sl_wisun_coap_set_options_list(sl_wisun_coap_packet_t *dest_packet, sl_wisun_coap_option_list_t *source)

Set options list.

const sl_wisun_coap_handle_t *

sl_wisun_coap_get_lib_handler(void)

Get the library handler pointer from the internal handler structure.

void

sl_wisun_coap_destroy_packet(sl_wisun_coap_packet_t *packet)

Destroy packet.

bool

sl_wisun_coap_compare_uri_path(const char *uri_path, const uint16_t buff_max_len)

Compare URI path with the stored from the previous parsed packet.

bool

sl_wisun_coap_compare(const char *str1, const uint16_t len1, const char *str2, const uint16_t len2)

Helper function to compare two strings with known lengths.

Function Documentation#

sl_wisun_coap_init#

bool 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. Returns

true Proper initialization
false Error

sl_wisun_coap_init_default#

static bool 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. Returns

true Proper initialization
false Error

sl_wisun_coap_is_initialized#

bool sl_wisun_coap_is_initialized (void )

Get lib state.

Parameters

Type	Direction	Argument Name	Description
void	N/A

Gets the initialized state of the CoAP library to decide whether the init is needed. Returns

true Initialized
false Not initialized

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_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.

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

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_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_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_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

sl_wisun_coap_get_parsed_uri_path#

const char* sl_wisun_coap_get_parsed_uri_path (char * dest_buff, const uint16_t buff_length)

Get the last parsed URI path.

Parameters

Type	Direction	Argument Name	Description
char *	N/A	dest_buff	destination buff
const uint16_t	N/A	buff_length	destination buffer size

Thread safe way to get the URI path from last parsed packet Returns

const char* On success, pointer to the destination buffer, NULL on failure

sl_wisun_coap_get_payload#

bool sl_wisun_coap_get_payload (const sl_wisun_coap_packet_t * source_packet, uint8_t * dest_buff, const uint16_t buff_length)

Get payload.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	[in]	source_packet	source packet
uint8_t *	[out]	dest_buff	destination buffer
const uint16_t	[in]	buff_length	length of destination buffer

Thread-safe deep copy Returns

true Success
false Failure

sl_wisun_coap_set_payload#

void sl_wisun_coap_set_payload (sl_wisun_coap_packet_t * dest_packet, uint8_t * source_buff, const uint16_t buff_length)

Set payload.

Parameters

Type	Direction	Argument Name	Description
sl_wisun_coap_packet_t *	[out]	dest_packet	destination packet
uint8_t *	[in]	source_buff	source buffer
const uint16_t	[in]	buff_length	source buffer length

Set the corresponding packet member ptr and length.

sl_wisun_coap_get_token#

bool sl_wisun_coap_get_token (const sl_wisun_coap_packet_t * source_packet, uint8_t * dest_buff, const uint16_t buff_length)

Get token.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	[in]	source_packet	source packet
uint8_t *	[out]	dest_buff	destination buffer
const uint16_t	[in]	buff_length	length of destination buffer

Thread-safe deep copy Returns

true Success
false Failure

sl_wisun_coap_set_token#

void sl_wisun_coap_set_token (sl_wisun_coap_packet_t * dest_packet, uint8_t * source_buff, const uint8_t buff_length)

Set token.

Parameters

Type	Direction	Argument Name	Description
sl_wisun_coap_packet_t *	N/A	dest_packet	destination packet
uint8_t *	N/A	source_buff	source buffer
const uint8_t	N/A	buff_length	source buffer length

Set the corresponding packet member ptr and length.

sl_wisun_coap_get_options_list#

bool sl_wisun_coap_get_options_list (const sl_wisun_coap_packet_t * source_packet, sl_wisun_coap_option_list_t * dest)

Get options list.

Parameters

Type	Direction	Argument Name	Description
const sl_wisun_coap_packet_t *	N/A	source_packet	source packet
sl_wisun_coap_option_list_t *	N/A	dest	destination option list structure

Thread-safe deep copy Returns

true Success
false Failure

sl_wisun_coap_set_options_list#

void sl_wisun_coap_set_options_list (sl_wisun_coap_packet_t * dest_packet, sl_wisun_coap_option_list_t * source)

Set options list.

Parameters

Type	Direction	Argument Name	Description
sl_wisun_coap_packet_t *	[out]	dest_packet	destination packet ptr
sl_wisun_coap_option_list_t *	[in]	source	source option list

Set the option list pointer.

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_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_compare_uri_path#

bool sl_wisun_coap_compare_uri_path (const char * uri_path, const uint16_t buff_max_len)

Compare URI path with the stored from the previous parsed packet.

Parameters

Type	Direction	Argument Name	Description
const char *	N/A	uri_path	URI path
const uint16_t	N/A	buff_max_len	buffer size of the URI path

Thread-safe way to compare URI paths. The buffer length must be set, eg strlen(uri_path) + 1 Returns

true Matched
false Not matched

sl_wisun_coap_compare#

bool sl_wisun_coap_compare (const char * str1, const uint16_t len1, const char * str2, const uint16_t len2)

Helper function to compare two strings with known lengths.

Parameters

Type	Direction	Argument Name	Description
const char *	N/A	str1	pointer to the first string
const uint16_t	N/A	len1	length of the first string
const char *	N/A	str2	pointer to the other string
const uint16_t	N/A	len2	length of the other string

Returns

true Matched
false Not matched