# SDDC : Smart Device Discovery & Control protocol

This module is the EdgerOS Smart Device Discovery & Control protocol module. This module is for privileged programs only. EdgerOS applications can indirectly manage and operate the device by related EdgerOS services.

User can use the following code to import the Sddc module.

var Sddc = require('sddc');

# Support

The following shows Sddc module APIs available for each permissions.

# Sddc Class

# new Sddc(ifname)

• ifname {String | Array} Specify the network interface on which the SDDC protocol operates.
• Returns: {Object} SDDC object.

Create SDDC protocol management object, this object can be used to discover peripheral devices, and can also communicate with peripheral devices simply and reliably.

# Example

var sddc = new Sddc('en1');

# Sddc Object

# sddc.setInfo(product, vendor[, excl[, server]])

• product {Object} Product information.
• vendor {String} Product manufacturer.
• excl {Boolean} This device is App exclusive. default: false.
• server {Object} Server summary provided by this machine. default: {}.

The product object must contain the following members:

• name {String} Name of the current machine. Typically: 'Printer', 'Patch panel', 'Air conditioning' ...
• type {String} The type of the machine. Typically: 'monitor', 'edger', 'device'.
• desc {String} Device description information, usually a URL.
• model {String} Device model.

The product object optional members:

• sn {String} Device serial number.

Set the current device information. When other devices request information about this device, this device will provide this information.

When the current device information changes, the device notifies previously discovered devices and lets them re-acquire the new information.

# Example

• Does not provide any services:

sddc.setInfo({ name: 'MyDevice', type: 'device', desc: 'mydevice.xxx.com', model: '1' }, 'xxx');

• Provide server information:

var server = {
  mqtt: [
    {
      type: 'mqtt',
      port: 1883,
      user: 'abc',
      passwd: '123'
    },
    {
      type: 'mqtt-sn',
      port: 1883,
      user: 'abc',
      passwd: '123'
    }
  ],
  coap: [
    {
      desc: '',
      port: 5683
    }
  ],
  vsoa: [
    {
      desc: '',
      port: 5686
    }
  ]
};

sddc.setInfo({ name: 'MyDevice', type: 'device', desc: 'mydevice.xxx.com', model: '1' }, 'xxx', server);

# sddc.setFilter(callback)

• callback {Function} Set communication filter.
  • uid {String} Device unique ID.
  • addr {String} IP address.

The SDDC protocol management object allows you to set a filter callback. Any data packet first goes through the filter callback. If it is allowed, the protocol processing is performed.

# Example

sddc.setFilter(function(uid, addr) {
  if (addr === '192.168.0.1') {
    return true; // Allow!
  } else {
    return false; // Denied!
  }
});

# sddc.security(uid, token)

• uid {String} Device unique ID.
• token {String} Device security communication token.

Add the communication token of the specified device.

# sddc.start()

Start SDDC protocol management object. Before starting, you must set the current device information use sddc.setInfo(). SDDC is a peer-to-peer protocol. Other devices can also discover the current device using SDDC protocol.

# sddc.close()

Stop the SDDC protocol management object. After stop, this object is not allowed to perform any further operations.

# sddc.discover([dest])

• dest {String | Array} Destination IP address. default: broadcast address.

Send a discover packet to discover surrounding or specified devices.

# Example

setInterval(function() {
  sddc.discover(); // Discover devices every minute
}, 60 * 1000);

# sddc.invite(uid[, callback[, retries]])

• uid {String} Device unique ID.
• callback {Function} Invitation result.
  • error {Error} Indicates an error information, success is undefined.
• retries {Integer} Number of retries. default: 4.

Invite a previously discovered device to the network.

# Example

sddc.discover();
sddc.on('found', function(uid, info) {
  sddc.invite(uid, function(error) {
    if (error) {
      console.error('Invite device error:', error.message);
    }
  });
});

# sddc.delete(uid)

• uid {String} Device unique ID.
• Returns: {Boolean} Whether the operation was successful.

Delete a device that has been discovered or joined to this network. After the deletion, if the device exists, it will continue to be discovered, but you must sddc.invite() again to send and receive message to or from this device.

# sddc.send(uid, msg[, req[, callback[, retries[, urgent]]]])

• uid {String} Device unique ID.
• msg {Object} Object to send. (will be converted to JSON)
• req {Boolean} Whether to require destination device confirmation. default: false.
• callback {Function} Call this function after the data packet is sent successfully or confirmed.
  • error {Error} Specify an error message when an error occurs, undefined means the transfer is complete.
• retries {Integer} When req is true, the maximum retries. default: 4.
• urgent {Boolean} Whether it is an urgent packet. default: false.

SDDC allows sending messages to devices that have been discovered and online. This message can be transmitted reliably or unreliably. When req is true indicates that the client needs to confirm that this data has been received. When req is false will not wait for remote response.

In order to ensure the orderliness of the specified remote device messages, SDDC uses a message sequencing method. When there is a message that may not be sent successfully, the current message will be queued, waiting for the previous message to be sent successfully or timed out.

When req is false, the callback function will be called immediately when the packet is sent, When req is true, the system will wait for the reply from the remote device. When the remote device does not reply, the system will automatically resend this message until the remote device responds or timeout. The remote device does not reply, the callback function will still be called and Specify error information through the error parameter.

# Example

• Unreliable messaging:

sddc.send(uid, { hello: 'Hello' });

• Reliable messaging:

sddc.send(uid, { hello: 'Hello' }, true, function(error) {
  if (error != undefined) {
    console.error('Msg send error:', error.message);
  } else {
    console.log('Msg send ok!');
  }
});

# Sddc Event

The Sddc object inherits from the EventEmitter. The following events are thrown in some specific situations.

# found

Found a new device. This event parameter is:

• uid {String} Device unique ID.
• info {Object} Description of the device when querying the device.
  • report {Object} Information reported by discovered devices.
    • name {String} Name of the new device.
    • type {String} The type of the device.
    • excl {Boolean} This device is App exclusive.
    • desc {String} Device description information, usually a URL.
    • model {String} Device model.
    • vendor {String} Device manufacturer.
    • version {Array} Device software version. optional.
    • sn {String} Device serial number. optional.
  • server {Object} Server summary provided by new device.
  • security {Boolean} Device encryption communication support.
• addr {String} Remote address.

# Example

sddc.on('found', function(uid, info) {
  console.log('A new device found:', uid);
});

# update

Receive this event when a previously discovered device has a status update. Such as server address changes, etc.

# Example

sddc.on('update', function(uid, info) {
  console.log('Device update:', uid);
});

# lost

Device was lost, device does not respond for a long time will trigger this event. After device is lost, SDDC management object will not allow to send message to this device.

# join

The device responded to the invitation and joined my SDDC network, could send and receive message normally.

# Example

sddc.invite(uid);
sddc.on('join', function(uid, info) {
  sddc.send(uid, 'hello!');
});

# refuse

The device rejected the invitation, did not join my SDDC network, and could not send or receive message.

# token

Can not communicate with device, need to set token.

# message

The current device received a message from a remote device. This event contains the following parameters:

• uid {String} Device unique ID.
• data {Object} Content of this message.

# Example

sddc.on('message', function(uid, data) {
  console.log('Msg:', data, 'recv from:', uid);
});