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
 

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_ACK_VARIANCE   (1U)
 Maximum variation for confirmable timeout. More...
 
#define COAP_MAX_RETRANSMIT   (4)
 
#define COAP_NSTART   (1)
 
#define COAP_DEFAULT_LEISURE   (5)
 

Macro Definition Documentation

◆ COAP_ACK_VARIANCE

#define COAP_ACK_VARIANCE   (1U)

Maximum variation for confirmable timeout.

Must be an integer, defined as:

(COAP_ACK_TIMEOUT * COAP_RANDOM_FACTOR) - COAP_ACK_TIMEOUT

Definition at line 203 of file nanocoap.h.

◆ 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 576 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 513 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 476 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 440 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 452 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 464 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 488 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 588 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 428 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 500 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 416 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 401 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 566 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 524 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 537 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 553 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