Gumband Exhibit Integration

Owned by Dheeraj Reddy (Deactivated)
Last updated: Jul 10, 2022 by Oscar Prom
2 min read

The Gumband SDKs are built on top of three core technologies, including a CRUD-style REST API, WebSockets, and an MQTT messaging broker. Where the Node.js or Python SDKs cannot be used, another option is to interface with each of these technologies directly. If an SDK does not exist for your software stack, please discuss with the Deeplocal team.

The following diagram shows how a local third-party Exhibit would integrate the core Gumband technologies to interface with the platform. Hardware shown as optional.

REST API

Gumband provides a CRUD-style REST API for Exhibits to interface with the platform. The API is broken into microservices as described below.

Authorization Service

The Authorization Service allows you to exchange a Gumband auth token (generated in the Gumband UI) for an Exhibit JSON Web Token (JWT) which will be used to authenticate further requests and create a secure WebSocket connection.

API docs: https://dev.gumband.com/api/v1/auth/docs/

Exhibit Service

The Exhibit Service handles manifest updates and allows for updates to individual Statues and Settings. The MQTT path should be queried by the Exhibit when the application initializes to connect to the service and register for Hardware messages.

API docs: https://dev.gumband.com/api/v1/exhibit-management/docs/

Hardware Service

The Hardware Service allows the Exhibit to get information about connected Hardware devices.

API docs: https://dev.gumband.com/api/v1/hardware-mgmt/docs/

Logging Service

The Logging Service allows the Exhibit to send developer-facing logs to Gumband.

API docs: https://dev.gumband.com/api/v1/logging/docs/

Reporting Service

The Reporting Service service allows the Exhibit to send events that can be aggregated and reported on, such as user selections, timeouts, or API errors.

API docs: https://dev.gumband.com/api/v1/reporting/docs/

Notification Service

The Notification Service allows the Exhibit to email a message to users with Exhibit notifications enabled in the Gumband UI.

API docs: https://dev.gumband.com/api/v1/notifications/docs/

Content Service

The Content Service allows the Exhibit to list and download files from Gumband. Files can also be managed via the Gumband UI.

API docs: https://dev.gumband.com/api/v1/content/docs/

WebSockets Interface

Exhibits receive real time information including altered Settings, triggered Controls, added Hardware and other critical updates from the Gumband platform via WebSockets. This service manages those connections and pushes messages to interested clients. Upon connecting, each WebSocket must immediately perform a handshake where it exchanges an Exhibit JWT to securely connect or the connection is severed.

The following WebSocket messages are received in real time with additional JSON data:

  • EXHIBIT_ONLINE

  • OP_MODE_RECEIVED

  • CONTROL_RECEIVED

  • SETTING_RECEIVED

  • FILE_UPLOADED

  • MQTT_PATH_UPDATED

MQTT Interface (Hardware Only)

Hardware events are brokered over a local MQTT server, which is typically run as a Docker image (eclipse-mosquitto) alongside the custom full-stack Exhibit code. Here is a list of MQTT client libraries that could be used with your existing backend software.

The local MQTT path (IP address and port) are set via the Gumband UI, which is then pushed to Exhibits via WebSockets and connected Hardware via MQTT. Each Hardware device then connects to the local MQTT server to send input/output to the Exhibit over the local network, rather than through the cloud.

If existing hardware is connected directly or no Gumband Hardware is used, no local MQTT server is required for the Exhibit.