...

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

...

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

...

Associate the Hardware with the Exhibit SDK

...

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

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

...

...

Setting Up the MQTT Broker

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:

const gb = new Gumband(
    TOKEN,
    EXHIBIT_ID,
    MANIFEST,
    {
        useLocalMQTTBroker: true,
        MQTTBrokerPort: 1885,
    },
);

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:

const gb = new Gumband(
    TOKEN,
    EXHIBIT_ID,
    MANIFEST,
    {
        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:

const gb = new Gumband(
    TOKEN,
    EXHIBIT_ID,
    MANIFEST,
    {
        useLocalMQTTBroker: true,
        allowedHardwareIds: ['ed028e04-41d9-4e77-a5d2-ab4e7346e3a7']
    },
);

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:

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:

...

Checking the Hardware LED Status

The hardware’s LED status will correspond to how it is connected.

Color	Description
Image Added Cyan	Only Cloud server connected
Image Added Blue	Only Application server connected
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 connected/disconnected event

// Event when hardware connects to the Exhibit SDK, but before it registers properties
gb.on(SOCKETS.HARDWARE_CONNECTED, async (payload) => {
    console.log(`Hardware with ID ${payload.id} connected.`);
});

// Event when hardware disconnects from the Exhibit SDK
gb.on(SOCKETS.HARDWARE_DISCONNECTED, async (payload) => {
    console.log(`Hardware with ID ${payload.id} disconnected.`);
});

Hardware registered event

// Event when hardware registers with the Exhibit SDK.
gb.on(SOCKETS.HARDWARE_FULLY_REGISTERED, async (payload) => {
    //  payload: {
    //    id: "ed028e04-41d9-4e77-a5d2-ab4e7346e3a7",
    //    system: {
    //      info: {
    //        ...systemInfo
    //      },
    //      properties: {
    //        ...systemProperties
    //      }
    //    },
    //    app: {
    //      info: {
    //        ...appInfo
    //      },
    //      properties: {
    //        ...appProperties
    //      }
    //    }
    //  }
});

Receive hardware property event

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

gb.hardware.setsetProperty(`{hardwareId}/{peripheral name}/{property name}`hardwareId,"my/property/path", value);

Get hardware property

value = gb.hardware.getgetProperty(`{hardwareId}/{peripheral name}/{property name}`hardwareId, "my/property/path");

Get list of currently

...

registered hardware devices

hwlist = gb.hardware.getOnlineHardwaregetAllRegisteredHardware();;

Examples

SDK Button LED Example

...

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',
    {
      gbttEnableduseLocalMQTTBroker: true, // Enable the hardware MQTT broker
      //gbttPortMQTTBrokerPort: 1883, // Port for the MQTT broker, defaults to 1883
      //noInternetConnection: true, // SDK in offline mode
      //noInternetHardwareIds: [] // Array of offline hardware IDs to 1883
    }
);

gb.on(Sockets.READY, async () => {
    console.log('Gumband Ready!');
});

// Event when hardware connects comesand online/connectsregisters
gb.on(Sockets.HARDWARE_ONLINEREGISTERED, async (payload) => {
    console.log(`Hardware with ID ${payload.hardwareIdid} connectedregistered.`);
});

// Event when hardware comes offline/disconnects
gb.on(Sockets.HARDWARE_OFFLINEDISCONNECTED, async (payload) => {
    console.log(`Hardware with ID ${payload.hardwareIdid} disconnected.`);
});

// Event when hardware sends a property
gb.on(Sockets.HARDWARE_PROPERTY_RECEIVED, async (payload) => {
  //console.log(`Hardware ID ${payload.hardwareIdid} sent a property`);
  //console.log(`  property: "${payload.peripheral}/${payload.property}"`);
  //console.log(`  value: ${payload.value}`);
  
  // If we receive the Button/Press property
  if(payload.peripheralproperty === '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.hardwareIdid}/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.hardwareIdid}/LED/Toggle`, 0);
    }
  }
});

...