See how to set up and use the Exhibit SDK first to get familiar with using the Node SDK, as well as the hardware getting started guide for using hardware for the first time.
Overview
| Table of Contents |
|---|
| minLevel | 1 |
|---|
| maxLevel | 6 |
|---|
| outline | false |
|---|
| type | list |
|---|
| printable | false |
|---|
|
Connecting the Hardware
There are two ways to connect hardware to an Exhibit SDK application:
Online Mode - authenticate, connect, and manage hardware using the Gumband Dashboard and Service.
Offline Mode - connect and manage hardware directly, no authentication through Gumband Services.
More information about authentication scenarios, including caching the authentication whitelist, see SDK Hardware Authentication Scenarios
Regardless of the mode, the first step is to enable GBTTin the SDK using a construction parameter.
Note: Gumband hardware connects to the Gumband Services and to the Gumband SDK using GBTT, the Gumband MQTT Hardware Service.
| Code Block |
|---|
|
const { Gumband, Sockets } = require('@deeplocal/gumband-node-sdk');
const EXHIBIT_ID = '40';
const EXHIBIT_TOKEN = 'a45ne3...';
const gb = new Gumband(
EXHIBIT_TOKEN,
EXHIBIT_ID,
'./manifest.json',
{
gbttEnabled: true, // Enable the hardware MQTT broker
gbttPort: 1883, // (Optional) port for the MQTT broker, defaults to 1883
}
);
gb.on(Sockets.READY, async () => {
console.log('Gumband Ready!');
}); |
Online Mode
| Expand |
|---|
| title | Steps to connect hardware via the Gumband Dashboard |
|---|
|
Online mode is all done using Gumband Dashboard! Set the Exhibit MQTT IP addressNote: This step is a current limitation of the SDK not registering the IP address where the hardware should connect to, and is planned to be removed in the future.
In the “Hardware” tab for the exhibit, enter the IP address the hardware should connect to. This is typically the IP of the computer running the SDK application.  | Info |
|---|
Whenever associated hardware connects to the cloud / Gumband Service, it is provided this IP. Any changes to this setting will immediately be sent to any online hardware. Any offline hardware will be sent the IP the next time it comes online. |
Associate the Hardware with the Exhibit SDK| Insert excerpt |
|---|
| Hardware UI |
|---|
| Hardware UI |
|---|
| name | HWUI Connect to exhibit |
|---|
| nopanel | true |
|---|
|
|
Offline Mode
| Expand |
|---|
| title | Steps to connect hardware manually |
|---|
|
For instances where you want to bypass hardware authentication and management through Gumband Services. This could include an on-site installation where there is flakey or non-existent cloud access. Whitelist the Hardware ID in the SDK| Code Block |
|---|
| const { Gumband, Sockets } = require('@deeplocal/gumband-node-sdk');
const EXHIBIT_ID = '40';
const EXHIBIT_TOKEN = 'a45ne3...';
const gb = new Gumband(
EXHIBIT_TOKEN,
EXHIBIT_ID,
'./manifest.json',
{
gbttEnabled: true, // Enable the hardware MQTT broker
gbttPort: 1883, // (Optional) port for the MQTT broker, defaults to 1883
noInternetConnection: true, // SDK needs to run in offline mode to use Hardware ID whitelist
noInternetHardwareIds: [] // Array of offline hardware IDs
}
);
gb.on(Sockets.READY, async () => {
console.log('Gumband Ready!');
}); |
The hardware needs to know the IP of the computer running the SDK application so it knows where to connect to. We’ll configure the hardware to use this IP, and disable the cloud/ Gumband Service from being able to change it. Description | Command | Set Exhibit Server to Static | write static_exhibit true
| Set Exhibit Server | write exhibit_server XX.XX.XX.XX:1883
|
|
Checking the Hardware LED Status
The hardware’s LED status will correspond to how it is connected.
Color | Description |
 Cyan | Only Cloud server connected |
 Blue | Only Application server connected |
 Green | Both Cloud server and Application server connected |
Interacting with the SDK
See SDK Events for more information.
Hardware online/offline event
| Code Block |
|---|
|
// Event when hardware comes online/connects
gb.on(Sockets.HARDWARE_ONLINE, async (payload) => {
console.log(`Hardware with ID ${payload.hardwareId} "${payload.name}" online.`);
console.log(payload.peripherals); // Registered properties
}); |
| Code Block |
|---|
|
// Event when hardware comes offline/disconnects
gb.on(Sockets.HARDWARE_OFFLINE, async (payload) => {
console.log(`Hardware with ID ${payload.hardwareId} "${payload.name}" offline.`);
}); |
Receive hardware property event
| Code Block |
|---|
|
// Event when hardware sends a property
gb.on(Sockets.HARDWARE_PROPERTY_RECEIVED, async (payload) => {
console.log(`Hardware ID ${payload.hardwareId} "${payload.name}" sent a property`);
console.log(` property: "${payload.peripheral}/${payload.property}"`);
console.log(` value: ${payload.value}`);
}); |
Set hardware property
| Code Block |
|---|
|
gb.hardware.set(`{hardwareId}/{peripheral name}/{property name}`, value); |
Get hardware property
| Status |
|---|
| colour | Red |
|---|
| title | NOT IMPLEMENTED |
|---|
|
| Code Block |
|---|
|
value = gb.hardware.get(`{hardwareId}/{peripheral name}/{property name}`); |
Get list of currently connected hardware devices
| Code Block |
|---|
|
hwlist = gb.hardware.getOnlineHardware(); |
Examples
Button presses from the hardware get sent to the SDK, and the SDK toggles the hardware LED in return.
| Expand |
|---|
| title | Hardware Arduino sketch |
|---|
|
| Code Block |
|---|
| /*
* Gumband Remote Button/LED Example
*
* Demonstrates how to control hardware using an Exhibit Application
* - sets up a property to turn the on-board LED on/off.
* - sets up a property that updates when on-board button is pressed/released.
*/
// Create the Gumband Properties
GumbandProp button_prop = gumbandCreate("Button", "Press", gmbnd_bool);
GumbandProp led_toggle_prop = gumbandCreate("LED", "Toggle", gmbnd_bool);
// Local variable that keeps track of the button state
static bool button_currently_pressed = false;
// Define our LED/Toggle property write callback
void led_toggle_callback(uint16_t length, void* data)
{
// Cast our received value to our intended value (we can ignore length since we are expecting one value)
gmbnd_bool_t toggle_val = GUMBAND_BOOL(data);
// Turn the on-board LED on or off using the toggle value
if(toggle_val == 1) {
gumbandLedOn();
}
else {
gumbandLedOff();
}
}
void setup()
{
// Attach the callback to executes when something is written to the LED/Toggle property
gumbandSetWriteCallback(led_toggle_prop, led_toggle_callback);
}
void loop()
{
// If the on-board button is pressed
if(gumbandButtonPressed() && button_currently_pressed == false) {
// Tell the exhibit application the button has been pressed
gumbandPublish(button_prop, true);
button_currently_pressed = true;
}
else if(!gumbandButtonPressed() && button_currently_pressed == true)
{
// Tell the exhibit application the button has been released
gumbandPublish(button_prop, false);
button_currently_pressed = false;
}
}
|
|
| Code Block |
|---|
| breakoutMode | wide |
|---|
| language | js |
|---|
|
const { Gumband, Sockets } = require('@deeplocal/gumband-node-sdk');
const EXHIBIT_ID = '40';
const EXHIBIT_TOKEN = 'a45ne3...';
const gb = new Gumband(
EXHIBIT_TOKEN,
EXHIBIT_ID,
'./manifest.json',
{
gbttEnabled: true, // Enable the hardware MQTT broker
//gbttPort: 1883, // Port for the MQTT broker, defaults to 1883
//noInternetConnection: true, // SDK in offline mode
//noInternetHardwareIds: [] // Array of offline hardware IDs
}
);
gb.on(Sockets.READY, async () => {
console.log('Gumband Ready!');
});
// Event when hardware comes online/connects
gb.on(Sockets.HARDWARE_ONLINE, async (payload) => {
console.log(`Hardware with ID ${payload.hardwareId} connected.`);
});
// Event when hardware comes offline/disconnects
gb.on(Sockets.HARDWARE_OFFLINE, async (payload) => {
console.log(`Hardware with ID ${payload.hardwareId} disconnected.`);
});
// Event when hardware sends a property
gb.on(Sockets.HARDWARE_PROPERTY_RECEIVED, async (payload) => {
//console.log(`Hardware ID ${payload.hardwareId} sent a property`);
//console.log(` property: "${payload.peripheral}/${payload.property}"`);
//console.log(` value: ${payload.value}`);
// If we receive the Button/Press property
if(payload.peripheral === 'Button' && payload.property === 'Press') {
// If the button is pressed
if(payload.value == 1) {
console.log(`Button pressed!`);
// Set the LED/Toggle property to 1 (on)
gb.hardware.set(`${payload.hardwareId}/LED/Toggle`, 1);
}
// If the button is not pressed
else {
console.log(`Button released!`);
// Set the LED/Toggle property to 0 (off)
gb.hardware.set(`${payload.hardwareId}/LED/Toggle`, 0);
}
}
});
|