Raspberry Pi Python Mates 控制器库

开发用于与使用 BBM Pi 适配器或类似连接的 Raspberry Pi 连接的 Mates Studio Commander 或 Architect Environment 和 BBM 模块一起使用的 Python 库。这个库的目标是简单到足以让初学者学习，并为有经验的开发人员提供丰富的功能。

它用于通过串行端口与 BBM 设备通信，并包含用于发送和检索与显示小部件、它们的状态和参数以及控制器的健康状况相关的数据的各种方法。有用的类和数据类型可以在mates.constants模块中找到。

硬件和软件支持

该库是为 Python3 开发的，只要该pyserial库支持，它就可以与任何操作系统一起使用。

安装

可以通过运行以下命令从 Python Packaging Index 安装此库：

pip3 install rpi-mates-controller

---

图书馆讨论

构造函数

MatesController（端口名称、resetPinIndex、resetActiveHigh、debugStream、debugFileLength）

构造与配合控制器对象的实例关联的所有必要属性。

参数：

端口名称：str

• 要打开的端口的名称。示例：Linux 的 /dev/ttyUSB0。

resetPinIndex：整数，字符串

• 连接到 Mates 设备复位引脚的引脚索引。

重置活动高：布尔

• 复位引脚是从逻辑低电平还是逻辑高电平驱动来复位器件。

调试流：io.TextIOWrapper

• 要写入调试代码的文本文件对象，提供 none 将导致不调试。示例包括 sys.stdout、open('log.txt', 'r+')

调试文件长度：int

• 在给定循环日志的情况下，确定与文件中的行相关的调试历史记录的范围。O 表示完整的历史记录，没有循环记录。用户必须在这里小心有效地管理存储空间。

示例 1：

# Creates a new instance named 'mates' which utilizes: 
#  - /dev/ttyS0 as the serial port
#  - with default reset pin (4) and no output stream
MatesController mates = MatesController("/dev/ttyS0") 

示例 2：

# Creates a new instance named 'mates' which utilizes: 
#  - /dev/ttyS0 as the serial port
#  - pin 4 as the reset pin
#  - LOW pulse as active pulse
#  - output_file as debug file stream
#  - debugFileLength of zero indicating no circular logging
MatesController mates = MatesController("/dev/ttyS0", resetPinIndex=4, resetActiveHigh=False, debugStream=output_file, debugFileLength=0) 

注意： 如果指定了调试文件，则应在运行此库的 begin() 函数之前使用“w+”或“r+”打开它。

方法

开始（波特率）

如果构造函数中未提供端口名，则开始串行连接。

参数：

波特率：int

• 串口波特率（默认：9600）

返回：

• 空白

示例 1：

# Initializes display serial port 9600 baud
# and resets the display if a reset function is provided
mates.begin(9600) 

关（）

关闭打开的串口。

参数：

空白。

返回：

空白。

例子：

# Closes serial port
mates.close()

重置（等待期）

使用硬件驱动信号硬重置配套设备。

参数：

wait_period：整数

• 确定在检查连接之前等待多长时间（毫秒）。值必须在 uint16 数据类型范围内（默认值：5000）

返回：

• 复位的布尔响应。

例子：

# 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 seconds

软重置（等待期）

向连接的设备发送串行命令以触发重置。

参数：waitPeriod
：int

• 确定在没有确认后超时之前等待多长时间（毫秒）。值必须在 uint16 数据类型范围内。

返回：

• 复位的布尔响应

例子：

# 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 seconds

设置背光（背光值）

设置连接设备的背光强度。

参数：
背光值：int

• 背光强度。值必须介于 0 和 15 之间，并且在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

# set backlight value of 15 (max)
mates.setBacklight(15)

设置页面（页面索引）

设置要在连接的设备上显示的页面。

参数：
pageIndex：int

• 要设置为当前页面的索引。值必须在 uint16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setPage(1) # Navigate to Page1

获取页面（）

返回连接设备显示的当前页面的索引。

参数：

• 空白。

返回：

• 对应于当前页面索引的整数。

例子：

activePage = mates.getPage() # Query active page

setWidgetValueById(widgetId, 值)

根据提供的 widgetId 设置特定小部件的值。

Args :
widgetId: int - 所需小部件的唯一 ID。值必须存在于 int16 数据类型范围内。

value：int 相应小部件将设置为的值。值必须存在于 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setWidgetValueById(MediaGaugeB0, 50) # Set value of MediaGaugeB0 to 50
# Note: The ID of MediaGaugeB0 can be copied or exported from Mates Studio

getWidgetValueById(widgetId)

根据提供的标识符获取特定小部件的值。

参数：widgetId
：int

• 目标小部件的唯一 ID。值必须在 uint16 数据类型范围内

返回：

• 对应于小部件值的整数。

例子：

widgetVal = mates.getWidgetValue(MediaLed4) # Query the current value of MediaLed4
# Note: The ID of MediaLed4 can be copied or exported from Mates Studio

setWidgetValueByIndex(widgetType, widgetIndex, value)

根据小部件类型中的索引设置特定小部件的值。

参数：
widgetType：MatesWidget

• 要更改的唯一类型的小部件。

小部件索引：int

• 特定类型的小部件的索引。值必须在 uint8 数据类型范围内。

值：整数

• 相应小部件将设置为的值。值必须在 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setWidgetValue(MATES_MEDIA_GAUGE_B, 0, 50) # Set value of MediaGaugeB0 to 50

注意： 此处列出了所有适用的小部件类型。

getWidgetValueByIndex(widgetType, widgetIndex)

根据小部件类型中的索引获取特定小部件的值。

参数：

小部件类型：MatesWidget

• 要更改的唯一类型的小部件。

小部件索引：int

• 特定类型的小部件的索引。值必须在 uint8 数据类型范围内。

返回：

• 对应于小部件值的整数。

例子：

widgetVal = mates.getWidgetValue(MATES_MEDIA_LED, 4) # Query the current value of MediaLed4

注意： 此函数不适用于Int32和Float LedDigits

setLedDigitsShortValue（小部件索引，值）

设置由 widgetIndex 指定的 Led Digits 小部件的 16 位整数值。

参数：

小部件索引：int

• LED 数字小部件的索引。值必须在 uint8 数据类型范围内。

值：整数，浮点数

• 相应小部件将设置为的值。值必须在 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setLedDigitsShortValue(2, 50) # Set value of LedDigits2 to 50

注意： 此功能仅适用于Int16 LedDigits

setLedDigitsLongValue（小部件索引，值）

设置由 widgetIndex 指定的 Led Digits 小部件的 32 位整数值。

参数：

小部件索引：int

• LED 数字小部件的索引。值必须在 uint8 数据类型范围内。

值：整数，浮点数

• 相应小部件将设置为的值。值必须在 int32 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setLedDigitsLongValue(2, 50) # Set value of LedDigits2 to 50

注意： 此功能仅适用于Int32 LedDigits

setLedDigitsFloatValue(widgetIndex, value):

设置由 widgetIndex 指定的 Led Digits 小部件的 32 位浮点值。

参数：

小部件索引：int

• LED 数字小部件的索引。值必须在 uint8 数据类型范围内。

值：整数，浮点数

• 相应小部件将设置为的值。值必须在 float32 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setLedDigitsFloatValue(2, 9.989) # Set value of LedDigits2 to 9.989

注意： 此功能仅适用于float32 LedDigits

setSpectrumValue（spectrumId，gaugeIndex，值）

设置频谱小部件（由spectrumId 指定）的列（由gaugeIndex 指定）的值。

参数：

频谱ID：int

• 相关 Spectrum 小部件的 id。值必须在 int16 数据类型范围内。

仪表索引：int

• 目标 Spectrum 小部件中的仪表索引。值必须在 uint8 数据类型范围内。

值：整数

• 相应小部件将设置为的值。值必须在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setSpectrumValue(MatesLedSpectrum5, 2, 64)
# Set value of gauge index 2 of LedSpectrum5 to 64

setLedSpectrumValue（ledSpectrumIndex，gaugeIndex，值）

设置 Led Spectrum 小部件（由 ledSpectrumIndex 指定）的列（由 gaugeIndex 指定）的值。

参数： ledSpectrumIndex：int

• 所需 LED Spectrum 小部件的索引。值必须在 uint8 数据类型范围内。

仪表索引：int

• 目标 LED Spectrum 小部件中的仪表索引。值必须在 uint8 数据类型范围内。

值：整数

• 相应小部件将设置为的值。值必须在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setLedSpectrumValue(5, 2, 64)
# Set value of gauge index 2 of LedSpectrum5 to 64

setMediaSpectrumValue（mediaIndex，gaugeIndex，值）

设置 Media Spectrum 小部件（由 ledSpectrumIndex 指定）的列（由 gaugeIndex 指定）的值。

参数： mediaIndex：int

• 媒体频谱小部件的索引。值必须在 uint8 数据类型范围内。

仪表索引：int

• 所需仪表的索引。值必须在 uint8 数据类型范围内。

值：整数

• 相应小部件将设置为的值。值必须在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setMediaSpectrumValue(4, 3, 48)
# Set value of gauge index 3 of MediaSpectrum4 to 48

setWidgetParamById(widgetId, 参数, 值)

根据小部件 id 和参数 id 设置小部件参数的值。

参数： widgetId：int

• 目标小部件的唯一 ID。值必须在 int16 数据类型范围内。

参数：int

• 目标参数的唯一标识。值必须在 int16 数据类型范围内。

值：整数

• 相应参数将设置为的值。值必须在 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

# 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 Studio

getWidgetParamById(widgetId, 参数)

根据小部件 id 和参数 id 获取小部件参数的值。

Args : widgetId: int - 目标小部件的唯一 ID。值必须在 int16 数据类型范围内。

param: int - 目标参数的唯一 id。值必须在 int16 数据类型范围内。

返回：

• 表示目标参数值的整数响应。

例子：

# 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 Studio

setWidgetParamByIndex（widgetType，widgetIndex，参数，值）

根据小部件索引和参数 id 设置小部件参数的值。

参数：widgetType：MatesWidget

• 目标小部件的类型。

小部件索引：int

• 目标小部件的索引。值必须在 uint8 数据类型范围内。

参数：int

• 目标参数的唯一标识。值必须在 int16 数据类型范围内。

值：整数

• 相应参数将设置为的值。值必须在 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

# Set GaugeA3's Background color to BLACK
mates.setWidgetParamByIndex(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR, BLACK) 

getWidgetParamByIndex(widgetType, widgetIndex, 参数)

根据小部件索引和参数 id 获取小部件参数的值。

参数：

小部件类型：MatesWidget

• 目标小部件的类型。

小部件索引：int

• 目标小部件的索引。值必须在 uint8 数据类型范围内。

参数：int

• 目标参数的唯一标识。值必须在 int16 数据类型范围内。

返回：

• 表示目标参数值的整数响应。

例子：

# Query the background color of GaugeA3
paramVal = mates.getWidgetParamByIndex(MATES_GAUGE_A, 3, MATES_GAUGE_A_BG_COLOR) 

clearTextArea(textAreaIndex)

清除目标文本区域。

参数：

文本区域索引：int

• 目标文本区域小部件的索引。值必须在 uint16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.clearTextArea(6) # Clear TextArea6

updateTextArea(textAreaIndex, textFormat, *formatArgs)

更新文本区域小部件中显示的文本。

参数：

文本区域索引：int

• 目标文本区域小部件的索引。值必须在 uint16 数据类型范围内。

文本格式：str

• 要显示的字符串格式。

格式参数：

• 要格式化为提供的文本格式字符串的零个或多个值。

返回：

• 指示命令成功或失败的布尔响应。

示例 1：

mates.updateTextArea(2, "Mates") # Update TextArea2 to "Mates"

示例 2：

int value = 76
mates.updateTextArea(3, "Value is {}", 76) # Print value to TextArea3

def clearPrintArea(printAreaIndex: int)

清除目标打印区域。

参数：

打印区域索引：int

• 目标打印区域小部件的索引。值必须在 uint16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.clearPrintArea(5) # Clear PrintArea5

setPrintAreaColor565(printAreaIndex, rgb565)

根据 rgb565 值设置 PrintArea 小部件的颜色。

参数：

打印区域索引：int

• 小部件的索引，值必须在 uint16 数据类型范围内。

RGB565：整数

• 设置小部件的颜色，值必须在 uint16 数据类型范围内。

回报：

• 指示命令成功或失败的布尔响应。

例子：

mates.setPrintAreaColor(4, 0xF800) # Set print color of PrintArea4 to RED (0xF800)

setPrintAreaColorRGB(printAreaIndex, red, green, blue)

设置目标打印区域的颜色。

参数：

打印区域索引：int

• 目标打印区域小部件的索引。值必须在 uint16 数据类型范围内。

红色：整数

• 红色浓度的无符号 8 位整数值。值必须在 uint8 数据类型范围内。

蓝色：int

• 绿色浓度的无符号 8 位整数值。值必须在 uint8 数据类型范围内。

绿色：整数

• 蓝色浓度的无符号 8 位整数值。值必须在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

mates.setPrintAreaColor(7, 0, 255, 0) # Set print color of PrintArea7 to GREEN

appendArrayToPrintArea(printAreaIndex, 数组)

将一个 8 位整数数组附加到目标打印区域。

参数：

打印区域索引：int

• 目标打印区域小部件的索引。值必须在 uint16 数据类型范围内。

缓冲区：[int]

• 要附加到范围小部件的数据点列表。值必须在 uint8 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

arr = [0xAB, 0xCD, 0xEF]
mates.appendArrayToPrintArea(6, arr) # Append "0xAB, 0xCD, 0xEF" to PrintArea6

appendStringToPrintArea(printAreaIndex, textFormat, *formatArgs)

将文本附加到目标打印区域。

参数：

打印区域索引：int

• 目标打印区域小部件的索引。值必须在 uint16 数据类型范围内。

文本格式：str

• 要附加到打印区域的字符串，其中包含零个或多个要格式化的格式说明符。

格式参数：

• 零个或多个可以格式化为 textFormat 字符串的参数。

返回：

• 指示命令成功或失败的布尔响应。

示例 1：

mates.appendStringToPrintArea(8, "Mates") # Append "Mates" to PrintArea8

示例 2：

int value = 108
mates.appendStringToPrintArea(9, "Value: {}", 108) # Append value as text to PrintArea9

def appendToScopeWidget（范围索引，缓冲区）

将整数列表附加到 Scope 小部件。

参数：

范围索引：int

• 目标 Scope 小部件的索引。值必须在 uint16 数据类型范围内。

缓冲区：[int]

• 要附加到范围小部件的数据点列表。值必须在 int16 数据类型范围内。

返回：

• 指示命令成功或失败的布尔响应。

例子：

data = {0xF8, 0x7F, 0x1F}
mates.appendToScopeWidget(7, data, 3) # Append data to Scope Widget 7

updateDotMatrixWidget(matrixIndex, textFormat, *formatArgs)

更改目标点阵小部件显示的文本。

参数：

matrixIndex (int)：矩阵索引。

• 目标 Scope 小部件的索引。值必须在 uint16 数据类型范围内。

文本格式：str

• 要附加到 Scope 小部件的字符串，其中包含要格式化的零个或多个格式说明符。

格式参数：

• 零个或多个可以格式化为 text_format 字符串的参数。

返回：

• 指示命令成功或失败的布尔响应。

示例 1：

mates.updateDotMatrix(8, "Mates") # Update DotMatrix0 to "Mates"

示例 2：

value = 108
mates.updateDotMatrix(9, "Value: {}", 108) # Update DotMatrix0 to show value

getButtonEventCount()

获取从适用的按钮小部件记录的事件数。

参数：

• 空白。

返回：

• 对应于事件数的整数。

例子：

# Get the number of logged button events
buttonEvents = mates.getButtonEventCount()

获取下一个按钮事件（）

获取从适用按钮记录的下一个事件源。

参数：

• 空白。

返回：

• 与按钮小部件 ID 对应的整数

例子：

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

获取从滑动手势记录的事件数。

参数：

• 空白。

返回：

• 对应于事件数的整数。

例子：

# Get the number of logged swipe events
swipeEvents = mates.getSwipeEventCount()

getNextSwipeEvent()

获取下一个滑动事件值。

参数：

• 空白。

返回：

• 与滑动事件对应的整数。

例子：

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

获取版本（）

帮助函数获取 Python Mates 控制器库的版本。

参数：

• 空白。

返回：

• 库版本的字符串响应。

例子：

# Get the library version number as string
matesVersion = mates.getVersion()

def getCompatibility()

帮助函数获取与此库版本兼容的 Mates Studio 版本。

参数：

• 空白。

返回：

• 与此库兼容的 Mates Studio 版本的字符串响应。

例子：

# Get the library version number as string
matesVersion = mates.getCompatibility()

打印版本（）

用于打印与此特定库版本兼容的 Mates Studio 版本的调试功能。

参数：

• 空白。

返回：

• 空白。

例子：

# Prints library version and compatible Mates Studio version to debug serial
mates.printVersion()

错误（）

返回配合控制器当前错误状态的函数。

参数：

• 空白。

返回：

• 当前错误的 MatesError 响应。

例子：

# Checks the last error that occurred
error = mates.getError()
if error == MATES_ERROR_NONE:
    # Last command was successful