Node.js SDK for the Avimesa Group API using AMQP (0-9-1)
This project the source code for the @avimesa/group-api-amqp npm package. The Avimesa Group API is documented here in detail.
- 1. Quick Start
- 2. API Reference
- Connection Settings
- Group Level
- Device Level
- Queue Level
Install the package:
npm install @avimesa/group-api-amqp
Configure your API credentials using the following options:
Use the setConnParams
function before accessing the API:
const groupApi = require('@avimesa/group-api-amqp');
groupApi.setConnParams({
apiKey: '<** Enter API Key **>',
apiPassword: '<** Enter API Password **>',
});
update or add your .env file in the project root:
# API Key
API_KEY= <** Enter API Key **>
# API Password
API_PASSWORD= <** Enter API Password **>,
Load the package:
...
const groupApi = require('@avimesa/group-api-amqp');
...
Use API per documentation, for example, listing Devices for the Group:
groupApi.listDevices(function(err, devices){
if(!err){
for (var i = 0; i < devices.length; i++){
console.log(devices[i]);
}
}
});
Set the connection parameters for the AMQP connection
const groupApi = require('@avimesa/group-api-amqp');
groupApi.setConnParams({
apiKey: '<** Enter API Key **>',
apiPassword: '<** Enter API Password **>',
});
Note, you can override connection paramaters as well:
groupApi.setConnParams({
apiKey: '<** Enter API Key **>',
apiPassword: '<** Enter API Password **>',
hostname: 'rmqserv001.avimesa.com',
port: 5671
vhost: '<** By default, same as the API Key **>',
});
Lists the devices for the Group
groupApi.listDevices(function(err, devices){ ... })
Parameters:
The callback signature contains:
err
(boolean) - true if error, false otherwisedevices
(array) - array of device IDs in string form
let response = await groupApi.listDevicesAsync();
Adds a Device to the Group. If successful, a generated Authentication Key is provided in the response.
groupApi.addDevice(devId, function(err, authKey){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.
The callback signature contains:
err
(boolean) - true if error, false otherwiseauthKey
(string) - the 128bit authentication key (32 characters, a-f0-9)
Notes:
- Use the
validDeviceId
utility function
let response = await groupApi.addDeviceAsync(devId);
Removes a Device from the Group. Any files or data cached for this device in the Avimesa Device Cloud will be removed and trashed.
WARNING: This may result in disabling a device in the field. Proceed with caution only if you know what you're doing!
groupApi.removeDevice(devId, function(err, msg){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - error message if there's an error
let response = await groupApi.removeDeviceAsync(devId);
Sends an actuation command to the devices actuation queue.
WARNING: You that you are responsible for checking the response in the data stream as the communication with the device is asynchronous (e.g. the device might be sleeping)
groupApi.actuate(devId, cmd, function(err, msg){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.cmd
(string) - Command. See here for details on the command
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - status for errors if any
let response = await groupApi.actuateAsync(devId, cmd);
List the files for the given Device ID.
groupApi.listFiles(devId, function(err, files){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.
The callback signature contains:
err
(boolean) - true if error, false otherwisefiles
(array) - array of files where each file has apath
(file path),size
(bytes) andtime
(Linux upload time) in the given format:
{
path: '/data/fw-app.dat',
size: '137895',
time: '1540929865'
}
let response = await groupApi.listFilesAsync(devId);
Upload a Device Driver Script for the given Device ID. The script is checked for potential errors upon upload, but not all runtime errors can be accounted for. If a runtime error occurs, it will show up in the syslog
queue.
groupApi.uploadScript(devId, fileBuf, function(err, msg){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.fileBuf
(Buffer) - Buffer holding the script file
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - error message. if any
let response = await groupApi.uploadScriptAsync(devId, fileBuf);
Upload a Device Configuration for the given Device ID. It will be checked for potential issues upon upload.
WARNING: the max configuration file size is 2048 bytes
groupApi.uploadConfig(devId, fileBuf, function(err, message){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.fileBuf
(Buffer) - Buffer holding the config file (JSON, DialTone Protocol)
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - error message. if any
let response = await groupApi.uploadConfigAsync(devId, fileBuf);
Upload a Device Firmware Update (DFU) Package for the given Device ID
Notes:
- This API uploads the package. You need to
actuate
the device to begin the update process. See here for details.
groupApi.uploadDfuPackage(devId, fileBuf, function(err, message){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.fileBuf
(Buffer) - Buffer type holding the Avimesa DFU Package
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - error message. if any
let response = await groupApi.uploadDfuPackageAsync(devId, fileBuf);
Update a Device's Authentication key for the given Device ID
WARNING: This may result in disabling a device in the field. Proceed with caution only if you know what you're doing!
groupApi.updateAuthKey(devId, function(err, authKey){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.
The callback signature contains:
err
(boolean) - true if error, false otherwiseauthKey
(string) - the 128bit authentication key (32 characters, a-f0-9)
let response = await groupApi.updateAuthKeyAsync(devId);
Begins consuming data from the given queue and will obtain all pending messages that are in the queue upon connection.
A callback is used on each message read that provides the ability to prevent an ACK (for a use case of, say, the database isn't available for storage)
WARNING: This results in an exclusive connection to the queue and other clients are blocked from using this queue (as intended)
groupApi.consume(queue, function(err, msg, ack){ ... })
Parameters:
devId
(string) - Device name. Lower case, 32 characters, a-f0-9.
The callback signature contains:
err
(boolean) - true if error, false otherwisemsg
(string) - the message from the queueack
(function) - a callback with signaturefunction(boolean)
Begins listening for data from the given exchange and routing key. A temporary queue is created and used, so there will be no prior messages as this is a new queue.
A callback is used on each message read, and the messages are automatically acknowledged.
groupApi.listen(exchange, key, function(err, msg){ ... })
Gets the message count of the given queue by name.
groupApi.count(queue, function(err, count){ ... })
Parameters:
queue
(string) - name of the queue. In the Avimesa system queues have a suffix'_q'
The callback signature contains:
err
(boolean) - true if error, false otherwisecount
(number) - the number of messages that are in the queue
let response = await groupApi.countAsync(queue);
Purges the given queue by name and gives the number of messages removed.
NOTE THIS MAY RESULT IN DATA LOSS. MAKE SURE YOU KNOW WHAT YOU ARE PURGING!.
groupApi.purge(queue, function(err, count){ ... })
Parameters:
queue
(string) - name of the queue. In the Avimesa system queues have a suffix'_q'
The callback signature contains:
err
(boolean) - true if error, false otherwisecount
(number) - the number of messages that were purged
Notes:
- If an exclusive connection is already connected this command would fail.
let response = await groupApi.purgeAsync(queue);