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.

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 type.

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:

void motorSpeedWriteCallback(uint16_t length, void* data) {
  if(length == 0) return;
  int32_t new_speed = GUMBAND_INT32(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.")

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.

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

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:

// Single Byte
{
  GumbandProp my_prop = gumbandCreate("My Peripheral", "My Property", gmbnd_byte);
  ...
  uint8_t data_val = 100;
  gumbandPublish(my_prop, data_val); // Publish the value of 100 to "My Property"
}

// Byte Array
{
  #define SEQUENCE_LENGTH = 4
  GumbandProp my_prop = gumbandCreateArray("My Peripheral", "Sequence", gmbnd_byte, SEQUENC_LENGTH);
  ...
  uint8_t data_arr[SEQUENCE_LENGTH] = { 0, 1, 2, 3 };
  gumbandPublish(my_prop, data_arr, SEQUENCE_LENGTH); // Publish 0 to 3 to "Sequence"
}

// Single Int
{
  GumbandProp my_prop = gumbandCreate("My Peripheral", "My Integer", gmbnd_int32);
  ...
  uint32_t data_val = -1000;
  gumbandPublish(my_prop, data_val); // Publish the value of -1000 to "My Integer"
}

// Int Array
{
  #define ARRAY_SIZE 7
  GumbandProp my_prop = gumbandCreate("My Peripheral", "List", gmbnd_int32, ARRAY_SIZE);
  ...
  uint32_t data_arr[ARRAY_SIZE] = { -3, -2, -1, 0, 1, 2, 3 };
  gumbandPublish(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);

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