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 Setting Up the MQTT Broker
- 1.1 Built In MQTT Broker
- 1.2 User Defined MQTT Broker
2 Connecting the Hardware
3 Checking the Hardware LED Status
4 Interacting with the SDK
5 Examples
- 5.1 SDK Button LED Example

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:

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

Screen Shot 2024-07-22 at 5.05.30 PM.png

The Components tab in the Gumband UI showing a component for the Exhibit SDK (“My Exhibit”) and a component for the Hardware (“My Hardware”)

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.

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.

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

Hardware registered event

Receive hardware property event

Set hardware property

Get hardware property

Get list of currently registered hardware devices

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

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

Using Hardware with an Exhibit SDK