UPDATED 9/21/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 Cloud.
Offline Mode - connect and manage hardware directly in the SDK, no authentication through the Gumband Cloud.
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 Cloud 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
Offline Mode
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 about these events and the available data in the payloads.
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
SDK Button LED Example
Button presses from the hardware get sent to the SDK, and the SDK toggles the hardware LED in return.
The firmware for the hardware is the Remote LED and Button example in Arduino (version 1.8.4 or newer).
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); } } });