node-coap

node-coap is a client and server library for CoAP modeled after the

http

• Introduction
• Installation
• Basic Example
• Proxy features
• API
• Contributing
• License & copyright

Introduction

What is CoAP?

Constrained Application Protocol (CoAP) is a software protocol intended to be used in very simple electronics devices that allows them to communicate interactively over the Internet. - Wikipedia

This library follows: * RFC 7252 for CoAP, * RFC 7641 for the observe specification, * RFC 7959 for the blockwise specification, * RFC 8132 for the PATCH, FETCH, and iPATCH methods.

It does not parse the protocol but it use CoAP-packet instead.

If you need a command line interface for CoAP, check out coap-cli.

node-coap is an OPEN Open Source Project, see the Contributing section to find out what this means.

Installation

$ npm install coap --save

Basic Example

The following example opens a UDP server and sends a CoAP message to it:

const coap = require('coap')
const server = coap.createServer()

server.on('request', (req, res) => {
  res.end('Hello ' + req.url.split('/')[1] + '\n')
})
// the default CoAP port is 5683
server.listen(() => {
  const req = coap.request('coap://localhost/Matteo')
  req.on('response', (res) => {
    res.pipe(process.stdout)
    res.on('end', () => {
      process.exit(0)
    })
  })
  req.end()
})

or on IPv6:

const coap = require('coap')
const server = coap.createServer({ type: 'udp6' })

server.on('request', (req, res) => {
  res.end('Hello ' + req.url.split('/')[1] + '\n')
})
// the default CoAP port is 5683
server.listen(() => {
  const req = coap.request('coap://[::1]/Matteo')
  req.on('response', (res) => {
    res.pipe(process.stdout)
    res.on('end', () => {
      process.exit(0)
    })
  })
  req.end()
})

Proxy features

The library now comes with the ability to behave as a COAP proxy for other COAP endpoints. In order to activate the proxy features, create the server with the

proxy

A proxy-enabled service behaves as usual for all requests, except for those coming with the

Proxy-Uri

You can find an example of how this mechanism works in

examples/proxy.js

• Ten requests are sent directly to the server (without reusing ports)
• Ten requests are sent through the proxy (without reusing ports)

The example shows that the target server sees the last ten requests as coming from the same port (the proxy), while the first ten come from different ports.

API

• coap.request()
• coap.createServer()
• IncomingMessage
• OutgoingMessage
• ObserveReadStream
• ObserveWriteStream
• coap.registerOption()
• coap.ignoreOption()
• coap.registerFormat()
• coap.Agent
• coap.globalAgent
• coap.globalAgentIPv6
• coap.updateTiming
• coap.defaultTiming

request(requestParams)

Execute a CoAP request.

requestParams

new URL(requestParams)

• host

  : A domain name or IP address of the server to issue the request to. Defaults to

  'localhost'

  .

• hostname

  : To support

  URL

  hostname

  is preferred over

  host

• port

  : Port of remote server. Defaults to 5683.

• method

  : A string specifying the CoAP request method. Defaults to

  'GET'

  .

• confirmable

  : send a CoAP confirmable message (CON), defaults to

  true

  .

• observe

  : send a CoAP observe message, allowing the streaming of updates from the server.

• pathname

  : Request path. Defaults to

  '/'

  . Should not include query string

• query

  : Query string. Defaults to

  ''

  . Should not include the path, e.g. 'a=b&c=d'

• options

  : object that includes the CoAP options, for each key-value pair the setOption() will be called.

• headers

  : alias for

  options

  , but it works only if

  options

  is missing.

• agent

  : Controls

  Agent

  behavior. Possible values:

  • undefined

    (default): use

    globalAgent

    , a single socket for all concurrent requests.

  • Agent

    object: explicitly use the passed in

    Agent

    .

  • false

    : opts out of socket reuse with an

    Agent

    , each request uses a new UDP socket.

• proxyUri

  : adds the Proxy-Uri option to the request, so if the request is sent to a proxy (or a server with proxy features) the request will be forwarded to the selected URI. The expected value is the URI of the target. E.g.: 'coap://192.168.5.13:6793'

• multicast

  : If set to

  true

  , it forces request to be multicast. Several

  response

  events will be emitted for each received response. It's user's responsibility to set proper multicast

  host

  parameter in request configuration. Default

  false

  .

• multicastTimeout

  : time to wait for multicast reponses in milliseconds. It is only applicable in case if

  multicast

  is

  true

  . Default

  20000 ms

  .

• retrySend

  : overwrite the default maxRetransmit, useful when you want to use a custom retry count for a request

coap.request()

pipe

end

If

hostname

'udp6'

Event: 'response'

function (response) { }

Emitted when a response is received.

response

If the

observe

'response'

createServer([options], [requestListener])

Returns a new CoAP Server object.

The

requestListener

'request'

The constructor can be given an optional options object, containing one of the following options: *

type

udp4

udp6

udp4

proxy

Proxy-Uri

/examples

false

multicastAddress

multicastInterface

multicastAddress

multicastAddress

piggybackReplyMs

sendAcksForNonConfirmablePackets

clientIdentifier

clientIdentifier(request)

IncomingMessage

reuseAddr

true

Event: 'request'

function (request, response) { }

Emitted each time there is a request.

request

response

If the

observe

response

write(data)

server.listen(port, [address], [callback])

Begin accepting connections on the specified port and hostname. If the hostname is omitted, the server will accept connections directed to any IPv4 or IPv6 address by passing

null

To listen to a unix socket, supply a filename instead of port and hostname.

A custom socket object can be passed as a

port

EventEmitter

message

error

close

send(msg, offset, length, port, address, callback)

dgram.Socket

This function is asynchronous.

server.close([callback])

Closes the server.

This function is synchronous, but it provides an asynchronous callback for convenience.

OutgoingMessage

An

OutgoingMessage

coap.request

coap.createServer

'response'

It implements the Writable Stream interface, as well as the following additional properties, methods and events.

message.code

The CoAP code of the message. It is HTTP-compatible, as it can be passed

404

message.statusCode

(same as message.code)

message.setOption(name, value)

Sets a single option value. All the options are in binary format, except for

'Content-Format'

'Accept'

'Max-Age'

'ETag'

Use an array of buffers if you need to send multiple options with the same name.

If you need to pass a custom option, pass a string containing a a number as key and a

Buffer

Example:

message.setOption('Content-Format', 'application/json')

or

message.setOption('555', [Buffer.from('abcde'), Buffer.from('ghi')])

setOption

setHeader

Also,

'Content-Type'

'Content-Format'

Since v0.7.0, this library supports blockwise transfers, you can trigger them by adding a

req.setOption('Block2', Buffer.of(0x2))

And since v0.25.0, this library supports rudimentry type 1 blockwise transfers, you can trigger them by adding a

req.setOption('Block1', Buffer.of(0x2))

(The hex value 0x2 specifies the size of the blocks to transfer with. Use values 0 to 6 for 16 to 1024 byte block sizes respectively.)

See the spec for all the possible options.

message.reset()

Returns a Reset COAP Message to the sender. The RST message will appear as an empty message with code

0.00

true

message.writeHead(code, headers)

Functions somewhat like

http

writeHead()

code

#.##

headers

message.on('timeout', function(err) { })

Emitted when the request does not receive a response or acknowledgement within a transaction lifetime.

Error

No reply in XXXs

retransmitTimeout

message.on('error', function(err) { })

Emitted when an error occurs. This can be due to socket error, confirmable message timeout or any other generic error.

Error

IncomingMessage

An

IncomingMessage

coap.createServer

coap.request

'request'

'response'

It implements the Readable Stream interface, as well as the following additional methods and properties.

message.payload

The full payload of the message, as a Buffer.

message.options

All the CoAP options, as parsed by CoAP-packet.

All the options are in binary format, except for

'Content-Format'

'Accept'

'ETag'

See the spec for all the possible options.

message.headers

All the CoAP options that can be represented in a human-readable format. Currently they are only

'Content-Format'

'Accept'

'ETag'

'Content-Type'

'Content-Format'

'GET'

'POST'

'PUT'

'DELETE'

null

'coap://localhost:12345/hello/world?a=b&b=c'

The sender informations, as emitted by the socket. See the

dgram

message.outSocket

Information about the socket used for the communication (address and port).

ObserveReadStream

An

ObserveReadStream

coap.request

'response'

'data'

It implements the Readable Stream and IncomingMessage interfaces, as well as the following additional methods, events and properties.

close()

Closes the stream.

message.rsinfo

The sender's information, as emitted by the socket. See the

dgram

message.outSocket

Information about the socket used for the communication (address and port).

ObserveWriteStream

An

ObserveWriteStream

coap.createServer

'response'

Each new

write()

It implements the Writable Stream interface, as well as the following additional methods and properties.

Event: 'finish'

Emitted when the client is not sending 'acks' anymore for the sent messages.

reset()

Returns a Reset COAP Message to the sender. The RST message will appear as an empty message with code

0.00

true

coap.registerOption(name, toBinary, toString)

Register a new option to be converted to string and added to the

message.headers

toBinary

Buffer

toString

Buffer

String

coap.ignoreOption(name)

Explicitly ignore an option; useful for compatibility with

http

coap.registerFormat(name, value)

Register a new format to be interpreted and sent in CoAP

Content-Format

These are the defaults formats: | Media Type | ID | | :-------------------------------------------------------: | :---: | |

text/plain

application/cose; cose-type="cose-encrypt0"

application/cose; cose-type="cose-mac0"

application/cose; cose-type="cose-sign1"

application/link-format

application/xml

application/octet-stream

application/exi

application/json

application/json-patch+json

application/merge-patch+json

application/cbor

application/cwt

application/multipart-core

application/cbor-seq

application/cose-key

application/cose-key-set

application/senml+json

application/sensml+json

application/senml+cbor

application/sensml+cbor

application/senml-exi

application/sensml-exi

application/coap-group+json

application/dots+cbor

application/missing-blocks+cbor-seq

application/pkcs7-mime; smime-type=server-generated-key

application/pkcs7-mime; smime-type=certs-only

application/pkcs8

application/csrattrs

application/pkcs10

application/pkix-cert

application/senml+xml

application/sensml+xml

application/senml-etch+json

application/senml-etch+cbor

application/td+json

application/vnd.ocf+cbor

application/oscore

application/javascript

application/vnd.oma.lwm2m+tlv

application/vnd.oma.lwm2m+json

application/vnd.oma.lwm2m+cbor

text/css

image/svg+xml

coap.Agent([opts])

An Agent encapsulate an UDP Socket. It uses a combination of

messageId

token

By default, no UDP socket are open, and it is opened on demand to send the messages.

Opts is an optional object with the following optional properties:

• type

  :

  'udp4'

  or

  'udp6'

  if we want an Agent on an IPv4 or IPv6 UDP socket.

• socket

  : use existing socket instead of creating a new one.

coap.globalAgent

The default

Agent

coap.globalAgentIPv6

The default

Agent

coap.updateTiming

You can update the CoAP timing settings, take a look at the examples:

const coapTiming = {
  ackTimeout: 0.25,
  ackRandomFactor: 1.0,
  maxRetransmit: 3,
  maxLatency: 2,
  piggybackReplyMs: 10
}
coap.updateTiming(coapTiming)

coap.defaultTiming

Reset the CoAP timings to the default values

Contributing

node-coap is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the CONTRIBUTING.md file for more details.

Contributors

node-coap is only possible due to the excellent work of the following contributors:

LICENSE

MIT, see LICENSE.md file.