coap

node-coap

node-coap is an highly experimental client and server library for CoAP modelled after the http module.

• Introduction
• Installation
• Basic Example
• API
• Contributing
• Licence & 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 the draft-18 of the standard.

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

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

This has been tested only on node v0.10.

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')
    , server      = coap.createServer()

server.on('request', function(req, res) {
  res.end('Hello ' + req.url.split('/')[1] + '\n')
})

// the default CoAP port is 5683
server.listen(function() {
  var req = coap.request('coap://localhost/Matteo')

  req.on('response', function(res) {
    res.pipe(process.stdout)
    res.on('end', function() {
      process.exit(0)
    })
  })

  req.end()
})

API

• coap.request()
• coap.createServer()
• IncomingMessage
• OutgoingMessage
• coap.registerOption()
• coap.registerFormat()

request(url)

Execute a CoAP request. url can be a string or an object. If it is a string, it is parsed using require('url').parse(url). If it is an object:

• host: A domain name or IP address of the server to issue the request to. Defaults to 'localhost'.
• hostname: To support url.parse() hostname is preferred over host
• port: Port of remote server. Defaults to 5483.
• method: A string specifying the CoAP request method. Defaults to 'GET'.
• 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'

coap.request() returns an instance of IncomingMessage. If you need to add a payload, just pipe into it. Otherwise, you must call end to submit the request.

Event: 'response'

function (response) { }

Emitted when a response is received. response is an instance of IncomingMessage.

createServer([requestListener])

Returns a new CoAP Server object.

The requestListener is a function which is automatically added to the 'request' event.

Event: 'request'

function (request, response) { }

Emitted each time there is a request. request is an instance of IncomingMessage and response is an instance of OutgoingMessage.

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

Begin accepting connections on the specified port and hostname. If the hostname is omitted, the server will accept connections directed to any IPv4 address (INADDR_ANY).

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

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 object is returned by coap.request or emitted by the coap.createServer 'response' event. It may be used to access response status, headers and data.

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

message.statusCode

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

message.setOption(name, value)

Sets a single option value. All the options are in binary format, except for 'Content-Format', 'Accept' and 'ETag'. See to know how to register more.

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

Example:

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

or

message.setOption("555", [new Buffer('abcde',

new Buffer('ghi')]);

setOption is also aliased as setHeader for HTTP API compatibility.

Also, 'Content-Type' is aliased to 'Content-Format' for HTTP compatibility.

See the spec for all the possible options.

IncomingMessage

An IncomingMessage object is created by coap.createServer or coap.request and passed as the first argument to the 'request' and 'response' event respectively. It may be used to access response status, headers and data.

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' and 'ETag'. See registerOption() to know how to register more.

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' and 'ETag'. See to know how to register more.

Also, 'Content-Type' is aliased to 'Content-Format' for HTTP compatibility.

message.code

The CoAP code of the message.

message.method

The method of the message, it might be 'GET', 'POST', 'PUT', 'DELETE' or null. It is null if the CoAP code cannot be parsed into a method, i.e. it is not in the '0.' range.

message.url

The URL of the request, e.g. 'coap://localhost:12345/hello/world?a=b&b=c'.

coap.registerOption(name, toBinary, toString)

Register a new option to be converted to string and added to the message.headers. toBinary is a function that accept a string and returns a Buffer. toString is a function that accept a Buffer and returns a String.

coap.registerFormat(name, value)

Register a new format to be interpreted and sent in CoAP Content-Format option. Each format is identified by a number, see the Content-Format registry.

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.

These are the defaults formats:

registerFormat('text/plain', 0)
registerFormat('application/link-format', 40)
registerFormat('application/xml', 41)
registerFormat('application/octet-stream', 42)
registerFormat('application/exi', 47)
registerFormat('application/json', 50)

Limitations

At the moment only non-confirmable messages are supported (NON in the CoAP spec). This means less reliability, as there is no way for a client to know if the server has received the message.

Moreover, the maximum packet size is 1280, as the blockwise is not supported yet.

The observe support is planned too.

Contributors

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

Matteo Collina	GitHub/mcollina	Twitter/@matteocollina

LICENSE

Copyright (c) 2013 node-coap contributors (listed above).

Coap-Packet is licensed under an MIT +no-false-attribs license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.