astarte-device-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.6 • Public • Published

    Astarte NodeJS Device SDK

    NodeJS Device SDK for Astarte IOT Platform. Create Astarte Devices and Simulators with NodeJS 14+. It integrates with MQTT.js & async-mqtt to ensure a smooth developer experience and to hide complex details regarding MQTT interactions.

    Installation

    Install with NPM

    npm i astarte-device-sdk
    

    Usage

    Register Device

    import { Pairing } from 'astarte-device-sdk'
    
    /* Global Constants */
    
    const astartePairingUrl = ""
    const astartePairingToken = ""
    const astarteRealm = ""
    
    /* Initialize Pairing SDK */
    const pairing = new Pairing({
    	pairingUrl: astartePairingUrl,
    	pairingToken: astartePairingToken,
    	realm: astarteRealm
    })
    
    /* Register Device */
    pairing.register({ hardwareId: "<uuid5 encoded device_id>" }).then((credentialSecret) => {
       /* Store this credentialSecret somewhere as this will be used later for 
       interacting with the device */
    })
    
    

    Once the device is registered and you saved the credentialSecret, the job of Pairing helper is all done, from here onwards you will be using Device SDK for all device related operations.

    Un-Register Device

    pairing.unregister(hardwareId)
    

    Initialize Device

    import Device from 'astarte-device-sdk`
    
    const device = new Device({
    	pairingUrl: astartePairingUrl,
    	pairingToken: astartePairingToken,
    	realm: astarteRealm,
    	hardwareId: "<uuid5 encoded device_id>", /* Used during registration */
    	credentialSecret: deviceCredentialSecret, /* Got & Saved during registration */
    	dir: "<path_to_local_file_directory>" /* This directory will be used by SDK to save device certificates */
    })
    

    Adding/Removing Interfaces in Device Introspection

    device.addInterface({ /* Astarte Interface Definition */ })
    device.removeInterface(interfaceName)
    

    Device Connection

    device.connect()
    .then(() => /* Device Connected with Astarte Broker */)
    .catch((err) => /* Device Connection Error */ )
    

    Publishing Data

    • Device SDK expose two seperate methods to publish device data.
      • sendIndividual : Used to publish data for interfaces that has aggregation = individual
      • sendAggregate: Used to publish data for interfaces that has aggregation = object

    sendIndividual ( interfaceName, path, value: number | string, timestamp?: Date): Promise

    device.sendIndividual('com.astarte.interface.Status', '/status/astarte/endpoint', 2.22, new  Date());
    

    sendAggregate ( interfaceName, path, value: Object, timestamp?: Date): Promise

    device.sendAggregate('com.astarte.interface.Status', '/status/astarte/endpoint', { name: "", age: "", city: "" }, new  Date());
    

    Note: Timestamp is Optional


    Subscribing Interfaces

    • In order to recieve data of a particular interface (Note: only the one's with ownership=server) you need to subscribe the device to that respective interface MQTT topic.
    device.subscribe(interfaceName)
    

    Receiving Data

    device.on('message', (topic, payload) => {
    	console.log(topic) /* MQTT Topic on which data is received */
    	console.log(payload) /* Javascript Object of the data received */
    })
    

    Device SDK exposes following events which can be subscribed using device.on(eventName, callback) method. (Just like we did while receiving data)

    Event 'connect'

    function (connack) {}

    Emitted on successful (re)connection (i.e. connack rc=0).

    • connack received connack packet. When clean connection option is false and server has a previous session for clientId connection option, then connack.sessionPresent flag is true. When that is the case, you may rely on stored session and prefer not to send subscribe commands for the client.

    Event 'reconnect'

    function () {}

    Emitted when a reconnect starts.

    Event 'close'

    function () {}

    Emitted after a disconnection.

    Event 'disconnect'

    function (packet) {}

    Emitted after receiving disconnect packet from broker. MQTT 5.0 feature.

    Event 'offline'

    function () {}

    Emitted when the client goes offline.

    Event 'error'

    function (error) {}

    Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs.

    The following TLS errors will be emitted as an error event:

    • ECONNREFUSED
    • ECONNRESET
    • EADDRINUSE
    • ENOTFOUND

    Event 'end'

    function () {}

    Emitted when mqtt.Client#end() is called. If a callback was passed to mqtt.Client#end(), this event is emitted once the callback returns.

    Event 'message'

    function (topic, message, packet) {}

    Emitted when the client receives a publish packet

    • topic topic of the received packet
    • message payload of the received packet
    • packet received packet, as defined in mqtt-packet

    Event 'packetsend'

    function (packet) {}

    Emitted when the client sends any packet. This includes .published() packets as well as packets used by MQTT for managing subscriptions and connections

    Event 'packetreceive'

    function (packet) {}

    Emitted when the client receives any packet. This includes packets from subscribed topics as well as packets used by MQTT for managing subscriptions and connections

    Logging

    • While initializing the SDK you can pass LOG_LEVEL = debug to get more logging information, By default the LOG_LEVEL is info.
    const pairing = new Pairing({ ...pairingOptions, LOG_LEVEL: 'debug' })
    const device = new Device({ ...deviceOptions, LOG_LEVEL: 'debug' })
    

    Credits

    Install

    npm i astarte-device-sdk

    DownloadsWeekly Downloads

    15

    Version

    0.0.6

    License

    ISC

    Unpacked Size

    72.2 kB

    Total Files

    23

    Last publish

    Collaborators

    • sagarkhan