Package: bbm-mates-controller
BBM Python Mates Controller LibraryThis is a Python Library developed to be used with Mates Studio Commander or Architect Environment and BBM modules connected using BBM programmer or similar USB-to UART modules. This library is aimed to be simple enough to learn for beginners and feature-rich for experienced developers.It is used for communicating with BBM Devices, over serial port and contains various methods for sending and retrieving data relating to display widgets, their states and parameters and the health of the controller. Helpful classes and datatypes can be found inmates.constantsmodule.Hardware and Software SupportThis library is developed for Python3 and designed to be used with any operating system as long as it is supported by thepyseriallibrary.InstallationThis library can be installed from the Python Packaging Index by running the command:pip3 install bbm-mates-controllerLibrary DiscussionConstructorMatesController(portName, debugStream, debugFileLength)Constructs all the necessary attributes associated with an instance
of a Mates Controller Object.Args:portName: strthe name of the port to be opened. Example: /dev/ttyUSB0 for linux.debugStream: io.TextIOWrapperText file object to write debugging code to, supply of none will result in no debugging. Examples include sys.stdout, open('log.txt', 'r+')debugFileLength: intDetermines the extent of debug history kept with respect to lines in a file, given a circular log. O indicates full history kept with no circular logging. Users must be careful here to manage storage space effectively.Example No. 1:# Creates a new instance named 'mates' which utilizes: 
#  - COM10 as the serial port
#  - with no reset function and no output stream
MatesController mates = MatesController("COM10")Example No. 2:# Creates a new instance named 'mates' which utilizes: 
#  - COM10 as the serial port
#  - output_file as debug file stream
#  - debugFileLength of zero indicating no circular logging
MatesController mates = MatesController("COM10", debugStream=output_file, debugFileLength=0)Note:If a debug file is specified, it should be opened using either 'w+' or 'r+' before running the begin() function of this library.Methodsbegin(baudrate)Begins the serial connection if portname not supplied in constructor.Args:baudrate: intthe baudrate of the serial port (default: 9600)Returns:voidExample No. 1:# Initializes display serial port 9600 baud
# and resets the display if a reset function is provided
mates.begin(9600)close()Closes opened serial port.Args:void.Returns:void.Example:# Closes serial port
mates.close()reset(waitPeriod)Uses hardware driven signal to hard reset companion device.Args:wait_period: intdetermines how long to wait (milliseconds) before checking for connection. Value must be within the uint16 datatype range (default: 5000)Returns:boolean response of reset.Example:# Reset the display and wait for
mates.reset()         # a period of 5 seconds (default)
# Reset the display and wait for
# mates.reset(4000)   # a period of 4 secondssoftReset(waitPeriod)Sends a serial command to the connected device to trigger a reset.Args:waitPeriod: intdetermines how long (milliseconds) to wait before timing out after no acknowledgement. Value must be within the uint16 datatype range.Returns:boolean response of resetExample:# Reset the display and wait for
mates.softReset()       # a period of 5 seconds (default)
# Reset the display and wait for
mates.softReset(4000)   # a period of 4 secondssetBacklight(backlightValue)Sets the intensity of the backlight of connected device.Args:backlightValue: intintensity of backlight. Value must be between 0 and 15, and within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:# set backlight value of 15 (max)
mates.setBacklight(15)setPage(pageIndex)Sets the page to be displayed on the connected device.Args:pageIndex: intindex of page to set as current. Value must be within the uint16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setPage(1) # Navigate to Page1getPage()Returns the index of the current page displayed by the connected device.Args:void.Returns:integer corresponding to current page index.Example:activePage = mates.getPage() # Query active pagesetWidgetValueById(widgetId, value)Sets the value of a specific widget based on the provided widgetId.Args:widgetId: int
- the unique id of the desired widget.
Value must exist within the int16 datatype range.value: int
the value the corresponding widget will be set to.
Value must exist within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setWidgetValueById(MediaGaugeB0, 50) # Set value of MediaGaugeB0 to 50
# Note: The ID of MediaGaugeB0 can be copied or exported from Mates StudiogetWidgetValueById(widgetId)Gets the value of a specific widget based on the provided identifier.Args:widgetId: intthe unique id of the target widget. Value must be within the uint16 datatype rangeReturns:integer corresponding to widget value.Example:widgetVal = mates.getWidgetValue(MediaLed4) # Query the current value of MediaLed4
# Note: The ID of MediaLed4 can be copied or exported from Mates StudiosetWidgetValueByIndex(widgetType, widgetIndex, value)Sets the value of a specific widget based on the index within a widget type.Args:widgetType: MatesWidgetthe unique type of widget to be changed.widgetIndex: intthe index of the widget, of a specific type. Value must be within the uint8 datatype range.value: intthe value the corresponding widget will be set to. Value must be within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setWidgetValue(MATES_MEDIA_GAUGE_B, 0, 50) # Set value of MediaGaugeB0 to 50Note:All applicable widget types are listed inhere.getWidgetValueByIndex(widgetType, widgetIndex)Gets the value of a specific widget based on the index within a widget type.Args:widgetType: MatesWidgetthe unique type of widget to be changed.widgetIndex: intthe index of the widget, of a specific type. Value must be within the uint8 datatype range.Returns:integer corresponding to widget value.Example:widgetVal = mates.getWidgetValue(MATES_MEDIA_LED, 4) # Query the current value of MediaLed4Note:This function is not applicable toInt32andFloatLedDigitssetLedDigitsShortValue(widgetIndex, value)Sets the 16-bit integer value of the Led Digits widget specified by widgetIndex.Args:widgetIndex: intthe index of the LED Digits widget. Value must be within uint8 datatype range.value: int, floatthe value the corresponding widget will be set to.
Values must be within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setLedDigitsShortValue(2, 50) # Set value of LedDigits2 to 50Note:This function is only applicable forInt16LedDigitssetLedDigitsLongValue(widgetIndex, value)Sets the 32-bit integer value of the Led Digits widget specified by widgetIndex.Args:widgetIndex: intthe index of the LED Digits widget. Value must be within uint8 datatype range.value: int, floatthe value the corresponding widget will be set to. Values must be within the int32 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setLedDigitsLongValue(2, 50) # Set value of LedDigits2 to 50Note:This function is only applicable forInt32LedDigitssetLedDigitsFloatValue(widgetIndex, value):Sets the 32-bit float value of the Led Digits widget specified by widgetIndex.Args:widgetIndex: intthe index of the LED Digits widget. Value must be within uint8 datatype range.value: int, floatthe value the corresponding widget will be set to.
Values must be within the float32 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setLedDigitsFloatValue(2, 9.989) # Set value of LedDigits2 to 9.989Note:This function is only applicable forfloat32LedDigitssetSpectrumValue(spectrumId, gaugeIndex, value)Sets the value of the column (specified by gaugeIndex) of the spectrum widget (specified by spectrumId).Args:spectrumId: intthe id of the relevant Spectrum widget. Value must be within the int16 datatype range.gaugeIndex: intthe gauge index within the target Spectrum widget. Value must be within the uint8 datatype range.value: intthe value the corresponding widget will be set to. Value must be within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setSpectrumValue(MatesLedSpectrum5, 2, 64)
# Set value of gauge index 2 of LedSpectrum5 to 64setLedSpectrumValue(ledSpectrumIndex, gaugeIndex, value)Sets the value of the column (specified by gaugeIndex) of the Led Spectrum widget (specified by ledSpectrumIndex).Args:
ledSpectrumIndex: intthe index of the desired LED Spectrum widget. Value must be within the uint8 datatype range.gaugeIndex: intthe gauge index within the target LED Spectrum widget. Value must be within the uint8 datatype range.value: intthe value the corresponding widget will be set to. Value must be within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setLedSpectrumValue(5, 2, 64)
# Set value of gauge index 2 of LedSpectrum5 to 64setMediaSpectrumValue(mediaIndex, gaugeIndex, value)Sets the value of the column (specified by gaugeIndex) of the Media Spectrum widget (specified by ledSpectrumIndex).Args:
mediaIndex: intthe index of the Media Spectrum widget. Value must be within the uint8 datatype range.gaugeIndex: intthe index of the desired gauge. Value must be within the uint8 datatype range.value: intthe value the corresponding widget will be set to. Value must be within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setMediaSpectrumValue(4, 3, 48)
# Set value of gauge index 3 of MediaSpectrum4 to 48setWidgetParamById(widgetId, param, value)Sets the value of a widget parameter based on widget id and parameter id.Args:
widgetId: intthe unique id of the target widget. Value must be within the int16 datatype range.param: intthe unique id of the target parameter. Value must be within the int16 datatype range.value: intthe value the corresponding parameter will be set to. Value must be within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:# Set GaugeA3's Background color to BLACK
mates.setWidgetParamById(GaugeA3, MATES_GAUGE_A_BG_COLOR, BLACK) 
# Note: The ID of GaugeA3 can be copied or exported from Mates StudiogetWidgetParamById(widgetId, param)Gets the value of a widget parameter based on widget id and parameter id.Args:
widgetId: int
- the unique id of the target widget.
Value must be within the int16 datatype range.param: int
- the unique id of the target parameter.
Value must be within the int16 datatype range.Returns:integer response indicating target parameter value.Example:# Query the background color of GaugeA3
paramVal = mates.getWidgetParamById(GaugeA3, MATES_GAUGE_A_BG_COLOR) 
# Note: The ID of GaugeA3 can be copied or exported from Mates StudiosetWidgetParamByIndex(widgetType, widgetIndex, param, value)Sets the value of a widget parameter based on widget index and parameter id.Args:
widgetType: MatesWidgetthe type of the target widget.widgetIndex: intthe index of the target widget. Value must be within the uint8 datatype range.param: intthe unique id of the target parameter. Value must be within the int16 datatype range.value: intthe value the corresponding parameter will be set to. Value must be within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:# Set GaugeA3's Background color to BLACK
mates.setWidgetParamByIndex(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR, BLACK)getWidgetParamByIndex(widgetType, widgetIndex, param)Gets the value of a widget parameter based on widget index and parameter id.Args:widgetType: MatesWidgetthe type of the target widget.widgetIndex: intthe index of the target widget. Value must be within the uint8 datatype range.param: intthe unique id of the target parameter. Value must be within the int16 datatype range.Returns:integer response indicating target parameter value.Example:# Query the background color of GaugeA3
paramVal = mates.getWidgetParamByIndex(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR)clearTextArea(textAreaIndex)Clears a targeted Text Area.Args:textAreaIndex: intthe index of the target Text Area widget. Value must be within the uint16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.clearTextArea(6) # Clear TextArea6updateTextArea(textAreaIndex, textFormat, *formatArgs)Updates the text displayed within Text Area widget.Args:textAreaIndex: intthe index of the target Text Area widget. Value must be within the uint16 datatype range.textFormat: strthe string format to be displayed.formatArgs:zero or more values to be formatted into the provided text format string.Returns:boolean response indicating command success or failure.Example No. 1:mates.updateTextArea(2, "Mates") # Update TextArea2 to "Mates"Example No. 2:int value = 76
mates.updateTextArea(3, "Value is {}", 76) # Print value to TextArea3def clearPrintArea(printAreaIndex: int)Clears a targeted Print Area.Args:printAreaIndex: intthe index of the target Print Area widget.
Value must be within the uint16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.clearPrintArea(5) # Clear PrintArea5setPrintAreaColor565(printAreaIndex, rgb565)Sets the color of a PrintArea Widget based on an rgb565 value.Args:printAreaIndex: intindex of widget, value must be within uint16 datatype range.rgb565: intcolour to set widget to, value must be within uint16 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setPrintAreaColor(4, 0xF800) # Set print color of PrintArea4 to RED (0xF800)setPrintAreaColorRGB(printAreaIndex, red, green, blue)Sets the colour of a targeted Print Area.Args:printAreaIndex: intthe index of the target Print Area widget. Value must be within the uint16 datatype range.red: intUnsigned 8 bit integer value of red concentration. Value must be within the uint8 datatype range.blue: intUnsigned 8 bit integer value of green concentration. Value must be within the uint8 datatype range.green: intUnsigned 8 bit integer value of blue concentration. Value must be within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:mates.setPrintAreaColor(7, 0, 255, 0) # Set print color of PrintArea7 to GREENappendArrayToPrintArea(printAreaIndex, array)Appends an array of 8-bit integers to a targeted Print Area.Args:printAreaIndex: intthe index of the target Print Area widget.
Value must be within the uint16 datatype range.buffer: [int]the list of datapoints to be appended to scope widget. Values must be within the uint8 datatype range.Returns:boolean response indicating command success or failure.Example:arr = [0xAB, 0xCD, 0xEF]
mates.appendArrayToPrintArea(6, arr) # Append "0xAB, 0xCD, 0xEF" to PrintArea6appendStringToPrintArea(printAreaIndex, textFormat, *formatArgs)Appends text to a targeted Print Area.Args:printAreaIndex: intthe index of the target Print Area widget.
Value must be within the uint16 datatype range.textFormat: strthe string to be appended to the Print Area
with zero or more format specifiers to be formatted.formatArgs:zero or more args that can be formatted into the
textFormat string.Returns:boolean response indicating command success or failure.Example No. 1:mates.appendStringToPrintArea(8, "Mates") # Append "Mates" to PrintArea8Example No. 2:int value = 108
mates.appendStringToPrintArea(9, "Value: {}", 108) # Append value as text to PrintArea9def appendToScopeWidget(scopeIndex, buffer)Appends a list of integers to a Scope widget.Args:scopeIndex: intthe index of the target Scope widget. Value must be within the uint16 datatype range.buffer: [int]the list of datapoints to be appended to scope widget. Values must be within the int16 datatype range.Returns:boolean response indicating command success or failure.Example:data = {0xF8, 0x7F, 0x1F}
mates.appendToScopeWidget(7, data, 3) # Append data to Scope Widget 7updateDotMatrixWidget(matrixIndex, textFormat, *formatArgs)Changes the text displayed by the target Dot Matrix widget.Args:matrixIndex (int): matrix index.The index of the target Scope widget.
Value must be within the uint16 datatype range.textFormat: strthe string to be appended to the Scope widget with zero or more format specifiers to be formatted.formatArgs:zero or more args that can be formatted into the text_format string.Returns:boolean response indicating command success or failure.Example No. 1:mates.updateDotMatrix(8, "Mates") # Update DotMatrix0 to "Mates"Example No. 2:value = 108
mates.updateDotMatrix(9, "Value: {}", 108) # Update DotMatrix0 to show valuegetButtonEventCount()Gets the number of events recorded from applicable button widgets.Args:void.Returns:integer corresponding to the number of events.Example:# Get the number of logged button events
buttonEvents = mates.getButtonEventCount()getNextButtonEvent()Gets the next event source logged from applicable buttons.Args:void.Returns:integer corresponding to the button widget IDExample:// If there is any event recorded
if mates.getButtonEventCount() > 0: 
    button = mates.getNextButtonEvent()
    if (button == MediaButton1):
        // if the button pressed is MediaButton1
        // do something
    // add more possible cases here...getSwipeEventCount()Gets the number of events recorded from swipe gestures.Args:void.Returns:integer corresponding to the number of events.Example:# Get the number of logged swipe events
swipeEvents = mates.getSwipeEventCount()getNextSwipeEvent()Gets the next swipe event value.Args:void.Returns:integer corresponding to the swipe event.Example:// If there is any event recorded
if mates.getSwipeEventCount() > 0:
    swipe = mates.getNextSwipeEvent()
    if ((swipe & MATES_SWIPE_SOUTH) == MATES_SWIPE_SOUTH):
        // if swipe is towards from top to bottom
    if ((swipe & MATES_SWIPE_EAST) == MATES_SWIPE_EAST):
        // if swipe is towards from left to right
    if ((swipe & MATES_SWIPE_TLBR) == MATES_SWIPE_TLBR):
        // if swipe is towards from top left to bottom rightgetVersion()Helper function to obtain the version of the Python Mates Controller library.Args:void.Returns:string response of library version.Example:# Get the library version number as string
matesVersion = mates.getVersion()def getCompatibility()Helper function to obtain the version of the Mates Studio compatible
with this library version.Args:void.Returns:string response of Mates Studio version compatible with this library.Example:# Get the library version number as string
matesVersion = mates.getCompatibility()printVersion()Debugging function to print the version of the Mates Studio compatible along with this specific library version.Args:void.Returns:void.Example:# Prints library version and compatible Mates Studio version to debug serial
mates.printVersion()getError()Function to return the current error state of the Mates Controller.Args:void.Returns:MatesError response of current error.Example:# Checks the last error that occurred
error = mates.getError()
if error == MATES_ERROR_NONE:
    # Last command was successful