@avimesa/group-api-amqp

    0.0.16 • Public • Published

    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

    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]);
    		}
    	}
    });
    

    Top

    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();
    

    Top

    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);
    

    Top

    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);
    

    Top

    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);
    

    Top

    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 a path (file path), size (bytes) and time (Linux upload time) in the given format:
    { 
        path: '/data/fw-app.dat', 
        size: '137895', 
        time: '1540929865' 
    }
    
    Async
    let response = await groupApi.listFilesAsync(devId);
    

    Top

    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);
    

    Top

    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);
    

    Top

    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);
    

    Top

    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);
    

    Top

    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 signature function(boolean)

    Top

    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){ ... })
    

    Top

    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);
    

    Top

    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);
    

    Top

    Keywords

    none

    Install

    npm i @avimesa/group-api-amqp

    DownloadsWeekly Downloads

    0

    Version

    0.0.16

    License

    SEE LICENSE IN LICENSE

    Unpacked Size

    185 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar