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

1 Connecting the Hardware
- 1.1 Online Mode
  - 1.1.1 Set the Exhibit MQTT IP address
  - 1.1.2 Associate the Hardware with the Exhibit SDK
    - 1.1.2.1 1. Navigate to the hardware you want to add.
    - 1.1.2.2 2. In the “Overview” tab, click “Connect to Exhibit”.
    - 1.1.2.3 3. Choose the Exhibit SDK to connect to.
- 1.2 Offline Mode
  - 1.2.1 Whitelist the Hardware ID in the SDK
  - 1.2.2 Configure the Exhibit Application IP on the Hardware
- 1.3 Checking the Hardware LED Status
2 Interacting with the SDK
3 Examples
- 3.1 SDK Button LED Example

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

Online mode is all done in the Gumband Cloud!

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 and MQTT port the hardware should connect to. This is typically the IP of the computer running the SDK application, with the default port being 1883.

Enter this information in the format:
<SDK Computer IP>:<SDK GBTT Port> ie. 192.168.1.100:1883

Anytime associated hardware connects to the Gumband Cloud, it is provided this IP to be able to connect to the Exhibit SDK. 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

For instances where you want to bypass hardware authentication and management through Gumband Cloud. 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 using the serial configuration interface, and disable the Gumband Cloud 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 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
});

Receive hardware property event

Set hardware property

Get hardware property

Get list of currently connected hardware devices

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).

Gumband Support

v1 Using Hardware with an Exhibit SDK