Avimesa Group API Node Package (Alpha)
Node.js SDK for the Avimesa Group API using AMQP (0-9-1)
Introduction
This project the source code for the @avimesa/group-api-amqp npm package. The Avimesa Group API is documented here in detail.
Table of Contents
- 1. Quick Start
-
2. API Reference
- Connection Settings
- Group Level
- Device Level
- Queue Level
1. Quick Start
Install the package:
npm install @avimesa/group-api-amqp
Configure your API credentials using the following options:
1.1 Set Credentials using setConnParams
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 **>',
});
1.2 Load Credentials using .env file
update or add your .env file in the project root:
# API Key
API_KEY= <** Enter API Key **>
# API Password
API_PASSWORD= <** Enter API Password **>,
1.3 Use the API
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]);
}
}
});
2. API Reference
setConnParams
Summary
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 **>',
});
listDevices
Summary
Lists the devices for the Group
Callback
groupApi.listDevices(function(err, devices){ ... })
Parameters:
The callback signature contains:
-
err
(boolean) - true if error, false otherwise -
devices
(array) - array of device IDs in string form
Async
let response = await groupApi.listDevicesAsync();
addDevice
Summary
Adds a Device to the Group. If successful, a generated Authentication Key is provided in the response.
Callback
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 otherwise -
authKey
(string) - the 128bit authentication key (32 characters, a-f0-9)
Notes:
- Use the
validDeviceId
utility function
Async
let response = await groupApi.addDeviceAsync(devId);
removeDevice
Summary
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!
Callback
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 otherwise -
msg
(string) - error message if there's an error
Async
let response = await groupApi.removeDeviceAsync(devId);
actuate
Summary
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)
Callback
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 otherwise -
msg
(string) - status for errors if any
Async
let response = await groupApi.actuateAsync(devId, cmd);
listFiles
Summary
List the files for the given Device ID.
Callback
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 otherwise -
files
(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'
}
Async
let response = await groupApi.listFilesAsync(devId);
uploadScript
Summary
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.
Callback
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 otherwise -
msg
(string) - error message. if any
Async
let response = await groupApi.uploadScriptAsync(devId, fileBuf);
uploadConfig
Summary
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
Callback
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 otherwise -
msg
(string) - error message. if any
Async
let response = await groupApi.uploadConfigAsync(devId, fileBuf);
uploadDfuPackage
Summary
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.
Callback
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 otherwise -
msg
(string) - error message. if any
Async
let response = await groupApi.uploadDfuPackageAsync(devId, fileBuf);
updateAuthKey
Summary
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!
Callback
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 otherwise -
authKey
(string) - the 128bit authentication key (32 characters, a-f0-9)
Async
let response = await groupApi.updateAuthKeyAsync(devId);
consume
Summary
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)
Callback
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 otherwise -
msg
(string) - the message from the queue -
ack
(function) - a callback with signaturefunction(boolean)
listen
Summary
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.
Callback
groupApi.listen(exchange, key, function(err, msg){ ... })
count
Summary
Gets the message count of the given queue by name.
Callback
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 otherwise -
count
(number) - the number of messages that are in the queue
Async
let response = await groupApi.countAsync(queue);
purge
Summary
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!.
Callback
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 otherwise -
count
(number) - the number of messages that were purged
Notes:
- If an exclusive connection is already connected this command would fail.
Async
let response = await groupApi.purgeAsync(queue);