學習目標
- ✓理解土壤含水量會改變導電程度。
- ✓使用原始值與教學用百分比積木。
- ✓建立同一支探頭的乾、濕校準流程。
BATCH 02 · 已發布
SENSOR / SOILMOISTURE
土壤濕度感測器用乾土、濕土與水中三點建立自己的校準
類比土壤濕度感測器利用探針與土壤導電程度產生 ADC 值。桃園版 Blockly 同時提供原始值與教學用百分比，但百分比只是 0–1023 線性映射，實機仍要用乾濕端點校準。
入門45 分鐘Arduino UNO
READYDATA
SIGNAL STABLE土壤濕度感測器
VCC / 3.3V 或 5VGND / GND
01 / PREPARE
課前準備
先確認這一課要學會什麼，以及桌面上需要哪些材料。
材料清單
1 個類比土壤濕度感測器電阻式探頭會因長時間通電而腐蝕。
1 組Arduino UNO類比輸出接 A0。
各 1乾土、濕土與水杯以三種狀態建立比較資料。
02 / HOW IT WORKS
百分比不是感測器直接量出的真實含水量
探針量到的是與土壤導電相關的類比訊號；Blockly 的百分比是方便教學的線性映射，必須配合實際土壤與探頭重新校準。
量乾土
記錄探頭在乾土中的原始值。
量濕土
加入水並等待分布後再量。
建立比例
用自己的乾濕端點取代固定百分比。
DISTANCE FORMULAteachingPercent = map(raw, 0, 1023, 0, 100)
不同探頭的輸出方向可能不同；不要把教學百分比直接當作體積含水率。
03 / WIRING
接線配置
使用 A0 讀取類比訊號；測試後拔除或關閉探頭電源，可降低電阻式探頭電解與腐蝕。
MODULE土壤濕度感測器VCCGNDAO／SIG
CONTROLArduino UNO3.3V 或 5VGNDA0
| 模組腳位 | 接到控制板 | 訊號方向 | 檢查重點 |
|---|---|---|---|
| VCC | 3.3V 或 5V | 電源 | 依模組規格。 |
| GND | GND | 地線 | 共地。 |
| AO／SIG | A0 | 類比輸出 | 對應 PIN。 |
✓ WIRING ROWS ALIGNED
已將 3 條線路依同一筆資料逐列對齊；電壓仍須依手上模組版本確認。
04 / BLOCK GUIDE
本課會用到的積木
積木名稱與型別以桃園版 Blockly 現行程式為準，不以通用積木替代。
土壤濕度初始化
BLOCK 01
playrobot_soil_moisture_setup土壤濕度初始化
設定類比輸入
位置：感測器 → 環境感測器 → 土壤濕度土壤濕度原始值
BLOCK 02
playrobot_soil_moisture_raw土壤濕度原始值
取得 ADC 原始資料
位置：感測器 → 環境感測器 → 土壤濕度土壤濕度百分比
BLOCK 03
playrobot_soil_moisture_percent土壤濕度百分比
取得教學用 0–100 映射值
位置：感測器 → 環境感測器 → 土壤濕度序列埠列印
BLOCK 04
serial_println序列埠列印
記錄校準資料
位置：輸出05 / BLOCK EXAMPLE
建立一支探頭的濕度尺
列印原始值與教學百分比，再用乾濕端點解讀。
桃園版 BLOCKLY / WORKSPACE● BLOCK STYLE
Arduino 程式
初始化
土壤濕度初始化（A0）
playrobot_soil_moisture_setup重複執行
arduino_delay土壤濕度原始值
playrobot_soil_moisture_raw土壤濕度百分比
playrobot_soil_moisture_percent序列埠列印
arduino_serial_print重複執行
土壤濕度初始化（A0）
playrobot_soil_moisture_setup重複執行
arduino_delay土壤濕度原始值
playrobot_soil_moisture_raw土壤濕度百分比
playrobot_soil_moisture_percent序列埠列印
arduino_serial_printX / 010Y / 024
組合步驟
三點測量
量乾土、濕土與水中讀值。
為什麼：知道模組的有效變化範圍。固定插入深度
每次保持探頭深度與角度相同。
為什麼：接觸面積會影響導電結果。避免長時間通電
採樣後關閉探頭。
為什麼：降低電阻式探頭腐蝕。積木使用重點先辨認積木是「回傳值」還是「執行動作」，再放到正確的拼接位置。
playrobot_soil_moisture_setup：設定類比輸入
EXAMPLE DOWNLOAD下載後即可練習
下載桃園版 Blockly 專案或對應的文字程式。
預期觀察結果
| 測試情境 | 可能讀值 | 判讀 |
|---|---|---|
| 乾土 | 讀值落在乾燥區間 | 土壤導電性較低。 |
| 濕土或水中 | 讀值改變 | 水分增加導電路徑。 |
06 / CODE EXPLAINED
範例程式逐段解說
這段程式把「土壤濕度感測器」的實體接線、桃園版 Blockly 積木與 Arduino 執行流程接在一起。先對照腳位，再看初始化、讀值、輸出與等待的順序；每一步都可以回到本頁的積木範例實測。
GENERATED LOGIC / EXCERPT積木背後的程式碼收合程式碼 −
TAOYUAN BLOCKLY / ARDUINO C++READ ONLY
const int SOIL_PIN = A0;
void setup() {
Serial.begin(115200);
}
void loop() {
int raw = analogRead(SOIL_PIN);
int teachingPercent = map(raw, 0, 1023, 0, 100);
Serial.print(raw);
Serial.print(", ");
Serial.println(teachingPercent);
delay(1000);
}SELF STUDY GUIDE先看哪一段、為什麼？
先載入函式庫與建立裝置
// 土壤濕度感測器 library函式庫提供桃園版 Blockly 產生器所需的底層功能；若這裡的函式庫或物件名稱不對，後面的 playrobot_soil_moisture_setup 就算接線正確也無法使用。
把程式腳位對回接線表
const int SOIL_PIN = A0;本頁接線是 VCC → 3.3V 或 5V、GND → GND、AO／SIG → A0。程式常數、積木欄位與實體線材必須使用同一組設定；若改了其中一邊，另外兩邊也要一起改。
在 setup 只做一次初始化
void setup() {啟動序列埠、I²C／UART 或感測器初始化通常只需要做一次，所以要放在「初始化」區，不要每一圈重複建立裝置。這也對應範例中的啟動積木。
在 loop 更新並取得資料
void loop() {重複執行區先讓感測器更新，再讀取 土壤濕度初始化。若元件有 data ready、可用性或逾時條件，先判斷狀態再使用數值，避免把無效資料當成真實測量。
輸出結果並控制取樣速度
Serial.print(raw);先把原始值、單位或狀態送到序列埠，才能和預期結果比較；等待時間則決定更新速度。若看到亂碼，先檢查鮑率；若數值跳動，先增加合理的取樣間隔或做校正。
自學檢查
- 實體接線：VCC → 3.3V 或 5V、GND → GND、AO／SIG → A0。
- 主要積木：playrobot_soil_moisture_setup；先確認它是回傳值還是執行動作。
- 本課板子：Arduino UNO；更換控制板或模組版本時，電壓、腳位與函式庫都要重新確認。
07 / DEBUG
常見問題與故障排除
先從「電源、接線、腳位、物體」四個方向檢查，再修改程式。
濕土百分比變小
先檢查：確認自己的模組輸出方向。
處理方式：以乾濕實測重新定義映射方向。
讀值飄動
先檢查：探頭是否接觸不穩或插入深度不同。
處理方式：固定探頭位置並取平均。
探頭變黑或腐蝕
先檢查：是否長時間浸在土中通電。
處理方式：改成間歇採樣或使用電容式防水探頭。
08 / NEXT MISSION
延伸挑戰
從顯示數值，逐步走向條件判斷、燈號回饋與雷達專題。
三狀態校準表
題目：記錄乾土、濕土與水中的原始值。
解題方向
這題要延伸「土壤濕度初始化」的基本讀值：先保留已驗證的接線與初始化，再把題目要求的資料處理加在重複執行區。先把資料整理成可觀察的序列埠或表格結果。
- 先匯入本頁 Blockly 範例，確認感測器在沒有加入挑戰功能時能穩定讀值。
- 保留 playrobot_soil_moisture_setup，先把讀值送到序列埠，建立正常範圍或基準值。
- 依題目「記錄乾土、濕土與水中的原始值。」加入比較、分類、累計或時間判斷；門檻要用實測資料決定，不要直接猜一個數字。
- 用至少三種不同情境測試，記錄輸入、程式判斷與輸出結果，再修正門檻或取樣間隔。
植物澆水提示
題目：低於自訂門檻時點亮 LED。
解題方向
這題要延伸「土壤濕度初始化」的基本讀值：先保留已驗證的接線與初始化，再把題目要求的資料處理加在重複執行區。把結果接到題目指定的輸出元件。
- 先匯入本頁 Blockly 範例，確認感測器在沒有加入挑戰功能時能穩定讀值。
- 保留 playrobot_soil_moisture_setup，先把讀值送到序列埠，建立正常範圍或基準值。
- 依題目「低於自訂門檻時點亮 LED。」加入比較、分類、累計或時間判斷；門檻要用實測資料決定，不要直接猜一個數字。
- 用至少三種不同情境測試，記錄輸入、程式判斷與輸出結果，再修正門檻或取樣間隔。
間歇供電
題目：設計只在量測前供電的探頭控制。
解題方向
這題要延伸「土壤濕度初始化」的基本讀值：先保留已驗證的接線與初始化，再把題目要求的資料處理加在重複執行區。先把資料整理成可觀察的序列埠或表格結果。
- 先匯入本頁 Blockly 範例，確認感測器在沒有加入挑戰功能時能穩定讀值。
- 保留 playrobot_soil_moisture_setup，先把讀值送到序列埠，建立正常範圍或基準值。
- 依題目「設計只在量測前供電的探頭控制。」加入比較、分類、累計或時間判斷；門檻要用實測資料決定，不要直接猜一個數字。
- 用至少三種不同情境測試，記錄輸入、程式判斷與輸出結果，再修正門檻或取樣間隔。
教師快速檢核4 POINT CHECK
- □ 能解釋土壤導電與含水量的關係。
- □ 能建立自己的乾濕校準端點。
- □ 能說明電阻式探頭的腐蝕問題。
09 / EVIDENCE資料來源與版本展開查看 ＋
官方教學桃園版 Blockly
Gravity Analog Soil Moisture SensorDFRobot
↗確認探針導電原理、供電與乾／濕／水中數值區間。
桃園版 Blockly 土壤濕度積木桃園版 Blockly
LOCAL對照 setup、raw 與 percent 積木。