# CoAP Client : CoAP client object

The coap module provides CoapClient. CoapClient can easily initiate coap requests.

This document focuses on the use of CoapClient.

User can use the following code to import the coap module and access CoapClient .

var coap = require('coap');

# Support

The following shows CoapClient module APIs available for each permissions.

# CoapClient Class

CoapClient class inherit from 'CoapPackage. Details to see CoapPackage` module.

# coap.request(url, callback[, opts[, dtlsOpt]])

• url {String} Coap url.
• callback {Function} Reuqest handler. The same as client.begin event callback. Arguments:
  • client {CoapClient} The client object.
• opts {Object} Has the following properties:
  • method {String} Coap method, default: POST.
  • path {String} The request uri path, default: url parsed path.
  • timeout {Integer} The request timeout. If the request times out, CoapClient will close.
  • confirm {Boolean} The request send is confirm or no.
  • options {Object} Coap options.
  • token {Buffer} Coap token used to identification resources.
  • observe {Boolean} Observe mode request. default: false.
  • payload {String | Buffer} The request payload data, default: undefined.
• dtlsOpt {Object} DTLS securely connections options. default: undefined, means use UDP connection.
• Returns: {CoapClient} The coap client request object.

This CoapClient object (request object) is created internally and returned from coap.request().

The coay payload data can be set in the opts.payload. If the opts.method is set to non-GET or the opts.payload defines valid data, then request() automatically end the request. Otherwise, the user can continue to set payload data via the client.write() method, in which case the user will eventually need to call client.end() to end the request.The connection will been close automatically after getting the response.

# Example

• GET request:

var client = coap.request('coap://192.168.7.31:5683', function (client) {
  client.on('response', function (client, res) {
    console.log('Recv message:', res.payload.toString());
  });
}, {method: 'GET'});

• POST request:

var client = coap.request('coap://192.168.7.31:5683', function (client) {
  client.on('response', function (client, res) {
    console.log('Recv message:', res.payload.toString());
  });
});

client.end('Hello world!');

# coap.get(url, callback[, opts[, dtlsOpt]])

• url {String} Coap url.
• callback {Function} Reuqest handler. The same as client.begin event callback. Arguments:
  • client {CoapClient} The client object.
• opts {Object} Has the following properties:
  • path {String} The request uri path, default: url parsed path.
  • timeout {Integer} The request timeout. If the request times out, CoapClient will close.
  • confirm {Boolean} The request send is confirm or no.
  • options {Object} Coap options.
  • token {Buffer} Coap token used to identification resources.
  • observe {Boolean} Observe mode request. default: false.
  • payload {String | Buffer} The request payload data, default: undefined.
• dtlsOpt {Object} DTLS securely connections options. default: undefined, means use UDP connection.
• Returns: {CoapClient} The coap client request object.

This CoapClient object (request object) is created internally and returned from coap.get().

Accepts the same options as coap.request(), with the method always set to GET.

Since most requests are GET requests, http provides this convenience method. The only difference between this method and http.request() is that it sets the method to GET and calls request.end() automatically.

# Example

• GET request:

var client = coap.get('coap://192.168.7.31:5683', function (client) {
  client.on('response', function (client, res) {
    console.log('Recv message:', res.payload.toString());
  });
});

# coap.mode()

• Returns: {String} Coap work mode.

Get the current process CoAP work mode.

• on CoAP is enabled.
• off CoAP is not enabled.

# CoapClient Object

CoapClient inherit from CoapPackage, see the CoapPackage module for details.

# client.close()

Close coap client..

# client.write(chunk)

• chunk {String | Object | Buffer} Coap payload.

This method set or append payload data. This method can call multiple times. After write all data, user should call client.end() to end request.

# client.end([chunk[, opts]])

• chunk {String | Object | Buffer} Coap payload data.
• opts {Object} send options, details:
  • confirm {Boolean} The request send is confirm or no.
  • token {Buffer} Coap token used to identification resources.
  • options {Object} The request coap options. See CoapPackage.options.

Send data to server.

# client.reset()

In observe mode, the server will continue to reply to the data monitored by the client until the client callsreset to end the process.

# CoapClient Events

# begin

A begin event is emitted when the coap response is begining. Properties:

# response

A response event is emitted when the coap response is coming. Properties:

• client {CoapCLient} Client object.
• res {HttpClientResponse} Coap response object.

In normal mode, the client just receive response event once. In observe mode, the client will receive response event multiple times until reset by client or server.

# end

A end event is emitted when the response finish.

# error

A error event is emitted when the client occur error.It has a err properties:

• err {Error} err instanceof Error object.

# CoapClientResponse Object

When coap.get(), coap.request() is called, the CoapClientResponse object is passed as a parameter to the response callback function. The response data can be accessed via the CoapClientResponse object.

CoapClientResponsethe same as CoapPackage, see the CoapPackage module for more details.

# Example

# Get

var iosched = require('iosched');
var coap = require('coap');

var client = coap.get('coap://192.168.7.31:5683', function (client) {
  client.on('response', function (client, res) {
    console.log('Recv message:', res.payload.toString());
  });

}).on('error', (e) => {
  console.log('Request error:', e);
});

while (true) {
  iosched.poll();
}

# Reqeust

var iosched = require('iosched');
var coap = require('coap');

var client = coap.request('coap://192.168.7.31:5683', function (client) {
  client.on('response', function (client, res) {
    console.log('Recv message:', res.payload.toString());
  });

}).on('error', (e) => {
  console.log('Request error:', e);
});

client.end('Hello world!');

while (true) {
  iosched.poll();
}

# Observe mode

var coap = require('coap');
var iosched = require('iosched');

var client = coap.request('coap://192.168.7.31:5683', function (client) {
  var count = 0;

  client.on('response', function (client, res) {
    console.log('Coap recv:', res.payload.toString());
    count++;
    if (count >= 5) {
      client.reset();
    }
  });

  client.on('end', function (client) {
    console.log('Coap observe end.');
  });

}, { observe: true, token: Buffer.from('ABC123')});

client.on('error', (e) => {
  console.log('Coap request error:', e);
});

client.end('Request temperature.');

while (true) {
  iosched.poll();
}