2026年11月22日 星期日

ESP32 IoT in Practice EP1: One DS18B20, Four Paths — Serial, Bluetooth, MQTT and a Self-Hosted Pi | ESP32 物聯網實戰 EP1:一顆溫度感測器的四條路(序列埠、藍牙、MQTT、自架 Pi)

📺 影片版(約 17 分鐘,有章節可跳著看):本集整理成一支影片,細節在下方文字與各篇原文。
YouTube:https://youtu.be/U8Ih9Xif6Vc(winson-DIY 頻道)

這是「ESP32 物聯網實戰」系列第一集的總整理。同一顆 DS18B20 溫度感測器,我在 2023 年陸續試了四種把讀值送出去的方法:序列埠接 C# 畫曲線、藍牙 SPP 上手機、公用 MQTT broker 接 Node-RED、在 Raspberry Pi 自架 Mosquitto 再用 cpolar 開通道。這篇把五篇原文串成一條線,並整理每條路的坑。

This is the wrap-up of EP1 of the "ESP32 IoT in Practice" series: one DS18B20 sensor, four ways to move its reading — serial to a C# chart, Bluetooth SPP to a phone, a public MQTT broker to Node-RED, and a self-hosted Mosquitto broker on a Raspberry Pi exposed through a cpolar tunnel.

本集用到的原文 | Original posts

第一章 DS18B20 與 1-Wire

一條資料線、每顆 64 位元序號、一條線可掛多顆;12 位元轉換要 750 ms,上電預設 85°C、斷線讀到 -127。DQ 要 4.7kΩ 上拉,ESP32 建議接 3.3V。序列埠指令 VER/DS18B20_ON/DS18B20_OFF(小寫自動轉大寫,用 strstr 比對)。

第二章 序列埠+C# 曲線

Node5 把溫度包成 JSON 經 Mesh 交給接 USB 的 Node1,C# 解析後畫曲線;手握探頭,不到 40 秒從約 23.7°C 升到 31°C。兩個坑:requestTemperatures 卡 750 ms、C# DataReceived 收到半行要先緩衝。

第三章 藍牙 SPP 上手機

BluetoothSerial 開「BT_BS18B20」,送「E+溫度」給手機 App 畫曲線。程式一輪呼叫兩次轉換(約 1.5 秒一筆)、手機端指令函式是空的;ESP32-S3/C3 與 iPhone 要改 BLE。

第四章 MQTT+Node-RED

公用 broker mqtt.eclipseprojects.io,發布 winsondiy/ESP32/temp 與環保署新竹 PM2.5,訂閱 winsondiy/ESP32/led 控制 GPIO16;先用 MQTT Explorer 驗證,再接 Node-RED。公用 broker 人人可讀寫,只適合測試。

第五章 Pi 自架 Mosquitto+cpolar

apt 安裝 mosquitto、兩個終端機 sub/pub 測試、一行腳本裝 Node-RED,cpolar 把本機 1883 開成 1.tcp.cpolar.io:10521,ESP32 只改 server 與 port。Mosquitto 2.0 預設只聽本機,區網直連要加 listener 與帳密。

第六章 四條路怎麼選

桌邊量測用序列埠、現場看用藍牙、快速驗證用公用 MQTT、長期使用自架 broker。下一集:沒有路由器也能組網的 ESP32 WiFi Mesh。

補充:原文沒寫到的原理與常見坑

補充一:DS18B20 與 1-Wire 重點

DS18B20 是 1-Wire 數位溫度感測器:一條資料線 DQ 同時負責傳指令和回資料,每顆出廠都有唯一的 64 位元 ROM 序號,所以同一條線可以並聯很多顆,用序號分辨。

項目規格(datasheet)
量測範圍-55~+125°C
精度±0.5°C(-10~+85°C)
解析度/轉換時間9 位元 93.75 ms、10 位元 187.5 ms、11 位元 375 ms、12 位元 750 ms(0.0625°C)
電源3.0~5.5V,也可寄生供電
特殊讀值上電預設 +85°C;DallasTemperature 讀不到時回 -127(DEVICE_DISCONNECTED_C)

接線注意:DQ 要有 4.7kΩ 上拉到 VCC(小模組板通常已焊好,防水探頭要自己加)。原文電路是 5V 供電、資料接 GPIO4;若上拉接 5V,DQ 閒置就是 5V,超過 ESP32 GPIO 的 3.3V 額定,建議 DS18B20 改接 3.3V。

補充二:讀溫度不要卡住主迴圈

requestTemperatures() 預設會等轉換完成才返回,12 位元要等 750 ms。主迴圈還要處理 Mesh、藍牙或 MQTT 時,改成「先發轉換、下一輪再讀」:

sensors.setResolution(12);
sensors.setWaitForConversion(false);   // 不等 750 ms
sensors.requestTemperatures();
unsigned long last = 0;

void loop() {
  if (millis() - last >= 2000) {        // 間隔要大於轉換時間
    last = millis();
    float t = sensors.getTempCByIndex(0);   // 上一輪的結果
    sensors.requestTemperatures();          // 立刻發下一次
    if (t != DEVICE_DISCONNECTED_C) { /* 送出 t */ }
  }
  // 其他工作:mesh.update()/MQTTClient.loop()…
}

(範例程式未實機編譯。)

補充三:藍牙 SPP 的限制

  • SPP(Serial Port Profile)是傳統藍牙(Classic BT)的「無線序列埠」,Arduino-ESP32 的 BluetoothSerial 用起來跟 Serial 一樣。
  • 只有原始 ESP32 有傳統藍牙;ESP32-S3、ESP32-C3 只有 BLE,沒有 BluetoothSerial,要改用 BLE(例如 Nordic UART Service)。
  • iPhone 一般 App 不能用傳統藍牙 SPP,要給 iPhone 看也得改 BLE。
  • 原文 SPP 版程式在 flag.DS18B20Flag == 1 時,先呼叫 vDS18B20Task()(裡面已 requestTemperatures 一次),接著又 requestTemperatures 一次,等於一輪等兩次轉換,12 位元下約 1.5 秒才送一筆(由程式推算);只呼叫一次即可。
  • 原文 BTprocessCommand() 是空函式,所以 DS18B20_ON/OFF 仍從 USB 序列埠下;要從手機開關,把 processCommand() 的判斷搬進去即可。SerialBT.readString() 會等到逾時(預設 1 秒)才返回,指令短的話改用 readStringUntil('\n')。

補充四:MQTT 要知道的幾件事

  • topic 用斜線分層,原文用 winsondiy/ESP32/temp、winsondiy/ESP32/pm2.5_avg(發布)、winsondiy/ESP32/led(訂閱);訂閱端可用 +、# 萬用字元,例如 winsondiy/ESP32/#。
  • QoS 0/1/2:0 送了就算、1 至少一次、2 剛好一次。PubSubClient 發布只支援 QoS 0,訂閱可 0 或 1;預設封包上限 256 位元組(setBufferSize() 可調),keepalive 15 秒。
  • retain:broker 保留最後一筆,新訂閱者一連上就拿到,適合「目前溫度」。遺囑(Last Will):裝置斷線時 broker 代發,例如 status = offline。
  • 公用 broker(mqtt.eclipseprojects.io、test.mosquitto.org)不用註冊,但任何人都能訂閱、也能發布到你的 led topic;只適合測試,topic 前綴取得獨特一點。
  • loop() 裡每 5 秒做一次 HTTPS 查詢(環保署 API),查詢期間 MQTTClient.loop() 跑不到;API 很慢時,可把查詢拉長間隔(PM2.5 每小時才更新),或放到另一個 FreeRTOS 任務。原文程式的間隔是 5000 ms,註解寫「每10秒」,以程式為準。

補充五:Pi 自架 Mosquitto 的設定坑

Mosquitto 2.0 起,沒有設定 listener 時只聽本機(127.0.0.1)。原文用 cpolar 從 Pi 本機轉送 1883,所以不受影響;但同一個區網的 ESP32 直接連 Pi 的 IP 會被拒絕。要讓區網連線,在 /etc/mosquitto/conf.d/ 加一個檔:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

用 sudo mosquitto_passwd -c /etc/mosquitto/passwd esp32 建帳號,重啟 sudo systemctl restart mosquitto;ESP32 端把 MQTTUser/MQTTPassword 填上。透過 cpolar 對外公開時更要設帳密。通道重開後位址或埠號若改變,ESP32 程式的 MQTTServer、MQTTPort 要跟著改;固定位址或改走 Tailscale 等 VPN 可避免(見本系列 EP3)。

補充六:四條路怎麼選

方式距離需要網路適合
序列埠+C#USB 線(或 Mesh 接力)不用桌邊量測、產線治具、要存檔畫圖
藍牙 SPP約 10 公尺不用現場用手機看、單人單機
公用 MQTT有網路就行要快速驗證、多人同時看
自架 MQTT+通道有網路就行要長期使用、資料自己管

ESP32 物聯網實戰系列 | ESP32 IoT in Practice

  • EP1:一顆溫度感測器的四條路(本篇)
  • EP2:沒有路由器的網路:ESP32 WiFi Mesh(製作中)
  • EP3:Pi 5 當 IoT 閘道:熱點、Tailscale、OTA 與繼電器(製作中)
  • EP4:省電與感測進階:深度睡眠、語音控制、WiFi CSI(製作中)

2026年11月21日 星期六

DIY Robot Cars EP3: Two-Wheel Self-Balancing, from Ball-and-Beam PID to an ESP32-S3 Stepper Robot | 自造機器人車 EP3:兩輪自平衡,從球與橫樑 PID 到 ESP32-S3 步進平衡車

📺 影片版(約 19 分鐘,有章節可跳著看):本集整理成一支影片,細節在下方文字與各篇原文。
YouTube:https://youtu.be/B4_qJp1G4Tc(winson-DIY 頻道)

English summary: The final episode of the "DIY Robot Cars" series merges five posts into one story about two-wheel self-balancing: a 2023 ball-and-beam PID rig (HC-SR04 plus a servo), stepper motors with the A4988 and microstepping, the MPU6050 and a complementary filter, and a 2026 ESP32-S3 stepper balancing robot with core 0 running WiFi/OTA/web tuning and core 1 running a 200 Hz interrupt-driven control loop. The tuning log goes from "can't read the IMU" to a 59-second stand within ±2°, with the key lessons: a stepper needs acceleration (not speed) from the angle loop, a "sudden loss of power" was the stepper losing steps at its speed cap, and a half-empty 2S battery and brownouts were the real bottleneck.

這是「自造機器人車」系列的第三集,也是最後一集:兩輪自平衡。把 2023 年的球與橫樑 PID、步進馬達與 A4988、MPU6050,和 2026 年 ESP32-S3 步進平衡車整理成一條故事線。影片約 20 分鐘,有章節可以跳著看;程式全文在各篇原文。

本集章節

  1. 先學 PID:球與橫樑:HC-SR04 量位置、MG995 轉橫樑、PID_v1(Kp 0.8/Ki 0.005/Kd 0.3、REVERSE、輸出 ±25°)、伺服不對稱基準。→ Balance Ball and Beam Control system(2023/11)
  2. 零件:步進馬達、A4988、MPU6050:微步表、3200 步一圈、AccelStepper vs FastAccelStepper、互補濾波。→ ESP32 control stepper motor(2023/12)、ESP32 I2C Bus Scanner – MPU6050(2023/07)、ESP32結合MPU6050用Processing做動態演示(2023/01)
  3. 平衡車架構:ESP32-S3 雙核:腳位重配、core 0 網路/core 1 200 Hz 控制、INT 驅動、狀態機、OTA 安全與回滾。→ ESP32-S3 步進平衡車(2026/11)
  4. 調參:從站不住到站一分鐘:主板沒上電、16 微步驗證、軸與正負號、PD 給加速度、kd 80→250、trim+速度環。
  5. 突然沒力:失步與電池:倒下前 0.1 秒輪速頂到 4000、vmax/amax、電池分壓與校正、半電低於 A4988 8 V、速度環減弱、59 秒 ±2°、brownout。
  6. 成果、坑與系列總整理:調參網頁、最終參數、extern "C" 回滾坑、CDCOnBoot、開機預設不平衡。

補充:原文沒寫到的原理與常見坑

補充一:球與橫樑、平衡車都是「放著就會倒」的系統

球放在稍微傾斜的橫樑上會越滾越快,平衡車放開手會越倒越快——兩者都是不穩定系統,控制器不出手,誤差只會變大。PID 的三項各管一件事:P 依「現在離目標多遠」出力;I 把長時間累積的誤差補掉(例如重心不在正中間);D 看「誤差變化多快」,提前踩煞車、壓住來回擺。球與橫樑的感測器是 HC-SR04,程式裡 distance = duration/29/2 存成整數公分,位置只有 1 公分的解析度,D 項算出來的變化量會一格一格跳,這也是 Kd 不能給太大的原因之一。

原文程式把 PID 輸出(±25°)對應到伺服角度時用了不對稱的基準(輸出為正 92+Output、為負 60+Output),等於手動補機構的死區與零點偏差;換機構時這兩個數字要重新找。

補充二:步進馬達與 A4988 的幾個規格

  • 1.8° 步進角=一圈 200 步;A4988 的 MS1~MS3 全接高是 1/16 微步,一圈 3200 步。平衡車 vmax 4000 steps/s = 1.25 轉/秒。
  • A4988 馬達電源 VMOT 規格 8~35 V(Allegro A4988 datasheet)。2S 18650 滿電 8.4 V、半電約 7.4 V,已經在規格邊緣以下。
  • 電流限制由板上的可變電阻設 Vref:Imax = Vref ÷ (8 × Rs),Rs 是板上的感測電阻(常見 0.05~0.1 Ω,看板子),調之前先查自己那片的電阻值。
  • 步進馬達轉得越快,線圈電流來不及建立(電感+反電動勢),扭力越小;供電電壓越低越明顯。需要的扭力超過當下能給的,就會「失步」:控制器以為輪子在轉,其實沒跟上。
  • AccelStepper 靠程式在迴圈裡不斷呼叫 run() 決定什麼時候出一個脈衝,迴圈被其他事情卡住脈衝就會不均勻;FastAccelStepper 在 ESP32 系列用 MCPWM/PCNT 硬體產生脈衝,控制程式只要更新目標速度。

補充三:互補濾波的直覺

加速度計算出來的傾角(atan2(accY, accZ))不會漂移,但車子一加減速就會被干擾;陀螺儀積分出來的角度短時間很準,但會慢慢漂。互補濾波每一圈做 angle = α·(angle + gyro·dt) + (1−α)·accAngle:短時間信陀螺儀、長時間被加速度計拉回來。時間常數約 τ = α·dt ÷ (1−α);α = 0.98、dt = 5 ms 時 τ ≈ 0.25 秒,也就是大約 0.25 秒以上的偏差會被加速度計慢慢修正。

補充四:為什麼步進平衡車要「PD 給加速度」

直流馬達給電壓,輸出的是力(扭力);步進馬達照指定速度轉,輸出的是速度。把傾斜 θ 的車身推回來,輪子需要的是約 g·tanθ 的水平加速度(倒單擺的近似)。所以角度環輸出加速度、再積分成輪速,才是對步進馬達「說對的語言」;直接把角度換成速度,輪子只會跟著傾角跑,車身持續偏一邊直到輪速飽和——這正是原文 ① 的現象。

自造機器人車系列

  • EP1 ESP32 藍牙遙控車到自動避障:文章/影片
  • EP2 麥克納姆輪:ESP32-CAM 影像車到 Pi 5 自走車:文章/影片
  • EP3 兩輪自平衡(本篇)

Moving My ESP32 RGB LED Matrix Clock to a Raspberry Pi 3 A+ (Part 1): OS Choice and HUB75 Wiring | ESP32 LED 點陣時鐘改用 Pi 3 A+ 驅動(一):系統選擇與 HUB75 接線規劃

【更新】已經實機點亮,接線、踩坑和 Python 時鐘寫在第二篇:ESP32 LED 點陣時鐘改用 Pi 3 A+ 驅動(二):實機點亮與 Python 時鐘。

2021 年我用 ESP32 加上一片 64×32 RGB LED 點陣面板做了一個網路時鐘,可以顯示時間、日期、溫濕度和 PM2.5。這片面板放了幾年,最近手邊多出一片 Raspberry Pi 3 Model A+,就決定把 ESP32 拿掉,改由 Pi 直接驅動面板。這篇是第一篇,記錄為什麼要換、系統怎麼選、線怎麼接。目前還在燒錄系統,下面的接線和指令都還沒在實機上驗證,等點亮之後會再寫一篇實測。

回顧:2021 年的 ESP32 版

原本的做法寫在部落格〈ESP32溫濕度網路時鐘〉:ESP32 連上 Wi-Fi 後,從 NTP 校時,向 OpenWeatherMap 抓天氣、向環保署抓 AQI,再用 Adafruit 的 RGBmatrixPanel 函式庫把資料畫到 HUB75 面板上。最下面一行會輪流顯示溫度、濕度和 PM2.5。

圖說:2021 年的 ESP32 版:時間、星期、日期,最下面一行顯示濕度

圖說:最下面一行輪流顯示溫度、濕度和 PM2.5

它能用,但有幾個地方一直不太順手:

  • 要改函式庫原始碼:RGBmatrixPanel 預設是給 Arduino Uno/Mega 用的,必須手動把 defaultrgbpins 改成 ESP32 的 {25, 26, 27, 21, 22, 23}。函式庫一更新,改過的地方就不見了。
  • Wi-Fi、API 金鑰、生日清單都寫死在程式裡:只要換個網路或改一段文字,就得接 USB 重燒。
  • 畫面偶爾會閃:ESP32 要同時處理 Wi-Fi、HTTP 和掃描面板,在抓資料的那一刻比較容易看出來。

新主角:Raspberry Pi 3 Model A+

圖說:Raspberry Pi 3 Model A+:BCM2837B0、512 MB、只有一個 USB、沒有網孔

  • 處理器:BCM2837B0,四核 Cortex-A53 1.4 GHz
  • 記憶體:512 MB,這是選系統時最大的限制
  • 網路:Wi-Fi 2.4/5 GHz+藍牙 4.2,沒有有線網孔
  • 其他:一個 USB-A、HDMI、CSI 相機、3.5mm 音源,以及標準的 40 pin GPIO

板子比 Pi 3B+ 小,耗電也低,拿來當面板的控制器剛好。驅動 HUB75 面板最常用的是 hzeller/rpi-rgb-led-matrix,它在 Pi 3 上的支援很成熟,也有 Python 綁定。之後畫面就能用 Python 寫,透過 SSH 改完重新啟動服務就好,不必再接線重燒。

架構對照

圖說:面板不變,把中間的控制器從 ESP32 換成 Pi 3 A+,管理改從 gx10 遠端進行

系統選擇:Raspberry Pi OS Lite(32-bit)

512 MB 的記憶體決定了大方向:

  • 選 Lite,不要桌面版:Lite 開機後只用大約 60~80 MB,桌面版在 512 MB 上會很卡。面板也不需要桌面。
  • 選 32-bit:同樣的程式在 32-bit 下佔用的記憶體比較少,除非要用只有 arm64 版本的套件,否則沒必要用 64-bit。
  • 官方系統:hzeller 的函式庫就是建議搭配 Raspberry Pi OS Lite,GPIO 支援也最完整。

這片沒有網孔,所以用 Raspberry Pi Imager 燒錄時,要在進階設定裡先填好主機名稱(我用 pi3-led)、使用者、Wi-Fi 和 開啟 SSH。這樣插卡開機就能直接連上網路,不用接螢幕和鍵盤。

HUB75 接線

面板背面的 16 pin 排針就是 HUB75:R1/G1/B1 和 R2/G2/B2 分別是上半部和下半部的顏色資料,A~D 選掃描的列(64×32 是 1/16 掃描,用 4 條;E 是 64 列的面板才需要),CLK、LAT、OE 是時脈、鎖存和輸出致能。Pi 這邊照 hzeller 的「regular」對應來接,下面的表我已經對照過官方的 wiring.md。

圖說:左:Pi 的 40 pin 排針,標出要用的腳;中:HUB75 接頭;右:對照表

HUB75Pi 腳號GPIOESP32 版用的 GPIO
R1/G1/B123/13/2611/27/725/26/27
R2/G2/B224/21/198/9/1021/22/23
A/B/C/D15/16/18/2222/23/24/2512/13/14/15
CLK/LAT/OE11/7/1217/4/184/2/0
GND6、9、14、20、25…任一—GND

接線時要注意這幾點:

  • 面板要另外接 5V 電源:64×32 全亮白色時可能超過 3~4 A,絕對不能從 Pi 的 5V 腳取電。我會用 5V 4A 以上的電源。
  • 一定要共地:面板電源的 GND 要和 Pi 的 GND 接在一起,否則訊號沒有共同的參考點,畫面會亂。
  • 3.3V 推 5V 面板:Pi 的 GPIO 是 3.3V,大多數面板直接推也能動(ESP32 版就是這樣用的)。如果畫面出現雜點或顏色錯亂,可以加 74HCT245 轉準位,或改用現成的 HUB75 轉接板。
  • 關掉板載音效:Pi 3 A+ 有 3.5mm 音源,板載音效會用到函式庫需要的硬體 PWM,兩個會衝突,一定要關掉。

預計的軟體步驟

系統開機、SSH 連得上之後,預計照下面的順序做(尚未實測,跑完會在下一篇補上實際結果):

# 1. 關掉板載音效(Pi OS Bookworm 之後的 config.txt 在 /boot/firmware/)
sudo sed -i 's/^dtparam=audio=on/dtparam=audio=off/' /boot/firmware/config.txt
echo "blacklist snd_bcm2835" | sudo tee /etc/modprobe.d/blacklist-rgb-matrix.conf
sudo reboot

# 2. 下載並編譯函式庫和範例
sudo apt install -y git build-essential python3-dev
git clone https://github.com/hzeller/rpi-rgb-led-matrix
cd rpi-rgb-led-matrix
make -C examples-api-use

# 3. 跑測試畫面(64×32、regular 對應;Pi 3 通常要加 slowdown)
sudo examples-api-use/demo -D0 --led-rows=32 --led-cols=64 \
     --led-gpio-mapping=regular --led-slowdown-gpio=2

測試畫面正常之後,再依 bindings/python 的說明裝 Python 綁定,把原本的時鐘畫面改寫成 Python。預計的程式骨架大概是這樣:

from rgbmatrix import RGBMatrix, RGBMatrixOptions, graphics

opt = RGBMatrixOptions()
opt.rows, opt.cols = 32, 64
opt.hardware_mapping = "regular"
opt.gpio_slowdown = 2
matrix = RGBMatrix(options=opt)
canvas = matrix.CreateFrameCanvas()
# 每秒畫一次:時間、星期、日期、溫濕度/PM2.5 輪播
# canvas = matrix.SwapOnVSync(canvas)  用雙緩衝避免閃爍

下一步

  • 系統燒好、開機連上 Wi-Fi,加入 Tailscale,之後就能從 gx10 遠端管理
  • 接上面板,跑 demo 確認接線正確,並調整 gpio_slowdown 和亮度
  • 把 ESP32 版的時鐘、星期、日期、溫濕度、PM2.5 和生日提醒改寫成 Python,設成 systemd 服務,開機自動執行
  • 把 Wi-Fi、API 金鑰和顯示內容改成設定檔,以後改內容不用動程式

2026年11月20日 星期五

Moving My ESP32 RGB LED Matrix Clock to a Raspberry Pi 3 A+ (Part 2): First Light and a Python Clock | ESP32 LED 點陣時鐘改用 Pi 3 A+ 驅動(二):實機點亮與 Python 時鐘

接續上一篇的規劃:這次真的把 2021 年那片 64×32 RGB LED 點陣面板從 ESP32 拆下來,改接到 Raspberry Pi 3 Model A+。從燒系統、接排線、第一次點亮,到用 Python 重寫網路時鐘並設成開機自動執行,一個下午就完成了。中間踩了幾個坑,這篇都記下來。

圖說:完成:Python 版時鐘跑在 Pi 3 A+ 上,版面延續 ESP32 版

一、系統:燒成了桌面版,改成開機不進桌面

上一篇建議用 Raspberry Pi OS Lite,但實際燒的時候選到了桌面版(Trixie 32-bit,kernel 6.18)。開機後閒置就用掉 204 MB 記憶體(總共只有 424 MB 可用),其中桌面相關的程式大約佔 130 MB。這次不重燒,直接把開機目標改成文字模式:

sudo systemctl set-default multi-user.target   # 想用桌面時改回 graphical.target

重開機後閒置只剩約 125 MB,跟 Lite 版差不多。

二、網路:找 IP、加家裡的 Wi-Fi、裝 Tailscale

  • 找 IP:不知道 Pi 拿到什麼 IP,就從同網段的電腦整段 ping 一次,再看 ARP 表裡有沒有樹莓派的 MAC(Pi 3 是 b8:27:eb 開頭)。第一次掃的時候找不到,因為 Pi 還在第一次開機(會擴充分割區、自動重開一次);過幾分鐘再掃就出現了,主機名稱.local 也解析得到。
  • 公司、家裡兩個 Wi-Fi:Imager 只設了公司的 AP。這台會帶回家用,所以再用 NetworkManager 加家裡的 2.4 GHz AP,哪個訊號在就連哪個:
    sudo nmcli connection add type wifi con-name winson2.4 ifname wlan0 ssid winson2.4 wifi-sec.key-mgmt wpa-psk wifi-sec.psk '密碼' connection.autoconnect-priority 5
  • Tailscale:用官方的 raspbian trixie 套件庫安裝,tailscale up --hostname=winson-pi3 加入 tailnet。之後不管在公司還是家裡,都用 Tailscale IP 連進去。

另外遇到一個小狀況:筆電 SSH 時跳出 REMOTE HOST IDENTIFICATION HAS CHANGED。原因是這個 IP 以前分給別的裝置用過,筆電的 known_hosts 裡還留著舊紀錄。先比對 Pi 本機的指紋(ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub),確認一致後,再用 ssh-keygen -R 192.168.1.141 刪掉舊紀錄就好。不要看到警告就直接刪,先比對指紋才安全。

三、關掉板載音效:只改 config.txt 不夠

rpi-rgb-led-matrix 會用到 Pi 的硬體 PWM,跟板載音效衝突,偵測到 snd_bcm2835 模組有載入就會拒絕執行。照一般做法在 /boot/firmware/config.txt 設了 dtparam=audio=off,重開機後模組還是被載入了。最後是加上強制不載入的規則才擋住:

# /etc/modprobe.d/blacklist-rgb-matrix.conf
blacklist snd_bcm2835
install snd_bcm2835 /bin/false

# Trixie 有 initramfs,要更新才會生效
sudo update-initramfs -u

這裡還有一個自己挖的坑:一開始用 echo 'blacklist snd_bcm2835' | sudo -S tee 檔案 寫檔,同時用 sudo -S 從標準輸入帶密碼。結果 sudo 把 stdin 拿去讀密碼,寫進去的是空檔,難怪模組擋不住。要用 sudo 寫檔,改成 sudo sh -c '... > 檔案',或先把 sudo 設好免密碼,就不會有這個問題。

順便照函式庫的建議,在 /boot/firmware/cmdline.txt 最後加上 isolcpus=3,把第 4 顆核心留給面板刷新用,畫面會比較穩。

四、編譯函式庫與 Python 綁定

git clone --depth 1 https://github.com/hzeller/rpi-rgb-led-matrix
cd rpi-rgb-led-matrix
make -j4 -C examples-api-use            # Pi 3 A+ 約 2 分鐘

# Trixie 不讓 pip 直接裝到系統(externally-managed),改用 venv
sudo apt install -y python3-dev python3-venv cython3 cmake ninja-build python3-pil
python3 -m venv --system-site-packages ~/led-venv
~/led-venv/bin/pip install .            # 約 2.5 分鐘

函式庫要直接存取 GPIO,所以程式要用 root 跑:sudo ~/led-venv/bin/python 程式.py。

五、接線:16 pin 排線的顏色怎麼對

圖說:面板背面:左邊 DATA_IN 是輸入(排線已插),右邊 DATA_OUT 用不到,白色座是 5V 電源

面板背面有兩個 16 pin 接頭,印著 DATA_IN 的才是輸入端,板上的箭頭也指出資料的方向。原本 ESP32 版留下來的彩虹排線就插在 DATA_IN 上,所以直接沿用,排線另一頭用杜邦線接到 Pi。

圖說:IDC 接頭上的 ▼ 三角形對著藍線,所以藍線是第 1 腳

雙排 16 pin 的編號是 Z 字形交錯:腳 1 在 ▼ 那一端,它的正對面是腳 2,腳 3 回到腳 1 旁邊……一排全是奇數、另一排全是偶數。排線也是照這個順序壓的,第 n 條線就是第 n 腳。所以只要找到第 1 條線,從那一條開始依序往下數就好。

圖說:這片面板的排線顏色對照:藍 R1→23、綠 G1→13、黃 B1→26、橘 GND→6……白 E 不接

要注意彩虹排線的顏色每 10 條會重複:藍、綠、黃、橘、紅、棕各有兩條,所以要用位置來認,不能只看顏色。如果不確定方向,可以用三用電表的導通檔碰面板電源的 GND,第 4 條和第 16 條會叫,就代表方向對了。

圖說:接好的樣子:Pi 直接放在面板背面,排線轉杜邦線接 40 pin

面板用自己的 5V 電源,Pi 用自己的 micro USB 電源。排線的 GND(第 4、16 條)已經接到 Pi 的 GND,兩邊就共地了。

六、第一次點亮

sudo examples-api-use/demo -D0 --led-rows=32 --led-cols=64 \
     --led-gpio-mapping=regular --led-slowdown-gpio=2

圖說:demo -D0 一次就亮:旋轉的漸層方塊上下半部接得很順,代表兩組顏色線和 A~D 位址線都對

旋轉方塊只能看出大致正常,所以我另外寫了一個固定的檢查畫面:白色外框、四個角各一個色塊(左上紅、右上綠、左下藍、右下黃),中間是紅綠藍三個字母。外框完整代表沒有缺行缺列;四角的顏色和位置對,代表方向沒有上下顛倒或左右相反;R、G、B 三個字的顏色對,代表三條顏色線沒有接錯。

圖說:接線檢查畫面:外框完整、四角顏色和位置都對、R G B 顏色正確

七、Python 版網路時鐘

版面照 2021 年的 ESP32 版:第 1 行是彩虹色的時間(顏色會隨秒數流動),第 2 行是紅色的星期,第 3 行是日期,第 4 行每 4 秒輪播溫度、濕度和 PM2.5(AQI 指數)。碰到家人生日,第 4 行會每 20 秒捲動一次彩虹色的「Happy Birthday ○○!」。字型用函式庫附的 5x8.bdf,剛好 4 行塞滿 32 px。

資料來源有一個變動:ESP32 版抓的是環保署的 opendata2.epa.gov.tw/AQI.json,這個網址已經停用了。溫濕度改用 Open-Meteo,不用申請金鑰,給經緯度就能拿到資料;PM2.5 一開始也用 Open-Meteo,後來跟家裡的魔鏡比對,改成 WAQI 新竹測站(原因見第九節)。兩個都每 10 分鐘更新一次:

# 溫度、濕度
https://api.open-meteo.com/v1/forecast?latitude=24.80&longitude=120.97&current=temperature_2m,relative_humidity_2m
# PM2.5(取 data.iaqi.pm25.v,是 AQI 指數;token 放在 secrets.json,不進 git)
https://api.waqi.info/feed/Hsinchu/?token=<token>

畫面的主迴圈很單純:每 40 ms 在後台畫布上重畫一次,再用 SwapOnVSync 換到前台,這樣就不會閃爍。

while True:
    now = datetime.now()
    canvas.Clear()
    t = now.strftime("%H:%M:%S")
    x = (64 - text_width(font, t)) // 2
    for i, ch in enumerate(t):                       # 每個字一個彩虹色
        x += graphics.DrawText(canvas, font, x, 7, wheel(i + now.second), ch)
    centered(canvas, font, 15, WEEKDAYS[now.weekday()], RED)
    centered(canvas, font, 23, now.strftime("%Y/%m/%d"), MAGENTA)
    s, col = items[int(time.time() // 4) % len(items)]   # 溫度/濕度/PM2.5 輪播
    centered(canvas, font, 31, s, col)
    canvas = matrix.SwapOnVSync(canvas)
    time.sleep(0.04)

經緯度、亮度和生日清單都放在 config.json,以後改內容不用動程式。最後設成 systemd 服務,開機自動執行,程式當掉也會自己重啟:

[Unit]
Description=64x32 HUB75 LED clock
After=network-online.target time-sync.target

[Service]
ExecStart=/home/pi/led-venv/bin/python /home/pi/led-clock/clock.py
WorkingDirectory=/home/pi/led-clock
Restart=always
User=root

[Install]
WantedBy=multi-user.target

八、調整亮度與字型

  • 亮度:從 10 開始往上試(10、12、15、20),最後定在 30。放在室內,30 已經很清楚,也不刺眼。原本 ESP32 版會用繼電器在白天切斷面板電源,這次不做了,全天固定亮度。
  • 低亮度的混色:亮度低的時候,PWM 的階數變少,像紫色 (200, 0, 255) 這種紅、藍比例不一樣的顏色,看起來會一點粉一點藍。把日期改成紅、藍都開到 255 的洋紅色,顏色就比較均勻。上面那張完成照拍的是改色之前,所以日期還是紫色的。
  • 粗體:試過把每個字錯開 1 px 畫兩次來做假粗體,字確實變粗了,但看起來比較擠,最後還是用回原本的細字。

資源用量方面:程式的 CPU 約 67%,大部分是刷新畫面的執行緒,它跑在 isolcpus 隔離出來的那顆核心上;記憶體總共用約 150 MB;供電正常,vcgencmd get_throttled 一直是 0x0。

九、跟魔鏡比對:PM2.5 為什麼差了一倍

家裡另一台 Pi 3 B+ 跑的是 MagicMirror 魔鏡,把兩台並排比對:溫度 15.3° 和 15.4°、濕度 60% 和 61%,幾乎一樣;但 PM2.5 魔鏡顯示 53,LED 時鐘顯示 24,差了一倍。

圖說:兩台 Pi 3 時鐘並排:左邊魔鏡,右邊 LED 點陣面板

查了魔鏡的 MMM-AQI 模組才知道,兩邊不只資料來源不同,連單位都不一樣:

魔鏡(MMM-AQI)LED 時鐘(改之前)
來源WAQI(aqicn.org),新竹實際測站Open-Meteo,歐洲 CAMS 的模型推估
數字的意思AQI 指數(美國 AQI 量表)濃度(μg/m³)
當時的值5323.7

PM2.5 的 AQI 53,換算成濃度大約只有 10~13 μg/m³。也就是說,測站量到的實際濃度,比 Open-Meteo 推估的 23.7 還低。模型推估在台灣的準確度比不上實際測站,加上兩台並排顯示兩個不同的數字也很奇怪,所以 LED 時鐘的 PM2.5 改成跟魔鏡一樣抓 WAQI,顯示 AQI 指數。WAQI 的 token 直接沿用魔鏡的,存成獨立的 secrets.json(權限 600、不進 git)。改完之後,兩台都顯示 53。

小提醒:很多網站和模組都把這個欄位標成「PM2.5」或「PM25」,但 WAQI 的 iaqi.pm25 給的是 AQI 指數,不是 μg/m³。拿不同來源的數字來比之前,先確認單位。

踩坑整理

問題原因解法
開機閒置就用掉 204 MB燒成了桌面版systemctl set-default multi-user.target
掃不到 Pi第一次開機還沒完成等幾分鐘,找 b8:27:eb 的 MAC 或 主機名稱.local
SSH 跳 HOST IDENTIFICATION HAS CHANGED同一個 IP 以前分給別的裝置先比對指紋,再 ssh-keygen -R IP
snd_bcm2835 還是被載入只設 dtparam=audio=off 不夠blacklist+install snd_bcm2835 /bin/false+更新 initramfs
黑名單檔案是空的echo | sudo -S tee,stdin 被 sudo 拿去讀密碼用 sudo sh -c '... > 檔案'
pip install 失敗Trixie 的 externally-managed 限制建 venv(--system-site-packages)
PM2.5 抓不到環保署舊的 opendata2 網址已停用改用其他來源
PM2.5 跟魔鏡差一倍Open-Meteo 是模型推估的濃度(μg/m³),魔鏡是 WAQI 測站的 AQI 指數改抓 WAQI 新竹測站,兩台一致
低亮度時紫色斑駁紅、藍比例不同,PWM 階數不夠改用紅、藍都 255 的洋紅色

下一步

  • 帶回家測試家裡的 Wi-Fi 能不能自動連上 ✅ 已完成:帶回家插電後,自動連上家裡的 winson2.4(不用接螢幕或改設定),時鐘和天氣都正常;從公司也能透過 Tailscale 連進去
  • 做一個外殼,把 Pi 固定在面板背面
  • 考慮加一個網頁設定頁,直接從手機改亮度和顯示內容

Controlling a Mitsubishi FX1S PLC from Python and the ATS Console: FX Programming Port Protocol | 用 Python 和 ATS 操作台控制三菱 FX1S PLC:FX 程式口協定實作

桌上有一台舊的三菱 MELSEC FX1S-14MR,加上一條 USB 程式線。平常改這種 PLC 要開 GX Developer/GX Works2,但我只想做三件事:看輸入有沒有進來、從電腦切輸出、讀寫幾個 D 暫存器。所以這次不靠三菱軟體,直接用 Python 講 FX 的「程式口協定」,先寫成命令列工具,再整合進自己的 ATS 網頁操作台,變成一個 PLC 控制頁。

圖說:FX1S-14MR 與 USB-SC09 類程式線(線上的標籤寫 Industrial Adapter and Interface link)

硬體

  • PLC:FX1S-14MR,AC85~264V 供電;輸入 X0~X7 共 8 點,繼電器輸出 Y0~Y5 共 6 點。
  • 傳輸線:一端是 Mini-DIN 8 pin,插 PLC 面板蓋子底下的程式口(RS-422);另一端是 USB。電腦上看到的是 USB-SERIAL CH340,接在 msi 筆電上是 COM40,裝好 CH340 驅動就能用。
  • 確認型號:連上之後讀特殊暫存器 D8001,回 22216。前兩碼 22 代表 FX1S,後面 216 是韌體 V2.16。

FX 程式口協定

這是 GX Developer 跟 FX 系列溝通用的協定,格式很單純:9600 bps、7 個資料位元、偶同位、1 個停止位元(7E1)。內容都是 ASCII,前面放 STX、後面放 ETX,最後加上 2 碼檢查碼。

圖說:讀取與強制兩種封包,檢查碼是 STX 之後到 ETX(含)的位元組加總,取低 8 位元

指令格式用途
ENQ05 → 回 06(ACK)確認 PLC 有沒有在線上
0 讀0+位址 4 碼+長度 2 碼讀 X、Y、M、D…(位元組位址)
1 寫1+位址+長度+資料寫 D 等暫存器,回 ACK
7/87(ON)或 8(OFF)+位元位址 4 碼強制單一個位元 ON/OFF

讀寫用的是位元組位址:X 從 0080、Y 從 00A0、M 從 0100、D 從 1000 開始(D 每個佔 2 bytes,低位元組在前)。M8000 這類特殊繼電器在 01E0,D8000 以上在 0E00。強制指令則用另一套位元位址:Y0=0500、X0=0400、M0=0800。

踩到的坑

  • 第一個 ENQ 沒回應:一開始 ping 失敗,改送原始封包卻正常。原因是 CH340 剛開埠時,第一個位元組會掉。解法是開埠後等 0.2 秒,ping 失敗再重試一次。
  • 強制指令的位址要反過來送:讀寫指令的位址照順序寫,強制指令卻是低位元組在前。Y0 的位元位址 0500 要送成 0005,送錯 PLC 會回 NAK。
  • X、Y 是八進位:FX 的 X、Y 編號沒有 8、9,X7 的下一個是 X10。程式裡算位址時要先當八進位轉換。
  • STOP 時強制會直接出力:我原本以為 STOP 時輸出都會關掉,強制只是改記憶體。實機一試,在 STOP 下強制 Y0、Y2,面板上 OUT 0、2 的燈就亮了。STOP 時沒有程式在跑,強制的值也不會被蓋掉,反而是最單純的測試方式。
  • RUN 時程式有用到的 Y 會被蓋掉:RUN 時 PLC 每次掃描都會依程式重算輸出,從電腦強制的值馬上被覆蓋。比較好的做法是在 PLC 程式寫 LD M0/OUT Y0,電腦去控 M0。這樣 PLC 裡的連鎖和保護也都還在。

命令列工具 fxplc.py

先用 pyserial 寫一支命令列工具,Windows、Linux 都能跑:

py -3 fxplc.py -p COM40 ping          # OK,PLC 有回應
py -3 fxplc.py -p COM40 status        # STOP | X0=□ … | Y0=□ …
py -3 fxplc.py -p COM40 on Y0         # 強制 Y0 ON
py -3 fxplc.py -p COM40 read D0 4     # [0, 0, 0, 0]
py -3 fxplc.py -p COM40 write D0 123
py -3 fxplc.py -p COM40 read D8001    # [22216] → FX1S V2.16

整合進 ATS:PLC 控制頁

ATS 主畫面上方多了一顆「PLC」按鈕,按下去會開一個獨立視窗。選好 COM 埠、按連線,標題會顯示型號和 RUN/STOP,然後每 0.5 秒更新一次:

  • 輸入 X0~X7:指示燈,唯讀。
  • 輸出 Y0~Y5、輔助繼電器 M0~M15:點一下切換,送的是強制 ON/OFF。
  • 資料暫存器 D:指定起點和數量讀成一張表,每列可以填新值寫入,也可以勾自動更新。
  • 任意元件:輸入 T0、M100、D8001 等,可以讀取或強制。
  • 依 RUN/STOP 顯示不同提示:STOP 時強制的 Y 會直接出力;RUN 時程式驅動的 Y 會被蓋掉,要改控 M。
  • 連著的時候 COM 埠被 ATS 占用;要用 GX Works 改程式前,先按「中斷」把埠放掉。

圖說:ATS 的 PLC 控制頁(這張是模擬模式的畫面,實機會顯示 COM40)

ATS 也加了一台模擬的 FX1S(--sim 時選「sim」),沒有接 PLC 也能測整個頁面。

實機:STOP 下強制 Y0、Y2

ATS 裝在 msi 筆電上,PLC 開關留在 STOP。在 PLC 頁點 Y0 和 Y2,畫面上兩個輸出亮起,PLC 面板上 OUT 的 0、2 兩顆紅燈也同時亮了(RUN 燈沒亮,確實是 STOP)。

圖說:msi 上的實機畫面:COM40、STOP,Y0 和 Y2 已強制 ON

圖說:同一時間的 PLC 面板:POWER 亮、RUN 不亮,OUT 0、2 亮

Y0 跟誰導通?

FX1S-14MR 是繼電器輸出,每個 Y 都是一顆繼電器的乾接點:Y0 ON 時,Y0 和它的共點 COM0 兩個端子接通。6 個輸出分成三組,實際接線請以端子蓋上的標示為準:

共點輸出
COM0Y0
COM1Y1
COM2Y2、Y3、Y4、Y5

接負載的方式就把它當成一個開關:電源一端接 COM0,經過負載後接到 Y0,交流、直流都可以,每點最多約 2 A。想先確認的話,把 PLC 撥到 RUN,三用電錶切到通路檔夾 COM0 和 Y0,在 ATS 上點 Y0,ON 時應該會嗶。

應用:用 Y0、Y1 控制兩顆 24V 電磁閥

圖說:FX1S-14MR 用 Y0、Y1 控制兩顆 24V 電磁閥的接法

這是很常見的氣動應用:外接一顆 24V 開關電源,+24V 接到兩顆電磁閥的一端,電磁閥另一端分別接 Y0、Y1,PLC 的 COM0 接電源 0V。Y0 ON 時繼電器把 Y0 和 COM0 接通,第一顆電磁閥通電動作;Y1 同理。換句話說,PLC 的繼電器只是串在電磁閥的 0V 那一側當開關,電磁閥的電源由開關電源提供,不是由 PLC 供電。

套用到 FX1S-14MR 時要注意兩件事:

  • Y1 的共點是 COM1,不是 COM0。很多網路上的接線圖是 Y0、Y1 共用 COM0,但 FX1S-14MR 的 Y0、Y1 各有自己的共點,所以圖中把 COM0 和 COM1 跳線接在一起,再接到 0V。Y2~Y5 則共用 COM2。
  • 電磁閥是電感性負載:直流線圈斷電時會產生反向突波,長期下來會讓繼電器接點燒蝕。所以圖中在每顆線圈兩端反向並聯一顆二極體(1N4007,陰極接 +24V 那一端);很多電磁閥接頭本身已經內建 LED 和保護元件,可以先確認一下。

目前進度與下一步

  • 實機已經確認:連線、型號(D8001)、讀 X/Y/M、讀 D、STOP 下強制 Y(面板 OUT 燈跟著亮)都正常。
  • 寫 D 只在模擬環境測過;繼電器接點還沒用三用電錶或實際負載量過。
  • 下一步:在 PLC 寫一段 M0~M5 → Y0~Y5 的梯形圖,讓電腦改控 M;也打算把 PLC 步驟加進 ATS 的測試流程,量測時順便切治具上的繼電器。

DIY Robot Cars EP2: Mecanum Wheels, from an ESP32-CAM Car to a Pi 5 Self-Driving Car | 自造機器人車 EP2:麥克納姆輪,從 ESP32-CAM 影像車到 Pi 5 自走車

📺 影片版(約 24 分鐘,有章節可跳著看):本集整理成一支影片,細節在下方文字與各篇原文。
YouTube:https://youtu.be/CJlI0VgPpS0(winson-DIY 頻道)

English summary: Episode 2 of the "DIY Robot Cars" series merges three posts into one story about mecanum wheels: why 45-degree rollers let a car strafe and move diagonally (with the kinematics formula), a 2024 ESP32-CAM car that streams video and sends 4-bit commands to an Arduino Mega2560 driving two L298Ns and a servo arm, and a 2026 Raspberry Pi 5 rebuild with web joysticks, YOLO, gyro-assisted straight driving, distance and route maps, camera ground-plane ranging, scan-driven obstacle avoidance, and record-and-replay routes. The big lesson: a runaway caused by lgpio leaving the enable pins high, and how pinctrl in systemd, a PWM watchdog and an operation log fixed it.

這是「自造機器人車」系列的第二集,主角換成麥克納姆輪。把 2024 年的 ESP32-CAM 影像車和 2026 年 Pi 5 自走車的兩篇文章整理成一條故事線:輪子為什麼能橫著走 → ESP32-CAM 邊看邊開 → 換 Pi 5 網頁遙控 → 陀螺儀走直線與地圖 → 自動避障與一次暴衝 → 錄路線照軌跡走。影片約 20 分鐘,有章節可以跳著看;程式全文在各篇原文。

本集章節

  1. 麥克納姆輪為什麼能橫著走:45° 滾子、X 排列、四輪速度公式、鏡像安裝的 CW/CCW。
  2. 2024:ESP32-CAM 邊看邊開:ESP32-CAM 影像+網頁、4 支 GPIO 當 4 位元指令碼、Mega2560 推兩片 L298N 與 4 顆手臂伺服;從程式反推每顆輪子的位置。→ ESP32CAM + 麥克納姆倫 + Car(2024/06)
  3. 2026:換 Pi 5 網頁遙控:零件與接線、12.6 V 與 PWM 上限、雙搖桿網頁與 0.5 秒斷線停車、輪子 invert、實體腳號 13 ≠ GPIO13。→ Pi 5 麥克納姆輪自走車(一)(2026/11)
  4. 走直線、畫地圖、鏡頭測距:3 秒偏 10° → PD+學習量、兩個網頁互蓋、積分飽和、距離圖與路線圖、地面法測距與鏡頭校正。→ 同上+Pi 5 麥克納姆輪自走車(二)(2026/11)
  5. 避障與暴衝:避障一路改版、超聲波打到自己的鏡頭、掃描導向策略;lgpio tx_pwm(0) 不拉低+SIGKILL、tx_servo(0) 卡住別支腳 PWM(79/80 → 0/90);systemd pinctrl、PWM 看門狗、操作紀錄。→ 同上兩篇
  6. 照軌跡走與總整理:每 3 cm/5° 記點、麥克納姆斜走追點、搬到目前位置、對齊起點;實車 5.3 m、142 點、24 秒。

單篇影片

  • ESP32CAM Mecanum wheel CAR:https://youtu.be/qQoEmHxq1BA
  • Pi 5 麥克納姆輪自走車:https://youtu.be/Imtc1hFkkwQ

補充:原文沒寫到的原理與常見坑

補充一:麥克納姆輪的運動學

每顆麥克納姆輪的外圈是一排斜 45° 的小滾子。輪子轉動時,地面推回來的力不是正前方,而是沿著滾子垂直的方向斜 45°;四顆輪子的斜向力加起來,前後分量和左右分量各自可以抵消或相加,所以車子能直走、平移、斜走、原地轉。由上往下看,四顆輪子的滾子要排成「X」(左前、右後一組,右前、左後一組),裝反的話平移方向會反。

vx:往前、vy:往左平移、w:逆時針旋轉(都在 -1~1)
FL = vx - vy - w      FR = vx + vy + w
RL = vx + vy - w      RR = vx - vy + w
任一輪的絕對值超過 1 時,四輪一起除以最大值(保持方向比例)

這就是 Pi 5 車 car/hw.py 的 mecanum()。例:vx=0、vy=1(往左平移)→ FL -1、FR +1、RL +1、RR -1,同一條對角線的兩顆輪子轉向一樣。只轉對角線上的兩顆(例如 FR 與 RL 往前),車子會往左前 45° 斜走。

補充二:從 2024 版程式反推每顆馬達的位置

Mega2560 程式裡的 Forward(CW、CCW、CCW、CW)和 S_Left(四顆全 CW)比較,變號的是 motors1 的馬達 2 和 motors2 的馬達 1,它們是同一條對角線;Xtrun(原地轉)變號的是 motors2 的兩顆,所以 motors2 管同一側。對照上面的公式可以推出:一片 L298N 管右側(右前、右後)、另一片管左側(左前、左後);Left() 只轉右前+左後,就是往左前斜走。左右兩側馬達是鏡像安裝,同樣讓車往前,一邊要正轉、另一邊要反轉,所以程式裡同一個動作會同時出現 CW 和 CCW。(依原文程式推論,非原作者說明)

補充三:ESP32-CAM 為什麼要再接一片 Mega2560

AI-Thinker ESP32-CAM 的鏡頭佔掉大部分 GPIO,排針上只拉出 GPIO 0、1、2、3、4、12、13、14、15、16,其中 16 在有 PSRAM 的板子上接著 PSRAM、 1/3 是序列埠、0 是開機模式腳、2/12/15 是開機 strapping 腳、2/4/12/13/14/15 同時接到 microSD 卡、GPIO4 還接著板上的閃光燈 LED。要同時推 4 顆馬達(8 支方向腳+PWM)和 4 顆手臂伺服,腳位根本不夠,所以原文用 ESP32-CAM 只負責影像和網頁,把 4 支 GPIO 當成 4 位元的指令碼送給 Mega2560,16 種組合剛好放得下 7 種移動、停止和 8 個手臂動作。

原文的 WRITE_PERI_REG(RTC_CNTL_BROWN_OUT_REG, 0) 是關掉欠壓偵測:馬達啟動拉低電壓時 ESP32-CAM 不會一直重開,代價是電壓真的太低時晶片可能跑出錯誤行為而不是乾淨地重開。比較好的做法仍是把馬達和 ESP32-CAM 的電源分開、加大電容。

補充四:TT 馬達的電壓與 PWM 上限

TT 黃色減速馬達常見額定 3~6 V。三顆 18650 串聯滿電 12.6 V,L298N(雙極電晶體 H 橋)大約吃掉 2 V,馬達端仍有 9~10 V,所以要用 PWM 上限把平均電壓壓低;原文從 60% 再降到 50%。PWM 只是平均值,峰值仍是全電壓,長時間高 PWM 會讓馬達發熱與壽命縮短。

補充五:接馬達的程式要先想「死掉時腳位停在哪」

  • 停車一定直接把 EN 腳寫成低電位,不要只「停掉 PWM」(lgpio 的 tx_pwm(…, 0) 會讓腳停在最後的電位)。
  • 服務啟動前、結束後用 pinctrl 把馬達腳全部拉低(ExecStartPre/ExecStopPost),程式被砍也一樣。
  • 網頁遙控要有「沒收到指令就停車」的逾時(原文 0.5 秒)。
  • 硬體上可在 EN 腳加下拉電阻,讓 Pi 開機、腳位還是輸入狀態時馬達也不會動。
  • Pi 5 的 GPIO12/13/18/19 是硬體 PWM 腳,換成硬體 PWM 可避開軟體 PWM 卡住的問題(原文列為待辦)。

補充六:只靠輪速推算位置會飄

沒有輪子編碼器時,位置是「送給馬達的指令 × 實測速度 × 時間」積分出來的(dead reckoning),方向用陀螺儀。輪子打滑、電池電壓下降、麥克納姆輪平移效率(原文假設 0.8)都會讓誤差一路累積,所以路線圖上「照著走」的綠線疊在黃線上,只代表控制照著計畫走,不代表地上的真實位置;要量真實偏差得用地上標記或俯拍。

自造機器人車系列

2026年11月19日 星期四

DIY Robot Cars EP1: ESP32 Bluetooth RC Car to Obstacle Avoidance | 自造機器人車 EP1:ESP32 藍牙遙控車到自動避障

📺 影片版(約 17 分鐘,有章節可跳著看):本集整理成一支影片,細節在下方文字與各篇原文。
YouTube:https://youtu.be/hXes9V4mknk(winson-DIY 頻道)

English summary: Episode 1 of the "DIY Robot Cars" series turns four posts from summer 2023 into one story: spinning DC motors with an L298N dual H-bridge, controlling them with single letters over ESP32 Classic Bluetooth SPP, building a four-wheel skid-steer car, driving it with the Bluetooth RC Controller app, and finally adding an HC-SR04 on a servo with two FreeRTOS tasks for obstacle avoidance. Along the way: L298N voltage drop and jumpers, the Arduino-ESP32 3.x LEDC API change, a strstr bug where "VER" also triggers Right(), and why readString() waits one second.

這是「自造機器人車」系列的第一集,把部落格 2023 年夏天連續四篇 ESP32 小車文章整理成一條故事線:L298N 讓馬達轉起來 → 藍牙 SPP 用字母控制 → 組成四輪車 → 手機 App 遙控 → 超音波+伺服馬達自動避障。影片約 16 分鐘,有章節可以跳著看;程式全文在各篇原文。

本集章節

  1. 讓馬達轉起來:L298N 雙 H 橋、接線(ENA 4、IN1~IN4 16~19、ENB 5)、共地;壓降 2~3 V、ENA/5V 跳帽;Robojax 函式庫與 ESP32 PWM 通道;Arduino-ESP32 3.x 的 LEDC 改版。→ ESP32 Bluetooth SPP control -- DC motors with L298N module(2023/07)
  2. 藍牙 SPP:手機送一個字母:BluetoothSerial、F/B/L/R/S;strstr 讓 VER 也觸發右轉;只有原版 ESP32 有傳統藍牙、iPhone 不開放 SPP。→ 同上
  3. 組一台四輪車:車體套件、18650 電池、四顆馬達同側並聯、L298N +5V 供電給 ESP32、滑移轉向三種轉法。→ ESP32 Bluetooth Remote Control Car -DIY(2023/08)
  4. App 遙控:Bluetooth RC Controller 指令表(F B L R G I H J S、W/U/V/X、0~9 q);為什麼程式比對的是 FS、FGFS(readString 預設等 1 秒)與逐字元改法。→ ESP32 Bluetooth RC Car APP - Bluetooth RC Controller(2023/08)
  5. 自動避障:HC-SR04(duration/29/2、Echo 5 V 分壓)、ESP32Servo 50 Hz 500~2400 µs、35 cm 避障邏輯、兩個 FreeRTOS 任務與 App X/x 切換;pulseIn 逾時、伺服電流、volatile、斜面軟布四個坑。→ ESP32 Obstacle Avoiding Robot Car(2023/08)
  6. 總整理與下一集:四篇=一台車長大;EP2 麥克納姆輪(ESP32-CAM 影像車 → Pi 5 自走車)、EP3 步進平衡車。

單篇影片

  • DC motors with L298N module - ESP32 Bluetooth SPP control:https://youtu.be/F3gByuOwLIU
  • ESP32 Bluetooth Remote Control Car DIY:https://youtu.be/mcMax-saFSY
  • ESP32 Bluetooth RC Car APP - Bluetooth RC Controller:https://youtu.be/RWFrd_aHiwI
  • ESP32 Obstacle Avoiding Robot Car:https://youtu.be/ZjxEfAh5XB8

補充:原文沒寫到的原理與常見坑

補充一、H 橋怎麼讓馬達正反轉

四個開關排成 H 字形,馬達在中間。L298 每個橋由 IN1/IN2 決定方向、EN 決定開關:

ENIN1IN2馬達
HHL一個方向(正轉)
HLH另一個方向(反轉)
HIN1=IN2快速煞車
L任意自由滑行

EN 接 PWM,開的時間比例=平均電壓=速度。所以每顆馬達要三條線:兩條管方向、一條管速度。

補充二、L298N 模組的三個坑

  • 壓降約 2~3 V:L298 是雙極電晶體輸出(datasheet 的飽和壓降上下橋合計在 1 A 時約 1.8~3.2 V),7.4 V 電池到馬達端可能只剩 5 V 左右。
  • ENA/ENB 跳帽:插著=EN 接 5 V,永遠全速;要用 PWM 調速必須拔掉,改接 ESP32。
  • 5V 穩壓跳帽:供電 12 V 以下才插著,此時 +5V 端子是輸出,可以供電給 ESP32(原文接線就是這樣接);超過 12 V 要拔掉、+5V 改成輸入。
  • 另外:ESP32 與 L298N 一定要共地;2 A 是單路上限,馬達堵轉時電流最大。

補充三、ESP32 的 PWM 與 Arduino-ESP32 3.x

ESP32 的 PWM 來自 LEDC 周邊(通道、頻率、解析度)。Arduino-ESP32 核心 3.0 起 LEDC API 改版:ledcSetup()+ledcAttachPin() 合併為 ledcAttach(pin, freq, resolution),ledcWrite() 改成用腳位而不是通道。2023 年依 2.0.x 寫的範例與函式庫(例如需要傳 PWM 通道的 L298N 函式庫)用新核心可能編譯失敗:在開發板管理員改裝 2.0.x,或改寫成 3.x 寫法。

// 3.x 寫法示意(未編譯)
ledcAttach(ENA, 1000, 8);    // 1 kHz、8 bit
ledcWrite(ENA, 180);         // 0~255
digitalWrite(IN1, LOW); digitalWrite(IN2, HIGH);

補充四、為什麼用傳統藍牙 SPP、它的限制

  • SPP(Serial Port Profile)把藍牙當序列埠,Android 上的終端機、遙控 App 最多,ESP32 用 BluetoothSerial 幾行就好。
  • 只有原版 ESP32(ESP32-WROOM/WROVER)有 BR/EDR 傳統藍牙;ESP32-S3、C3、C6 只有 BLE,BluetoothSerial 不能用。
  • iOS 不開放一般 App 使用 SPP(需 MFi),要支援 iPhone 就改用 BLE(例如 Nordic UART Service)或 WiFi。

補充五、strstr 的小坑:打 VER 車子會右轉

原文 USB 序列埠這一路用 strstr(data, "R") 判斷「字串裡有沒有 R」;查版本的 VER 剛好含 R,所以印出版本號的同時也會呼叫 Right()(依程式邏輯推論,原文沒有寫到這個現象)。改法:

if (strcmp(data, "VER") == 0) { Serial.println(F("ESP32_20230710")); return; }
switch (data[0]) {
  case 'F': Forward(); break;
  case 'B': Reverse(); break;
  case 'L': Left();    break;
  case 'R': Right();   break;
  case 'S': Stop();    break;
}

補充六、四輪車的電源與轉彎

  • 電源:電池 → L298N +12V(馬達);L298N +5V → ESP32 5V 腳(主控)。兩顆 18650 串聯滿電 8.4 V、標稱 7.4 V,扣掉 L298N 壓降,馬達約 5~6 V。
  • 四顆馬達同側並聯:左兩顆接 OUT1/OUT2、右兩顆接 OUT3/OUT4,程式仍只有 motor1/motor2。
  • 滑移轉向(skid steering):輪子不能轉向,只能靠兩側速度差。單邊停(原文 L/R)以停住那側為圓心畫弧;兩邊反向=原地旋轉,最快但輪胎側滑、耗電;兩邊同向不同速=差速轉彎,最順(原文 App 版 FGFS 等斜角就是 60%/100%)。
  • 原文三篇的 Left()/Right() 改過一次:2023/07、2023/08 第一版是單邊往後轉,App 版改成另一側單邊往前轉。

補充七、Bluetooth RC Controller 指令表與 readString 等一秒

按鍵送出
前/後/左/右F/B/L/R,放開送 S
左前/右前/左後/右後G/I/H/J
前燈/後燈W 開 w 關/U 開 u 關
喇叭/額外鍵V/v、X/x(原文用 X/x 切換自動避障)
速度滑桿0~9、q(100%)

原文 App 版比對的是 "FS"、"FGFS" 這種組合,原因是 SerialBT.readString() 會一直讀到「超過逾時都沒有新字元」才回傳,預設逾時 1000 ms:一秒內的按下、放開會黏成一串,而且每個指令都要等一秒才執行。改法是逐字元處理:

void loop() {
  while (SerialBT.available()) {
    char c = SerialBT.read();
    switch (c) {
      case 'F': Forward(); break;
      case 'B': Reverse(); break;
      case 'G': ForwardLeft(); break;   // 60% / 100%
      case 'I': ForwardRight(); break;
      case 'S': Stop(); break;
      case 'X': autoMode = false; Stop(); break;
      case 'x': autoMode = true; break;
    }
  }
}

(或至少 SerialBT.setTimeout(20);,讓 readString 只等 20 ms。)

補充八、避障車:超音波、伺服與常見坑

  • HC-SR04:Trig 送 10 µs 脈衝,Echo 高電位時間=聲波去回時間。聲速約 340 m/s,1 cm 約 29 µs,去回除以 2 → distance = duration / 29 / 2(例:2030 µs ≈ 35 cm)。
  • Echo 是 5 V 訊號,ESP32 GPIO 只能 3.3 V:建議 1 kΩ/2 kΩ 分壓。
  • 伺服:ESP32 要用 ESP32Servo 函式庫;50 Hz(20 ms),原文 attach(13, 500, 2400):0° 500 µs、180° 2400 µs,90° 約 1450 µs;程式用 90°(前)、20°(右)、160°(左)。
  • pulseIn() 預設逾時 1 秒:前方沒回波時任務會卡一秒,建議 pulseIn(ECHO, HIGH, 25000)(約 4 m);原文定義的 MAX_DISTANCE 200 可以用在這裡。
  • 伺服啟動電流大,電壓掉下來 ESP32 可能 brownout 重開:伺服另外供電、加 470 µF 以上電容、共地。
  • distance、HCSR04Flag 由兩個 FreeRTOS 任務共用:宣告 volatile 或改用 queue。
  • 斜面會把超音波彈走、軟布會吸收,量不到 → 可加紅外線或 ToF(如 VL53L0X)補強。

自造機器人車系列

Driving an ODrive Motor from ECU RPM: OBD-II PID 0C to Set_Input_Vel on One CAN Bus | ECU 轉速連動 ODrive:行車電腦 OBD 轉速換算後直接控制無刷馬達

上一篇〈ATS 操作台用 PCAN 控制 ODrive v3.6〉已經能在網頁上手動控制兩顆無刷馬達。這次要讓馬達「自己動」:從行車電腦模擬器用 OBD-II 讀引擎轉速,換算成馬達速度、加上限制,一直送給 ODrive 的 M1(A2212 1400KV,沒有編碼器的 sensorless 馬達)。引擎轉速升高,馬達就跟著轉快;熄火、斷線,馬達就停。

為了少一支 PCAN,ODrive 和模擬器接在同一條 CAN bus 上,全部交給 ATS 處理。功能一天就寫好、在模擬環境測過,真正花時間的是實機接上去之後的幾個坑,這篇都記下來。

圖說:整體架構:PCAN、行車電腦模擬器、ODrive 三個節點在同一條 500k 的 CAN bus 上

做法

1. 讀轉速:OBD-II PID 0C

ATS 原本就有 OBD 掃描頁。引擎轉速是 Mode 01 的 PID 0C:送功能定址 7DF 02 01 0C,ECU 從 7E8 回 04 41 0C A B,轉速=(A×256+B)/4 rpm。OBD 頁平常會輪流問儀表那 8 個 PID 再加一個其他的,轉速大約每 0.5 秒才更新一次,太慢。所以連動多了一個選項「OBD 只問轉速」,打勾時只輪詢 0C,實測每秒約 14 次,資料延遲約 50 ms。

2. 換算與限制

  • 線性換算:轉速下限 → 速度下限、轉速上限 → 速度上限之間拉一條直線,超出範圍就停在兩端。實測用 600~8000 rpm 對 5~40 turns/s。
  • 熄火就停:低於 500 rpm 送 0。速度下限設 5 turns/s 是因為 sensorless 太慢轉不穩。
  • 速度上限:不管換算出多少,最多 40 turns/s(ODrive 本身的 vel_limit 是 50)。
  • 加減速斜率:20 turns/s²,轉速跳動時馬達不會跟著猛拉。
  • ECU 逾時:500 ms 沒有新的轉速就把目標歸 0。
  • 反轉:勾了就送負的速度。

圖說:換算規則(藍線)和實機量到的點(橘點):轉速約 5150 rpm 時 M1 約 26.6 turns/s,落在線上

3. 送速度給 ODrive

ODrive 韌體 0.5.6 走 CANSimple,CAN ID=node×32+指令。M1 是 node 3,Set_Input_Vel 是指令 0x0D,所以 ID 是 0x06D,資料是兩個 little-endian float(速度 turns/s、力矩前饋)。連動開始時先送 Set_Controller_Mode 切成「速度控制+PASSTHROUGH」,斜率由 ATS 自己算,之後每 50 ms 送一次速度。

同一條 bus 上 ID 會不會打架?ODrive 兩軸(node 2、3)用的是 0x40~0x7F,OBD 用 0x7DF/0x7E8,不會衝突。

4. 網頁畫面

在 ATS 的 ODrive 頁下面加一張「ECU 轉速連動」卡片:轉速來源可以選同一條 bus 或另一支 PCAN,所有參數都能在畫面上改、按「套用設定」立即生效。下面四格即時顯示 ECU 轉速、目標速度、送出速度(含斜率)和轉速資料延遲。

圖說:實機畫面:ECU 5153 rpm → 目標 26.53 turns/s,轉速資料延遲 47 ms

圖說:同一時間的 M1:閉迴路、26.63 turns/s,沒有錯誤

實測結果

連動中從 ATS 的 WebSocket 錄 60 秒(約 300 點):模擬器的轉速在 5117~5245 rpm 之間小幅跳動,目標速度跟著在 26.36~26.97 turns/s 之間變,M1 實際速度和目標的差距平均 0.11 turns/s、最大 0.47。OBD 這段時間 4510 次查詢只逾時 4 次。

圖說:60 秒實錄:藍線是由轉速換算的目標,橘線是 M1 的 sensorless 估計速度(縱軸只放大 26~27 turns/s 這一段)

實機踩到的坑

坑 1:ODrive 還是 250k,bus 上全是錯誤框

模擬器是 500k,ODrive 出廠設定是 250k。PCAN 用 500k 一連上,2 秒就是 5 萬多個錯誤框,ATS 自動斷線。CAN 讀不到 ODrive 的設定,改走 ODrive 的 USB 序列埠(ASCII 協定):w can.config.baud_rate 500000 → ss 存檔 → sr 重開,再讀回確認是 500000。之後只接 ODrive 的 5 秒內收了 1106 框、零錯誤。

坑 2:零星錯誤框被當成錯誤風暴

模擬器接上 bus 後會有零星的接收錯誤框(平均幾秒一個),PCAN 的錯誤計數一直停在 1,OBD 也照樣有回應。但 ATS 原本的規則是「錯誤持續 2 秒就斷線、剛送過框又出錯 0.5 秒就重開通道」,把它當成風暴,結果一直斷線、或重開通道打斷 OBD。改成:一波至少 50 個送出時的錯誤才重開通道(接收錯誤是別人的框壞掉,重開自己沒用),至少 500 個且持續 2 秒才斷線;零星的只在紀錄裡報告。

坑 3:模擬器卡住後,OBD 不會自己再問

模擬器一度沒回應,OBD 掃描第一次問不到支援表就停在「沒有回應」,模擬器好了也不會再試,要手動重開 OBD。改成沒回應時每 3 秒自動重試(紀錄只寫第一次),模擬器一回應連動就自己接上。

坑 4:OBD 重開後「只問轉速」失效,馬達一頓一頓

「只問轉速」原本是開始連動時設在當下那個 OBD 掃描器上。OBD 被停掉重開後換了一個新的,又回到輪詢全部 PID,轉速約 0.5 秒才更新一次,剛好碰到 500 ms 的逾時,速度在「歸 0」和「恢復」之間一直跳。改成每次讀轉速時都把設定套到目前的掃描器。

坑 5:模擬器 bus-off

有兩次模擬器只回了 1~2 秒,接著來一波錯誤,然後完全不說話,bus 上也沒有錯誤框了。ODrive 照樣在回 ACK,表示 bus 是通的,是模擬器自己停了。研判是錯誤太多進入 bus-off,模擬器斷電重開、重新檢查接線後才恢復。其中一次是在模擬器的 GND 拉到 PCAN 共地之後發生的,零星錯誤框的根本原因(接線、地、或模擬器本身的位元時序)還沒查清楚,先記下來。

安全:打開 ODrive 看門狗

連動時馬達是一直轉的。按「停止連動」或停止 ODrive 控制,ATS 都會先送速度 0;但如果 ATS 當掉、被直接關掉,或 PCAN 被拔掉,ODrive 會一直維持最後的速度。所以把 ODrive 兩軸的看門狗打開:config.enable_watchdog = 1、config.watchdog_timeout = 1.0(秒),存檔。ATS 開著 ODrive 控制時每 0.1 秒會用 RTR 問一次狀態,連動時每 50 ms 送一次速度,這些 CAN 指令都會餵看門狗;1 秒沒收到,該軸就自己回 IDLE。

副作用是 ATS 沒在跑 ODrive 控制時,兩軸會帶著 WATCHDOG_TIMER_EXPIRED 錯誤,所以使用順序變成:ODrive 頁按「開始」→ 兩軸「清錯誤」→ M1「閉迴路」→「開始連動」。ATS 的「設定(USB)」也加了看門狗兩欄,可以直接看、改、存檔。

小結

  • OBD 讀轉速 → 線性換算、限制、斜率 → Set_Input_Vel,ECU 和 ODrive 共用一條 500k CAN bus 可行,ID 不衝突。
  • 只問 PID 0C 時轉速每秒約 14 次、延遲約 50 ms,M1 跟目標的差距平均 0.11 turns/s。
  • 沒有編碼器的 M1 用 CAN 切進 sensorless 閉迴路,這次在實機上確認可行。
  • 實機上最花時間的是實體層:鮑率、終端電阻、錯誤框的判讀,以及模擬器 bus-off。
  • 還沒做:零星錯誤框的根本原因、用示波器看 CAN-H/L 波形。

Controlling an ODrive v3.6 over CAN from the ATS Console: Two BLDC Motors, Sensorless Pitfalls and USB Settings | ATS 操作台用 PCAN 控制 ODrive v3.6:兩顆無刷馬達、sensorless 抖動與 USB 設定讀寫

手邊這片 ODrive v3.6-56V 以前就玩過兩次:2023 年用 odrivetool 調 SunnySky X2212 配 TLE5012B 編碼器做位置控制,2025 年用 PeakCAN 控制兩顆馬達(另一顆 A2212 走 sensorless)。這次把它接進自己寫的 ATS 網頁操作台:同一支 PCAN 開一個「ODrive」視窗,兩軸的狀態、校正、閉迴路、位置/速度/力矩控制、即時曲線、緊急停止都在網頁上按;CAN 讀不到的設定值,再走 ODrive 的 USB 序列埠讀寫、存檔。這篇記錄做法,還有實測時踩到的四個坑。

圖說:整體架構:控制走 CAN(PCAN-USB FD,250k),設定走 USB(ODrive 的 CDC 序列埠,ASCII 協定),兩條可以同時用

硬體與接線

項目內容
控制板ODrive v3.6-56V(STM32F405、兩顆 DRV8301),韌體 0.5.6;板上 DIP 開關有 CAN-R(120 Ω 終端)、RUN/DFU
電源12 V,接 DC+/DC−
M0(axis0)SunnySky X2212-13 KV980,7 極對,TLE5012B 磁編碼器(incremental,CPR 16384)→ 位置控制
M1(axis1)A2212/10T 1400KV,7 極對,沒有編碼器 → sensorless 速度控制
AUX2 Ω 鋁殼煞車電阻(減速時把回充的能量燒掉)
CANPCAN-USB FD 接 ODrive 的 CAN H/L,250 kbit/s,Classic CAN(不開 FD)
USBODrive 的 micro USB 接同一台筆電,Windows 上出現 COM48(VID 1209、PID 0D32)

圖說:實際接線:M0 接 X2212(三相+編碼器排線接到 M0 編碼器座),AUX 接鋁殼煞車電阻,M1 接 A2212(只有三相),右側 DC 端子接 12 V

ODrive 的 CAN 協定(CANSimple)

ODrive 0.5.x 的 CAN 協定叫 CANSimple,很單純:CAN ID = node_id × 32 + 指令編號(11-bit 標準框,資料 little-endian)。每一軸有自己的 node ID,這片板子是 axis0=node 2、axis1=node 3,所以 M0 的 ID 落在 0x040~0x05F、M1 在 0x060~0x07F。「讀」類的指令要送 RTR(remote frame),ODrive 用同一個 ID 回資料。這次用到的:

指令編號方向資料
Heartbeat0x01ODrive 自己送,每 100 msaxis 錯誤碼 u32、目前狀態 u8、各子系統錯誤旗標
Estop0x02送(無)→ 該軸停下並帶 ESTOP_REQUESTED 錯誤
Set Axis State0x07送u32:1 IDLE、3 完整校正、4 馬達校正、7 編碼器校正、8 閉迴路
Encoder Estimates0x09ODrive 自己送,每 10 ms位置 f32(turns)、速度 f32(turns/s)
Set Controller Mode0x0B送控制模式 i32(1 力矩、2 速度、3 位置)、輸入模式 i32(1 PASSTHROUGH、2 VEL_RAMP、5 TRAP_TRAJ…)
Set Input Pos/Vel/Torque0x0C/0x0D/0x0E送目標值 f32(位置另帶兩個 int16 前饋)
Set Limits0x0F送vel_limit f32、current_limit f32
Get Iq0x14RTR 問Iq 設定 f32、Iq 實際 f32
Get Sensorless Estimates0x15RTR 問sensorless 的位置、速度 f32
Get Vbus Voltage0x17RTR 問電壓 f32
Clear Errors0x18送(無)

例如讓 M1 用 10 turns/s 轉:ID = 3×32+0x0D = 0x06D,資料 00 00 20 41 00 00 00 00(前 4 byte 是 float 10.0)。進閉迴路:ID 0x067、資料 08 00 00 00。

接上之後第一件事是「只聽、不送」:用 PCAN 在 250k 收 2 秒,看到 0x041/0x061(heartbeat)和 0x049/0x069(編碼器估計),才知道 node ID 是 2、3,不是一般預設的 0、1。再用 RTR 讀 Encoder Count,node 2 有計數(336)、node 3 是 0,確認 node 2 就是接編碼器的 M0。

ATS 的 ODrive 視窗

ATS 開一條 PCAN 連線(250k、不勾 FD),工具列按「ODrive」就跳出這個視窗,按「開始」。程式(ats/odrive.py)掛在 CAN 收訊執行緒上解碼 ODrive 的框,另開一個輪詢執行緒每 100 ms 用 RTR 問 Iq 和 sensorless 估計、每 500 ms 問 Vbus,網頁每 0.1 秒更新一次。ODrive 一秒大約送 250 框,預設「安靜」不進 CAN 視窗和 log,只有我送出的指令和狀態變化會各記一行。

圖說:實機畫面(msi 筆電、Vbus 12.23 V):M0 位置模式正在用梯形軌跡跑向目標,M1 sensorless 穩定在約 10 turns/s。目前狀態的按鈕會亮綠色

  • 每一軸:狀態(灰=IDLE、橘=校正中、綠=閉迴路)、錯誤碼解碼成名稱、位置/速度/Iq,按鈕有 IDLE、馬達校正、編碼器校正、完整校正、閉迴路、清錯誤、停止(M1 沒有編碼器,不顯示編碼器校正)。
  • 控制:位置/速度/力矩三種模式加輸入模式;目標值可以打數字、按 ±1/±10,或拖滑桿(勾「拖曳即送」就邊拖邊送,一秒最多 20 次)。
  • 曲線:最近 20 秒的位置(虛線是目標)、速度、Iq,各自自動縮放。
  • 安全:右上「全部 IDLE」「緊急停止」(Esc 鍵也可以);按「停止」或關掉 CAN 連線時兩軸自動送 IDLE。
  • 限制與增益:vel_limit、電流上限、軌跡速度/加減速、pos_gain、vel 增益可以從 CAN 改,但不會存進 flash。

沒有接硬體時,ATS 的模擬模式裡另外有一條 virtual CAN 通道 odrive-sim,上面掛一片假的 ODrive(node 2 有編碼器、node 3 sensorless),校正、閉迴路、軌跡都會動,畫面可以先在電腦上測好。

CAN 讀不到設定值,改走 USB

CANSimple 只有上面那一組固定訊息:可以下指令、讀狀態,但讀不到任何設定值(相電阻、sensorless 參數、增益、node ID…),也不能存檔。新版韌體 0.6 的 CAN 可以讀寫任意參數,但那只給 ODrive Pro/S1,v3.6 最後一版就是 0.5.6。

所以 ODrive 視窗下面加了「設定(USB)」:ODrive 的 USB 除了 odrivetool 用的原生介面,還有一個 CDC 序列埠,可以送 ASCII 指令,不用另外裝 odrivetool:

r axis1.motor.config.phase_resistance      ← 讀,回一行值(不存在回 invalid property)
w axis1.motor.config.current_lim 15        ← 寫,不回應(ATS 寫完會再讀回比對)
ss                                         ← save_configuration,存進 flash(ODrive 會重開)
sr                                         ← reboot

按「讀取」一次讀主板和兩軸約 100 個值(實機 0.1 秒),分成主板、狀態、CAN、馬達、編碼器、Sensorless、控制器、開機幾組並排顯示。灰字是唯讀(量到或算出來的),改過的欄位會變黃底,按「寫入變更」才送出;寫入只改 RAM,按「存檔」才會留到下次開機(兩軸都要 IDLE 才准存)。每次操作才開、用完就關 COM 埠,不會占著。

圖說:設定(USB)上半:韌體、CAN 鮑率、兩軸狀態與錯誤碼、node ID、馬達校正結果(相電阻 M0 0.088 Ω、M1 0.065 Ω)

圖說:設定(USB)下半:sensorless 參數、控制器增益、開機選項

實測踩到的坑

1. 送了速度,馬達不動:忘了進閉迴路

第一次實機測速度:完整校正做完、切速度模式、送 10 turns/s,馬達不動。看 log,set_input_vel 都有送出去,但校正完軸回到 IDLE,之後沒有送過「閉迴路」(0x047 08 00 00 00),IDLE 的軸會忽略所有目標值。原因是介面上「閉迴路」按鈕一直是藍底,看起來像已經在閉迴路。改成:目前是哪個狀態,那顆按鈕才亮綠色。

2. 急停之後按什麼都沒反應:要先清錯誤

按過緊急停止,兩軸帶著 ESTOP_REQUESTED。ODrive 只要身上有錯誤,就拒絕所有狀態切換,重開 ATS 也一樣(錯誤在 ODrive 上)。偏偏錯誤標籤被頁首的樣式蓋成灰色,很不明顯。改成:錯誤標籤紅底;有錯誤時「清錯誤」按鈕閃橘色;這時按其他狀態按鈕不送出,直接在紀錄提示「先按清錯誤」。

3. M1(sensorless)一直原地抖:相電阻校正壞掉

M1 進閉迴路後給 1~5 turns/s,只會原地抖,sensorless 估計的位置幾乎不動。用 USB 讀設定,sensorless 已經開、pm_flux_linkage = 5.513 / (7 × 1400) ≈ 0.000563 也對,問題在馬達校正值:

項目M0(正常)M1 校正前M1 重新校正後
相電阻 phase_resistance0.087 Ω0.000125 Ω0.0637 Ω
電流迴路 i_gain—0.12563.7

電阻小了約 700 倍。sensorless 是用「電壓 − 電阻 × 電流」積分出磁通來估轉子角度,電流迴路的積分增益也是用電阻算的,電阻幾乎是 0,兩邊都會歪。重新按一次「馬達校正」,電阻回到 0.0637 Ω,M1 就能正常轉。現在 USB 設定表裡相電阻小於 0.005 Ω 會紅字提示「重做馬達校正」。

另一個要知道的:ODrive 0.5.x 的 sensorless 一進閉迴路,會先用 10 A 把馬達拖到電氣 400 rad/s(7 極對換算約 9 turns/s)才交給估計器,之後給太低的速度又會開始抖。實測 M1 維持在 10 turns/s 左右很穩(曲線上速度在 9.4~10.7 之間小幅起伏),要停就按 IDLE,不要給 0。sensorless 的「位置」會繞回(截圖裡在 ±3.7 之間鋸齒狀),只能看速度。

4. 存檔重開後 M0 變成 INVALID_STATE

圖說:存檔後 ODrive 重開:M1 直接就能進閉迴路,M0 卻帶著 INVALID_STATE

把 M1 的新校正值存檔後,ODrive 重開,M1 沒事,M0 卻一開機就是 INVALID_STATE。讀 USB 設定就看懂了:

  • M1 的 motor.config.pre_calibrated 是 1:開機沿用存好的校正值,sensorless 不需要編碼器,所以開機就能用。
  • M0 的 pre_calibrated 是 0:重開後馬達等於沒校正;但 startup_encoder_offset_calibration 是 1,開機會自動做編碼器校正,而編碼器校正需要馬達先校正好 → 失敗,留下 INVALID_STATE。
  • M0 的 TLE5012B 用的是 incremental 模式、沒有 index 訊號,編碼器偏移本來就每次上電都要重做,不能 pre_calibrated。

可以把 M0 的馬達 pre_calibrated 勾起來再存檔,開機就會自動完成編碼器校正(通電時 M0 會自己轉一小段)。我選擇維持現狀、每次手動做,比較清楚馬達什麼時候會動。

每次上電的操作順序

M0(X2212+編碼器)M1(A2212 sensorless)
1清錯誤(開機自動校正失敗留下的 INVALID_STATE)有錯誤才清
2完整校正(嗶一聲、再轉一小段,回到 IDLE)不用(已存 pre_calibrated)
3選位置(TRAP_TRAJ)或速度模式選速度模式
4閉迴路(按鈕變綠)閉迴路
5送目標位置/速度送 8~10 turns/s 以上
停0 =減速並鎖住;IDLE =放掉IDLE

小結

ODrive v3.6 用 CAN 控制其實很簡單,難的是「看得到狀態」:沒進閉迴路、帶著錯誤、校正值壞掉,從馬達外表看起來都只是「不動」或「抖」。這次的介面把狀態按鈕、錯誤、校正值都攤在同一個視窗,CAN 控制和 USB 設定一起用,下次換馬達或調參數應該就快很多。之前的 ATS 文章:ATS 操作台讀行車電腦模擬器(OBD-II、PCAN)、ATS 透過網路控制 ESP32 四路繼電器。ODrive 早期的設定過程在軟硬體的天空:odrive perform Sunnysky X2212 980KV motor with Encoder TLE5012B、PeakCAN Control ODrive with A2212-1400KV and X2212-980KV。

2026年11月18日 星期三

Turning an Old Android Phone into a GPS Tracker with Termux: On-Device Logging, a Leaflet Map, and Five Pitfalls | 舊 Android 手機用 Termux 變 GPS 追蹤器:手機端記錄、Leaflet 地圖頁與五個實測踩坑

一支沒插 SIM 卡的舊 Android 手機,裝上 Termux 之後可以當成 GPS 追蹤器:手機自己記錄位置,家裡的 Linux 主機把資料收回來,用瀏覽器就能看到目前位置、走過的軌跡、每一趟行程的里程和時速。整套東西不用寫 Android App、不用 Google Maps 金鑰、不用雲端服務,主機端只用 Python 標準函式庫。這篇記錄兩天內從第一版做到可用的過程,重點放在實際踩到的五個坑,每一個都是實測出來的。

先講清楚範圍:這是放在自己手機、看自己位置的工具,網頁只開在 Tailscale 私有網路裡。文中的截圖用的是裁掉住家和公司附近路段之後的示範資料。


圖說:完成後的畫面:軌跡依時速上色,下方是目前位置和這趟行程的摘要

一、架構:手機記錄、主機同步、瀏覽器顯示

圖說:三個部分各做一件事,中間只靠 SSH 和 HTTP

  • 手機:Termux 加 Termux:API,一支 shell script 常駐,用 termux-location 取位置,寫進手機本機的 CSV。
  • 主機:一支 Python 程式,每 20 秒用 SSH 把 CSV 裡比資料庫新的行拉回來存進 SQLite,同時提供網頁和 JSON API。
  • 瀏覽器:Leaflet 加 OpenStreetMap 圖磚,每 10 秒更新一次。
  • 連線:手機和主機都在 Tailscale 裡,手機不管連家裡 Wi-Fi、公司 Wi-Fi 還是另一支手機的熱點,主機都用同一個位址連得到。

手機要能遠端 SSH 進 Termux、開機自動起 sshd 和 Tailscale,這部分的設定是另一個專題,這裡不重複。座標轉地址用 OpenStreetMap 的 Nominatim,免費、不用金鑰,規定是每秒最多查一次,所以主機端有快取。

二、第一版為什麼不行:主機每分鐘去問手機

最直覺的做法是主機每分鐘 SSH 到手機跑一次 termux-location,把結果存起來。在家裡測沒問題,第二天帶出門就露出兩個毛病:

  • 斷網就漏:手機走熱點時連線不穩,有一段 6 分鐘、一段 14 分鐘主機連不上手機,那幾分鐘的位置就永遠沒有了。地圖上變成一條橫跨街區、切過河面的直線。
  • 太稀:一次 SSH 加一次定位就要十幾秒,實際是 1.5 到 2 分鐘才一筆,開車時每個轉彎都被切掉。

所以改成手機自己記:位置先寫在手機本機,主機只負責同步。網路斷掉時照記,連上後一次補回來。

# 手機端:取一筆、寫一行(欄位:時間,緯度,經度,誤差,海拔,速度,來源)
j=$(timeout 15 termux-location -p gps -r once </dev/null)
echo "$(date +%s),$lat,$lon,$acc,$alt,$speed,gps" >> ~/gpslog/track.csv

# 主機端:只拉比資料庫新的行(since 是資料庫裡最後一筆的時間)
ssh -p 8022 phone "awk -F, -v t=$since '\$1>t' ~/gpslog/track.csv"

主機的同步指令順便檢查記錄程式還在不在,不在就把它叫起來,所以手機重開機後不用另外設自動啟動。

三、踩到的五個坑

坑 1:termux-* 指令會吃掉 stdin

用 ssh phone 'bash -s' <<EOF 一次送一整批指令過去測試時,跑到一半後面的指令全部不見,有些還假性逾時。原因是 termux-* 這些指令會讀標準輸入,把還沒執行的腳本內容當成輸入吃掉了。解法是每個指令後面加 </dev/null,或先把腳本 scp 過去再執行。

坑 2:室內等不到 GPS,Termux:API 被系統砍掉,通知狂跳

圖說:手機放在辦公室約一小時,累積了 50 則錯誤通知

手機帶進辦公室後,位置變成 20 分鐘才進來一筆,通知列還一直跳「Termux:API Error: Error in ResultReturner」。從手機的 logcat 看,Termux:API 這個 App 每 80 秒左右就被重啟一次:

09:12:42  TermuxAPIApplication: AppInit                 ← 行程啟動
09:14:05  com.termux.api: reacting to signal 3          ← 系統判定沒回應,要它吐堆疊
09:14:05  com.termux.api: Wrote stack traces to tombstoned
09:14:05  TermuxAPIApplication: AppInit                 ← 被砍掉後重啟
09:14:05  ResultReturner: java.io.IOException: Connection refused   (連續好幾筆)

termux-location -r once 是「等到下一筆定位才回」。室內收不到衛星就一直等,卡到系統判定這個 App 沒回應而砍掉它;這時排隊中的其他請求,客戶端早就逾時走了,App 重啟後一筆一筆回傳都找不到人,每筆失敗就跳一則通知。

對策是室內根本不要試 GPS。判斷方法很土但有效:手機連著家裡或公司的 Wi-Fi 就當作在室內,只讀系統已經算好的網路定位(-p network -r last,這個是立即回應的);連的是熱點或沒有 Wi-Fi 才進 GPS 模式。

INDOOR_SSIDS="家裡的SSID|公司的SSID"
if ssid | grep -qxE "$INDOOR_SSIDS"; then
  termux-location -p network -r last </dev/null   # 立即回應,不會卡
  sleep 60; continue
fi

坑 3:移動中的網路定位會把你丟回幾百公尺外

過橋的時候 GPS 有一次沒在時限內回應,程式退而求其次用了網路定位,結果拿到的是對岸 600 公尺外的舊位置(誤差標示 100 公尺)。軌跡就多了一條從南岸跳回北岸再跳回來的線。

網路定位靠的是周圍 Wi-Fi 基地台的位置資料庫,人在移動、又是連著一支也在移動的熱點時,它給的常常是過時的位置。處理分兩層:

  • 手機端:兩分鐘內有過 GPS 定位,就繼續等 GPS,不拿網路定位頂替。
  • 主機端:顯示和匯出前過濾,前後三分鐘內有 GPS 點的網路定位不採用;要時速 180 公里以上才到得了的點也丟掉。資料庫保留原始資料,只在輸出時濾。

坑 4:兩次 GPS 請求之間多做一件事,晶片就涼了

這個最難找。同一支程式,早上去程是 4 秒一筆、誤差 2 到 3 公尺;傍晚回程卻變成 8 到 30 秒一筆、誤差 10 公尺,軌跡變成鋸齒狀。

早上去程傍晚回程
取樣間隔約 4 秒8~30 秒
誤差2~3 公尺9~11 公尺
差別每輪:GPS → 休息 2 秒每輪:查 Wi-Fi 名稱 → GPS → 休息 2 秒

差別就是坑 2 加的那個「每輪先查 Wi-Fi 名稱」。查一次約 2 秒,加上原本休息的 2 秒,兩次 GPS 請求之間隔太久,GPS 晶片就關掉了;下一筆等於重新開機定位,要十幾秒,而且剛定到位的第一筆精度本來就差。請求夠密的時候晶片一直開著,每筆幾秒就回,精度也好。

改法是 GPS 剛定到位(10 秒內)就不查 Wi-Fi,直接要下一筆;只有 GPS 斷了一陣子才回頭查是不是進室內了。改完當場在戶外量 100 秒:

間隔(誤差):4(2m) 5(1m) 4(1m) 5(1m) 6(2m) 4(2m) 5(2m) 4(2m) 4(2m) 4(2m) 5(2m) 5(2m) 5(2m) 5(2m) 4(2m) 4(2m)

結論是:GPS 請求之間不要插任何耗時的動作,間隔維持在 4 秒左右。

坑 5:想讓 GPS 保持開著,反而更慢

在找到坑 4 的真正原因之前,我先猜是「GPS 晶片沒保溫」,於是在背景多開一個 termux-location -p gps -r updates 想讓晶片不要關。結果更糟。實測發現兩件事:這一版 Termux:API 的 updates 跑 32 秒只回一筆;而且定位請求是排隊一個一個處理的,背景那個佔著的時候,正常的請求全部被擋住。這個修改上線約兩小時就拿掉了。先量再改,比先猜再改省事。

四、網頁功能

圖說:手機上的即時畫面

  • 目前位置:藍點加誤差圈,下方顯示地址、時間、座標、誤差、定位來源、電量、目前時速。
  • 回現在位置:地圖跟著手機移動;手動拖地圖就停止跟隨,方便看別的地方。
  • 旋轉與車頭朝上:Leaflet 本身不能轉,用 leaflet-rotate 外掛。車頭朝上是拿最近兩分鐘內相距 20 公尺以上的兩個 GPS 點算行進方向,停著不動時沿用上一次的方向,不會亂轉。
  • 依日期查看、下載:選某一天看整天路線;可下載 GPX(匯入其他地圖軟體)或 CSV(Excel 直接開)。
  • 停止記錄:按一下,主機通知手機關掉記錄程式。停止的時段另外記在資料庫,那段時間的位置一律不匯入,地圖上直接斷開。

圖說:車頭朝上:地圖轉成行進方向朝上,左上的紅色箭頭指向北方

行程清單、時速上色、平滑

圖說:行程清單:自動切成一趟一趟,點一趟就只看那一趟

  • 切行程:資料中斷超過 5 分鐘,或在 60 公尺範圍內停留滿 5 分鐘,就算一趟結束。不到 200 公尺的不算,免得室內定位飄動被當成出門。
  • 時速:手機單次定位回來的速度欄位幾乎都是 0,所以用前後兩點的距離除以時間來算。軌跡線依時速分四級上色。
  • 交通方式:用移動中時速的中位數猜,只分走路、慢速、行車。開車和騎機車從速度分不出來,就不硬分。
  • 平滑:連續的 GPS 點做 1-2-1 加權平均,濾掉一兩公尺的左右跳動。地圖和 GPX 用平滑後的位置,CSV 給原始座標。

圖說:點進單一行程:藍色是 25~60 公里,橘色 7~25,綠色是 7 以下(等紅燈、轉彎)

五、資料量和耗電

  • 資料量:一筆約 70 位元組。每天外出兩小時(GPS 4 秒一筆)加上其餘時間在室內,一天約 0.2 MB,一年不到 100 MB。
  • 室內不重複存:位置沒變(30 公尺內)就不寫,只每 10 分鐘存一筆表示還活著。
  • 耗電:晚上連續記錄約 35 分鐘(多數時間 GPS 開著),電量從 98% 掉到 97%。樣本只有這一次,長時間的數字還要再觀察。

六、還沒做和已知限制

  • 車頭朝上、目前時速這兩項做好時手機都不在移動,只用指定方向的方式驗證過畫面,實際邊走邊轉的效果還沒看過。
  • 戶外長時間收不到衛星(例如地下停車場)時,仍可能偶爾跳一兩則 Termux:API 錯誤通知。
  • 手機靜置室內時系統會放慢背景程式,設定 60 秒一輪實際拉長到 3、4 分鐘。位置沒變所以影響不大,還沒處理。
  • 資料庫沒有備份,只有主機上一份。
  • 看一整週的軌跡時點數會很多,還沒做抽稀。
  • 室內的判斷靠 Wi-Fi 名稱清單,常待的新地點要手動加進去。

回頭看,這個專題真正花時間的不是地圖頁,而是搞清楚 termux-location 在各種情況下的行為:什麼時候立即回、什麼時候會卡住、卡住會拖累誰、請求之間隔多久晶片會關。這些文件上都沒寫,只能一個一個量出來。