MATRIX Mini R4 Blocks API
本文件提供 MATRIX Mini R4 機器人的 Blockly 視覺化編程積木完整API參考。
MATRIX Mini 基礎
初始化設定
功能說明： 初始化 MATRIX Mini 開發板的基本設定。此積木應該放在程式開始處。這是一個 HAT（帽子）積木。 所有除事件、自訂函數外的主要代碼應該放在此處，其概念與Arduino的Setup、Loop相同。
註：請勿在程式畫面中放置多個此方塊，將導致功能異常。
使用方式：
此積木會自動初始化板載硬體，請依需求設定電池、Serial等資訊。
所有程式核心業務邏輯都在此執行，Setup(設置)只會運行一次，Loop(循環)則會不斷重複。
按鈕讀取
功能說明： 讀取板載按鈕的狀態。
回傳值：
true：按鈕被按下false：按鈕未被按下
電源電壓讀取
功能說明： 讀取電源輸入電壓值（單位：伏特）。
回傳值：
浮點數，表示當前電源電壓
數位輸入讀取
功能說明： 讀取指定數位腳位的輸入狀態。
參數：
腳位：選擇要讀取的數位腳位，數位腳位的四根針腳為Left, Right, VCC, GND
回傳值：
HIGH(1)：高電位LOW(0)：低電位
數位輸出設定
功能說明： 設定指定數位腳位的輸出狀態。
參數：
腳位：選擇要設定的數位腳位，數位腳位的四根針腳為Left, Right, VCC, GND
狀態：HIGH 或 LOW
類比輸入讀取
功能說明： 讀取指定類比腳位的數值。
參數：
腳位：選擇要讀取的類比腳位，類比腳位的四根針腳為Left, Right, VCC, GND
回傳值：
整數值（0-1023）
直流馬達方向設定
功能說明： 設定直流馬達的旋轉方向。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
方向：正轉或反轉
馬達 PPR 與 RPM 設定
功能說明： 設定編碼器馬達的脈衝數（PPR）和額定轉速（RPM）參數。
參數：
馬達腳位：馬達連接的腳位(M1~M4)
PPR：每轉脈衝數（預設：545）
RPM：額定轉速（預設：200）
說明：
PPR 值取決於使用的編碼器馬達規格，常見馬達參考數值：
MATRIX TT Encoder Motor: 545
LEGO Mid Motor: 360
Ranger 180 Motor: 695
RPM 值用於速度控制計算，常見馬達參考數值：
MATRIX TT Encoder Motor: 200
LEGO Mid Motor: 260
Ranger 180 Motor: 240
馬達功率控制
功能說明： 設定馬達功率(PWM)並開始運轉。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
速度：-100% 到 100%（負數為反轉）
馬達速度控制
功能說明： 設定馬達速度並開始運轉，但通過Encoder實時計算速度，並利用PID進行穩定的速度控制。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
速度：-100% 到 100%（負數為反轉）
馬達煞車
功能說明： 停止馬達並進行煞車。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
煞車方法：Brake為通過馬達H橋驅動晶片加速停車、Coast為鬆油門滑行、Hold為PID煞車確保角度穩定(尚未推出)
編碼器重置
功能說明： 將編碼器計數值歸零。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
編碼器讀取
功能說明： 讀取編碼器的當前計數值。
參數：
馬達：選擇 馬達連接的腳位(M1~M4)
回傳值：
馬達已經運轉的角度(degrees)
RC 伺服馬達方向設定
功能說明： 設定 RC 伺服馬達的旋轉方向。
參數：
伺服馬達：選擇 RC Servo連接的腳位
方向：正向或反向
RC 伺服馬達角度設定
功能說明： 設定 RC 伺服馬達的角度位置。
非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)
參數：
伺服馬達：選擇 RC Servo連接的腳位
角度：0-180 度 (如欲控制180以上角度之Servo，則將0-270重新映射到0-180即可使用)
移動控制
本分類提供了機器人移動的高階控制積木，包含同步控制、陀螺儀輔助等功能。
底盤配置設定
功能說明：
如使用非MATRIX馬達，使用前請先通過馬達方塊配置好PPR、RPM、方向等資訊。
配置左右馬達及其反轉設定，用於差動驅動機器人。
參數：
左馬達腳位：選擇 馬達連接的腳位(M1~M4)
左馬達反轉：是否反轉左馬達方向
右馬達腳位：選擇 馬達連接的腳位(M1~M4)
右馬達反轉：是否反轉右馬達方向
PID 控制參數設定
功能說明： 設定 PID 控制器的參數，用於移動同步或陀螺儀控制。
參數：
PID 類型：MoveSync（馬達同步控制）、MoveGyro（陀螺儀移動）、TurnGyro（陀螺儀轉彎）
Kp：比例增益
Ki：積分增益
Kd：微分增益
調整建議：
增加 Kp 可提高反應速度，但過大會震盪
Ki 用於消除穩態誤差
Kd 可減少超調，提高穩定性
預設PID數值(Kp, Ki, Kd)參考：
MoveSync:
LEGO-MID(0.002, 0.00, 0.004)
MATRIX-TT(0.02, 0.00, 0.04)
MoveGyro:
LEGO-MID(0.52, 0.00, 0.15)
MATRIX-TT(6.01, 0.00, 2.15)
TurnGyro:
LEGO-MID(22.75, 0.02, 1.54)
MATRIX-TT(22.75, 0.08, 0.25)
移動指定距離/角度
功能說明： 控制機器人移動指定的距離或角度。
參數：
單位：秒、度數或圈數
數值：移動量
左輪速度：-100 到 100
右輪速度：-100 到 100
同步移動指定距離/角度
功能說明： 使用 PID 同步控制，使左右輪保持一致的移動。
參數：
單位：秒、度數或圈數
數值：移動量
左輪速度：-100 到 100
右輪速度：-100 到 100
特點：
使用 PID 控制確保左右輪同步
適合需要直線行駛的場合
陀螺儀輔助移動
功能說明： 使用陀螺儀感測器輔助，保持直線移動。
參數：
單位：秒、度數或圈數
數值：移動量
速度：0 到 100
特點：
利用陀螺儀修正方向偏差
適合長距離直線移動
連續移動
功能說明： 啟動連續移動，直到停止指令。*功率為PWM輸出，無PID速控，適合搭配用戶自己寫的循線或其他算法(如PID)使用
參數：
左輪速度：-100 到 100
右輪速度：-100 到 100
連續同步移動
功能說明： 使用 PID 同步控制的連續移動。
參數：
左輪速度：-100 到 100
右輪速度：-100 到 100
連續陀螺儀直線移動
功能說明： 使用陀螺儀輔助的連續直線移動。
參數：
速度：0 到 100
陀螺儀轉彎(單輪轉)
功能說明： 控制機器人轉向指定角度，可設定轉彎速度。使用陀螺儀之Yaw Heading來進行轉向角度偵測。
參數：
角度：轉彎航向角（度），正值為順時針，負值為逆時針
速度：0 到 100
特點：
使用陀螺儀確保精確轉向
陀螺儀轉彎(雙輪轉)
功能說明： 控制機器人轉向指定角度，可設定轉彎速度。使用陀螺儀之Yaw Heading來進行轉向角度偵測。
參數：
角度：轉彎航向角（度），正值為順時針，負值為逆時針
速度：0 到 100
底盤移動累積角度
功能說明： 讀取馬達從上次重置後累積轉動的角度值，可用於計算行駛距離。 其計算方法為 (abs(leftMotorDegs) + abs(rightMotorDegs)) / 2。 註: 與原有馬達之Encoder角度計算不衝突。
回傳值：
馬達累積轉動的角度（度）
重置底盤累積角度
功能說明： 將底盤累積角度重置為零，用於重新開始距離計算。建議在需要精確測量距離前先執行重置。 註: 與原有馬達之Encoder角度計算不衝突。
停止移動
功能說明： 停止機器人移動。 煞車方法：Brake為通過馬達H橋驅動晶片加速停車、Coast為鬆油門滑行、Hold為PID煞車確保角度穩定(尚未推出)
外觀與顯示
RGB LED 設定
功能說明： 設定板載 RGB LED 的顏色。
參數：
LED：選擇要控制的 LED
R：紅色亮度（0-255）
G：綠色亮度（0-255）
B：藍色亮度（0-255）
蜂鳴器播放頻率
功能說明： 以指定頻率和音量播放音調。
非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)
參數：
頻率：音調頻率（Hz）
播放時長：毫秒(ms)
蜂鳴器播放音符
功能說明： 播放預定義的音符。
非阻塞函數，程式會立刻繼續向下執行，必要時請手動添加延遲(delay)
參數：
音符：選擇音符（如 C4、D4、E4 等）
播放時長：毫秒(ms)
蜂鳴器停止
功能說明： 停止蜂鳴器播放。
OLED 清除螢幕
功能說明： 清除 OLED 顯示器的所有內容。
OLED 顯示文字
功能說明： 在 OLED 螢幕的指定位置顯示文字。
參數：
文字：要顯示的文字內容
X 座標：水平位置（像素）(0-128)
Y 座標：垂直位置（像素）(0-32)
更新：為了避免過多的更新螢幕導致閃爍，多個螢幕顯示可以只在最後一個方塊更新畫面，即可避免閃爍問題。
OLED 設定文字大小
功能說明： 設定 OLED 顯示的文字大小。
參數：
大小：1-3（數字越大文字越大）
OLED 設定文字顏色
功能說明： 設定 OLED 顯示的文字顏色。
參數：
顏色：白色或黑色
序列通訊
USB 序列輸出（不換行）
功能說明： 透過 USB 序列埠輸出文字，不自動換行。
參數：
文字：要輸出的內容
USB 序列輸出（換行）
功能說明： 透過 USB 序列埠輸出文字，並自動換行。
參數：
文字：要輸出的內容
USB 序列寫入位元組
功能說明： 透過 USB 序列埠寫入原始位元組資料。
參數：
資料：要寫入的位元組值
USB 序列輸出三軸資料
功能說明： 以特定格式輸出三軸感測器資料，方便軟體右下角的 Serial Plotter 圖表顯示。
參數：
數值1：第一軸數值
數值2：第二軸數值
數值3：第三軸數值
延遲：輸出間隔（毫秒）
USB 序列可讀取資料檢查
功能說明： 檢查序列埠緩衝區是否有可讀取的資料。
回傳值：
整數，表示可讀取的位元組數
USB 序列讀取
功能說明： 從序列埠讀取一個字元。
回傳值：
整數（ASCII 值），若無資料則回傳 -1
感測器
MJ2 手把輪詢
功能說明： 更新 MJ2(PS2) 手把的狀態資料。應該放在主迴圈中定期執行。
**MJ2手把的連接方式指南：
MJ2 按鈕狀態
功能說明： 讀取 MJ2(PS2) 手把的按鈕狀態。
如何連接MJ2手把？請向上滑動至"MJ2 手把輪詢"小節，有連接指南。
參數：
按鈕：選擇要讀取的按鈕
回傳值：
true：按鈕被按下false：按鈕未被按下
MJ2 搖桿數值
功能說明： 讀取 MJ2(PS2) 手把搖桿的類比數值。
如何連接MJ2手把？請向上滑動至"MJ2 手把輪詢"小節，有連接指南。
參數：
搖桿：選擇左搖桿或右搖桿的 X/Y 軸
回傳值：
0-255 (中心點約為 128、X軸由左至右0-255、Y軸由上至下0-255)
IMU 重置
功能說明： 重置板載 IMU（慣性測量單元）的數值。
IMU 加速度讀取
功能說明： 讀取加速度感測器數值。
參數：
軸向：X、Y 或 Z 軸
回傳值：
浮點數（單位：g）
IMU 陀螺儀讀取
功能說明： 讀取陀螺儀角速度。
參數：
軸向：X、Y 或 Z 軸
回傳值：
浮點數（單位：度/秒）
IMU 歐拉角讀取
功能說明： 讀取姿態角度（Roll、Pitch、Yaw）。
參數：
角度：Roll（橫滾）、Pitch（俯仰）或 Yaw（偏航）
回傳值：
浮點數（單位：度）
灰階感測器讀取
功能說明： 讀取 MATRIX 灰階感測器數值。
參數：
腳位：連接的類比腳位
回傳值：
0-1023（數值越小表示越深色）
電位器讀取
功能說明： 讀取 MATRIX 電位器（旋鈕）數值。
參數：
腳位：連接的類比腳位
回傳值：
0-1023
水位感測器讀取
功能說明： 讀取 MATRIX 水位感測器數值。
參數：
腳位：連接的類比腳位
回傳值：
0-1023（數值越大表示水位越高）
土壤濕度感測器讀取
功能說明： 讀取 MATRIX 土壤濕度感測器數值。
參數：
腳位：連接的類比腳位
回傳值：
0-1023（數值越大表示濕度越高）
微動開關狀態
功能說明： 讀取 MATRIX 微動開關狀態。
參數：
腳位：連接的數位腳位(D1-D4)
回傳值：
true：開關被觸發false：開關未觸發
PIR 人體紅外線感測器
功能說明： 讀取 MATRIX PIR 人體紅外線感測器狀態。
參數：
腳位：連接的數位腳位(D1-D4)
回傳值：
true：偵測到人體移動false：未偵測到移動
DHT 溫濕度感測器輪詢
功能說明： 更新 DHT 溫濕度感測器的讀數。
參數：
腳位：連接的數位腳位(D1-D4)
DHT 溫濕度讀取
功能說明： 讀取 DHT 感測器的溫度或濕度。
參數：
腳位：連接的數位腳位(D1-D4)
類型：溫度或濕度
回傳值：
浮點數（溫度單位：°C，濕度單位：%）
DS18B20 溫度感測器
功能說明： 讀取 DS18B20 溫度感測器數值。
參數：
腳位：連接的數位腳位(D1-D4)
回傳值：
浮點數（單位：°C）
MATRIX 顏色感測器初始化（V1, V2）
功能說明： 初始化 MATRIX 顏色感測器 V2 版本。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
注意：V1, V2與V3硬體不相容，請注意使用的硬體版本與程式
MATRIX 顏色感測器讀取（V1, V2）
功能說明： 讀取 MATRIX 顏色感測器 V2 的顏色辨識結果。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
模式：Color ID(樂高顏色標準)、RGB、HSV、CMYK
回傳值：
對應的數值
Color ID對應編號表：
MATRIX 顏色感測器初始化（V3）
功能說明： 初始化 MATRIX 顏色感測器 V3 版本。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
注意：V1, V2與V3硬體不相容，請注意使用的硬體版本與程式
MATRIX 顏色感測器讀取（V3）
功能說明： 讀取 MATRIX 顏色感測器 V3 的 RGB 或 HSV 數值。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
模式：Color ID(樂高顏色標準)、RGBC、HSV
回傳值：
對應的數值
Color ID對應編號表：
MATRIX 雷射測距感測器初始化（V1）
功能說明： 初始化 MATRIX 雷射測距感測器 V1 版本。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
注意：V1與V2硬體不相容，請注意使用的硬體版本與程式
MATRIX 雷射測距感測器讀取（V1）
功能說明： 讀取 MATRIX 雷射測距感測器 V1 的距離。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
回傳值：
整數（單位：公釐）
MATRIX 雷射測距感測器初始化（V2）
功能說明： 初始化 MATRIX 雷射測距感測器 V2 版本。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
注意：V1與V2硬體不相容，請注意使用的硬體版本與程式
MATRIX 雷射測距感測器讀取（V2）
功能說明： 讀取 MATRIX 雷射測距感測器 V2 的距離。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
回傳值：
整數（單位：公釐）
MATRIX 手勢感測器初始化
功能說明： 初始化 MATRIX 手勢感測器。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
MATRIX 手勢感測器讀取
功能說明： 讀取 MATRIX 手勢感測器辨識的手勢。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
回傳值：
數字：0: None, 1: Right, 2: Left, 3: Up, 4: Down, 5: Forward, 6: Backward 7: Clockwise, 8: Anti-Clockwise, 9: Wave
MATRIX 手勢感測器判斷
功能說明： 判斷手勢感測器是否偵測到特定手勢。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
手勢：要判斷的手勢類型
回傳值：
true或false
MVision 視覺感測器初始化
功能說明： 初始化 MVision 視覺感測器（透過 UART）。
MVision 讀取資料
功能說明： 讀取 MVision 視覺感測器的辨識結果。
MVision 取得資料
功能說明： 取得 MVision 視覺感測器的特定資料欄位。
參數：
資料類型：用戶於MVision Camera撰寫程式時自訂
回傳值：
整數
HuskyLens 初始化
功能說明： 初始化 HuskyLens AI 視覺感測器（透過 UART，Baud Rate 9600）。
註：切勿直接使用原裝的JST to JST線材直接連接HuskyLens Camera，由於腳位定義不同需要跳線!
註：MATRIX UART 腳位由左至右為 (TX, RX, V, G)
HuskyLens 讀取
功能說明： 讀取 HuskyLens 的辨識結果。
HuskyLens 取得方塊
功能說明： 取得 HuskyLens 辨識的方塊（物體）資訊。
參數：
索引：方塊編號
資料類型：ID、X、Y、寬度、高度
回傳值：
整數
HuskyLens 取得箭頭
功能說明： 取得 HuskyLens 辨識的箭頭（線條）資訊。
參數：
索引：箭頭編號
資料類型：起點 X、起點 Y、終點 X、終點 Y
回傳值：
整數
HuskyLens 偵測判斷
功能說明： 判斷 HuskyLens 是否偵測到物體。
回傳值：
true或false
MATRIX 循線感測器初始化
功能說明： 初始化 MATRIX 10 通道循線感測器。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
MATRIX 循線感測器校準
功能說明： 控制循線感測器的校準程序。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
動作：開始校準或停止校準
使用說明：
呼叫「開始校準」
將感測器移動到白線和黑線上
呼叫「停止校準」以完成校準
MATRIX 循線感測器讀取
功能說明： 讀取指定通道的感測器數值。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
感測器編號：1-10
回傳值：
整數（0-100，數值越高表示越接近黑線）
MATRIX 循線感測器取得數值
功能說明： 取得循線感測器的誤差值或線位置。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
類型：誤差值（ERROR）、線寬（Line Width）、路口類型（Junction Type）、最後在線感應器（Last Sensor）
回傳值：
浮點數
ERROR：-4.5 到 4.5（0 表示正中央，其數值範圍可通過比例調整）
Line Width：0 到 10
Junction Type：0 = None, 1 = Left, 2 = Right, 3 = T or Cross, 4 = Unknown/None
Last Sensor：1 - 10
MATRIX 循線感測器取得狀態
功能說明： 查詢循線感測器的狀態。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
類型：感應器是否還在線上
回傳值：
true或false
MATRIX 循線感測器設定權重
功能說明： 設定感測器 S6-S10 的權重值，用於計算誤差。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
S6-S10：各通道權重（預設：0.5, 1.5, 2.5, 3.5, 4.5）
說明：
權重值影響誤差計算的靈敏度
通常對稱設定（S1=-S10, S2=-S9...）
MATRIX 循線感測器設定閾值
功能說明： 設定感測器的黑線判斷閾值。
參數：
I2C 腳位：I2C0, Port A3 (循線感應器當前版本僅支持連接原生通道)
閾值：0-100（預設：30）
說明：
數值越高，判斷為黑線的標準越寬鬆
建議先校準後再調整此值
第三方模組
HiTechnic 顏色感測器初始化
功能說明： 初始化 HiTechnic 顏色感測器。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
HiTechnic 顏色感測器讀取
功能說明： 讀取 HiTechnic 顏色感測器的數值。
參數：
I2C 腳位：選擇連接的I2C腳位(I2C0-I2C4)
類型：顏色ID (HiTechnic ID)、R、G、B、HSV
回傳值：
整數
DHT11 溫濕度讀取
功能說明： 讀取 DHT11 溫濕度感測器數值。
參數：
腳位：連接的數位腳位(D1-D4)
類型：溫度或濕度
回傳值：
整數（溫度單位：°C，濕度單位：%）
DS18B20 溫度讀取
功能說明： 讀取 DS18B20 防水溫度感測器。
參數：
腳位：連接的數位腳位(D1-D4)
回傳值：
浮點數（單位：°C）
Grove 超音波感測器
功能說明： 讀取 Grove 超音波測距感測器距離。
參數：
腳位：連接的數位腳位(D1-D4)
回傳值：
浮點數（單位：公分）
超音波感測器
功能說明： 讀取標準 HC-SR04 超音波感測器距離。
參數：
Trig 腳位：觸發腳位
Echo 腳位：回音腳位
回傳值：
浮點數（單位：公分）
計時器重置
功能說明： 重置計時器，從 0 開始計時。
計時器讀取
功能說明： 讀取計時器經過的時間。
回傳值：
整數（單位：毫秒）
IoT 物聯網
WiFi 連線
功能說明： 連接到 WiFi 網路（僅2.4GHz）。
參數：
SSID：WiFi 網路名稱
密碼：WiFi 密碼
說明：
Arduino Uno R4 WiFi晶片僅支援 2.4GHz WiFi
連線過程需要數秒時間
WiFi 狀態
功能說明： 檢查 WiFi 連線狀態。
回傳值：
true：已連線false：未連線
WiFi 本地 IP
功能說明： 取得裝置的本地 IP 位址。
回傳值：
字串（例如："192.168.1.100"）
WiFi 設定靜態 IP
功能說明： 設定裝置使用固定 IP 位址。
參數：
IP1-IP4：IP 位址的四個數值
範例：
設定 192.168.4.1
WiFi 建立熱點
功能說明： 將裝置設為 WiFi 熱點（AP 模式）。
參數：
SSID：熱點名稱
密碼：熱點密碼（至少 8 位）
BLE 初始化
功能說明： 初始化藍牙低功耗（BLE）功能。
BLE 設定名稱
功能說明： 設定 BLE 裝置的廣播名稱。
參數：
名稱：顯示的裝置名稱
BLE 啟用 Nordic UART
功能說明： 啟用 Nordic UART Service，用於 BLE 序列通訊，較接近以往HC-05的使用方式。
BLE 更新
功能說明： 更新 BLE 連線狀態和資料。應該放在主迴圈中定期執行。
BLE 連線狀態
功能說明： 檢查 BLE 是否有裝置連線。
回傳值：
true：已連線false：未連線
BLE UART 發送
功能說明： 透過 BLE UART 發送訊息。(單次最高128字節)
參數：
訊息：要發送的文字內容
BLE 當收到資料時
功能說明： 當 BLE 收到資料時執行內部程式碼。這是一個 HAT（帽子）積木。
註：請勿在程式畫面中放置多個此方塊，將導致功能異常。
使用方式：
當 BLE 收到資料時顯示 BLE 接收到的資料
BLE 接收到的資料
功能說明： 取得 BLE 接收到的資料內容。(單次最高128字節)
回傳值：
字串
MQTT 連線
功能說明： 連線到 MQTT Broker。
參數：
Broker：MQTT 伺服器位址
Port：連接埠（預設：1883）
Client ID：客戶端識別碼（留空自動生成）
使用者名稱：登入帳號（選填）
密碼：登入密碼（選填）
常用免費測試的 Broker：
broker.hivemq.com（免費公開）
test.mosquitto.org（測試用）
電腦上可以用來測試MQTT服務的免費網站：
MQTT 迴圈
功能說明： 維護 MQTT 連線並處理訊息。應該放在主迴圈中定期執行。
MQTT 訂閱主題
功能說明： 訂閱 MQTT 主題以接收訊息。
參數：
主題：要訂閱的主題路徑
範例：
"matrix/r4/test"
"robot/sensors/#"（# 表示通配符）
MQTT 發佈訊息
功能說明： 向 MQTT 主題發佈訊息。
參數：
主題：目標主題路徑
訊息：要發送的內容
MQTT 當收到訊息時
功能說明： 當 MQTT 收到訂閱主題的訊息時執行內部程式碼。這是一個 HAT（帽子）積木。
註：請勿在程式畫面中放置多個此方塊，將導致功能異常。
使用方式：
xxxxxxxxxx當 MQTT 收到訊息時如果 MQTT 接收到的主題 = "robot/cmd"顯示 MQTT 接收到的訊息
MQTT 接收到的主題
功能說明： 取得 MQTT 訊息的來源主題。
回傳值：
字串
MQTT 接收到的訊息
功能說明： 取得 MQTT 訊息的內容。
回傳值：
字串
MQTT 連線狀態
功能說明： 檢查 MQTT 是否連線中。
回傳值：
true：已連線false：未連線
控制流程
等待
功能說明： 暫停程式執行指定時間。
參數：
時間：等待的毫秒數（1000ms = 1秒）
如果...那麼
功能說明： 條件判斷，當條件為真時執行內部程式。
使用方式：
xxxxxxxxxx如果 溫度 > 30開啟風扇
如果...那麼...否則
功能說明： 條件判斷，根據條件執行不同程式。
使用方式：
xxxxxxxxxx如果 按鈕被按下LED 亮紅燈否則LED 亮綠燈
重複執行
功能說明： 重複執行內部程式指定次數。
參數：
次數：重複執行的次數
使用方式：
xxxxxxxxxx重複執行 10 次閃爍 LED
無限重複
功能說明： 無限重複執行內部程式，直到程式停止。
使用方式：
xxxxxxxxxx無限重複讀取感測器更新顯示
等待直到
功能說明： 暫停程式執行，直到條件為真。
使用方式：
xxxxxxxxxx等待直到 按鈕被按下執行任務
重複直到
功能說明： 重複執行內部程式，直到條件為真。
使用方式：
xxxxxxxxxx重複直到 距離 < 10前進煞車
取得執行時間
功能說明： 取得程式開始執行後經過的毫秒數。
回傳值：
整數（單位：毫秒）
用途：
計時功能
非阻塞式延遲
事件間隔控制
運算子
映射範圍
功能說明： 將數值從一個範圍映射到另一個範圍。
參數：
數值：要映射的數值
來源最小值：原始範圍下限
來源最大值：原始範圍上限
目標最小值：目標範圍下限
目標最大值：目標範圍上限
範例：
將 0-1023 的感測器值映射到 0-100 的百分比
限制範圍
功能說明： 限制數值在指定範圍內。
因為方式constrain()底層設計原因，請避免在括號內使用變數與常數以外的資料，否則可能導致錯誤的結果。
參數：
數值：要限制的數值
最小值：下限
最大值：上限
範例：
限制馬達速度在 -100 到 100 之間
加法
功能說明： 計算兩個數值的和。
減法
功能說明： 計算兩個數值的差。
乘法
功能說明： 計算兩個數值的積。
除法
功能說明： 計算兩個數值的商。
隨機數
功能說明： 產生指定範圍內的隨機整數。
參數：
起始值：範圍下限
結束值：範圍上限（包含）
設定隨機種子
功能說明： 設定隨機數產生器的種子值。
參數：
種子：整數值
用途：
產生可重現的隨機序列
使用 0 來產生真正隨機的序列
小於
功能說明： 判斷第一個數值是否小於第二個數值。
回傳值：
true或false
等於
功能說明： 判斷兩個數值是否相等。(也可用於字串比較)
回傳值：
true或false
大於
功能說明： 判斷第一個數值是否大於第二個數值。
回傳值：
true或false
布林常數
功能說明： 提供 true 或 false 布林常數。
且（AND）
功能說明： 邏輯 AND 運算，兩個條件都為真時回傳真。
回傳值：
true或false
或（OR）
功能說明： 邏輯 OR 運算，至少一個條件為真時回傳真。
回傳值：
true或false
非（NOT）
功能說明： 邏輯 NOT 運算，反轉布林值。
回傳值：
true或false
字串連接
功能說明： 連接兩個字串。
範例：
"Hello" + "World" = "HelloWorld"
三字串連接
功能說明： 連接三個字串。
取得字元
功能說明： 取得字串中指定位置的字元。
參數：
位置：字元位置（從 1 開始）
字串：來源字串
回傳值：
單一字元
字串長度
功能說明： 取得字串的長度。
回傳值：
整數（字元數）
轉換為字串
功能說明： 將數值轉換為字串。
轉換為浮點數
功能說明： 將字串轉換為浮點數。
取餘數
功能說明： 計算除法的餘數。
範例：
5 mod 2 = 1
四捨五入
功能說明： 將數值四捨五入到最接近的整數。
數學運算
功能說明： 執行進階數學運算。
選項：
abs：絕對值
floor：無條件捨去
ceiling：無條件進位
sqrt：平方根
sin、cos、tan：三角函數 (返回以弧度為單位的值。結果介於-1和1之間)
asin、acos、atan：反三角函數(返回以弧度為單位的值。結果介於-1和1之間)
ln：自然對數
log：常用對數
e^：指數函數
10^：10 的次方
變數
變數分類提供了建立和管理變數的功能。
建立變數
點擊「建立變數」按鈕可以建立新的變數。
設定變數
將數值存入變數中。
讀取變數
取得變數中儲存的數值。
變數增加
將變數的值增加指定數量。
自訂積木
自訂積木分類允許您建立可重複使用的程式區塊。
建立自訂積木
點擊「建立積木」按鈕
輸入積木名稱
選擇是否加入參數
定義積木的程式內容
優點
程式碼重複使用
提高程式可讀性
簡化複雜邏輯
方便維護和修改
使用自訂積木
建立後，自訂積木會出現在此分類中，可以像使用其他積木一樣拖曳使用。
自訂積木變數 - 數字
為僅供自訂積木內使用的數字區域變數
自訂積木變數 - 字串
為僅供自訂積木內使用的字串區域變數
自訂積木變數 - 布林值
為僅供自訂積木內使用的布林值區域變數
版本資訊：
文件版本：1.0
最後更新：2025年12月
適用硬體：MATRIX Mini R4 (Arduino Uno R4 WiFi)