nanocoap.h

nanocoap API

COAP_GET
1
(0x1)
COAP_POST
1
(0x2)
COAP_PUT
1
(0x4)
COAP_DELETE
1
(0x8)
NANOCOAP_NOPTS_MAX
1
(16)
NANOCOAP_URI_MAX
1
(64)
NANOCOAP_BLOCK_SIZE_EXP_MAX

Maximum size for a blockwise transfer as power of 2. 

1
(6)
COAP_OPT_FINISH_NONE

no special handling required 

1
(0x0000)
COAP_OPT_FINISH_PAYLOAD

expect a payload to follow 

1
(0x0001)
COAP_FORMAT_NONE

Nanocoap-specific value to indicate no format specified. 

1
(UINT16_MAX)
COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER

Resource definition for the default .well-known/core handler. 

1
2
3
4
5
{ \
        .path = "/.well-known/core", \
        .methods = COAP_GET, \
        .handler = coap_well_known_core_default_handler \
    }
msp430_types.h::ssize_t(* coap_handler_t()

Resource handler type.

const coap_resource_t coap_resources()

Global CoAP resource list.

const unsigned coap_resources_numof

Number of entries in global CoAP resource list.

int coap_parse(coap_pkt_t * pkt, uint8_t * buf, msp430_types.h::size_t len)

Parse a CoAP PDU.

This function parses a raw CoAP PDU from buf with size len and fills the structure pointed to by pkt. pkt must point to a preallocated coap_pkt_t structure.

Parameters

pkt:structure to parse into
buf:pointer to raw packet data
len:length of packet at buf

Return values

  • 0 on success
  • <0 on error
msp430_types.h::ssize_t coap_build_reply(coap_pkt_t * pkt, unsigned code, uint8_t * rbuf, unsigned rlen, unsigned payload_len)

Build reply to CoAP request.

This function can be used to create a reply to any CoAP request packet. It will create the reply packet header based on parameters from the request (e.g., id, token). Passing a non-zero payload_len will ensure the payload fits into the buffer along with the header.

Parameters

pkt:packet to reply to
code:reply code (e.g., COAP_CODE_204)
rbuf:buffer to write reply to
rlen:size of rbuf
payload_len:length of payload

Return values

  • size of reply packet on success
  • <0 on error
msp430_types.h::ssize_t coap_reply_simple(coap_pkt_t * pkt, unsigned code, uint8_t * buf, msp430_types.h::size_t len, unsigned ct, const uint8_t * payload, uint8_t payload_len)

Create CoAP reply (convenience function)

This is a simple wrapper that allows for building CoAP replies for simple use-cases.

The reply will be written to buf. Is payload and payload_len non-zero, the payload will be copied into the resulting reply packet.

Parameters

pkt:packet to reply to
code:reply code (e.g., COAP_CODE_204)
buf:buffer to write reply to
len:size of buf
ct:content type of payload
payload:ptr to payload
payload_len:length of payload

Return values

  • size of reply packet on success
  • <0 on error
msp430_types.h::ssize_t coap_handle_req(coap_pkt_t * pkt, uint8_t * resp_buf, unsigned resp_buf_len)

Handle incoming CoAP request.

This function will find the correct handler, call it and write the reply into resp_buf.

Parameters

pkt:pointer to (parsed) CoAP packet
resp_buf:buffer for response
resp_buf_len:size of response buffer

Return values

  • size of reply packet on success
  • <0 on error
msp430_types.h::ssize_t coap_build_hdr(coap_hdr_t * hdr, unsigned type, uint8_t * token, msp430_types.h::size_t token_len, unsigned code, uint16_t id)

Builds a CoAP header.

Caller must ensure hdr can hold the header and the full token!

Parameters

hdr:hdr to fill
type:CoAP packet type (e.g., COAP_TYPE_CON, …)
token:token
token_len:length of token
code:CoAP code (e.g., COAP_CODE_204, …)
id:CoAP request id

Return values

  • length of resulting header
void coap_pkt_init(coap_pkt_t * pkt, uint8_t * buf, msp430_types.h::size_t len, msp430_types.h::size_t header_len)

Initialize a packet struct, to build a message buffer.

Parameters

pkt:pkt to initialize
buf:buffer to write for pkt, with CoAP header already initialized
len:length of buf
header_len:length of header in buf, including token

msp430_types.h::size_t coap_put_option(uint8_t * buf, uint16_t lastonum, uint16_t onum, uint8_t * odata, msp430_types.h::size_t olen)

Insert a CoAP option into buffer.

This function writes a CoAP option with nr. onum to buf. It handles calculating the option delta (from lastonum), encoding the length from olen and copying the option data from odata.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 for first option
onum:number of option
odata:ptr to raw option data (or NULL)
olen:length of odata (if any)

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_put_option_ct(uint8_t * buf, uint16_t lastonum, uint16_t content_type)

Insert content type option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
content_type:content type to set

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_opt_put_string(uint8_t * buf, uint16_t lastonum, uint16_t optnum, const char * string, char separator)

Encode the given string as multi-part option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
optnum:option number to use
string:string to encode as option
separator:character used in string to separate parts

Return values

  • number of bytes written to buf
msp430_types.h::size_t coap_opt_put_uri_path(uint8_t * buf, uint16_t lastonum, const char * uri)

Convenience function for inserting URI_PATH option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
uri:ptr to source URI

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_opt_put_uri_query(uint8_t * buf, uint16_t lastonum, const char * uri)

Convenience function for inserting URI_QUERY option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
uri:ptr to source URI

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_opt_put_location_path(uint8_t * buf, uint16_t lastonum, const char * location)

Convenience function for inserting LOCATION_PATH option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
location:ptr to string holding the location

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_opt_put_location_query(uint8_t * buf, uint16_t lastonum, const char * location)

Convenience function for inserting LOCATION_QUERY option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), or 0 if first option
location:ptr to string holding the location

Return values

  • amount of bytes written to buf
int coap_get_blockopt(coap_pkt_t * pkt, uint16_t option, uint32_t * blknum, unsigned * szx)

Generic block option getter.

Parameters

pkt:pkt to work on
option:actual block option number to get
blknum:block number
szx:SZX value

Return values

  • -1 if option not found
  • 0 if more flag is not set
  • 1 if more flag is set
int coap_get_block1(coap_pkt_t * pkt, coap_block1_t * block1)

Block1 option getter.

This function gets a CoAP packet’s block1 option and parses it into a helper structure.

If no block1 option is present in pkt, the values in block1 will be initialized with zero. That implies both block1->offset and block1->more are also valid in that case, as packet with offset==0 and more==0 means it contains all the payload for the corresponding request.

Parameters

pkt:pkt to work on
block1:ptr to preallocated coap_block1_t structure

Return values

  • 0 if block1 option not present
  • 1 if structure has been filled
int coap_get_block2(coap_pkt_t * pkt, coap_block1_t * block2)

Block2 option getter.

Parameters

pkt:pkt to work on
block2:ptr to preallocated coap_block1_t structure

Return values

  • 0 if block2 option not present
  • 1 if structure has been filled
msp430_types.h::size_t coap_put_option_block1(uint8_t * buf, uint16_t lastonum, unsigned blknum, unsigned szx, int more)

Insert block1 option into buffer.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), must be < 27
blknum:block number
szx:SXZ value
more:more flag (1 or 0)

Return values

  • amount of bytes written to buf
msp430_types.h::size_t coap_put_block1_ok(uint8_t * pkt_pos, coap_block1_t * block1, uint16_t lastonum)

Insert block1 option into buffer (from coap_block1_t)

This function is wrapper around nanocoap.h::coap_put_option_block1(), taking its arguments from a coap_block1_t struct.

It will write option Nr. 27 (COAP_OPT_BLOCK1).

It is safe to be called when block1 was generated for a non-blockwise request.

Parameters

pkt_pos:buffer to write to
block1:ptr to block1 struct (created by nanocoap.h::coap_get_block1())
lastonum:last option number (must be < 27)

Return values

  • amount of bytes written to pkt_pos
msp430_types.h::ssize_t coap_opt_add_string(coap_pkt_t * pkt, uint16_t optnum, const char * string, char separator)

Encode the given string as option(s) into pkt.

Use separator to split string into multiple options.

Parameters

pkt:pkt referencing target buffer
optnum:option number to use
string:string to encode as option
separator:character used in string to separate parts

Return values

  • number of bytes written to buffer
  • -ENOSPC if no available options
msp430_types.h::ssize_t coap_opt_add_uint(coap_pkt_t * pkt, uint16_t optnum, uint32_t value)

Encode the given uint option into pkt.

Parameters

pkt:pkt referencing target buffer
optnum:option number to use
value:uint to encode

Return values

  • number of bytes written to buffer
  • <0 reserved for error but not implemented yet
msp430_types.h::ssize_t coap_opt_finish(coap_pkt_t * pkt, uint16_t flags)

Finalizes options as required and prepares for payload.

Parameters

pkt:pkt to update
flags:see COAP_OPT_FINISH… macros

Return values

  • total number of bytes written to buffer
msp430_types.h::size_t coap_opt_put_block2(uint8_t * buf, uint16_t lastonum, coap_block_slicer_t * slicer, bool more)

Insert block2 option into buffer.

When calling this function to initialize a packet with a block2 option, the more flag must be set to prevent the creation of an option with a length too small to contain the size bit.

Parameters

buf:buffer to write to
lastonum:number of previous option (for delta calculation), must be < 23
slicer:coap blockwise slicer helper struct
more:more flag (1 or 0)

Return values

  • amount of bytes written to buf
unsigned coap_get_content_type(coap_pkt_t * pkt)

Get content type from packet.

Parameters

pkt:packet to work on

Return values

  • the packet’s content type value if included, COAP_FORMAT_NONE otherwise
msp430_types.h::ssize_t coap_opt_get_string(const coap_pkt_t * pkt, uint16_t optnum, uint8_t * target, msp430_types.h::size_t max_len, char separator)

Read a full option as null terminated string into the target buffer.

This function is for reading and concatenating string based, multi-part CoAP options like COAP_OPT_URI_PATH or COAP_OPT_LOCATION_PATH. It will write all parts of the given option into the target buffer, separating the parts using the given separator. The resulting string is \0 terminated.

Parameters

pkt:packet to read from
optnum:absolute option number
target:target buffer
max_len:size of target
separator:character used for separating the option parts

Return values

  • -ENOSPC if the complete option does not fit into target
  • nr of bytes written to target (including ‘\0’)
msp430_types.h::ssize_t coap_get_uri_path(const coap_pkt_t * pkt, uint8_t * target)

Convenience function for getting the packet’s URI_PATH.

This function decodes the pkt’s URI option into a “/”-separated and ‘\0’-terminated string.

Caller must ensure target can hold at least NANOCOAP_URI_MAX bytes!

Parameters

pkt:pkt to work on
target:buffer for target URI

Return values

  • -ENOSPC if URI option is larger than NANOCOAP_URI_MAX
  • nr of bytes written to target (including ‘\0’)
msp430_types.h::ssize_t coap_get_uri_query(const coap_pkt_t * pkt, uint8_t * target)

Convenience function for getting the packet’s URI_QUERY option.

This function decodes the pkt’s URI_QUERY option into a “&”-separated and ‘\0’-terminated string.

Caller must ensure target can hold at least NANOCOAP_URI_MAX bytes!

Parameters

pkt:pkt to work on
target:buffer for target URI

Return values

  • -ENOSPC if URI option is larger than NANOCOAP_URI_MAX
  • nr of bytes written to target (including ‘\0’)
msp430_types.h::ssize_t coap_get_location_path(const coap_pkt_t * pkt, uint8_t * target, msp430_types.h::size_t max_len)

Convenience function for getting the packet’s LOCATION_PATH option.

This function decodes the pkt’s LOCATION_PATH option into a ‘/’-separated and ‘\0’-terminated string.

Caller must ensure target can hold at least 2 bytes!

Parameters

pkt:pkt to work on
target:buffer for location path
max_len:size of target in bytes

Return values

  • -ENOSPC if URI option is larger than max_len
  • nr of bytes written to target (including ‘\0’)
msp430_types.h::ssize_t coap_get_location_query(const coap_pkt_t * pkt, uint8_t * target, msp430_types.h::size_t max_len)

Convenience function for getting the packet’s LOCATION_QUERY option.

This function decodes the pkt’s LOCATION_PATH option into a ‘&’-separated and ‘\0’-terminated string.

Caller must ensure target can hold at least 2 bytes!

Parameters

pkt:pkt to work on
target:buffer for location path
max_len:size of target in bytes

Return values

  • -ENOSPC if URI option is larger than max_len
  • nr of bytes written to target (including ‘\0’)
void coap_block2_init(coap_pkt_t * pkt, coap_block_slicer_t * slicer)

Initialize a block2 slicer struct for writing the payload.

This function determines the size of the response payload based on the size requested by the client in pkt.

Parameters

pkt:packet to work on
slicer:Preallocated slicer struct to fill

void coap_block2_finish(coap_block_slicer_t * slicer)

Finish a block2 response.

This function finalizes the block2 response header

Checks whether the more bit should be set in the block2 option and sets/clears it if required. Doesn’t return the number of bytes as this overwrites bytes in the packet, it doesn’t add new bytes to the packet.

Parameters

slicer:Preallocated slicer struct to use

msp430_types.h::ssize_t coap_block2_build_reply(coap_pkt_t * pkt, unsigned code, uint8_t * rbuf, unsigned rlen, unsigned payload_len, coap_block_slicer_t * slicer)

Build reply to CoAP block2 request.

This function can be used to create a reply to a CoAP block2 request packet. In addition to nanocoap.h::coap_build_reply(), this function checks the block2 option and returns an error message to the client if necessary.

Parameters

pkt:packet to reply to
code:reply code (e.g., COAP_CODE_204)
rbuf:buffer to write reply to
rlen:size of rbuf
payload_len:length of payload
slicer:slicer to use

Return values

  • size of reply packet on success
  • <0 on error
msp430_types.h::size_t coap_blockwise_put_char(coap_block_slicer_t * slicer, uint8_t * bufpos, char c)

Add a single character to a block2 reply.

This function is used to add single characters to a CoAP block2 reply. It checks whether the character should be added to the buffer and ignores it when the character is outside the current block2 request.

Parameters

slicer:slicer to use
bufpos:pointer to the current payload buffer position
c:character to write

Return values

  • Number of bytes writen to bufpos
msp430_types.h::size_t coap_blockwise_put_bytes(coap_block_slicer_t * slicer, uint8_t * bufpos, const uint8_t * c, msp430_types.h::size_t len)

Add a byte array to a block2 reply.

This function is used to add an array of bytes to a CoAP block2 reply. it checks which parts of the string should be added to the reply and ignores parts that are outside the current block2 request.

Parameters

slicer:slicer to use
bufpos:pointer to the current payload buffer position
c:byte array to copy
len:length of the byte array

Return values

  • Number of bytes writen to bufpos
unsigned coap_szx2size(unsigned szx)

Helper to decode SZX value to size in bytes.

Parameters

szx:SZX value to decode

Return values

  • SZX value decoded to bytes
unsigned coap_get_ver(coap_pkt_t * pkt)

Get the CoAP version number.

Parameters

pkt:CoAP packet

Return values

  • CoAP version number
unsigned coap_get_type(coap_pkt_t * pkt)

Get the message type.

Parameters

pkt:CoAP packet

Return values

  • COAP_TYPE_CON
  • COAP_TYPE_NON
  • COAP_TYPE_ACK
  • COAP_TYPE_RST
unsigned coap_get_token_len(coap_pkt_t * pkt)

Get a message’s token length [in byte].

Parameters

pkt:CoAP packet

Return values

  • length of token in the given message (0-8 byte)
unsigned coap_get_code_class(coap_pkt_t * pkt)

Get a message’s code class (3 most significant bits of code)

Parameters

pkt:CoAP packet

Return values

  • message code class
unsigned coap_get_code_detail(coap_pkt_t * pkt)

Get a message’s code detail (5 least significant bits of code)

Parameters

pkt:CoAP packet

Return values

  • message code detail
unsigned coap_get_code_raw(coap_pkt_t * pkt)

Get a message’s raw code (class + detail)

Parameters

pkt:CoAP packet

Return values

  • raw message code
unsigned coap_get_code(coap_pkt_t * pkt)

Get a message’s code in decimal format ((class * 100) + detail)

Parameters

pkt:CoAP packet

Return values

  • message code in decimal format
unsigned coap_get_id(coap_pkt_t * pkt)

Get the message ID of the given CoAP packet.

Parameters

pkt:CoAP packet

Return values

  • message ID
uint8_t * coap_hdr_data_ptr(coap_hdr_t * hdr)

Get the start of data after the header.

Parameters

hdr:Header of CoAP packet in contiguous memory

Return values

  • pointer to first byte after the header
unsigned coap_get_total_hdr_len(coap_pkt_t * pkt)

Get the total header length (4-byte header + token length)

Parameters

pkt:CoAP packet

Return values

  • total header length
uint8_t coap_code(unsigned cls, unsigned detail)

Encode given code class and code detail to raw code.

Parameters

cls:message code class
detail:message code detail

Return values

  • raw message code
void coap_hdr_set_code(coap_hdr_t * hdr, uint8_t code)

Write the given raw message code to given CoAP header.

Parameters

hdr:CoAP header to write to
code:raw message code

void coap_hdr_set_type(coap_hdr_t * hdr, unsigned type)

Set the message type for the given CoAP header.

Parameters

hdr:CoAP header to write
type:message type as integer value [0-3]

unsigned coap_method2flag(unsigned code)

Convert message code (request method) into a corresponding bit field.

Parameters

code:request code denoting the request method

Return values

  • bit field corresponding to the given request method
bool coap_has_observe(coap_pkt_t * pkt)

Identifies a packet containing an observe option.

Parameters

pkt:CoAP packet

Return values

  • true if observe value is set
  • false if not
void coap_clear_observe(coap_pkt_t * pkt)

Clears the observe option value from a packet.

Parameters

pkt:CoAP packet

uint32_t coap_get_observe(coap_pkt_t * pkt)

Get the value of the observe option from the given packet.

Parameters

pkt:CoAP packet

Return values

  • value of the observe option
msp430_types.h::ssize_t coap_well_known_core_default_handler(coap_pkt_t * pkt, uint8_t * buf, msp430_types.h::size_t len, void * context)

Reference to the default .well-known/core handler defined by the application.

struct coap_hdr_t

Raw CoAP PDU header structure.

uint8_t ver_t_tkl

version, token, token length

uint8_t code

CoAP code (e.g.m 205)

uint16_t id

Req/resp ID.

struct coap_optpos_t

CoAP option array entry.

uint16_t opt_num

full CoAP option number

uint16_t offset

offset in packet

struct coap_pkt_t

CoAP PDU parsing context structure.

coap_hdr_t * hdr

pointer to raw packet

uint8_t * token

pointer to token

uint8_t * payload

pointer to payload

uint16_t payload_len

length of payload

uint16_t options_len

length of options array

coap_optpos_t options()

option offset array

struct coap_resource_t

Type for CoAP resource entry.

const char * path

URI path of resource.

unsigned methods

OR’ed methods this resource allows.

nanocoap.h::coap_handler_t handler

ptr to resource handler

void * context

ptr to user defined context data

struct coap_block1_t

Block1 helper struct.

msp430_types.h::size_t offset

offset of received data

uint32_t blknum

block number

unsigned szx

szx value

int more

-1 for no option, 0 for last block, 1 for more blocks coming

struct coap_block_slicer_t

Blockwise transfer helper struct.

msp430_types.h::size_t start

Start offset of the current block.

msp430_types.h::size_t end

End offset of the current block.

msp430_types.h::size_t cur

Offset of the generated content.

uint8_t * opt

Pointer to the placed option.