...

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.

...

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. 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) {
  gumbandPublishIntgumbandPublish(motor_speed_prop, current_motor_speed);
}
...
gumbandSetReadCallback(motor_speed_prop, motorSpeedReadCallback);

...

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*)GUMBAND_INT32(data);
}
...
gumbandSetWriteCallback(motor_speed_prop, motorSpeedWriteCallback);

...

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

Status
colour Yellow title 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()

Status
colour Yellow title UNFINISHED

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

Syntax:

...

)

...

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

Example Usage:

// TBD

gumbandPublishByte()

Publish a single byte to a property of type gmbnd_byte.

Syntax:

void gumbandPublishByte(GumbandProp handle, uint8_t data);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;
  gumbandPublishBytegumbandPublish(my_prop, data_val); // Publish the value of 100 to "My Property"

gumbandPublishByteArray()

Status
colour Yellow title 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
}

// Byte Array
{
  #define SEQUENCE_LENGTH = 4
  GumbandProp my_prop = gumbandCreategumbandCreateArray("My Peripheral", "Sequence", gmbnd_byte, SEQUENC_LENGTH);
  ...
  uint8_t data_arr[SEQUENCE_LENGTH] = { 0, 1, 2, 3 };
gumbandPublishByteArray  gumbandPublish(my_prop, data_arr, sizeof(data_arr)SEQUENCE_LENGTH); // 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:

}

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

gumbandPublishIntArray()

Status
colour Yellow title 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:

}

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

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

...

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

...

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

...

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

Status
colour Red title Undocumented

Syntax:

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

Example Usage:

// TBD

...

Gumband Configuration API

...

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

...

gumbandSetAuthToken()

Syntax:

void gumbandSetAuthToken(const char* text);

gumbandSetHardwareID()

Syntax:

void gumbandSetHardwareID(const char* text);

gumbandSetCloudServer()

Syntax:

void gumbandSetCloudServer(const char* addr);

...

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

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

...

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