...

...

...

...

...

...

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

Creates Initialize a Gumband property endpointthat 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 property type. You can see them all in 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 to . This function will be called when a read command request is received sent from a remote server (the exhibit or cloud serversExhibit 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 to . This function will be called when a write command is received from the exhibit or cloud serversdata 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 is128 is 128 characters.

Syntax:

int8_t gumbandSetDescription(GumbandProp handle, const char* description);

Example Usage:

...

gumbandSetHidden()

Set the property as hidden to prevent it from being displayed on the Gumband cloud dashboard.

Syntax:

int8_t gumbandSetHidden(GumbandProp handle);

Example Usage:

gumbandClearHidden()

Set the property as visible (note this change will only be written if we also resubscribe to the server using gumbandSubscribe).

Syntax:

int8_t gumbandClearHidden(GumbandProp handle)

Example Usage:

gumbandPublish()

Syntax:

void gumbandPublish();

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 gumbandPublishBytegumbandPublish(GumbandProp handle, uint8gmbnd_*_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:

gumbandPublishByteArray()

Syntax:

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

Example Usage:

gumbandPublishInt()

Syntax:

void gumbandPublishInt(GumbandProp handle, uint32_t data);

Example Usage:

gumbandPublishIntArray()

Syntax:

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

Example Usage:

gumbandDebug()

// 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

Insert excerpt
Hardware Logging & Events Hardware Logging & Events name Log limit nopanel true

Syntax:

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

Example Usage:

...

gumbandLog()

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 gumbandDebuggumbandError(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 gumbandErrorgumbandNotify(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")

...

Syntax:

void gumbandEvent(const char* text, uint32_t val);

Example Usage:

;

gumbandEvent("My Event", 100);

...

Gumband Configuration API

...

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.

Syntax:

void gumbandSetExhibitServer(const char* addr, uint8_t static_flag);

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