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()

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.

Syntax:

GumbandProp gumbandCreate(const char peripheral, const char property, gmbnd_type_t type)

Example Usage:

GumbandProp motor_start_prop = gumbandCreate("Motor", "Spin", gmbnd_bool);
GumbandProp motor_speed_prop = gumbandCreate("Motor", "Speed", gmbnd_int32);

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) {
  gumbandPublishInt(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:

void motorSpeedWriteCallback(uint16_t length, void* data) {
  if(length == 0) return;
  int32_t new_speed = *((gmbnd_int32_t*)data);
}
...
gumbandSetWriteCallback(motor_speed_prop, motorSpeedWriteCallback);

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:

gumbandSetDescription(motor_speed_prop, "This property controls the speed of the motor.")

gumbandSetHidden() UNFINISHED

Set the property as hidden to prevent it from being displayed on the Gumband Cloud dashboard. This has no affect on the Exhibit server.

Syntax:

int8_t gumbandSetHidden(GumbandProp handle);

Example Usage:

gumbandSetHidden(motor_speed_prop); // Hide the motor speed property from the dashboard

gumbandClearHidden() UNFINISHED

Set the property as visible to allow it to be shown on the Gumband Cloud dashboard.

Syntax:

int8_t gumbandClearHidden(GumbandProp handle)

Example Usage:

gumbandClearHidden(motor_speed_prop); // Show the motor speed prop on the dashboard again

gumbandSubscribe()

Complete the hardware registration with all remote servers (both Cloud and Exhibit if connected). The registration sends all of the information for the initialised properties and creates the properties on the remote server.

Syntax:

void gumbandSubscribe(void);

Example Usage:

// Create all peripherals and their properties
GumbandProp first_prop = gumbandCreate("My Peripheral", "First", gmbnd_byte);
GumbandProp second_prop = gumbandCreate("My Peripheral", "Second", gmbnd_byte);
...
// Register the peripherals and properties with the broker
gumbandSubscribe();

gumbandPublish() UNFINISHED

TBD on the implementation of this, but the intent is to be a type agnostic way to publish.

Syntax:

void gumbandPublish();

Example Usage:

// TBD

gumbandPublishByte()

Publish a single byte to a property of type gmbnd_byte.

Syntax:

void gumbandPublishByte(GumbandProp handle, uint8_t data);

Example Usage:

GumbandProp my_prop = gumbandCreate("My Peripheral", "My Property", gmbnd_byte);
...
uint8_t data_val = 100;
gumbandPublishByte(my_prop, data_val); // Publish the value of 100 to "My Property"

gumbandPublishByteArray() UNFINISHED

Publish an array of bytes to a property of type gmbnd_byte and length >1.

Syntax:

gumbandPublishByteArray(GumbandProp handle, uint8_t* data, uint8_t len);

Example Usage:

GumbandProp my_prop = gumbandCreate("My Peripheral", "Sequence", gmbnd_byte);
...
uint8_t data_arr[] = { 0, 1, 2, 3 };
gumbandPublishByteArray(my_prop, data_arr, sizeof(data_arr)); // Publish 0 to 3 to "Sequence"

gumbandPublishInt()

Publish a single uint32 to a property of type gmbnd_int32.

Syntax:

void gumbandPublishInt(GumbandProp handle, uint32_t data);

Example Usage:

GumbandProp my_prop = gumbandCreate("My Peripheral", "My Integer", gmbnd_byte);
...
int32_t data_val = -1000;
gumbandPublishInt(my_prop, data_val); // Publish the value of -1000 to "My Integer"

gumbandPublishIntArray() UNFINISHED

Publish an array of uint32 to a property of type gmbnd_int32 and length > 1.

Syntax:

void gumbandPublishIntArray(GumbandProp handle, uint32_t* data, uint8_t len);

Example Usage:

GumbandProp my_prop = gumbandCreate("My Peripheral", "List", gmbnd_int32);
...
#define ARRAY_SIZE 7
uint8_t data_arr[ARRAY_SIZE] = { -3, -2, -1, 0, 1, 2, 3 };
gumbandPublishByteArray(my_prop, data_arr, ARRAY_SIZE); //Publish -3 to 3 to "List"

Gumband Logging API

Functions to send informational messages to the Gumband Cloud dashboard. '

gumbandDebug()

https://deeplocal.atlassian.net/wiki/spaces/GS/pages/52822092#Debug-Logs

Debug Logs are limited to 20 messages every 2 seconds and are currently not sent to exhibits. If this rate is exceeded there is a 5 second hold-off period where no messages will be sent.

Syntax:

void gumbandDebug(const char* text, ...);

Example Usage:

gumbandDebug("Hello Gumband! I am a debug message.");

uint8_t test_data = 100;
gumbandDebug("Sending data value of %d...", test_data);

gumbandError()

https://deeplocal.atlassian.net/wiki/spaces/GS/pages/52822092#Error-Logs

Syntax:

void gumbandError(const char* text, ...);

Example Usage:

gumbandError("Hello Gumband! I am an error log message.");

const char* error_string = "Example Error";
gumbandError("Warning! Encountered an error with message: %s", error_string);

gumbandNotify()

https://deeplocal.atlassian.net/wiki/spaces/GS/pages/52822092#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, ...);

Example Usage:

gumbandNotify("Hello Gumband! I am a notification in your e-mail that something happened.");

gumbandEvent()

https://deeplocal.atlassian.net/wiki/spaces/GS/pages/52822092#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);

Example Usage:

gumbandEvent("My Event");

gumbandEvent("My Event", 100);

gumbandLog() UNDOCUMENTED

Syntax:

void gumbandDebug(const char* text, ...);

Example Usage:

// TBD

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);

#define FW_VERSION 53
gumbandSetUserFirmwareVer(FW_VERSION);

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. 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 gumbandSetExhibitServer(const char* addr, uint8_t static_flag);

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);