Table of Contents

minLevel	1
maxLevel	6
outline	false
style	default
type	list
printable	false

...

Connecting the

...

Built In MQTT Broker

The Exhibit SDK comes with a built in MQTT Broker that the hardware and SDK can use to communicate with each other. To enable the MQTT Broker during the SDK initialization:

...

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

Code Block

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'./manifest.json',
    {
        useLocalMQTTBrokergbttEnabled: true, // Enable the hardware MQTT broker
  MQTTBrokerPort: 1885,   gbttPort: 1883, },
);

This will instruct the Exhibit SDK to create an MQTT broker at port 1885 (the default port is 1883), and to connect a client to the broker on the Exhibit SDK’s behalf. In this case, the MQTT IP is not required since the SDK has a direct reference to the MQTT broker.

User Defined MQTT Broker

If you want to use your own MQTT Broker instead, you can do that by providing the MQTTBrokerIP option:

Code Block
const gb = new Gumband( TOKEN, EXHIBIT_ID, MANIFEST, // (Optional) port for the MQTT broker, defaults to 1883 } ); gb.on(Sockets.READY, async () => { MQTTBrokerIP: "123.123.1.12", }, );

This will instruct the Exhibit SDK to create a client that connects to the broker at 123.123.1.12:1883

Connecting the Hardware

An Exhibit SDK application will only accept messages from hardware that are whitelisted. There are three options to define this whitelist:

Default: Accept Messages From Any Hardware ID

By default, the whitelist will consist of only a *. This indicates that the SDK will accept and process messages from any hardware that sends them over the MQTT broker.

Only Accept Messages From Hardware IDs in the Approved Whitelist

Set a whitelist of hardware IDs when the Exhibit SDK first initializes:

Code Block
const console.log('Gumband Ready!'); });

Online Mode

Expand

title	Steps to connect hardware via the Gumband Dashboard

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

Image Added

Info
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”.

Image Added

3. Choose the Exhibit SDK to connect to.

A modal will pop up and display all available Exhibits within the same organization.

Image Added

The hardware is set to connect to an Exhibit SDK if the Exhibit name is displayed in the “Overview” tab.

Image Added

Offline Mode

Expand

title	Steps to connect hardware manually

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

Code Block

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

'./manifest.json',
    {

useLocalMQTTBroker

gbttEnabled: true, // Enable the hardware MQTT broker

allowedHardwareIds:

['ed028e04-41d9-4e77-a5d2-ab4e7346e3a7']

   gbttPort: 1883,

},

//

);

This will only allow the Exhibit SDK to accept messages from hardware with an ID of ed028e04-41d9-4e77-a5d2-ab4e7346e3a7. All other messages will still be seen by the SDK, but will be ignored.

Only Accept Messages From Hardware That Are Associated With the Same Exhibit in the Gumband UI

Set the whitelist of hardware IDs to whatever hardwares are associated with the same exhibit as the Exhibit SDK in the Gumband UI:

Code Block
const gb = new Gumband( TOKEN, EXHIBIT_ID, MANIFEST, { useLocalMQTTBroker: true, allowOnlyCloudHardwareIds: true }, );

You can see which Exhibit SDKs and Hardware are associated with any given exhibit by navigating to the Components tab of any exhibit:

...

Note

If two hardwares with the same ID connect through the MQTT Broker, the registration of the first hardware will be overwritten by the second hardware. This is because the properties of a hardware are stored in the SDK based on ID.

(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

Image Removed
Image Added Cyan
Only Cloud server connected
Image Removed
Image Added Blue
Only Application server connected
Image Removed
Image Added 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.

There are two stages that the hardware goes through when it connects to the Exhibit SDK. When the SDK receives its first registration message from the hardware, the hardware is considered “connected”. At this time, the SOCKETS.HARDWARE_CONNECTED event is emitted through the SDK class.

After all system properties and at least one application property has been registered with the Exhibit SDK, that hardware is considered “registered” and the SDK will emit a SOCKETS.HARDWARE_REGISTERED event. The “registered” event is the more significant of the two, since that event means the SDK is ready to start sending/receiving property updates to/from the hardware.

...

Hardware online/offline event

Code Block

language	js

// 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

language	js

// 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

...

language	js

// Event when hardware

...

sends

...

property
gb.on(

...

Sockets.HARDWARE_

...

PROPERTY_

...

RECEIVED, async (payload) => {
  console.log(`Hardware

...

Receive hardware property event

Code Block

language	js

// Event when hardware system or app property is changed
gb.on(SOCKETS.HARDWARE_PROPERTY_RECEIVED, async (payload) => {
  //  {
  //      id: 'ed028e04-41d9-4e77-a5d2-ab4e7346e3a7',
  //      info: {
  //        system: { info: [Object], properties: [Array] },
  //        app: { info: [Object], properties: [Array] }
  //      },
  //      value: [ "myValue" ],
  //      property: 'My Property',
  //      source: 'app'
  //  }
});

Set hardware property

...

language	js

...

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

Code Block

...


value = gb.hardware.

...

get(

...

`{hardwareId}/{peripheral name}/{property name}`);

Get list of currently

...

connected hardware devices

Code Block

...

language	js

hwlist = gb.hardware.

...

getOnlineHardware();

Info
To see the full the full SDK API with examples, see our API Reference Docs.

Examples

SDK Button LED Example

...

Expand

title	Remote LED and Button Hardware Arduino sketch

Code Block

language	arduino

/*
 * 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.
 */
#include
<Gumband.h> 
// Create the Gumband Properties
GumbandBoolGumbandProp button_prop = gumbandCreate("Button", "Press", gmbnd_bool);
GumbandBoolGumbandProp led_toggle_prop = gumbandCreate("LED", "Toggle");

// Define our LED/Toggle property write callback
void led_toggle_callback(void)
{, gmbnd_bool);
 
// TurnLocal thevariable on-boardthat LEDkeeps ontrack orof off using the togglebutton valuestate
static bool if(ledbutton_toggle_prop.getValue()) {
    psocLEDOn();
  }
  else {
    psocLEDOff();
  }
}

void setup()
{
  // Initialize Gumband
  gumbandInit();

  // Attach the callback to execute when something is written to the currently_pressed = false;
 
// Define our LED/Toggle property write callback
void led_toggle_prop.setWriteCallbackcallback(led_toggle_callback);

  // Automatically tell the exhibit application when the button is pressed or released
  button_prop.setPublishOnChange();
  // Prevent the exhibit application from updating our button
  button_prop.setReadOnly();

  // Register properties by calling subscribe
  gumbandSubscribe();
}

void loop()
{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);
 
    // Get ifTurn the on-board buttonLED ison pressedor off  button_prop.setValue(psocButtonIsPressed());

  // Call update to handle incoming Gumband messages
  gumbandUpdate();
}

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',

using the toggle value
    if(toggle_val == 1) {

useLocalMQTTBroker: true, // Enable the hardware MQTT broker //MQTTBrokerPort: 1883, // Port for the MQTT broker, defaults to 1883 } ); gb.on(Sockets.READY, async () =>

gumbandLedOn();
    }
    else {

console.log('Gumband

Ready!'); }

 gumbandLedOff();

//

Event

when

hardware

connects

and

registers gb.on(Sockets.HARDWARE_REGISTERED, async (payload) => { console.log(`Hardware with ID ${payload.id} registered.`); }); // Event when hardware disconnects gb.on(Sockets.HARDWARE_DISCONNECTED, async (payload) => { console.log(`Hardware with ID ${payload.id} disconnected.`); }); // Event when hardware sends a property gb.on(Sockets.HARDWARE_PROPERTY_RECEIVED, async (payload) => { //console.log(`Hardware ID ${payload.id} sent a property`); //console.log(` property: "${payload.property}"`); //console.log(` value: ${payload.value}`);


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

we

the

receive

on-board

the

button

Button/Press

is

property

pressed
  if

(payload.property === 'Button/Press') { // If the button is pressed if(payload.value == 1

(gumbandButtonPressed() && button_currently_pressed == false) {

console.log(`Button pressed!`);

//

Set

Tell the

LED/Toggle

exhibit

property

application

to

the

1

button

(on)

has been pressed

gb.hardware.set(`${payload.id}/LED/Toggle`, 1); }

gumbandPublish(button_prop, true);

//

If

the

 button_currently_pressed

is

not

true;

pressed

  }
  else

{ console.log(`Button released!`);

if(!gumbandButtonPressed() && button_currently_pressed == true)
  {
    //

Set

Tell the

LED/Toggle

exhibit

property

application

to

the

0

button

(off)

has been released

gb.hardware.set(`${payload.id}/LED/Toggle`, 0); }

gumbandPublish(button_prop, false);
 
    button_currently_pressed = false;
  }
}

);

Versions Compared

Old Version 1

New Version Current

Key

Connecting the

Built In MQTT Broker

Hardware

User Defined MQTT Broker

Connecting the Hardware

Default: Accept Messages From Any Hardware ID

Only Accept Messages From Hardware IDs in the Approved Whitelist

Online Mode

Set the Exhibit MQTT IP address

Associate the Hardware with the Exhibit SDK

1. Navigate to the hardware you want to add.

2. In the “Overview” tab, click “Connect to Exhibit”.

3. Choose the Exhibit SDK to connect to.

Offline Mode

Whitelist the Hardware ID in the SDK

Only Accept Messages From Hardware That Are Associated With the Same Exhibit in the Gumband UI

Configure the Exhibit Application IP on the Hardware

Checking the Hardware LED Status

Interacting with the SDK

Hardware online/offline event

Receive hardware property event

Receive hardware property event

Set hardware property

Set hardware property

Get hardware property

Get list of currently

connected hardware devices

Examples

SDK Button LED Example

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Connecting the

Built In MQTT Broker

Hardware

User Defined MQTT Broker

Connecting the Hardware

Default: Accept Messages From Any Hardware ID

Only Accept Messages From Hardware IDs in the Approved Whitelist

Online Mode

Set the Exhibit MQTT IP address

Associate the Hardware with the Exhibit SDK

1. Navigate to the hardware you want to add.

2. In the “Overview” tab, click “Connect to Exhibit”.

3. Choose the Exhibit SDK to connect to.

Offline Mode

Whitelist the Hardware ID in the SDK

Only Accept Messages From Hardware That Are Associated With the Same Exhibit in the Gumband UI

Configure the Exhibit Application IP on the Hardware

Checking the Hardware LED Status

Interacting with the SDK

Hardware online/offline event

Receive hardware property event

Receive hardware property event

Set hardware property

Set hardware property

Get hardware property

Get list of currently

connected hardware devices

Examples

SDK Button LED Example