AMQP Client

Import AMQP Client

var AmqpClient = require('spacebunny').AmqpClient;

Connection parameters

Prerequisites: you must have created a device through the Space Bunny's web interface. You also have at least one enabled channel, e.g. 'data' (name is not mandatory, but we'll use this for our example). See our Getting Started for a quick introduction to Space Bunny's base concepts. Once everything is set up get your device's Device key from Space Bunny's web application: on the web interface, go to devices section and create or pick an existing device. Click on the 'SHOW CONFIGURATION' link, copy the Device key and substitute it here:

var connectionParams = { deviceKey: 'your-device-key' };

You can also provide the endpointUrl key to use a different endpoint, default points to our Live Application.

You can also provide full manual configuration, all information can be retrieved from the 'SHOW CONFIGURATION' view on Space Bunny web interface. With the following configuration the SDK will not contact the endpoint for configurations.

var connectionParams = {
  deviceId: 'device-id',
  secret: 'device-secret',
  host: 'hostname',
  port: 5672, // default for AMQP
  vhost: 'organization-id',
  channels: [ 'data', 'alarms' ],
  endpoint: {
    host: 'api.spacebunny.io',
    port: 3000
  }
};

You can also customize endpoint passing a complete URL:

var connectionParams = {
  deviceId: 'device-id',
  endpoint: {
    url: 'http://mycustomendpoint.com'
  }
};

Secure connection

If you want to connect using an encrypted channel, you must enable TLS and provide the client and CA certificates path. Default port for AMQPS connections is 5671. Certificates paths are not mandatory, if not provided the platform just creates an encrypted communication channel without peer verification.

var connectionParams = {
  deviceKey: 'your-device-key',
  tls: true,
  ca: '/path/to/ca_certificate.pem',
  cert: '/path/to/client_certificate.pem',
  key: '/path/to/client_key.pem'
};

Instantiate the client

var amqpClient = new AmqpClient(connectionParams);

At this point the SDK is auto-configured and ready to use. Configurations are automatically fetched by the SDK.

Receive messages

When a message is sent on the inbox channel of the current device, the callback function will be called.

// callback called when a message is received
var messageCallback = function(content, field, properties) {
  console.log(content);
};
amqpClient.connect().then(function() {
  amqpClient.onReceive(messageCallback).then(function(res) {
    console.log('Start receiving..');
  }).catch(function(reason) {
    console.error(reason);
  });
}).catch(function(reason) {
  console.error(reason);
});

Receive options

It is possible to specify some options to modify message reception behaviour:

• noAck (default true): the broker won't expect an acknowledgement of messages delivered
• discardFromApi (default false): causes the SDK to filter out messages published through APIs (or WEB UI) or generally sent directly through Space Bunny's platform.
• discardMine (default false): causes the SDK to filter out auto-messages i.e. messages sent from this device and, for some reason, returned to the sender. This can happen in some particular situation such as when using m2m groups.
• allUpTo (default true): all outstanding messages prior to and including the given message shall be considered acknowledged. If false, or omitted, only the message supplied is acknowledged.
• requeue (default false): if is truthy, the server will try to put the message or messages back on the queue or queues from which they came.

var receiveOpts = { ... };
amqpClient.connect().then(function() {
  amqpClient.onReceive(messageCallback, receiveOpts).then(function(res) {
    console.log('Start receiving..');
  }).catch(function(reason) {
    console.error(reason);
  });
}).catch(function(reason) {
  console.error(reason);
});

Send messages

publish function takes two mandatory arguments (channel's name and payload) and a variety of options:

• withConfirm (default false): when set to true this requires Space Bunny's platform to confirm the receipt of the message. This is useful when message delivery assurance is mandatory for your use case.
• topic (default null): when present the message will be published appending topic to the default routing key.
• routingKey (default null): when present the message will be published ovverriding the routing key with this parameter.

var payload = { some: 'json' };
var publishOpts = { ... };
amqpClient.connect().then(function() {
  // Select a channel or you can use amqpClient.channels() to get the complete channels' list
  var channel = 'data';
  amqpClient.publish(channel, payload, publishOpts).then(function(res) {
    console.log('Message sent!');
  }).catch(function(reason) {
   console.error(reason);
  });
}).catch(function(reason) {
 console.error(reason);
});

The platform can manage the sending and receiving of data in any format. The default format is JSON.