C++ Library

Gumband API Functions

gumbandInit()

void gumbandInit(void)

Initialize Gumband

gumbandUpdate()

void gumbandUpdate(void)

Check for messages and perform property updates

gumbandSubscribe()

void gumbandSubscribe(void)

Indicate that the Gumband application registration is ready, or has changed

gumbandDebug()

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

Publish a debug log using printf-style syntax

• Parameters
  • text - Format cstring
  • ... - optional format arguments

gumbandWarning()

void gumbandWarning(const char* text, ...)

Publish a warning log using printf-style syntax

• Parameters
  • text - Format cstring
  • ... - optional format arguments

gumbandError()

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

Publish a error log using printf-style syntax

• Parameters
  • text - Format cstring
  • ... - optional format arguments

gumbandPrint()

void gumbandPrint(const char* text, ...)

print a message using printf-style syntax

• Parameters
  • text - Format cstring
  • ... - optional format arguments

gumbandSetUserFirmwareVer()

void gumbandSetUserFirmwareVer(const char* version)

Set the application version

• Parameters
  • version - Application version as a null-terminated cstring, ex: "v2.0-test"

gumbandSetCredentials()

void gumbandSetCredentials(const char* id, const char* token)

Set the device Gumband ID and Token

• Parameters
  • id - Registered ID in Gumband, as a null-terminated cstring
  • token - Registered authentication token in Gumband, as a null-terminated cstring

gumbandDeviceSetting()

void gumbandDeviceSetting(const char* parameter, const char* value)

Set a Gumband device setting

• Parameters
  • parameter - Device setting parameter/key, as a null-terminated cstring
  • value - Device setting value, as a null-terminated cstring

gumbandConnectionSetting()

void gumbandConnectionSetting(uint8_t connection, const char* parameter, const char* value)

Set a Connection setting

• Parameters
  • connection - Connection number, starting from 0
  • parameter - Connection setting parameter, as a null-terminated cstring
  • value - Connection setting value, as a null-terminated cstring

Gumband Property Class

The Gumband Property type is a templated type and has the following templated definitions. These are for ease of use and correspond directly to the types defined in the MQTT API definition.

Gumband Property	Gumband Array Property	Gumband Type	Base Type
N/A	GumbandText	gmbnd_primitive	char
GumbandBool	GumbandBoolArray	gmbnd_primitive	bool
GumbandTrigger	N/A	gmbnd_primitive	void
GumbandByte	GumbandByteArray	gmbnd_primitive	uint8_t
GumbandInt	GumbandIntArray	gmbnd_primitive	int32_t
GumbandFloat	GumbandFloatArray	gmbnd_primitive	double
GumbandColor	GumbandColorArray	gmbnd_color	gmbnd_color_t

note

The type T is used to refer to the Base Type of the specific templated Gumband Property type being used throughout this document. For an array type it will always be a pointer i.e the base type for a GumbandBoolArray is a bool*.

GumbandProperty() Constructor

GumbandProperty(const char* property_path)

GumbandProperty(const char* property_path, property_options_t property_options)

GumbandProperty(const char* group, const char* property_name)

GumbandProperty(const char* property_path, uin16_t length = 1) (Array Specific)

GumbandProperty(const char* property_path, property_options_t property_options, uint16_t length = 1) (Array Specific)

GumbandProperty(const char* group, const char* property_name, uint16_t length = 1) (Array Specific)

~GumbandProperty() Destructor

~GumbandProperty()

checkNewValue()

bool checkNewValue()

Check if the most recent write changed the value of the property variable.

• Returns bool
  • True or False

clearNewValue()

void clearNewValue()

Set the new value flag to false, this will be set to true again only when a value, that differs from the current value, is written to the internal property variable.

getPropLength()

uint16_t getPropLength()

Get the array length of the property (always 1 if not an array type).

• Returns uint16_t
  • The property length

getPropPath()

void getPropPath(char* path)

Get the property path.

• Parameters
  • path - pointer to copy the property path into.

getValue()

T getValue()

Gets the value of the Gumband property. If this is an array type the return will be the pointer to the internal value.

• Returns T
  • The property value

T getValue(T value, uint16_t len) (Array Specific)

Copies the value of the property into the value parameter.

• Parameters
  • value - pointer to copy the values into.
  • len - Number of T items to copy into value.
• Returns T
  • The pointer to the internal value

publish()

void publish()

Generic publish. Publishes the current property contents.

Note: for GumbandText properties, this will only publish up to the first null character

void publish(T value) (Non-Array Specific)

Set and publish a value

• Parameters
  • value - Value to publish

void publish(const T value, uint16_t len) (Array Specific)

Publish a value and manually specify the number of items in the arrayto set and publish.

This is most useful for something like a gmbnd_text type where the default publish() does not publish the full internal array contents. This will force a publish of the length passed in (up to the max length of the internal storage).

• Parameters
  • value - Value to set and publish
  • uint16_t - number of iterms to set and publish

void publish(const char* text) (GumbandText Specific)

GumbandText specific publish

• Parameters
  • text - Null-terminated string

setChangeCallback()

void setChangeCallback(void (*func)(void) = nullptr)

Assign a function callback to execute on a write request if the data being written differs from the existing data. This function will execute after the value has been written to the local variable

Note: use nullptr to remove the callback

• Parameters
  • func - pointer to a user function with no parameters or return value: void function (void)

void setChangeCallback(void (*func) (GumbandProperty *prop_object) = nullptr)

Assign a function callback to execute on a write request if the data being written differs from the existing data. Callback function takes a GumbandProperty object. When the function is executed this will hold the context for the specific property being written.

Note: use nullptr to remove the callback

• Parameters
  • func - pointer to a user function with the GumbandProperty as a parameter and no return value: void function (GumbandProperty*)

setDescription()

void setDescription(const char* description)

Provide a text description for the property, this text description is visible on the admin UI and is also provided to any connected Application.

• Parameters
  • description - text field containing up to GMBND_STR_FIELD_LEN characters.

setHidden()

void setHidden(bool hidden = true)

Hide the property on the Admin UI, this control does not effect the ability to read or write this property programmatically through Application code.

• Parameters
  • hidden - True/False

setPermissions()

void setPermissions(property_permission_t read_write = PROP_PUBLISH_ONLY)

Set the read/write permissions of a property

• Parameters
  • read_write
    • PROP_READ_ONLY - Property can be read by external connections
    • PROP_WRITE_ONLY - Property can be written by external connections
    • PROP_READ_WRITE - Property can be read and written by external connections
    • PROP_PUBLISH_ONLY - Property can't be read or written by external connections, only published

setPublishInterval()

void setPublishInterval(uint21_t time)

Set the property to publish on a fixed interval. This interval is always measured from the most recent publish regardless of which mechanism triggered that publish. Any change to this value will use the previous interval value until the next publish Default: "0"

• Parameters
  • time - Publish interval in seconds (0 = disables interval publish)

setPublishOnChange()

void setPublishOnChange(bool pub = true)

Set the property to publish anytime a value, that differs from the current value, is written to the internal property variable. Default: "false"

• Parameters
  • pub - True/False

setPublishOnWrite()

void setPublishOnWrite(bool pub = true)

Set the property to publish anytime a value is written to the internal property variable Default: "false"

• Parameters
  • pub - True/False

setReadCallback()

void setReadCallback(void (*func)(void) = nullptr)

Assign a function callback to execute on a read request. This function will execute before the local value is published.

Note: use nullptr to remove the callback

• Parameters
  • func - pointer to a user function with no parameters or return value: void function (void)

void setReadCallback(void (*func) (GumbandProperty *prop_object) = nullptr)

Assign a function callback to execute on a read request. This function will execute before the local value is published. Callback function takes a GumbandProperty object. When the function is executed this will hold the context for the specific property being read

Note: use nullptr to remove the callback

• Parameters
  • func - pointer to a user function with the GumbandProperty as a parameter and no return value: void function (GumbandProperty*)

setValue()

bool setValue(T value) (Non-Array Specific)

Set property value

Note: This will potentially call publish if publish on write or publish on change are set

• Parameters
  • value - The value to set
• Returns bool
  • True if the new value was published

bool setValue(const T value, uint16_t len) (Array Specific)

Array specific setValue

Note: This will potentially call publish if publish on write or publish on change are set

• Parameters
  • value - Pointer to value to set
  • len - Number of items to set
• Returns bool
  • True if the new value was published

bool setValue(const char* text) (GumbandText Specific)

GumbandText specific setValue

Note: This will potentially call publish if publish on write or publish on change are set

• Parameters
  • text - Null-terminated string to set
• Returns bool
  • True if the new value was published

setWriteCallback()

void setChangeCallback(void (*func)(void) = nullptr)

Assign a function callback to execute on a write request. This function will execute after the value has been written to the local variable

• Parameters
  • func - pointer to a user function with no parameters or return value: void function (void)

void setWriteCallback(void (*func) (GumbandProperty *prop_object) = nullptr)

Assign a function callback to execute on a write request. This function will execute after the value has been written to the local variable. Callback function takes a GumbandProperty object. When the function is executed this will hold the context for the specific property being written

• Parameters
  • func - pointer to a user function with the GumbandProperty as a parameter and no return value: void function (GumbandProperty*)

operator=() (Non-Array Only)

void operator=(T value)

Set a property value

• Parameters
  • value - The value to set

operator==() (Non-Array Only)

bool operator==(T value)

Check two gumband properties for equality

• Parameters
  • value - The value to compare
• Returns bool
  • True/False if equal

operator[]() (Array Only)

T& operator[](uint16_t index)

Array index operator

Note: This operator functions as both a get and set, so "prop[0] = 123;" and "int val = prop[0];" both are satisfied by this operator.

• Parameters
  • index - The index of the array
• Returns T&
  • A reference to the value stored at the index provided

Typdefs

gmbnd_color_t

Attributes

• struct
  • red - uint8_t
  • green - uint8_t
  • blue - uint8_t
  • union
    • alpha - uint8_t
    • white - uint8_t
• hex - uint32_t

union type that can be accessed using a 32bit hex value or individually with alpha, white, red, green, and blue fields.

// Idividual values can be set
gmbnd_color_t translucent_purple = {.alpha = 0x80, .red=0xFF, .green = 0x00, .blue = 0xFF};

// You can also just assign a RGB hex value which will be stored just like settig the .hex field
gmbnd_color_t white =  0xFFFFFF;

property_options_t

Attributes

• description
  • char[] - Default: ""
• permissions
  • property_permission_t - Default: PROP_READ_WRITE
• hidden
  • bool - Default: false
• readCallback
  • void(*)(void) - Default: nullptr
• writeCallback
  • void(*)(void) - Default: nullptr
• changeCallback
  • void(*)(void) - Default: nullptr
• readCallbackWithArgs
  • void(*)(GumbandProperty) - Default: nullptr
• writeCallbackWithArgs
  • void(*)(GumbandProperty) - Default: nullptr
• changeCallbackWithArgs
  • void(*)(GumbandProperty) - Default: nullptr
• publishInterval
  • uint16_t - Default: 0
• publishOnWrite
  • bool - Default: false
• publishOnChange
  • bool - Default: false

Enums

property_permission_t

• PROP_PUBLISH_ONLY - Property can't be read or written by external connections, only published
• PROP_READ_ONLY - Property can be read by external connections
• PROP_WRITE_ONLY - Property can be written by external connections
• PROP_READ_WRITE - Property can be read and written by external connections

Definitions

GMBND_STR_FIELD_LEN

The maximum string field length that the configured Gumband platform supports.