v1 Gumband API (C/C++)
- Thomas Driscoll
Gumband Properties API
Functions to interact with Gumband properties. Gumband properties are end points which are used to control individual elements of the hardware system either from the debug dashboard or from exhibit software via the SDK.
Also see:
gumbandCreate() & gumbandCreateArray()
Initialize a Gumband property that can be used to send and receive data to and from the online dashboard or an exhibit. Every property must be initialized using gubmandCreate() before calling any gumbandSet() function that applies to that property.
A property does not get created on the remote server until gumbandSubscribe() is called.
Syntax:
GumbandProp gumbandCreate(const char peripheral, const char property, gmbnd_type_t type)
GumbandProp gumbandCreateArray(const char peripheral, const char property, gmbnd_type_t type, uint16_t length)
Example Usage:
GumbandProp motor_start_prop = gumbandCreate("Motor", "Spin", gmbnd_bool);
GumbandProp motor_speed_prop = gumbandCreate("Motor", "Speed", gmbnd_int32);
GumbandProp motor_configreg_prop = gumbandCreateArray("Motor", "Config Register", gmbnd_byte, 10);GUMBAND_TYPE() & GUMBAND_TYPE_ARRAY()
Casts data to a supported Gumband property type. You can see them all in v1 Property Types
Syntax:
GUMBAND_TYPE(data)
GUMBAND_TYPE_ARRAY(data)
Example Usage:
void callback(uint16_t length, void* data) {
// Cast the void pointer to the appropriate type
uint32_t int_data = GUMBAND_INT32(data);
// Same data represented as a byte array
uint8_t byte_data[4] = GUMBAND_BYTE_ARRAY(data);
}gumbandSetReadCallback()
Attach a callback function to a Gumband property. This function will be called when a read request is sent from a remote server (the Exhibit or Cloud server).
Syntax:
int8_t gumbandSetReadCallback(GumbandProp handle, callback_func read_callback);
Example Usage:
void motorSpeedReadCallback(uint16_t length, void* data) {
gumbandPublish(motor_speed_prop, current_motor_speed);
}
...
gumbandSetReadCallback(motor_speed_prop, motorSpeedReadCallback);
gumbandSetWriteCallback()
Attach a callback function to a Gumband property. This function will be called when data is written to this property on the hardware from a remote server (the Exhibit or Cloud server).
Syntax:
int8_t gumbandSetWriteCallback(GumbandProp handle, callback_func write_callback);
Example Usage:
gumbandSetDescription()
Assign a text description to a Gumband property (visible on the Gumband cloud dashboard). Max text length is 128 characters.
Syntax:
int8_t gumbandSetDescription(GumbandProp handle, const char* description);
Example Usage:
gumbandSubscribe()
Complete the hardware registration with all remote servers (both Cloud and Exhibit if connected). The registration sends all of the information for the initialized properties and creates the properties on the remote server.
gumbandSubscribe() must be called before publishing or sending log messages
Syntax:
void gumbandSubscribe(void);
Example Usage:
gumbandPublish()
Syntax:
void gumbandPublish(GumbandProp handle, gmbnd_*_t data, [uint16_t length]);
where gmbnd_*_t is any supported gumband type, and length is an optional field for publishing an array of values (The property must have previously been registered with an appropriate length).
Example Usage:
Gumband Logging API
Functions to send informational messages to the Gumband Cloud dashboard.
gumbandDebug()
v1 Hardware Logging & Events | Debug Logs
Syntax:
void gumbandDebug(const char* text, ...);
Example Usage:
gumbandError()
v1 Hardware Logging & Events | Error Logs
Syntax:
void gumbandError(const char* text, ...);
Parameters: |
|
|---|---|
text | A text string of the Error message, up to 127 characters allowed. |
… | A optional series of formatting variables |
Example Usage:
gumbandNotify()
v1 Hardware Logging & Events | Notify
Send a notification message to the Cloud. Anyone who is subscribed to notification messages for this hardware will immediately receive an email notification with the message.
Syntax:
void gumbandNotify(const char* text, ...);
Parameters: |
|
|---|---|
text | A message associated with the notification, up to 127 characters allowed. |
Example Usage:
gumbandEvent()
v1 Hardware Logging & Events | Event Logs
Send an “Event” to the Cloud. These Events are plotted on a graph and can be viewed in real time on the dashboard. The data can be viewed either as frequency of named Events over time or Event values over time.
Syntax:
void gumbandEvent(const char* text, uint32_t val);
Parameters: |
|
|---|---|
text | A text string name for the Event. Events are grouped by matching name. |
val | An optional value for the event. |
Example Usage:
Gumband Configuration API
Functions to configure the Gumband hardware connections to the the Gumband hardware with Gumband properties. Gumband properties are end points which are used to control individual elements of the hardware system either from the debug dashboard or from exhibit software via the SDK.
gumbandSetUserFirmwareVer()
This sets the version number for the user firmware. This is separate from the Gumband version and is an optional value that is visible from the overview dashboard on the Cloud server and available to the Exhibit. This can be any integer and allows you to keep track of the current firmware on the device. This must be called before gumbandSubscribe().
Syntax:
void gumbandSetUserFirmwareVer(uint8_t fw);
Parameters: |
|
|---|---|
fw | A byte value (0-255) indicating the current firmware version. |
In most cases it is not recommended to use any of the following 4 functions to configure the hardware, these changes should be made via the configuration interface (link)
gumbandSetAuthToken()
Syntax:
void gumbandSetAuthToken(const char* text);
gumbandSetHardwareID()
Syntax:
void gumbandSetHardwareID(const char* text);
gumbandSetCloudServer()
Syntax:
void gumbandSetCloudServer(const char* addr);
gumbandSetExhibitServer()
Set the IP of the exhibit server, the static_flag variable can be set to the version number for the user firmware.
Syntax:
void gumbandSetExhibitServer(const char* addr, uint8_t static_flag);
Parameters: |
|
|---|---|
addr | A text string of the IP address |
static_flag | A “boolean”, set to 1 to indicate this Exhibit address should override the Exhibit address set by the Cloud server. |
gumbandSetOTAFirmware()
Temporarily puts the hardware device into “OTA firmware update mode” for local updates.
Syntax:
void gumbandSetOTAFirmware(void);
Gumband Status API
Functions to monitor the status of the Gumband hardware external connections.
gumbandConnected()
Syntax:
uint8_t gumbandConnected(void);
gumbandCloudConnected()
Syntax:
uint8_t gumbandCloudConnected(void);
gumbandExhibitConnected()
Syntax:
uint8_t gumbandExhibitConnected(void);
gumbandUSBConnected()
Syntax:
uint8_t gumbandUSBConnected(void);
Gumband Hardware API
Functions to control specific aspects of the physical Gumband hardware, support for these functions may vary depending on platform.
gumbandWriteUserData()
Syntax:
void gumbandWriteUserData(uint8_t index, uint8_t data);
gumbandReadUserData()
Syntax:
uint8_t gumbandReadUserData(uint8_t index);
gumbandLedSetBrightness()
Syntax:
void gumbandLedSetBrightness(uint8_t pwm);
gumbandLedOn()
Syntax:
void gumbandLedOn(void);
gumbandLedOff()
Syntax:
void gumbandLedOff(void);
gumbandLedToggle()
Syntax:
void gumbandLedToggle(void);
gumbandLedOut()
Syntax:
void gumbandLedOut(uint8_t state);
gumbandLedPWM()
Syntax:
void gumbandLedPWM(uint8_t pwm);
gumbandButtonPressed()
Syntax:
uint8_t gumbandButtonPressed(void);