nanocoap small CoAP library

Provides CoAP functionality optimized for minimal resource usage. More...

Detailed Description

Provides CoAP functionality optimized for minimal resource usage.

Files

file  nanocoap.h
 nanocoap API
 
file  nanocoap_sock.h
 nanocoap high-level API
 

Data Structures

struct  coap_hdr_t
 Raw CoAP PDU header structure. More...
 
struct  coap_pkt_t
 CoAP option array entry. More...
 
struct  coap_resource_t
 Type for CoAP resource entry. More...
 

Macros

#define COAP_PORT   (5683)
 CoAP port to use.
 
#define COAP_WELL_KNOWN_CORE_DEFAULT_HANDLER   { "/.well-known/core", COAP_GET, coap_well_known_core_default_handler }
 Resource definition for the default .well-known/core handler.
 

Typedefs

typedef ssize_t(* coap_handler_t) (coap_pkt_t *pkt, uint8_t *buf, size_t len)
 Resource handler type.
 

Functions

int coap_parse (coap_pkt_t *pkt, uint8_t *buf, size_t len)
 Parse a CoAP PDU. More...
 
ssize_t coap_build_reply (coap_pkt_t *pkt, unsigned code, uint8_t *rbuf, unsigned rlen, unsigned payload_len)
 Build reply to CoAP request. More...
 
ssize_t coap_reply_simple (coap_pkt_t *pkt, unsigned code, uint8_t *buf, size_t len, unsigned ct, const uint8_t *payload, uint8_t payload_len)
 Create CoAP reply (convenience function) More...
 
ssize_t coap_handle_req (coap_pkt_t *pkt, uint8_t *resp_buf, unsigned resp_buf_len)
 Handle incoming CoAP request. More...
 
ssize_t coap_build_hdr (coap_hdr_t *hdr, unsigned type, uint8_t *token, size_t token_len, unsigned code, uint16_t id)
 Builds a CoAP header. More...
 
size_t coap_put_option (uint8_t *buf, uint16_t lastonum, uint16_t onum, uint8_t *odata, size_t olen)
 Insert a CoAP option into buffer. More...
 
size_t coap_put_option_ct (uint8_t *buf, uint16_t lastonum, uint16_t content_type)
 Insert content type option into buffer. More...
 
size_t coap_put_option_uri (uint8_t *buf, uint16_t lastonum, const char *uri, uint16_t optnum)
 Insert URI encoded option into buffer. More...
 
static unsigned coap_get_ver (coap_pkt_t *pkt)
 Get the CoAP version number. More...
 
static unsigned coap_get_type (coap_pkt_t *pkt)
 Get the message type. More...
 
static unsigned coap_get_token_len (coap_pkt_t *pkt)
 Get a message's token length [in byte]. More...
 
static unsigned coap_get_code_class (coap_pkt_t *pkt)
 Get a message's code class (3 most significant bits of code) More...
 
static unsigned coap_get_code_detail (coap_pkt_t *pkt)
 Get a message's code detail (5 least significant bits of code) More...
 
static unsigned coap_get_code_raw (coap_pkt_t *pkt)
 Get a message's raw code (class + detail) More...
 
static unsigned coap_get_code (coap_pkt_t *pkt)
 Get a message's code in decimal format ((class * 100) + detail) More...
 
static unsigned coap_get_id (coap_pkt_t *pkt)
 Get the message ID of the given CoAP packet. More...
 
static unsigned coap_get_total_hdr_len (coap_pkt_t *pkt)
 Get the total header length (4-byte header + token length) More...
 
static uint8_t coap_code (unsigned class, unsigned detail)
 Encode given code class and code detail to raw code. More...
 
static void coap_hdr_set_code (coap_hdr_t *hdr, uint8_t code)
 Write the given raw message code to given CoAP header. More...
 
static void coap_hdr_set_type (coap_hdr_t *hdr, unsigned type)
 Set the message type for the given CoAP header. More...
 
static unsigned coap_method2flag (unsigned code)
 Convert message code (request method) into a corresponding bit field. More...
 
static bool coap_has_observe (coap_pkt_t *pkt)
 Identifies a packet containing an observe option. More...
 
static void coap_clear_observe (coap_pkt_t *pkt)
 Clears the observe option value from a packet. More...
 
static uint32_t coap_get_observe (coap_pkt_t *pkt)
 Get the value of the observe option from the given packet. More...
 
ssize_t coap_well_known_core_default_handler (coap_pkt_t *pkt, uint8_t *buf, size_t len)
 Reference to the default .well-known/core handler defined by the application.
 

Variables

const coap_resource_t coap_resources []
 Global CoAP resource list.
 
const unsigned coap_resources_numof
 Number of entries in global CoAP resource list.
 

Nanocoap specific maximum values

#define NANOCOAP_URL_MAX   (64)
 
#define NANOCOAP_QS_MAX   (64)
 

CoAP option numbers

#define COAP_OPT_URI_HOST   (3)
 
#define COAP_OPT_OBSERVE   (6)
 
#define COAP_OPT_URI_PATH   (11)
 
#define COAP_OPT_CONTENT_FORMAT   (12)
 
#define COAP_OPT_URI_QUERY   (15)
 

CoAP packet types

#define COAP_REQ   (0)
 
#define COAP_RESP   (2)
 
#define COAP_RST   (3)
 

Message types -- confirmable, non-confirmable, etc.

#define COAP_TYPE_CON   (0)
 
#define COAP_TYPE_NON   (1)
 
#define COAP_TYPE_ACK   (2)
 
#define COAP_TYPE_RST   (3)
 

CoAP method codes used in header

#define COAP_CLASS_REQ   (0)
 
#define COAP_METHOD_GET   (1)
 
#define COAP_METHOD_POST   (2)
 
#define COAP_METHOD_PUT   (3)
 
#define COAP_METHOD_DELETE   (4)
 

CoAP method flags used in coap_handlers array

#define COAP_GET   (0x1)
 
#define COAP_POST   (0x2)
 
#define COAP_PUT   (0x4)
 
#define COAP_DELETE   (0x8)
 

Empty CoAP message code

#define COAP_CODE_EMPTY   (0)
 

Response message codes: success

#define COAP_CLASS_SUCCESS   (2)
 
#define COAP_CODE_CREATED   ((2 << 5) | 1)
 
#define COAP_CODE_DELETED   ((2 << 5) | 2)
 
#define COAP_CODE_VALID   ((2 << 5) | 3)
 
#define COAP_CODE_CHANGED   ((2 << 5) | 4)
 
#define COAP_CODE_204   ((2 << 5) | 4)
 
#define COAP_CODE_CONTENT   ((2 << 5) | 5)
 
#define COAP_CODE_205   ((2 << 5) | 5)
 
#define COAP_CODE_231   ((2 << 5) | 31)
 

Response message codes: client error

#define COAP_CLASS_CLIENT_FAILURE   (4)
 
#define COAP_CODE_BAD_REQUEST   ((4 << 5) | 0)
 
#define COAP_CODE_UNAUTHORIZED   ((4 << 5) | 1)
 
#define COAP_CODE_BAD_OPTION   ((4 << 5) | 2)
 
#define COAP_CODE_FORBIDDEN   ((4 << 5) | 3)
 
#define COAP_CODE_PATH_NOT_FOUND   ((4 << 5) | 4)
 
#define COAP_CODE_404   ((4 << 5) | 4)
 
#define COAP_CODE_METHOD_NOT_ALLOWED   ((4 << 5) | 5)
 
#define COAP_CODE_NOT_ACCEPTABLE   ((4 << 5) | 6)
 
#define COAP_CODE_PRECONDITION_FAILED   ((4 << 5) | 0xC)
 
#define COAP_CODE_REQUEST_ENTITY_TOO_LARGE   ((4 << 5) | 0xD)
 
#define COAP_CODE_UNSUPPORTED_CONTENT_FORMAT   ((4 << 5) | 0xF)
 

Response message codes: server error

#define COAP_CLASS_SERVER_FAILURE   (5)
 
#define COAP_CODE_INTERNAL_SERVER_ERROR   ((5 << 5) | 0)
 
#define COAP_CODE_NOT_IMPLEMENTED   ((5 << 5) | 1)
 
#define COAP_CODE_BAD_GATEWAY   ((5 << 5) | 2)
 
#define COAP_CODE_SERVICE_UNAVAILABLE   ((5 << 5) | 3)
 
#define COAP_CODE_GATEWAY_TIMEOUT   ((5 << 5) | 4)
 
#define COAP_CODE_PROXYING_NOT_SUPPORTED   ((5 << 5) | 5)
 

Content types

#define COAP_CT_LINK_FORMAT   (40)
 
#define COAP_CT_XML   (41)
 
#define COAP_CT_OCTET_STREAM   (42)
 
#define COAP_CT_EXI   (47)
 
#define COAP_CT_JSON   (50)
 

Content-Format option codes

#define COAP_FORMAT_TEXT   (0)
 
#define COAP_FORMAT_LINK   (40)
 
#define COAP_FORMAT_OCTET   (42)
 
#define COAP_FORMAT_JSON   (50)
 
#define COAP_FORMAT_CBOR   (60)
 
#define COAP_FORMAT_NONE   (65535)
 nanocoap-specific value to indicate no format specified. More...
 

Observe (RFC 7641) constants

#define COAP_OBS_REGISTER   (0)
 
#define COAP_OBS_DEREGISTER   (1)
 

Timing parameters

#define COAP_ACK_TIMEOUT   (2U)
 
#define COAP_RANDOM_FACTOR   (1.5)
 
#define COAP_MAX_RETRANSMIT   (4)
 
#define COAP_NSTART   (1)
 
#define COAP_DEFAULT_LEISURE   (5)
 

Macro Definition Documentation

◆ COAP_FORMAT_NONE

#define COAP_FORMAT_NONE   (65535)

nanocoap-specific value to indicate no format specified.

Definition at line 178 of file nanocoap.h.

Function Documentation

◆ coap_build_hdr()

ssize_t coap_build_hdr ( coap_hdr_t hdr,
unsigned  type,
uint8_t *  token,
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
[out]hdrhdr to fill
[in]typeCoAP packet type (e.g., COAP_TYPE_CON, ...)
[in]tokentoken
[in]token_lenlength of token
[in]codeCoAP code (e.g., COAP_CODE_204, ...)
[in]idCoAP request id
Returns
length of resulting header

◆ coap_build_reply()

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
[in]pktpacket to reply to
[in]codereply code (e.g., COAP_CODE_204)
[out]rbufbuffer to write reply to
[in]rlensize of rbuf
[in]payload_lenlength of payload
Returns
size of reply packet on success
<0 on error

◆ coap_clear_observe()

static void coap_clear_observe ( coap_pkt_t pkt)
inlinestatic

Clears the observe option value from a packet.

Parameters
[in]pktCoAP packet

Definition at line 567 of file nanocoap.h.

◆ coap_code()

static uint8_t coap_code ( unsigned  class,
unsigned  detail 
)
inlinestatic

Encode given code class and code detail to raw code.

Parameters
[in]classmessage code class
[in]detailmessage code detail
Returns
raw message code

Definition at line 504 of file nanocoap.h.

◆ coap_get_code()

static unsigned coap_get_code ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
message code in decimal format

Definition at line 467 of file nanocoap.h.

◆ coap_get_code_class()

static unsigned coap_get_code_class ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
message code class

Definition at line 431 of file nanocoap.h.

◆ coap_get_code_detail()

static unsigned coap_get_code_detail ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
message code detail

Definition at line 443 of file nanocoap.h.

◆ coap_get_code_raw()

static unsigned coap_get_code_raw ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
raw message code

Definition at line 455 of file nanocoap.h.

◆ coap_get_id()

static unsigned coap_get_id ( coap_pkt_t pkt)
inlinestatic

Get the message ID of the given CoAP packet.

Parameters
[in]pktCoAP packet
Returns
message ID

Definition at line 479 of file nanocoap.h.

◆ coap_get_observe()

static uint32_t coap_get_observe ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
value of the observe option

Definition at line 579 of file nanocoap.h.

◆ coap_get_token_len()

static unsigned coap_get_token_len ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
length of token in the given message (0-8 byte)

Definition at line 419 of file nanocoap.h.

◆ coap_get_total_hdr_len()

static unsigned coap_get_total_hdr_len ( coap_pkt_t pkt)
inlinestatic

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

Parameters
[in]pktCoAP packet
Returns
total header length

Definition at line 491 of file nanocoap.h.

◆ coap_get_type()

static unsigned coap_get_type ( coap_pkt_t pkt)
inlinestatic

Get the message type.

Parameters
[in]pktCoAP packet
Returns
COAP_TYPE_CON
COAP_TYPE_NON
COAP_TYPE_ACK
COAP_TYPE_RST

Definition at line 407 of file nanocoap.h.

◆ coap_get_ver()

static unsigned coap_get_ver ( coap_pkt_t pkt)
inlinestatic

Get the CoAP version number.

Parameters
[in]pktCoAP packet
Returns
CoAP version number

Definition at line 392 of file nanocoap.h.

◆ coap_handle_req()

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
[in]pktpointer to (parsed) CoAP packet
[out]resp_bufbuffer for response
[in]resp_buf_lensize of response buffer
Returns
size of reply packet on success
<0 on error

◆ coap_has_observe()

static bool coap_has_observe ( coap_pkt_t pkt)
inlinestatic

Identifies a packet containing an observe option.

Parameters
[in]pktCoAP packet
Returns
true if observe value is set
false if not

Definition at line 557 of file nanocoap.h.

◆ coap_hdr_set_code()

static void coap_hdr_set_code ( coap_hdr_t hdr,
uint8_t  code 
)
inlinestatic

Write the given raw message code to given CoAP header.

Parameters
[out]hdrCoAP header to write to
[in]coderaw message code

Definition at line 515 of file nanocoap.h.

◆ coap_hdr_set_type()

static void coap_hdr_set_type ( coap_hdr_t hdr,
unsigned  type 
)
inlinestatic

Set the message type for the given CoAP header.

Precondition
(type := [0-3])
Parameters
[out]hdrCoAP header to write
[in]typemessage type as integer value [0-3]

Definition at line 528 of file nanocoap.h.

◆ coap_method2flag()

static unsigned coap_method2flag ( unsigned  code)
inlinestatic

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

Parameters
[in]coderequest code denoting the request method
Returns
bit field corresponding to the given request method

Definition at line 544 of file nanocoap.h.

◆ coap_parse()

int coap_parse ( coap_pkt_t pkt,
uint8_t *  buf,
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
[out]pktstructure to parse into
[in]bufpointer to raw packet data
[in]lenlength of packet at buf
Returns
0 on success
<0 on error

◆ coap_put_option()

size_t coap_put_option ( uint8_t *  buf,
uint16_t  lastonum,
uint16_t  onum,
uint8_t *  odata,
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
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 for first option
[in]onumnumber of option
[in]odataptr to raw option data (or NULL)
[in]olenlength of odata (if any)
Returns
amount of bytes written to buf

◆ coap_put_option_ct()

size_t coap_put_option_ct ( uint8_t *  buf,
uint16_t  lastonum,
uint16_t  content_type 
)

Insert content type option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]content_typecontent type to set
Returns
amount of bytes written to buf

◆ coap_put_option_uri()

size_t coap_put_option_uri ( uint8_t *  buf,
uint16_t  lastonum,
const char *  uri,
uint16_t  optnum 
)

Insert URI encoded option into buffer.

Parameters
[out]bufbuffer to write to
[in]lastonumnumber of previous option (for delta calculation), or 0 if first option
[in]uriptr to source URI
[in]optnumoption number to use (e.g., COAP_OPT_URI_PATH)
Returns
amount of bytes written to buf

◆ coap_reply_simple()

ssize_t coap_reply_simple ( coap_pkt_t pkt,
unsigned  code,
uint8_t *  buf,
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
[in]pktpacket to reply to
[in]codereply code (e.g., COAP_CODE_204)
[out]bufbuffer to write reply to
[in]lensize of buf
[in]ctcontent type of payload
[in]payloadptr to payload
[in]payload_lenlength of payload
Returns
size of reply packet on success
<0 on error