You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 5
Next »
UPDATED 8/15/23
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
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 GBTT in 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.
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
Steps to connect hardware via the Gumband Dashboard
Online mode is all done using Gumband Dashboard!
Set the Exhibit MQTT IP address
Note: 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.
Associate the Hardware with the Exhibit SDK
This can alternatively be done from the Exhibit SDK’s Hardware Tab.
1. Navigate to the hardware you want to add.
Sites > [Project Site] > [Hardware] > Overview
2. In the “Overview” tab, click “Connect to Exhibit”.
3. Choose the Exhibit SDK to connect to.
A modal will pop up and display all available Exhibits within the same organization.
The hardware is set to connect to an Exhibit SDK if the Exhibit name is displayed in the “Overview” tab.
Offline Mode
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
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
// 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
});
// 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
// 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
gb.hardware.set(`{hardwareId}/{peripheral name}/{property name}`, value);
Get hardware property NOT IMPLEMENTED
value = gb.hardware.get(`{hardwareId}/{peripheral name}/{property name}`);
Get list of currently connected hardware devices
hwlist = gb.hardware.getOnlineHardware();
Examples
Putting it all together!
Button presses from the hardware get sent to the SDK, and the SDK toggles the hardware LED in return.
Hardware Arduino sketch
/*
* 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;
}
}
Node SDK application
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);
}
}
});