SDK Configuration Options

Here is a list of the configuration options that the SDK constructor takes as parameters.

constructor (token: string, exhibitId: number, manifestLocation: string, options = {})

token

The exhibit token generated through the Exhibit/Auth tab in the Gumband UI. This is required to authenticate the SDK with Gumband.

exhibitId

The ID of the exhibit in Gumband. This can be found under the Exhibit/Auth tab in the Gumband UI. This is required to authenticate the SDK with Gumband.

manifestLocation

The directory path to the JSON file that defines the exhibit manifest.

options

All of the remaining optional parameters that enables certain features of the Gumband SDK.

contentLocation: string

Including this option tells the SDK to download a copy of each file in the Exhibit/Files tab of the Gumband UI and save them in this location. The SDK will automatically sync these files each time it starts and connects to Gumband, but the files can also be synced manually with the gb.content.sync() function.

endpoint: string

Set to “app” by default. May be set to “custom” if app.gumband.com is not the instance of Gumband to which you’re connecting your exhibit. If set to “custom”, the “customServerIP” option must also be defined.

customServerIP: string

If the “endpoint” configuration option is set to “custom”, this option must also be set in order to tell the SDK the IP address of the Gumband server to which it is connecting.

version: string

The version of the Gumband Cloud to which the exhibit should connect. Set to “v1” by default.

noInternetConnection: boolean

Tells the SDK that the exhibit is expected to be disconnected from the internet, and should not attempt to authenticate with Gumband.

noInternetHardwareIds: number[]

An array of hardware ID that should be connected to, even though there is no internet connection. These are Gumband Hardware that should be permitted to connect to the exhibit, even though they have not authenticated themselves with Gumband.

gbttEnabled: boolean

Whether a local MQTT broker (the GBTT service) should be started when the SDK is initialized. This MQTT broker is used to communicate with Gumband Hardware.

gbttPort: number

Only applicable if the “gbttEnabled” option is true. This option is the port that the local MQTT broker is exposed on.

skipOrganizationFileSync: boolean

Set to true by default. Tells the SDK not to download all organization files along with the exhibit files when the “contentLocation” option is provided. Exhibit files are only accessible by the exhibit under the Exhibit/Files tab in the Gumband UI, but organization files are available to all exhibits under the organization and can be seen under each exhibits' Files tab. Organization files are prefixed by “[ORG]” and are managed by the Strapi CMS.

Function Library

isReady( )

Returns true if Gumband is connected to the Gumband Cloud and is ready to process requests. Useful when the Gumband SDK is initialized in multiple places since the constructor returns a singleton and it is possible to "miss" the READY event if an event listener is not configured yet.

setManifest(manifestLocation: string): Promise<void>

Use a local manifest to update the exhibit items on the gumband cloud. This function updates the SDK cache of the manifest as well.

manifestLocation

The directory path to the manifest.

Example

gumbandSDK.setManifest('./path/to/manifest.json');

getOperatingMode( ): Promise<boolean>

Get the current operating mode for the exhibit from Gumband.

Example

let operatingMode = await gumbandSDK.getOperatingMode();

console.log(`Operating Mode: ${operatingMode}`);
// Operating Mode: true

setOperatingMode(opMode: boolean): Promise<void>

Set the operating mode for the exhibit in Gumband.

opMode

The target operating mode.

Example

await gumbandSDK.setOperatingMode(true);

getStatus(statusName: string): Promise<string>

Get the value of a status from Gumband.

statusName

The “id” field of the status in the manifest.

Example

let statusValue = await gumbandSDK.getStatus('cpu-usage');

console.log(`CPU Usage: ${statusValue}`);
// CPU Usage: 50%

setStatus(statusName: string, value: string): Promise<void>

Set the value of a status in Gumband.

statusName

The “id” field of the status in the manifest.

value

The target value to which the status should be set.

Example

await gumbandSDK.setStatus('cpu-usage', "50%");

getSetting(manifestId: string): Promise<string>

Get the value of a setting from Gumband.

manifestId

The “id” field of the setting in the manifest.

Example

let motorRPM = await gumbandSDK.getSetting('motor-rpm');

console.log(`Motor RPM: ${motorRPM}`);
// Motor RPM: 30

setSetting(settingName: string, value: string): Promise<void>

Set the value of a setting in Gumband.

settingName

The “id” field of the setting in the manifest.

value

The target value to which the setting should be set.

Example

await gumbandSDK.setSetting('motor-rpm', '30');

getAllSettings( ): Promise<Map<Setting>>

Get all settings as a map, where the key is the “id” field of each setting in the manifest.

Example

console.log(await gumbandSDK.getAllSettings());

//{
//  'motor-rpm': {
//    id: 14,
//    manifestId: 'motor-rpm',
//    exhibitId: 1,
//    type: 'IntegerInput',
//    display: 'Motor RPM',
//    enabledOpMode: null,
//    value: 30,
//    default: 0,
//    order: 0,
//    touchless: null,
//    listId: null,
//    groupId: null,
//    read: true,
//    write: true
//  }
//}

getAllSettingLists( ): Promise<SettingList[ ]>

Get all setting lists in the manifest as an array.

Example

console.log(await gumbandSDK.getAllSettingLists());

//[
//  {
//    id: 1,
//    exhibitId: 1,
//    manifestId: 'my-list',
//    listDisplay: 'List Label',
//    listParent: null,
//    schema: [ [Object], [Object] ],
//    listItemCount: 1,
//    order: [ 'item 1' ],
//    orderSelf: null,
//    groupId: null,
//    settinglistitems: [ [Object] ],
//    type: 'SettingsList'
//  }
//]

getOnlineHardware( ): Hardware[ ]

Get the list of Gumband Hardware that are currently connected to the SDK.

Example

console.log(gumbandSDK.getOnlineHardware());

//[
//  {
//    hardwareId: 83,
//    name: 'Gumband SDK Tutorial',
//    peripherals: { Button: [Object], LED: [Object] }
//  }
//]

exhibit.getManifest( ): Promise<Manifest>

Get the full manifest of this exhibit from Gumband.

Example

console.log(await gumbandSDK.exhibit.getManifest());

//{
//  manifest: {
//    id: 249,
//    siteId: 34,
//    name: 'Gumband SDK Tutorial',
//    mqttPath: '',
//    online: true,
//    manifestLocked: false,
//    opMode: 'On',
//    settingLists: [],
//    settingGroups: [ [Object], [Object] ],
//    settings: [ [Object] ],
//    statuses: [ [Object], [Object], [Object] ],
//    controls: [ [Object], [Object] ],
//    strapiContent: []
//  }
//}

exhibit.getStrapiContentSetting(id: number): Promise<StrapiContent>

Get an exhibit setting with type StrapiContent.

id

The database ID of the StrapiContent.

hardware.set(topic: string, value): Promise<void>

Set a hardware property to a value.

topic

A string of the form {hardwareId}/{periph}/{prop}, where hardwareId is the ID of the hardware found under the Hardware/Auth tab in the Gumband UI, periph is the name of the peripheral the property is within, and prop is the name of the property that is having its value set.

value

The new value to which the property will be set.

Example

//gmbnd_bool property type
await gumbandSDK.hardware.set("1/My Peripheral/My Property", 1);

hardware.getExhibitHardware( ): Promise<Response<Hardware[ ]>>

Get all hardware associated with this exhibit in the Gumband UI.

Example

console.log(await gumbandSDK.hardware.getExhibitHardware());

//{
//  response: 'success',
//  hardware: [
//    {
//      id: 83,
//      siteId: 34,
//      exhibitId: 249,
//      mac: '16:95:62:21:1h:h2',
//      name: 'Gumband SDK Tutorial',
//      lastHeartbeat: '2023-08-21T16:02:12.133Z',
//      online: true,
//      numPeripherals: 2,
//      controlDebug: true,
//      gumband_fw: '47',
//      user_fw: '0',
//      ip: '192.168.2.2',
//      exhibitIP: '192.168.83.17:1884',
//      exhibitState: 1,
//      temp: '43.217',
//      voltage: '4.609',
//      uptime: '49',
//      createdAt: '2023-08-08T17:42:11.390Z',
//      updatedAt: '2023-08-21T16:02:12.131Z'
//    }
//  ]
//}

hardware.sendMqttMessage(topic: string, rawPayload): Promise<void>

Sends an MQTT message directly to the hardware with the given topic and rawPayload.

topic

A string of the form {hardwareId}/{periph}/{prop}, where hardwareId is the ID of the hardware found under the Hardware/Auth tab in the Gumband UI, periph is the name of the peripheral the property is within, and prop is the name of the property that is having its value set.

rawPayload

The raw value to be parsed directly by the hardware.

content.getRemoteFileList( ): Promise<Response<File[ ]>

Get a list of all remote file names. These file names will match the files list under the Exhibit/Files tab in the Gumband UI.

Example

let remoteFiles = await gumbandSDK.content.getRemoteFileList();

console.log(remoteFiles);
//{
//  response: 'OK',
//  files: [
//    {
//      file: 'gumband-cassette.png',
//      name: 'gumband-cassette.png',
//      hash: 'SlTZJxaq+s5YH4R1KX6wHA==',
//      lastUpdated: '2023-08-14T19:22:08.547Z',
//      size: '81204'
//    }
//  ],
//  errors: []
//}

content.getLocalFileList( ): File[ ]

Get a list of all locally saved file names for the exhibit.

Example

let localFiles = gumbandSDK.content.getLocalFileList();

console.log(localFiles);
//{
//  files: [
//    {
//      file: 'gumband-cassette.png',
//      name: 'gumband-cassette.png',
//      hash: 'SlTZJxaq+s5YH4R1KX6wHA==',
//      lastUpdated: '2023-08-14T19:22:08.547Z',
//      size: '81204'
//    }
//  ]
//}

content.sync( ): Promise<void>

Sync locally saved files with the list of remote files. This is called whenever the SDK makes a connection to Gumband if local files is enabled.

Example

await gumbandSDK.content.sync();

content.uploadFile(fileStream: ReadStream): Promise<void>

Uploads a file to the list of remote files for the exhibit.

fileStream

A stream of data from a function such as fs.createReadStream("path/to/file").

Example

const fileStream = fs.createReadStream("path/to/file");
await gumbandSDK.content.uploadFile(fileStream);

content.downloadFile(file: string): Promise<void>

Downloads the given file name from the remote list of files for the exhibit in Gumband, and saves it in the contentLocation directory for the locally saved exhibit files. Existing files with the same name will be overwritten.

file

The name of the file.

Example

await gumbandSDK.content.downloadFile("gumband-cassette.png");

event.create(eventName: string, data: any): Promise<void>

await gumbandSDK.logger.error("This is an error log message");

metrics.endInteraction(data?: object)

Ends an active interaction for a given exhibit.

Example

gumbandSDK.metrics.endInteraction()

metrics.startInteraction(data?: object)

Starts an active interaction for a given exhibit.

Example

gumbandSDK.metrics.startInteraction()

notifications.email(message: string): Promise<void>

Sends a custom email notification through Gumband. Custom email notifications can be subscribed to on an individual user basis under the Exhibit/Notifications tab of the Gumband UI.

message

The message for the custom email notification.

Example

await gumbandSDK.notification.email("Your exhibit requires maintenance");

Websocket Events

This is a list of the possible websocket events that may be emitted by the SDK; for example:

const { Sockets } = require("@deeplocal/gumband-node-sdk");

gumbandSDK.on(Sockets.CONTROL_RECEIVED, (payload) => {
  //code reached when the SDK emits a Sockets.CONTROL_RECEIVED event
});

Sockets.READY

Emitted after the SDK successfully authenticates with Gumband, comes online, and is ready to make requests to Gumband.

Example

gumbandSDK.on(Sockets.READY, (manifest) => {
    console.log(manifest);
    
    // {
    //     id: 1,
    //     siteId: 1,
    //     name: 'E',
    //     mqttPath: null,
    //     online: true,
    //     manifestLocked: false,
    //     opMode: 'Off',
    //     settingLists: [...],
    //     settingGroups: [...],
    //     settings: [...],
    //     statuses: [...],
    //     controls: [...],
    //     strapiContent: [...]
    // }
});

Sockets.EXHIBIT_ONLINE

Emitted when the SDK successfully authenticates with Gumband and comes online.

Example

gumbandSDK.on(Sockets.EXHIBIT_ONLINE, () => {
    //no payload for the the Sockets.EXHIBIT_ONLINE event.
});

Sockets.EXHIBIT_OFFLINE

Emitted when the SDK losses its websocket connection with Gumband.

Example

gumbandSDK.on(Sockets.EXHIBIT_OFFLINE, () => {
    //no payload for the the Sockets.EXHIBIT_OFFLINE event.
});

Sockets.CONTROL_RECEIVED

Emitted when a control is triggered, usually through the Exhibit/Controls tab in the Gumband UI.

Example

gumbandSDK.on(Sockets.CONTROL_RECEIVED, async (payload) => {
    console.log(payload);

    // {
    //   id: 'control_manifest_id',
    //   touchless: undefined,
    //   sessionId: undefined,
    //   sessionUser: undefined
    // }
});

Sockets.SETTING_RECEIVED

Emitted when a setting is changed, usually through the Exhibit/Settings tab in the Gumband UI.

Example

gumbandSDK.on(Sockets.SETTING_RECEIVED, (payload) => {
    console.log(payload);
    
    // {
    //     id: 'setting_manifest_id',
    //     value: 'new value',
    //     touchless: undefined,
    //     sessionId: undefined,
    //     sessionUser: undefined
    // }
});

Sockets.SETTING_LIST_RECEIVED

Emitted when a new setting list item is added or deleted, when the setting list items have their order changed, or when a setting within a setting list item is changed. The payload is the new setting list with all of its items.

Example

gumbandSDK.on(Sockets.SETTING_LIST_RECEIVED, (payload) => {
    console.log(payload);
    
    // { 
    //     id: 'setting_list_manifest_id', 
    //     value: [
    //         ...settingListItems
    //     ]
    // }
});

Sockets.SETTING_LIST_ITEM_DELETED

Emitted when a setting list item is deleted. The payload is the setting list item that was deleted.

Example

gumbandSDK.on(Sockets.SETTING_LIST_ITEM_DELETED, (payload) => {
    console.log(payload);
    
    // {
    //   "id": "list_manifest_id",
    //   "value": [
    //     {
    //       "id": "deleted_list_item_name",
    //       "value": [ ...listItemValues ]
    //     }
    //   ]
    // }
});

Sockets.OP_MODE_RECEIVED

Emitted when the Operation Mode is changed, usually through the Exhibit dashboard in the Gumband UI.

Example

gumbandSDK.on(Sockets.OP_MODE_RECEIVED, (payload) => {
    console.log(payload);
    
    // {
    //   value: true
    // }
});

Sockets.HARDWARE_ONLINE

Emitted when a Gumband Hardware associated with the exhibit connects to the exhibit.

Example

gumbandSDK.on(Sockets.HARDWARE_ONLINE, (payload) => {
    console.log(payload);
    
    // {
    //   hardwareId: 1,
    //   name: 'Gumband Hardware Name',
    //   peripherals: { Button: { Press: [Object] }, LED: { Toggle: [Object] } }
    // }
});

Sockets.HARDWARE_OFFLINE

Emitted when a Gumband Hardware associated with the exhibit disconnects from the exhibit.

Example

gumbandSDK.on(Sockets.HARDWARE_OFFLINE, (payload) => {
    console.log(payload);
    
    // {
    //   hardwareId: 1,
    //   name: 'Gumband Hardware Name'
    // }
});

Sockets.HARDWARE_PROPERTY_RECEIVED

Emitted when a property is changed in a Gumband Hardware that is connected to the exhibit.

Example

gumbandSDK.on(Sockets.HARDWARE_PROPERTY_RECEIVED, async (payload) => {
    console.log(payload);
    
    // {
    //   hardwareId: '1',
    //   name: 'Gumband Hardware Name',
    //   value: 1,
    //   peripheral: 'Button',
    //   property: 'Press'
    // }
});

Sockets.FILE_UPLOADED

Emitted when a new file has been uploaded to Gumband, usually through the Exhibit/Files tab of the Gumband UI.

Example

gumbandSDK.on(Sockets.FILE_UPLOADED, (payload) => {
    console.log(payload);
    
    // {
    //   file: 'uploadedFileName.png',
    //   size: 7891,
    //   exhibitId: '1',
    //   lastUpdated: '2023-08-28T16:14:54.418Z'
    // }
});

Sockets.FILE_DELETED

Emitted when a file is deleted from Gumband, usually through the Exhibit/Files tab of the Gumband UI.

Example

gumbandSDK.on(Sockets.FILE_DELETED, (payload) => {
    console.log(payload);
    
    // { 
    //   file: 'deletedFileName.png'
    // }
});

API Reference

SDK Configuration Options

token

exhibitId

manifestLocation

options

contentLocation: string

endpoint: string

customServerIP: string

version: string

noInternetConnection: boolean

noInternetHardwareIds: number[]

gbttEnabled: boolean

gbttPort: number

skipOrganizationFileSync: boolean

Function Library

isReady( )

setManifest(manifestLocation: string): Promise<void>

manifestLocation

getOperatingMode( ): Promise<boolean>

setOperatingMode(opMode: boolean): Promise<void>

opMode

getStatus(statusName: string): Promise<string>

statusName

setStatus(statusName: string, value: string): Promise<void>

statusName

value

getSetting(manifestId: string): Promise<string>

manifestId

setSetting(settingName: string, value: string): Promise<void>

settingName

value

getAllSettings( ): Promise<Map<Setting>>

getAllSettingLists( ): Promise<SettingList[ ]>

getOnlineHardware( ): Hardware[ ]

exhibit.getManifest( ): Promise<Manifest>

exhibit.getStrapiContentSetting(id: number): Promise<StrapiContent>

id

hardware.set(topic: string, value): Promise<void>

topic

value

hardware.getExhibitHardware( ): Promise<Response<Hardware[ ]>>

hardware.sendMqttMessage(topic: string, rawPayload): Promise<void>

topic

rawPayload

content.getRemoteFileList( ): Promise<Response<File[ ]>

content.getLocalFileList( ): File[ ]

content.sync( ): Promise<void>

content.uploadFile(fileStream: ReadStream): Promise<void>

fileStream

content.downloadFile(file: string): Promise<void>

file

event.create(eventName: string, data: any): Promise<void>

eventName

data

logger.info(message: string): Promise<void>

message

logger.debug(message: string): Promise<void>

message

logger.warn(message: string): Promise<void>

message

logger.error(message: string): Promise<void>

message

metrics.endInteraction(data?: object)

metrics.startInteraction(data?: object)

notifications.email(message: string): Promise<void>

message

Websocket Events

Sockets.READY

Sockets.EXHIBIT_ONLINE

Sockets.EXHIBIT_OFFLINE

Sockets.CONTROL_RECEIVED

Sockets.SETTING_RECEIVED

Sockets.SETTING_LIST_RECEIVED

Sockets.SETTING_LIST_ITEM_DELETED

Sockets.OP_MODE_RECEIVED

Sockets.HARDWARE_ONLINE

Sockets.HARDWARE_OFFLINE

Sockets.HARDWARE_PROPERTY_RECEIVED

Sockets.FILE_UPLOADED