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.

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

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!');
});

Configure the Exhibit Application IP on the Hardware

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!

SDK Button LED Example

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;
  }
}

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);
    }
  }
});

Using Hardware with an Exhibit SDK