SDK-Hardware Interface
- Oscar Prom
- Luke Derrick
- Devon Gardner
- Pat Sweeney
SDK-Hardware Authentication
Just as the hardware authenticates with the Gumband Cloud, it also needs to authenticate with the SDK to ensure only expected hardware interacts with exhibits. The SDK gets the list of connected hardware from the Gumband Cloud, and then allows hardware to connect and authenticate with the same ID / token combination.
Available in version 1.0.31 and later in the Node.js SDK
SDK “Waiting for Auth” Queue
When the exhibit connection to the Gumband Cloud is pending or unstable, the following connections are added to a “Waiting for Authentication” queue until the SDK receives the connected hardware list from the Gumband Cloud. If the SDK does not receive that list within 10 sec of the hardware connection, the SDK initiates a disconnection at which point the hardware will back off and retry. That cycle continues until the SDK has the required hardware info and the hardware is able to successfully connect.
How Two MQTT Connections for the Same Hardware ID Respond
If two hardware connections authenticate with the same hardware ID, the SDK will respond in the following way:
If that hardware ID connection is “Waiting for Auth”, the SDK will disconnect the older connection and hold the newer connection for authentication.
If the hardware ID connection is authenticated, the SDK will reject the newer connection and hold the existing hardware connection.
Removing an Active SDK-Hardware Connection
If hardware is removed from an exhibit through the Gumband Cloud dashboard and is currently connected to the exhibit, it will be immediately disconnected and will not be allowed to further authenticate.
SDK Offline Mode
An SDK can operate in “offline mode” where it will blindly accept hardware based on hardware ID. Add the following lines to the SDK constructor:
{
noInternetConnection: true,
noInternetHardwareIds: [100, 121, 10], // list hardware IDs to allow
}
SDK Events
Event Name | Description |
|---|---|
Sockets.HARDWARE_ONLINE | Emitted when a hardware device connects to the SDK |
Sockets.HARDWARE_OFFLINE | Emitted when a hardware device disconnects from the SDK |
Sockets.HARDWARE_PROPERTY_RECEIVED | Emitted when the SDK receives a property sent by the hardware. |
SDK HARDWARE_ONLINE & HARDWARE_OFFLINE Callbacks
There is a HARDWARE_ONLINE callback for the SDK that is used when the token is accepted and the SDK sends back true on hardwareId/authenticate. There is also an "expiry" timeout that triggers a HARDWARE_OFFLINE event in the SDK if the heartbeat for a particular harwareId isn’t received within 20s. The hardware currently sends a heartbeat every 16s
Online Data Payload
{
hardwareId: ##,
name: 'Name of device',
peripherals:
{
'examplePeripheral':
{
'Example Property 1':
{
peripheral: 'examplePeripheral',
property: 'Example Property 1',
order: 0,
numProperties: 2,
type: 'gmbnd_byte',
length: 1,
settable: 'false',
gettable: 'false',
hidden: 'false',
info: 'example property description',
},
'Example Property 2': {},
},
'anotherPeripheral':
{
'Example Property 3': {},
}
}
}Offline Data Payload
{
hardwareId: ##,
name: 'Name of device',
}
SDK HARDWARE_PROPERTY_RECEIVED Callbacks
There is a HARDWARE_PROPERTY_RECEIVED callback for the SDK triggered whenever a property is published by the hardware device.