MATRIX Mini R4 Blocks API

本文件提供 MATRIX Mini R4 機器人的 Blockly 視覺化編程積木完整API參考。

MATRIX Mini 基礎

初始化設定

mini_setup

功能說明： 初始化 MATRIX Mini 開發板的基本設定。此積木應該放在程式開始處。這是一個 HAT（帽子）積木。 所有除事件、自訂函數外的主要代碼應該放在此處，其概念與Arduino的Setup、Loop相同。

註：請勿在程式畫面中放置多個此方塊，將導致功能異常。

使用方式：

按鈕讀取

mini_BTNget

功能說明： 讀取板載按鈕的狀態。

回傳值：

電源電壓讀取

mini_PWR_getVolt

功能說明： 讀取電源輸入電壓值（單位：伏特）。

回傳值：

數位輸入讀取

mini_DIget

功能說明： 讀取指定數位腳位的輸入狀態。

參數：

回傳值：

數位輸出設定

mini_DOset

功能說明： 設定指定數位腳位的輸出狀態。

參數：

類比輸入讀取

mini_AIget

功能說明： 讀取指定類比腳位的數值。

參數：

回傳值：

直流馬達方向設定

mini_MsetDIR

功能說明： 設定直流馬達的旋轉方向。

參數：

馬達 PPR 與 RPM 設定

mini_ddc_set_ppr_rpm

功能說明： 設定編碼器馬達的脈衝數（PPR）和額定轉速（RPM）參數。

參數：

說明：

馬達功率控制

mini_Mset

功能說明： 設定馬達功率(PWM)並開始運轉。

參數：

馬達速度控制

mini_MsetSpeed

功能說明： 設定馬達速度並開始運轉，但通過Encoder實時計算速度，並利用PID進行穩定的速度控制。

參數：

馬達煞車

mini_Mbrake

功能說明： 停止馬達並進行煞車。

參數：

編碼器重置

mini_ENC_reset

功能說明： 將編碼器計數值歸零。

參數：

編碼器讀取

mini_ENC_get

功能說明： 讀取編碼器的當前計數值。

參數：

回傳值：

RC 伺服馬達方向設定

mini_RCsetDIR

功能說明： 設定 RC 伺服馬達的旋轉方向。

參數：

RC 伺服馬達角度設定

mini_RCset

功能說明： 設定 RC 伺服馬達的角度位置。

非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)

參數：

移動控制

本分類提供了機器人移動的高階控制積木，包含同步控制、陀螺儀輔助等功能。

底盤配置設定

mini_ddc_setting

功能說明：

如使用非MATRIX馬達，使用前請先通過馬達方塊配置好PPR、RPM、方向等資訊。

配置左右馬達及其反轉設定，用於差動驅動機器人。

參數：

PID 控制參數設定

mini_ddc_set_pid

功能說明： 設定 PID 控制器的參數，用於移動同步或陀螺儀控制。

參數：

調整建議：

預設PID數值(Kp, Ki, Kd)參考：

移動指定距離/角度

mini_ddc_runFor

功能說明： 控制機器人移動指定的距離或角度。

參數：

同步移動指定距離/角度

mini_ddc_runFor_sync

功能說明： 使用 PID 同步控制，使左右輪保持一致的移動。

參數：

特點：

陀螺儀輔助移動

mini_ddc_runFor_gyro

功能說明： 使用陀螺儀感測器輔助，保持直線移動。

參數：

特點：

連續移動

mini_ddc_on

功能說明： 啟動連續移動，直到停止指令。*功率為PWM輸出，無PID速控，適合搭配用戶自己寫的循線或其他算法(如PID)使用

參數：

連續同步移動

mini_ddc_on_sync

功能說明： 使用 PID 同步控制的連續移動。

參數：

連續陀螺儀直線移動

mini_ddc_on_gyro

功能說明： 使用陀螺儀輔助的連續直線移動。

參數：

陀螺儀轉彎(單輪轉)

mini_ddc_turn

功能說明： 控制機器人轉向指定角度，可設定轉彎速度。使用陀螺儀之Yaw Heading來進行轉向角度偵測。

參數：

特點：

陀螺儀轉彎(雙輪轉)

mini_ddc_turntwo

功能說明： 控制機器人轉向指定角度，可設定轉彎速度。使用陀螺儀之Yaw Heading來進行轉向角度偵測。

參數：

底盤移動累積角度

mini_ddc_get_degs

功能說明： 讀取馬達從上次重置後累積轉動的角度值，可用於計算行駛距離。 其計算方法為 (abs(leftMotorDegs) + abs(rightMotorDegs)) / 2。 註: 與原有馬達之Encoder角度計算不衝突。

回傳值：

重置底盤累積角度

mini_ddc_reset_degs

功能說明： 將底盤累積角度重置為零，用於重新開始距離計算。建議在需要精確測量距離前先執行重置。 註: 與原有馬達之Encoder角度計算不衝突。

停止移動

mini_ddc_off

功能說明： 停止機器人移動。 煞車方法：Brake為通過馬達H橋驅動晶片加速停車、Coast為鬆油門滑行、Hold為PID煞車確保角度穩定(尚未推出)

外觀與顯示

RGB LED 設定

mini_setRGB

功能說明： 設定板載 RGB LED 的顏色。

參數：

蜂鳴器播放頻率

mini_Buzzer_Tone

功能說明： 以指定頻率和音量播放音調。

非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)

參數：

蜂鳴器播放音符

mini_Buzzer_ToneNote

功能說明： 播放預定義的音符。

非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)

參數：

蜂鳴器停止

mini_Buzzer_NoTone

功能說明： 停止蜂鳴器播放。

OLED 清除螢幕

mini_OLED_clear

功能說明： 清除 OLED 顯示器的所有內容。

OLED 顯示文字

mini_OLED_printEASY

功能說明： 在 OLED 螢幕的指定位置顯示文字。

參數：

OLED 設定文字大小

mini_OLED_setTextSize

功能說明： 設定 OLED 顯示的文字大小。

參數：

OLED 設定文字顏色

mini_OLED_setTextColor

功能說明： 設定 OLED 顯示的文字顏色。

參數：

序列通訊

USB 序列輸出（不換行）

mini_Serial_print

功能說明： 透過 USB 序列埠輸出文字，不自動換行。

參數：

USB 序列輸出（換行）

mini_Serial_println

功能說明： 透過 USB 序列埠輸出文字，並自動換行。

參數：

USB 序列寫入位元組

mini_Serial_write

功能說明： 透過 USB 序列埠寫入原始位元組資料。

參數：

USB 序列輸出三軸資料

mini_Serial_printAXIS

功能說明： 以特定格式輸出三軸感測器資料，方便軟體右下角的 Serial Plotter 圖表顯示。

參數：

USB 序列可讀取資料檢查

mini_Serial_available

功能說明： 檢查序列埠緩衝區是否有可讀取的資料。

回傳值：

USB 序列讀取

mini_Serial_read

功能說明： 從序列埠讀取一個字元。

回傳值：

感測器

MJ2 手把輪詢

mini_ps2_polling

功能說明： 更新 MJ2(PS2) 手把的狀態資料。應該放在主迴圈中定期執行。

**MJ2手把的連接方式指南：

MJ2 按鈕狀態

mini_ps2_btn

功能說明： 讀取 MJ2(PS2) 手把的按鈕狀態。

如何連接MJ2手把？請向上滑動至"MJ2 手把輪詢"小節，有連接指南。

參數：

回傳值：

MJ2 搖桿數值

mini_ps2_joy

功能說明： 讀取 MJ2(PS2) 手把搖桿的類比數值。

如何連接MJ2手把？請向上滑動至"MJ2 手把輪詢"小節，有連接指南。

參數：

回傳值：

IMU 重置

mini_motion_reset

功能說明： 重置板載 IMU（慣性測量單元）的數值。

IMU 加速度讀取

mini_motion_getAccel

功能說明： 讀取加速度感測器數值。

參數：

回傳值：

IMU 陀螺儀讀取

mini_motion_getGyro

功能說明： 讀取陀螺儀角速度。

參數：

回傳值：

IMU 歐拉角讀取

mini_motion_getEuler

功能說明： 讀取姿態角度（Roll、Pitch、Yaw）。

參數：

回傳值：

灰階感測器讀取

mini_MXGrayscale_getGrayscale

功能說明： 讀取 MATRIX 灰階感測器數值。

參數：

回傳值：

電位器讀取

mini_MXPot_getPot

功能說明： 讀取 MATRIX 電位器（旋鈕）數值。

參數：

回傳值：

水位感測器讀取

mini_MXWaterLevel_getLevel

功能說明： 讀取 MATRIX 水位感測器數值。

參數：

回傳值：

土壤濕度感測器讀取

mini_MXSoilMoisture_getMoisture

功能說明： 讀取 MATRIX 土壤濕度感測器數值。

參數：

回傳值：

微動開關狀態

mini_MXMiniatureSwitch_getState

功能說明： 讀取 MATRIX 微動開關狀態。

參數：

回傳值：

PIR 人體紅外線感測器

mini_MXPIR_getState

功能說明： 讀取 MATRIX PIR 人體紅外線感測器狀態。

參數：

回傳值：

DHT 溫濕度感測器輪詢

mini_MXDHT_Polling

功能說明： 更新 DHT 溫濕度感測器的讀數。

參數：

DHT 溫濕度讀取

mini_MXDHT

功能說明： 讀取 DHT 感測器的溫度或濕度。

參數：

回傳值：

DS18B20 溫度感測器

mini_MXOnewireDT

功能說明： 讀取 DS18B20 溫度感測器數值。

參數：

回傳值：

MATRIX 顏色感測器初始化（V1, V2）

mini_i2c_MXcolor_begin

功能說明： 初始化 MATRIX 顏色感測器 V2 版本。

參數：

注意：V1, V2與V3硬體不相容，請注意使用的硬體版本與程式

MATRIX 顏色感測器讀取（V1, V2）

mini_i2c_MXcolor_getColor

功能說明： 讀取 MATRIX 顏色感測器 V2 的顏色辨識結果。

參數：

回傳值：

Color ID對應編號表：

0_ColorID

MATRIX 顏色感測器初始化（V3）

mini_i2c_MXcolorV3_begin

功能說明： 初始化 MATRIX 顏色感測器 V3 版本。

參數：

注意：V1, V2與V3硬體不相容，請注意使用的硬體版本與程式

MATRIX 顏色感測器讀取（V3）

mini_i2c_MXcolorV3_getColor

功能說明： 讀取 MATRIX 顏色感測器 V3 的 RGB 或 HSV 數值。

參數：

回傳值：

Color ID對應編號表：

0_ColorID

MATRIX 雷射測距感測器初始化（V1）

mini_i2c_MXlaser_begin

功能說明： 初始化 MATRIX 雷射測距感測器 V1 版本。

參數：

注意：V1與V2硬體不相容，請注意使用的硬體版本與程式

MATRIX 雷射測距感測器讀取（V1）

mini_i2c_MXlaser_getDistance

功能說明： 讀取 MATRIX 雷射測距感測器 V1 的距離。

參數：

回傳值：

MATRIX 雷射測距感測器初始化（V2）

mini_i2c_MXLaserV2_begin

功能說明： 初始化 MATRIX 雷射測距感測器 V2 版本。

參數：

注意：V1與V2硬體不相容，請注意使用的硬體版本與程式

MATRIX 雷射測距感測器讀取（V2）

mini_i2c_MXLaserV2_getDistance

功能說明： 讀取 MATRIX 雷射測距感測器 V2 的距離。

參數：

回傳值：

MATRIX 手勢感測器初始化

mini_i2c_MXGesture_begin

功能說明： 初始化 MATRIX 手勢感測器。

參數：

MATRIX 手勢感測器讀取

mini_i2c_MXGesture_getGesture

功能說明： 讀取 MATRIX 手勢感測器辨識的手勢。

參數：

回傳值：

MATRIX 手勢感測器判斷

mini_i2c_MXGesture_getGesture_equals

功能說明： 判斷手勢感測器是否偵測到特定手勢。

參數：

回傳值：

MVision 視覺感測器初始化

mini_mvision_begin

功能說明： 初始化 MVision 視覺感測器（透過 UART）。

MVision 讀取資料

mini_mvision_read

功能說明： 讀取 MVision 視覺感測器的辨識結果。

MVision 取得資料

mini_mvision_getdata

功能說明： 取得 MVision 視覺感測器的特定資料欄位。

參數：

回傳值：

HuskyLens 初始化

mini_huskylens_begin

功能說明： 初始化 HuskyLens AI 視覺感測器（透過 UART，Baud Rate 9600）。

註：切勿直接使用原裝的JST to JST線材直接連接HuskyLens Camera，由於腳位定義不同需要跳線!

註：MATRIX UART 腳位由左至右為 (TX, RX, V, G)

HuskyLens 讀取

mini_huskylens_read

功能說明： 讀取 HuskyLens 的辨識結果。

HuskyLens 取得方塊

mini_huskylens_getblock

功能說明： 取得 HuskyLens 辨識的方塊（物體）資訊。

參數：

回傳值：

HuskyLens 取得箭頭

mini_huskylens_getarrow

功能說明： 取得 HuskyLens 辨識的箭頭（線條）資訊。

參數：

回傳值：

HuskyLens 偵測判斷

mini_huskylens_isdetect

功能說明： 判斷 HuskyLens 是否偵測到物體。

回傳值：

MATRIX 循線感測器初始化

mini_i2c_mxlinetracer_begin

功能說明： 初始化 MATRIX 10 通道循線感測器。

參數：

MATRIX 循線感測器校準

mini_i2c_mxlinetracer_calibration

功能說明： 控制循線感測器的校準程序。

參數：

使用說明：

  1. 呼叫「開始校準」
  2. 將感測器移動到白線和黑線上
  3. 呼叫「停止校準」以完成校準

MATRIX 循線感測器讀取

mini_i2c_mxlinetracer_getsensor

功能說明： 讀取指定通道的感測器數值。

參數：

回傳值：

MATRIX 循線感測器取得數值

mini_i2c_mxlinetracer_get_number

功能說明： 取得循線感測器的誤差值或線位置。

參數：

回傳值：

MATRIX 循線感測器取得狀態

mini_i2c_mxlinetracer_get_boolean

功能說明： 查詢循線感測器的狀態。

參數：

回傳值：

MATRIX 循線感測器設定權重

mini_i2c_mxlinetracer_setweights

功能說明： 設定感測器 S6-S10 的權重值，用於計算誤差。

參數：

說明：

MATRIX 循線感測器設定閾值

mini_i2c_mxlinetracer_setthreshold

功能說明： 設定感測器的黑線判斷閾值。

參數：

說明：

第三方模組

HiTechnic 顏色感測器初始化

mini_i2c_HTcolor_begin

功能說明： 初始化 HiTechnic 顏色感測器。

參數：

HiTechnic 顏色感測器讀取

mini_i2c_HTcolor_get

功能說明： 讀取 HiTechnic 顏色感測器的數值。

參數：

回傳值：

DHT11 溫濕度讀取

mini_DHT11get

功能說明： 讀取 DHT11 溫濕度感測器數值。

參數：

回傳值：

DS18B20 溫度讀取

mini_DS18B20_get

功能說明： 讀取 DS18B20 防水溫度感測器。

參數：

回傳值：

Grove 超音波感測器

mini_Grove_US_Get

功能說明： 讀取 Grove 超音波測距感測器距離。

參數：

回傳值：

超音波感測器

mini_USget

功能說明： 讀取標準 HC-SR04 超音波感測器距離。

參數：

回傳值：

計時器重置

mini_timer_reset

功能說明： 重置計時器，從 0 開始計時。

計時器讀取

mini_timer_read

功能說明： 讀取計時器經過的時間。

回傳值：

IoT 物聯網

WiFi 連線

mini_wifi_connect

功能說明： 連接到 WiFi 網路（僅2.4GHz）。

參數：

說明：

WiFi 狀態

mini_wifi_status

功能說明： 檢查 WiFi 連線狀態。

回傳值：

WiFi 本地 IP

mini_wifi_localip

功能說明： 取得裝置的本地 IP 位址。

回傳值：

WiFi 設定靜態 IP

mini_wifi_config

功能說明： 設定裝置使用固定 IP 位址。

參數：

範例：

WiFi 建立熱點

mini_wifi_create_ap

功能說明： 將裝置設為 WiFi 熱點（AP 模式）。

參數：

BLE 初始化

mini_ble_begin

功能說明： 初始化藍牙低功耗（BLE）功能。

BLE 設定名稱

mini_ble_set_name

功能說明： 設定 BLE 裝置的廣播名稱。

參數：

BLE 啟用 Nordic UART

mini_ble_uart_enable

功能說明： 啟用 Nordic UART Service，用於 BLE 序列通訊，較接近以往HC-05的使用方式。

BLE 更新

mini_ble_poll

功能說明： 更新 BLE 連線狀態和資料。應該放在主迴圈中定期執行。

BLE 連線狀態

mini_ble_connected

功能說明： 檢查 BLE 是否有裝置連線。

回傳值：

BLE UART 發送

mini_ble_uart_send

功能說明： 透過 BLE UART 發送訊息。(單次最高128字節)

參數：

BLE 當收到資料時

mini_ble_on_received

功能說明： 當 BLE 收到資料時執行內部程式碼。這是一個 HAT（帽子）積木。

註：請勿在程式畫面中放置多個此方塊，將導致功能異常。

使用方式：

當 BLE 收到資料時
    顯示 BLE 接收到的資料

BLE 接收到的資料

mini_ble_received_data

功能說明： 取得 BLE 接收到的資料內容。(單次最高128字節)

回傳值：

MQTT 連線

mini_mqtt_connect

功能說明： 連線到 MQTT Broker。

參數：

常用免費測試的 Broker：

電腦上可以用來測試MQTT服務的免費網站：

MQTT 迴圈

mini_mqtt_loop

功能說明： 維護 MQTT 連線並處理訊息。應該放在主迴圈中定期執行。

MQTT 訂閱主題

mini_mqtt_subscribe

功能說明： 訂閱 MQTT 主題以接收訊息。

參數：

範例：

MQTT 發佈訊息

mini_mqtt_publish

功能說明： 向 MQTT 主題發佈訊息。

參數：

MQTT 當收到訊息時

mini_mqtt_on_message

功能說明： 當 MQTT 收到訂閱主題的訊息時執行內部程式碼。這是一個 HAT（帽子）積木。

註：請勿在程式畫面中放置多個此方塊，將導致功能異常。

使用方式：

當 MQTT 收到訊息時
    如果 MQTT 接收到的主題 = "robot/cmd"
        顯示 MQTT 接收到的訊息

MQTT 接收到的主題

mini_mqtt_received_topic

功能說明： 取得 MQTT 訊息的來源主題。

回傳值：

MQTT 接收到的訊息

mini_mqtt_received_message

功能說明： 取得 MQTT 訊息的內容。

回傳值：

MQTT 連線狀態

mini_mqtt_is_connected

功能說明： 檢查 MQTT 是否連線中。

回傳值：

控制流程

等待

control_wait

功能說明： 暫停程式執行指定時間。

參數：

如果...那麼

control_if

功能說明： 條件判斷，當條件為真時執行內部程式。

使用方式：

如果 溫度 > 30
    開啟風扇

如果...那麼...否則

control_if_else

功能說明： 條件判斷，根據條件執行不同程式。

使用方式：

如果 按鈕被按下
    LED 亮紅燈
否則
    LED 亮綠燈

重複執行

control_repeat

功能說明： 重複執行內部程式指定次數。

參數：

使用方式：

重複執行 10 次
    閃爍 LED

無限重複

control_forever

功能說明： 無限重複執行內部程式，直到程式停止。

使用方式：

無限重複
    讀取感測器
    更新顯示

等待直到

control_wait_until

功能說明： 暫停程式執行，直到條件為真。

使用方式：

等待直到 按鈕被按下
執行任務

重複直到

control_repeat_until

功能說明： 重複執行內部程式，直到條件為真。

使用方式：

重複直到 距離 < 10
    前進
煞車

取得執行時間

mini_millis

功能說明： 取得程式開始執行後經過的毫秒數。

回傳值：

用途：

運算子

映射範圍

mini_map

功能說明： 將數值從一個範圍映射到另一個範圍。

參數：

範例：

限制範圍

operator_constrain

功能說明： 限制數值在指定範圍內。

因為方式constrain()底層設計原因，請避免在括號內使用變數與常數以外的資料，否則可能導致錯誤的結果。

參數：

範例：

加法

operator_add

功能說明： 計算兩個數值的和。

減法

operator_subtract

功能說明： 計算兩個數值的差。

乘法

operator_multiply

功能說明： 計算兩個數值的積。

除法

operator_divide

功能說明： 計算兩個數值的商。

隨機數

operator_random

功能說明： 產生指定範圍內的隨機整數。

參數：

設定隨機種子

mini_randomSeed

功能說明： 設定隨機數產生器的種子值。

參數：

用途：

小於

operator_lt

功能說明： 判斷第一個數值是否小於第二個數值。

回傳值：

等於

operator_equals

功能說明： 判斷兩個數值是否相等。(也可用於字串比較)

回傳值：

大於

operator_gt

功能說明： 判斷第一個數值是否大於第二個數值。

回傳值：

布林常數

operator_const_bool

功能說明： 提供 true 或 false 布林常數。

且（AND）

operator_and

功能說明： 邏輯 AND 運算，兩個條件都為真時回傳真。

回傳值：

或（OR）

operator_or

功能說明： 邏輯 OR 運算，至少一個條件為真時回傳真。

回傳值：

非（NOT）

operator_not

功能說明： 邏輯 NOT 運算，反轉布林值。

回傳值：

字串連接

operator_join

功能說明： 連接兩個字串。

範例：

三字串連接

operator_join_three

功能說明： 連接三個字串。

取得字元

operator_letter_of

功能說明： 取得字串中指定位置的字元。

參數：

回傳值：

字串長度

operator_length

功能說明： 取得字串的長度。

回傳值：

轉換為字串

operator_toString

功能說明： 將數值轉換為字串。

轉換為浮點數

operator_toFloat

功能說明： 將字串轉換為浮點數。

取餘數

operator_mod

功能說明： 計算除法的餘數。

範例：

四捨五入

operator_round

功能說明： 將數值四捨五入到最接近的整數。

數學運算

operator_mathop

功能說明： 執行進階數學運算。

選項：

變數

變數分類提供了建立和管理變數的功能。

建立變數

點擊「建立變數」按鈕可以建立新的變數。

設定變數

將數值存入變數中。

讀取變數

取得變數中儲存的數值。

變數增加

將變數的值增加指定數量。

自訂積木

自訂積木分類允許您建立可重複使用的程式區塊。

建立自訂積木

  1. 點擊「建立積木」按鈕
  2. 輸入積木名稱
  3. 選擇是否加入參數
  4. 定義積木的程式內容

優點

使用自訂積木

建立後，自訂積木會出現在此分類中，可以像使用其他積木一樣拖曳使用。

自訂積木變數 - 數字

為僅供自訂積木內使用的數字區域變數

自訂積木變數 - 字串

為僅供自訂積木內使用的字串區域變數

自訂積木變數 - 布林值

為僅供自訂積木內使用的布林值區域變數

版本資訊：