# LoRaDev : LoRaWAN device operation

This module is the EdgerOS LoRaWAN communication module. Applications can use this module to operate any LoRa nodes connected to this EdgerOS machine.

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

var LoRa = require('lora');

EdgerOS has a LoRaWAN gateway service (some machines may not have this function), and the LoRa module communicates with LoRa node through the EdgerOS LoRaWAN gateway service.

Due to the large number of possible LoRa nodes, LoRa uses a subscription and publishing mechanism to operate. Before operation the application must ensure that it has the LoRa network operation permission:

# Example

var permission = require('permission');

var perm = {
  lora: true
};

permission.check(perm, function(res) {
  if (res) {
    console.log('Current App has LoRa network operation permission.');
  }
});

# Support

The following shows LoRa module APIs available for each permissions.

# LoRa Class

# new LoRa()

• Returns: {Object} LoRa network object.

Create a LoRa network object. Unlike Device objects, a LoRa object can operate all LoRa nodes connected to the network.

# Example

var lora = new LoRa();

# LoRa.support()

• Returns: {Boolean} Whether the current system support LoRaWAN.

Get whether the current system support LoRaWAN, If not supported, this module cannot be used. This API is available on EdgerOS 1.9.9 and later.

# LoRa.count(callback)

• callback {Function} Callback function.
  • error {Error} If an error occurs, indicate the cause of the error.
  • count {Integer} Total number of lora devices.

Get the total number of LoRa devices managed in the system.

# Example

LoRa.count(function(error, count) {
  if (error) {
    console.error(error.message);
  } else {
    console.log('Total number:', count);
  }
});

# LoRa.list(callback)

• callback {Function} Callback function.
  • error {Error} If an error occurs, indicate the cause of the error.
  • list {Array} LoRa devices id and alias array.
    • alias {String} LoRa device alias.
    • devEUI {String} LoRa device EUI.

Get the all LoRa devices managed in the system id array.

# Example

LoRa.list(function(error, list) {
  if (error) {
    console.error(error.message);
  } else {
    list.forEach(function(item) {
      console.log('IDs:', item.alias, item.devEUI);
    });
  }
});

# LoRa Object

# lora.close()

Close the current LoRa object. After this object is closed, you will no longer be able to send and receive data. Recommend: After using the LoRa network, close this object, which can reduce system resources.

# lora.publish(devEUI, data[, req[, callback]])

• devEUI {String} The target node to be sent.
• data {Buffer} Data to be sent.
• req {Boolean} Whether need LoRa node return acknowledge message. default: false.
• callback {Function} Whether the message is delivered to the LoRaWAN gateway service. default: undefined.
  • error {Error} Indicate an error information when an error occurs.

Send a data to the specified LoRa node, the LoRaWAN gateway service will do its best to send it (LoRaWAN gateway service will choose the time window), but because LoRa is a long sleep mode communication, there is no guarantee that the specified LoRa node receives this message.

# Example

var buf = new Buffer(4);

buf[0] = 0x11;
buf[1] = 0x22;
buf[2] = 0x33;
buf[3] = 0x44;

// Send data
lora.publish(devEUI, buf);
// Or:
lora.publish(devEUI, buf, false, function(error) {
  if (error) {
    console.error('LoRaWAN gateway error:', error.message);
  }
});

# Example

var cnt = 0;
var tmr = new Timer();
var buf = new Buffer(4);

buf[0] = 0x11;
buf[1] = 0x22;
buf[2] = 0x33;
buf[3] = 0x44;

// LoRa is a long-sleep narrowband communication, cycle period cannot be too short
// Recommended for more than 3 minutes
const PERIOD = 5 * 60 * 1000;

tmr.start(PERIOD, PERIOD, function() {
  cnt++;
  if (cnt <= 3) {
    lora.publish(devEUI, buf);
  } else {
    tmr.stop();
  }
});

# lora.subscribe([devEUI])

• devEUI {String} Node messages that need to be subscribed. default: undefined.

Add node messages that need to be subscribed. LoRa objects can subscribe to messages from many nodes. If you need to subscribe to all network node messages, set devEUI to undefined.

# Example

lora.subscribe(); // Subscribe to all LoRa node message.
lora.subscribe(devEUI); // Subscribe specified LoRa node message.

# lora.unsubscribe([devEUI])

• devEUI {String} Node messages that need to be unsubscribed. default: undefined.

Unsubscribe the previously subscribed LoRa node message, if you want to unsubscribe all LoRa node message, set devEUI to undefined.

# LoRa Events

LoRa objects inherit from EventEmitter, The following events are thrown in some specific situations.

# message

• devEUI {String} Node messages from which LoRa node.
• data {Buffer} Node messages data.

Received a subscribed LoRa node message.

# Example

lora.on('message', function(devEUI, data) {
  console.log('LoRa receive from:', devEUI, 'data:', data.toString('hex'));
});

# failed

• devEUI {String} Node failed from which LoRa node.
• error {Error} Node failed error.

This event will be received when there is a message sending error. When a publish() has a request acknowledge option and does not receive a acknowledge from the LoRa node, a sending failure event will occur.

# Example

lora.on('failed', function(devEUI, error) {
  console.warn('LoRa send failed:', devEUI., error.message);
});