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.
| Anchor | ||||
|---|---|---|---|---|
|
Gumband provides a CRUD-style REST API for Exhibits to interface with the platform. The API is broken into microservices as described below.
| Anchor | ||||
|---|---|---|---|---|
|
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/
| Anchor | ||||
|---|---|---|---|---|
|
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/
| Anchor | ||||
|---|---|---|---|---|
|
The Hardware Service allows the Exhibit to get information about connected Hardware devices.
API docs: https://dev.gumband.com/api/v1/hardware-mgmt/docs/
| Anchor | ||||
|---|---|---|---|---|
|
The Logging Service allows the Exhibit to send developer-facing logs to Gumband.
API docs: https://dev.gumband.com/api/v1/logging/docs/
| Anchor | ||||
|---|---|---|---|---|
|
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/
| Anchor | ||||
|---|---|---|---|---|
|
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/
| Anchor | ||||
|---|---|---|---|---|
|
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/
| Anchor | ||||
|---|---|---|---|---|
|
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
| Anchor | ||||
|---|---|---|---|---|
|
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.