C Mates Controller Library

Introduction

This is a C Library developed to be used with Mates Studio's Commander and Architect Environments. This library is aimed to be simple enough to learn for beginners and feature-rich for experienced developers.

Setup

This section serves to give brief discussion about the setup requirements before the host controller can communicate with BBM devices.

Requirements

The following functions provide an interface to set the requirements of the library which includes UART control, timer and GPIO control.

Hardware Reset

Function: mates_attachHwResetFnc(resetFnc)

This should be used during setup to attach a function that will reset the display through the hardware reset pin.

The reset function should be in the format: void resetFnc(void)

Parameters	Type	Description
resetFnc	void (* resetFnc)(void)	A function triggering a short digital pulse to reset the display

Returns: void

Set 'resetFnc' as Hardware Reset Function

// 'resetFnc' will be used to perform a hardware reset
// during the execution of mates_begin() and mates_reset() functions
mates_attachHwResetFnc(resetFnc);

System Timer

Function: mates_attachMillisFnc(millisFnc)

This should be used during setup to attach a function that returns the system time in milliseconds.

The millis function should be in the format: uint32_t millisFnc(void)

Parameters	Type	Description
millisFnc	uint32_t (* millisFnc)(void)	A function that returns the system time in milliseconds

Returns: void

Set 'millisFnc' as System Timer Function

// 'millisFnc' will be used to wait for timeouts
mates_attachMillisFnc(millisFnc);

RX Byte Count

Function: mates_attachRxCountFnc(rxCountFnc)

This should be used during setup to attach a function that returns the number of bytes available to read from the Serial UART buffer

The RX count function should be in the format: uint8_t rxCountFnc(void)

Parameters	Type	Description
rxCountFnc	uint8_t (* rxCountFnc)(void)	A function that returns the number of bytes available to read

Returns: void

Set 'rxCountFnc' as RX Byte Count Function

// 'rxCountFnc' will be used to check the no. of bytes available to read
mates_attachRxCountFnc(rxCountFnc);

Read Byte

Function: mates_attachReadFnc(readFnc)

This should be used during setup to attach a function that reads 1 byte from the Serial UART buffer and returns it.

The read function should be in the format: uint8_t readFnc(void)

Parameters	Type	Description
readFnc	uint8_t (* readFnc)(void)	A function that reads a byte from Serial UART buffer

Returns: void

Set 'readFnc' as Read Byte Function

// 'readFnc' will be used to read data received from the display and stored in RX buffer
mates_attachReadFnc(readFnc);

Write Byte

Function: mates_attachWriteFnc(writeFnc)

This should be used during setup to attach a function that sends 1 byte to the display.

The write function should be in the format: void writeFnc(uint8_t)

Parameters	Type	Description
writeFnc	void (* writeFnc)(uint8_t)	A function that sends 1 byte through the Serial UART connection

Returns: void

Set 'writeFnc' as Write Byte Function

// 'writeFnc' will be used to write each byte of data for each Mates Command
mates_attachWriteFnc(writeFnc);

Timeouts

The following functions can be used to adjust the timeouts allowed by the library before raising errors.

Boot Timeout

Function: mates_setBootTimeout(timeout)

This function can be used to adjust the boot timeout period that the library waits for during boot or reset. The default boot timeout is 5 seconds.

It is usually unncessary to use this function unless the display needs more time for setup and the ready signal (0x06) is not being received on time.

Parameters	Type	Description
timeout	uint16_t	The new timeout period in milliseconds to wait for when resetting the display

Returns: void

Set the boot timeout period to 6 seconds

mates_setBootTimeout(6000);

Command Timeout

Function: mates_setCmdTimeout(timeout)

This function can be used to adjust the command timeout period that the library waits for when waiting for an ACK/NACK response. The default command timeout is 500 milliseconds.

It is usually unncessary to use this function unless the display needs more time to accomplised the command.

Parameters	Type	Description
timeout	uint16_t	The new timeout period in milliseconds to wait for when waiting for ACK/NACK

Returns: void

Set the command timeout period to 600 milliseconds

mates_setCmdTimeout(600);

Response Timeout

Function: mates_setRspTimeout(timeout)

This function can be used to adjust the command timeout period that the library waits for when waiting for an ACK/NACK response and a return value. The default response timeout is 500 milliseconds.

It is usually unncessary to use this function unless the display needs more time to accomplised the command.

Parameters	Type	Description
timeout	uint16_t	The new timeout period in milliseconds to wait for when waiting for response

Returns: void

Set the response timeout period to 1 second

mates_setRspTimeout(1000);

Initialization

Function: mates_begin()

This function must be used once to check required functions, reset the display and wait until the display is ready.

Returns: success or failure (boolean)

Complete Setup

// Attach Required Functions
mates_attachHwResetFnc(resetFnc);
mates_attachMillisFnc(millisFnc);
mates_attachWriteFnc(writeFnc);
mates_attachReadFnc(readFnc);
mates_attachRxCountFnc(rxCountFnc);

// Optionally, adjust timeouts
// mates_setBootTimeout(6000);
// mates_setCmdTimeout(600);
// mates_setRspTimeout(1000);

// Checks the required functions, resets the display and wait until the display is ready
if (!mates_begin()) {
    // if this returns false, it could be either:
    //   - a required function hasn't been attached to the library
    //   - the display didn't respond with a ready signal (0x06) on time
    while (1); // this only serves as an example, blocking completely is not recommended
}
// otherwise, the begin function will exit when the display is ready

Note

Ensure that all required hardware peripherals and software setup (Reset I/O, Serial UART and Timers) are attached before using this function
Ensure that the Serial UART of the host is set to the same baudrate that matches the setting of the Mates Studio Commander/Architect project before this function is used

General Functions

This section includes general use functions that may be use to perform reset, page navigation and brightness control.

Hardware Reset

Function: mates_reset()

This function can be used to reset the display by sending a reset pulse from the reset pin by utilizing the reset function attached using mates_attachHwResetFnc.

The function finishes as soon as the display sends the ready signal or the wait period passes. The default wait period is 5 seconds.

Returns: success or failure (boolean)

Perform a Hardware Reset

// Resets the display and wait until the display is ready
if (!mates_reset()) {
    // if this returns false:
    //  - the display didn't respond with a ready signal (0x06) on time
    while (1); // this only serves as an example, blocking completely is not recommended
}
// otherwise, the reset function will exit when the display is ready

Software Reset

Function: mates_softReset()

This function can be used to reset the display by sending a Serial UART reset command.

The function finishes as soon as the display sends the ready signal or the wait period passes. The default wait period is 5 seconds.

Returns: success or failure (boolean)

Perform a Software Reset

// Resets the display and wait until the display is ready
if (!mates_softReset()) {
    // if this returns false:
    //  - the display didn't respond with a ready signal (0x06) on time
    while (1); // this only serves as an example, blocking completely is not recommended
}
// otherwise, the reset function will exit when the display is ready

Set Backlight Level

Function: mates_setBacklight(value)

This function can be used to set the backlight level to the value specified.

Parameters	Type	Description
value	uint8_t	The target backlight level

Returns: success or failure (boolean)

Set backlight to level 7

mates_setBacklight(7);

Set Page Number

Function: mates_setPage(page)

This function can be used to navigate to the specified page.

Parameters	Type	Description
page	uint16_t	The target page index

Returns: success or failure (boolean)

Navigate to Page1

mates_setPage(1);

Get Current Page

Function: mates_getPage()

This function can be used to query the current active page.

Returns: Active page index (uint16_t)

Query Active Page

uint16_t activePage = mates_getPage();

Function: mates_setWidgetValue(type, index, value)

This function can be used to set the 16-bit integer value of the specified widget

Parameters	Type	Description
type	MatesWidget	The type of the target widget
index	int8_t	The index of the target widget
value	int16_t	The new value for the widget

Returns: success or failure (boolean)

Set Value of MediaGaugeB0 to 50

mates_setWidgetValue(MATES_MEDIA_GAUGE_B, 0, 50);

Note

All applicable widget types are listed in here.

Function: mates_getWidgetValue(type, index)

This function can be used to query the value of the widget specified by type and index.

Parameters	Type	Description
type	MatesWidget	The type of the target widget
index	int8_t	The index of the target widget

Returns: Value of the specified widget (int16_t)

Query the Current Value of MediaLed4

int16_t widgetVal = mates_getWidgetValue(MATES_MEDIA_LED, 4);

Note

This function is not applicable to Int32 and Float LedDigits

Function: mates_setWidgetParam(type, index, param, value)

This function can be used to set the parameter (param) of the target widget, determined by type and index, to the specified value.

Parameters	Type	Description
type	MatesWidget	The type of the target widget
index	int8_t	The index of the target widget
param	int16_t	The target widget parameter
value	int32_t	The new value for the widget parameter

Returns: success or failure (boolean)

Set GaugeA3's Background Color to BLACK

mates_setWidgetParam(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR, BLACK);

Note

This is only applicable for Commander projects with Runtime Mode set to Editable

Function: mates_getWidgetParam(type, index, param)

This function can be used to query the parameter (param) of the target widget, determined by type and index.

Parameters	Type	Description
type	MatesWidget	The type of the target widget
index	int8_t	The index of the target widget
param	int16_t	The target widget parameter

Returns: The current _param_ value of the widget (int16_t)

Query the Background Color of GaugeA3

int16_t paramVal = mates_getWidgetParam(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR);

LedDigits Functions

The following functions may only be used for LedDigits widgets

Set 16-bit Integer Value

Function: mates_setLedDigitsShortValue(index, value)

This function can be used to set the 16-bit integer value of the LedDigits specified by index

Parameters	Type	Description
index	int8_t	The index of the target LedDigits
value	int16_t	The new value for the LedDigits

Returns: success or failure (boolean)

Set Value of LedDigits2 to 50

mates_setLedDigitsShortValue(2, 50);

Note

This function is only applicable for Int16 LedDigits

Set 32-bit Integer Value

Function: mates_setLedDigitsLongValue(index, value)

This function can be used to set the 32-bit integer value of the LedDigits specified by index

Parameters	Type	Description
index	int8_t	The index of the target LedDigits
value	int32_t	The new value for the LedDigits

Returns: success or failure (boolean)

Set value of LedDigits0 to 602214076

mates_setLedDigitsLongValue(0, 602214076);

Note

This function is only applicable for Int32 LedDigits

Set 32-bit Float Value

Function: mates_setLedDigitsFloatValue(index, value)

This function can be used to set the floating point value of the LedDigits specified by index

Parameters	Type	Description
index	int8_t	The index of the target LedDigits
value	float	The new value for the LedDigits

Returns: success or failure (boolean)

Set Value of LedDigits1 to 3.1416

mates_setLedDigitsFloatValue(1, 3.1416);

Note

This function is only applicable for Float LedDigits

Spectrum Functions

The following functions may only be used for LedSpectrum and MediaSpectrum widgets.

Set Spectrum Value

Function: mates_setSpectrumValue(type, index, gaugeIndex, value)

This function can be used to set the value of a specified gaugeIndex of the Spectrum widget determined by type and index.

Parameters	Type	Description
type	MatesWidget	The type of the target Spectrum widget
index	int8_t	The index of the target Spectrum widget
gaugeIndex	int8_t	The gauge index of the target Spectrum widget
value	int16_t	The new value for the column/row of the widget

Returns: success or failure (boolean)

Set LedSpectrum4's 4th Column/Row (index 3) to 32

mates_setSpectrumValue(MATES_LED_SPECTRUM, 4, 3, 32);

Set LedSpectrum Value

Function: mates_setLedSpectrumValue(index, gaugeIndex, value)

This function can be used to set the value of a specified gaugeIndex of the Led Spectrum widget determined by index.

Parameters	Type	Description
index	int8_t	The index of the target Led Spectrum widget
gaugeIndex	int8_t	The gauge index of the target Led Spectrum widget
value	int16_t	The new value for the column/row of the widget

Returns: success or failure (boolean)

Set LedSpectrum5's 3rd Column/Row (index 2) to 64

mates_setLedSpectrumValue(5, 2, 64);

Set MediaSpectrum Value

Function: mates_setMediaSpectrumValue(type, index, gaugeIndex, value)

This function can be used to set the value of a specified gaugeIndex of the Media Spectrum widget determined by index.

Parameters	Type	Description
index	int8_t	The index of the target Led Spectrum widget
gaugeIndex	int8_t	The gauge index of the target Led Spectrum widget
value	int16_t	The new value for the column/row of the widget

Returns: success or failure (boolean)

Set MediaSpectrum4's 4th Column/Row (index 3) to 48

mates_setMediaSpectrumValue(4, 3, 48);

Set Buffer Size

Function: mates_setBufferSize(size)

This function can be used to adjust the max string buffer size to be used when composing a string for a TextArea or a PrintArea. The string composition is done by mates_updateTextArea, mates_appendArrayToPrintArea and mates_appendStringToPrintArea

Parameters	Type	Description
size	uint16_t	The new buffer size

Returns: void

Increase Buffer Size to a Maximum of 100 Characters

mates_setBufferSize(100);

Clear PrintArea

Function: mates_clearPrintArea(index)

This function can be used to clear the PrintArea specified by_index_.

Parameters	Type	Description
index	uint16_t	The index of the target PrintArea widget

Returns: success or failure (boolean)

Example

mates_clearPrintArea(5); // Clear PrintArea5

Clear TextArea

Function: mates_clearTextArea(index)

This function can be used to clear the TextArea specified by_index_.

Parameters	Type	Description
index	uint16_t	The index of the target TextArea widget

Returns: success or failure (boolean)

Example

mates_clearTextArea(6); // Clear TextArea6

Set PrintArea Color

RGB565

Function: mates_setPrintAreaColor565(index, color)

This function can be used to set the print color (rgb565) used by the PrintArea specified by_index_.

Parameters	Type	Description
index	uint16_t	The index of the target PrintArea widget
rgb565	int16_t	The color as a 16-bit RGB565 value

Returns: success or failure (boolean)

Example

mates_setPrintAreaColor565(4, 0xF800); // Set print color of PrintArea4 to RED (0xF800)

RGB888

Function: mates_setPrintAreaColorRGB(index, r, g, b)

This function can be used to set the print color used by the PrintArea specified by_index_. The color is determined by r, g and b.

Parameters	Type	Description
index	uint16_t	The index of the target PrintArea widget
r	uint8_t	The red component of the new color value
g	uint8_t	The green component of the new color value
b	uint8_t	The blue component of the new color value

Returns: success or failure (boolean)

Example

mates_setPrintAreaColor(7, 0, 255, 0); // Set print color of PrintArea7 to GREEN

Append to PrintArea

Array

Function: mates_appendArrayToPrintArea(index, buffer, len)

This function can be used to append a number of bytes (len) from the data in buffer to the PrintArea specified by_index_ .

Parameters	Type	Description
index	uint16_t	The index of the target Print Area widget
buffer	const int8_t *	The source of data to be appended
len	uint16_t	The number of bytes to be sent

Returns: success or failure (boolean)

Append Data to PrintArea7

int8_t data = {0xF8, 0x7F, 0x1F};
mates_appendArrayToPrintArea(7, data, 3);

String

Function: mates_appendStringToPrintArea(index, str)

This function can be used to append contents to the PrintArea specified by_index_ with the text formed by format and the additional arguments.

Parameters	Type	Description
index	uint16_t	The index of the target Print Area widget
str	const char *	The text to be written to the PrintArea

Returns: success or failure (boolean)

Append \"Mates\" to PrintArea8

mates_appendStringToPrintArea(8, "Mates");

Update TextArea

Function: mates_updateTextArea(index, str)

This function can be used to update the contents of the TextArea specified by_index_ with the text formed by format and the additional arguments.

Parameters	Type	Description
index	uint16_t	The index of the target TextArea widget
str	const char *	The text to be written to the Text Area

Returns: success or failure (boolean)

Example

mates_updateTextArea(2, "Mates"); // Update TextArea2 to "Mates"

Update DotMatrix

Function: mates_updateDotMatrix(index, str)

This function can be used to append contents to the PrintArea specified by_index_ with the text formed by format and the additional arguments.

Parameters	Type	Description
index	uint16_t	The index of the target Print Area widget
str	const char *	The text to be written to the PrintArea

Returns: success or failure (boolean)

Update DotMatrix0 to \"Mates\"

mates_updateDotMatrix(8, "Mates");

Scope Functions

This function include functions that can be used to control Scope widgets.

Append to Scope

Function: mates_appendToScope(index, buffer, len)

This function can be used to append a number of 16-bit values (len) from the data in buffer to the Scope widget specified by_index_ .

Parameters	Type	Description
index	uint16_t	The index of the target Scope widget
buffer	const int16_t *	The source of data to be appended
len	uint16_t	The number of values to be sent

Returns: success or failure (boolean)

Append Data to PrintArea7

int16_t data = {0xF8, 0x7F, 0x1F};
mates_appendToScope(7, data, 3);

Support Functions

The following functions can be used to check version information and errors occurring during runtime.

Mates Studio Version

Function: mates_getCompatibility()

This function can be used to query the version number of Mates Studio compatible with the version of the library.

Returns: Compatibility Version Information (char *)

Get Mates Studio Version as String

char * matesVersion = mates_getCompatibility();

Library Version

Function: mates_getVersion()

This function can be used to query the version number of the library.

Returns: Version Information (char *)

Get Library Version as String

char * libVersion = mates_getVersion();

Get Error

Function: mates_getError()

This function can be used to investigate errors that occurred while controlling the display module. Detailed information of the possible errors is discussed in here.

Returns: Latest Error (Mates Error)

Check if No Error Occurred

int error = mates_getError();
if (error == MATES_ERROR_NONE) {
    // Last command was successful
}

C Mates Controller Library

Introduction

Setup

Requirements

Hardware Reset

System Timer

RX Byte Count

Read Byte

Write Byte

Timeouts

Boot Timeout

Command Timeout

Response Timeout

Initialization

General Functions

Hardware Reset

Software Reset

Set Backlight Level

Set Page Number

Get Current Page

Common Widget Functions

Set Widget Value

Get Widget Value

Set Widget Parameter

Get Widget Parameter

LedDigits Functions

Set 16-bit Integer Value

Set 32-bit Integer Value

Set 32-bit Float Value

Spectrum Functions

Set Spectrum Value

Set LedSpectrum Value

Set MediaSpectrum Value

String Widget Functions

Set Buffer Size

Clear PrintArea

Clear TextArea

Set PrintArea Color

RGB565

RGB888

Append to PrintArea

Array

String

Update TextArea

Update DotMatrix

Scope Functions

Append to Scope

Support Functions

Mates Studio Version

Library Version

Get Error