...
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
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.
| Code Block |
|---|
gb.setManifest('./path/to/manifest.json'); |
getOperatingMode( ): Promise<boolean>
Get the current operating mode for the exhibit from Gumband.
| Code Block |
|---|
let operatingMode = await gb.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.
| Code Block |
|---|
await gb.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.
| Code Block |
|---|
let statusValue = await gb.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.
| Code Block |
|---|
await gb.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.
| Code Block |
|---|
let motorRPM = await gb.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.
| Code Block |
|---|
await 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.
| Code Block |
|---|
console.log(await gb.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.
| Code Block |
|---|
console.log(await gb.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.
| Code Block |
|---|
console.log(gb.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.
| Code Block |
|---|
console.log(await gb.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.
| Code Block |
|---|
//gmbnd_bool property type
await gb.hardware.set("1/My Peripheral/My Property", 1); |
hardware.getExhibitHardware( ): Promise<Response<Hardware[ ]>>
Get all hardware associated with this exhibit in the Gumband UI.
| Code Block |
|---|
console.log(await gb.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.
| Code Block |
|---|
let remoteFiles = await gb.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.
| Code Block |
|---|
let localFiles = 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.
| Code Block |
|---|
await 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").
| Code Block |
|---|
const fileStream = fs.createReadStream("path/to/file");
await gb.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.
| Code Block |
|---|
await gb.content.downloadFile("gumband-cassette.png"); |
event.create(eventName: string, data: any): Promise<void>
Creates a reporting event of the given event name, and includes the data object given as an object on the event.
eventName
The name of the reporting event.
data
Any data object to be associated with the event.
| Code Block |
|---|
await gb.event.create("Red Button Pressed", { holdTime: 2.52 }); |
logger.info(message: string): Promise<void>
Logs a message to Gumband as an “info” level log. Logs can be viewed under the Exhibit/Logs tab in the Gumband UI.
message
The message for the log.
| Code Block |
|---|
await gb.logger.info("This is an info log message"); |
logger.debug(message: string): Promise<void>
Logs a message to Gumband as an “debug” level log. Logs can be viewed under the Exhibit/Logs tab in the Gumband UI.
message
The message for the log.
| Code Block |
|---|
await gb.logger.debug("This is a debug log message"); |
logger.warn(message: string): Promise<void>
Logs a message to Gumband as an “warn” level log. Logs can be viewed under the Exhibit/Logs tab in the Gumband UI.
message
The message for the log.
| Code Block |
|---|
await gb.logger.warn("This is a warning log message"); |
logger.error(message: string): Promise<void>
Logs a message to Gumband as an “error” level log. Logs can be viewed under the Exhibit/Logs tab in the Gumband UI.
message
The message for the log.
| Code Block |
|---|
await gb.logger.error("This is an error log message"); |
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.
| Code Block |
|---|
await gb.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:
| Code Block |
|---|
gb.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.
Sockets.EXHIBIT_ONLINE
Emitted when the SDK successfully authenticates with Gumband and comes online.
Sockets.EXHIBIT_OFFLINE
Emitted when the SDK losses its websocket connection with Gumband.
Sockets.CONTROL_RECEIVED
Emitted when a control is triggered, usually through the Exhibit/Controls tab in the Gumband UI.
Sockets.SETTING_RECEIVED
Emitted when a setting is changed, usually through the Exhibit/Settings tab in the Gumband UI.
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.
Sockets.SETTING_LIST_ITEM_DELETED
Emitted when a setting list item is deleted. The payload is the setting list item that was deleted.
Sockets.OP_MODE_RECEIVED
Emitted when the Operation Mode is changed, usually through the Exhibit dashboard in the Gumband UI.
Sockets.HARDWARE_ONLINE
Emitted when a Gumband Hardware associated with the exhibit connects to the exhibit.
Sockets.HARDWARE_OFFLINE
Emitted when a Gumband Hardware associated with the exhibit disconnects from the exhibit.
Sockets.HARDWARE_PROPERTY_RECEIVED
Emitted when a property is changed in a Gumband Hardware that is connected to the exhibit.
Sockets.FILE_UPLOADED
Emitted when a new file has been uploaded to Gumband, usually through the Exhibit/Files tab of the Gumband UI.
Sockets.FILE_DELETED
Emitted when a file is deleted from Gumband, usually through the Exhibit/Files tab of the Gumband UI.