電子發燒友App
?
1 簡介
RTduino為RT-Thread的Arduino生態兼容層，是RT-Thread社區的下屬子社區，旨在兼容Arduino社區生態（如上千種分門別類的Arduino庫，以及Arduino社區優秀的開源項目），來豐富RT-Thread社區軟件包生態，并降低RT-Thread操作系統以及與RT-Thread適配的芯片的學習門檻。可以讓用戶通過Arduino的函數和編程方法，輕松地將RT-Thread以及特定的芯片使用起來。用戶也可以直接使用Arduino社區的庫（例如I2C傳感器驅動庫、算法庫等）直接用在RT-Thread工程中，極大地補充了RT-Thread社區生態。該項目由RT-Thread社區核心開發和維護者滿鑒霆發起。本軟件包可以運行在RT-Thread Studio IDE和Keil編譯環境下，因為Arduino的庫都是基于GCC環境開發的，因此強烈推薦使用RT-Thread Studio IDE運行。1.1 已經支持Arduino生態兼容層的RT-Thread BSP
| BSP名稱 | 備注 |
|---|---|
| STM32L475潘多拉 | 引腳異構布局，但外設豐富 |
| STM32F072 Nucleo | 標準Arduino UNO引腳布局 |
| STM32F401 Nucleo | 標準Arduino UNO引腳布局 |
| STM32F469 Discovery | 標準Arduino UNO引腳布局 |
| STM32F103 BluePill | 引腳異構布局 |
| ES32F3696 | 引腳異構布局 |
注：RTduino也可以無需適配特定BSP，直接運行在任意RT-Thread BSP上，請參考第5章-RTduino精簡模式。
2 如何使用本兼容層
本軟件包需要對特定的BSP進行適配之后才可以使用，適配方法很簡單請參考。本節以STM32L475潘多拉開發板和RT-Studio開發環境為例，來講解如何使用本兼容層。2.1 參考資料
2.2 工程的創建和導入
請到RT-Thread Github官方倉庫，下載最新的源碼。對于部分用戶下載Github源碼慢的問題，可以百度或者到B站搜索“Github加速”等關鍵字來解決，此處不再贅述。
rt-threadspstm32stm32l475-atk-pandora。工程名字隨便起一個就好，比如STM32：
點擊完成(Finish)，稍等片刻即可完成工程導入。
導入成功之后，雙擊RT-Thread Settings，進入到RT-Thread工程配置界面，點擊<<按鈕，進入到詳細配置頁面：
?
點擊Hardware，選擇Support Arduino，只需要點一下即可，其他依賴項會自動處理。然后點擊小錘子按鈕進行編譯，RT-Thread Studio會自動保存你當前的配置并下載RTduino軟件包以及依賴項軟件包，并將這些軟件包加入到工程中，最后自動編譯整個工程。
總的來講，你只需要選擇Support Arduino，并點一下小錘子按鈕，就坐等編譯成功即可。
至此，RTduino軟件包安裝完成，此BSP工程已經具備了兼容Arduino生態的能力。
2.3 RTduino文件夾目錄結構
RTduino軟件包包含有兩個主要的文件夾：core和libraries。
-
core文件夾主要是提供Arduino內置的所有的API函數，例如analogWrite、analogRead函數等等，這些函數可以在Arduino官方找到詳細的介紹。
-
libraries文件夾是Arduino庫所在文件夾。其中：
-
buildin文件夾下存放著Arduino內置的一些庫，例如Servo舵機驅動庫，Wire I2C驅動庫等等；
-
user文件夾是用戶文件夾，這是對用戶來說很重要的一個文件夾，里邊默認是空的，用戶可以把下載好的Arduino庫拖入到此文件夾中來，在下個章節會細說這個操作。
2.4 Arduino經典的setup和loop函數在哪里？
對于Arduino，最經典的莫過于setup和loop函數。這兩個函數位于BSP目錄下的applications文件夾內arduino_main.cpp文件中。以潘多拉板為例，這兩個函數位于：bsp/stm32/stm32l475-atk-pandora/applications/arduino_main.cpp文件中，在開啟RTduino軟件包后，你可以直接在工程的Applications組中找到它。2.5 點一個LED燈吧！
1#include?可以看到，板載的LED燈已經開始閃爍，串口開始輸出了。
注意：
?
由于RT-Thread的main.c文件內，也會默認閃爍一個LED燈，如果板子上只有一個LED燈的話，兩個線程會發生干涉。但是你會發現這個LED的閃爍速度明顯變快了。因為main.c那邊的閃爍周期是1000ms，上面這個例程是200ms。
?
如果你用潘多拉板，main.c閃爍的是紅燈，RTduino兼容層的Arduino程序默認閃爍的是綠色的燈，二者不會發生干擾。
2.6 具體Arduino引腳分布信息
由于每個BSP的板子設計、以及芯片型號等，引腳分布是有區別的，因此需要到指定BSP的applications/arduino文件夾下的README.md文件查看詳細信息。例如：
STM32L475潘多拉板的Arduino引腳布局的詳細說明 | STM32F072 Nucleo板的Arduino引腳布局的詳細說明
3 Arduino庫的導入和使用
3.1 術語說明
軟件包：英文為 software package，是指RT-Thread社區所屬維護的第三方擴展，是RT-Thread原生生態一部分。
庫：英文為library，是指Arduino社區所屬維護的第三方擴展，是Arduino原生生態一部分。
庫和軟件包其實是一個意思，只不過兩個社區叫法不一樣。
3.2 RTduino兼容層對Arduino庫的兼容情況
目前RTduino兼容層可以實現對Arduino純軟件類（例如算法類、數據處理類等）、串口相關、I2C傳感器相關的庫做到100%兼容。
支持的詳細情況和計劃，請查看：
https://github.com/RTduino/RTduino/discussions/26
3.3 導入一個Arduino庫到RT-Thread工程（以潘多拉板為例）
首先，你需要到Arduino官方的軟件包分類中心去查找你想要的庫，或者直接在Github上搜索你想要的庫，一般都是C++類型的。比如，我想要一個驅動AHT10溫濕度傳感器的庫，可以在此處下載。此處以潘多拉板為例，因為潘多拉板板載了AHT10傳感器。下載好之后，直接將zip壓縮包拖進RTduino文件夾下的librariesuser這個目錄下即可。選擇當前工程右鍵選擇Sync Sconscript to project也就是讓RT-Studio重新掃描并組織一遍工程目錄，在掃描的過程中，RT-Studio會自動將zip壓縮包解壓，并按照Arduino IDE的文件添加邏輯（也就是忽略examples文件夾，并將其他文件夾的.c文件和.h路徑添加到工程），將Arduino庫添加到RT-Thread工程中來。然后再點一下小錘子按鈕來重新編譯一下工程。
?
?
工程編譯通過之后，你可以將這個AHT10 Arduino庫的例程（位于該庫文件夾下的examples文件夾）直接復制到arduino_main.cpp文件下運行，你可以看到，串口會輸出當前的溫濕度，Arduino的例程是直接可以在RT-Thread上運行起來的。3.4 RTduino內置庫
在RTduino中內置了兩類庫，方便用戶直接使用。
一類是在Arduino中原生內建(buildin)的庫，存放于 libraries/buildin 文件夾內。具體如下表所示：
4 如何給某個BSP適配RTduino
4.1 創建文件夾和文件
需要在某個BSP的applications文件夾下創建如下文件、文件夾：
參考示例BSP：STM32F072 Nucleo板applications文件夾 | STM32L475 潘多拉板applications文件夾
4.1.1 arduino_main.cpp文件
該文件是Arduino的編程入口，提供setup和loop函數。在loop函數默認以200ms為周期，閃爍Arduino內建LED燈（LED_BUILTIN）。如果該BSP默認支持SPI功能且為UNO引腳布局，由于SPI和LED_BUILTIN可能存在沖突(D13)，可以在loop函數內以 Serial.println("Hello Arduino "); 代替頻閃LED（例如STM32F401 Nucleo板）。
4.1.2 arduino_pinout文件夾
需要在applications文件夾下創建arduino_pinout文件夾，這個文件夾主要包含 arduino_pinout.c 和 arduino_pinout.h 兩個關鍵的文件，這兩個文件是對接的關鍵。用戶只需要做好這兩個文件，即可完成與RTduino的對接。
同時，這個文件夾內也需要SConscript腳本文件，以及提供Arduino引腳布局的README說明文檔。請參照上面的示例BSP來完成對這兩個文件的編寫。
4.1.3 arduino_pinout.c 文件的編寫
arduino_pinout.c 內需要完成一個IO編號和功能的映射表。由于Arduino的習慣是采用1-13 (D0-D13) 以及 A0-A5的引腳編號，而正規的MCU的引腳編號一般都是PA1之類，因此需要將MCU真正的引腳編號與Arduino引腳編號映射起來。
以下段代碼來舉例講解：
1/*
2????{Arduino?Pin,?RT-Thread?Pin?[,?Device?Name(PWM?or?ADC),?Channel]}
3????[]?means?optional
4????Digital?pins?must?NOT?give?the?device?name?and?channel.
5????Analog?pins?MUST?give?the?device?name?and?channel(ADC,?PWM?or?DAC).
6????Arduino?Pin?must?keep?in?sequence.
7*/
8/*?按照先數字引腳后模擬引腳的順序從0開始，一定要按序排列?*/
9/*?可以按照板卡實際IO情況，靈活調整功能，不一定非得按照Arduino?UNO的引腳功能布局，但是建議按此布局設計?*/
10const?pin_map_t?pin_map_table[]=
11{
12????{D0},?/*?RX?*/
13????{D1},?/*?TX?*/
14????{D2,?GET_PIN(A,10)},
15????{D3,?GET_PIN(B,3),?"pwm2",?2},?/*?PWM?*/
16????{D4,?GET_PIN(B,5)},
17????{D5,?GET_PIN(B,4),?"pwm3",?1},?/*?PWM?*/
18????{D6,?GET_PIN(B,10),?"pwm2",?3},?/*?PWM?*/
19????{D7,?GET_PIN(A,8)},
20????{D8,?GET_PIN(A,9)},
21????{D9,?GET_PIN(C,7),?"pwm3",?2},?/*?PWM?*/
22????{D10,?GET_PIN(B,6),?"pwm16",?1},?/*?PWM?*/
23????{D11,?GET_PIN(A,7),?"pwm17",?1},?/*?PWM?*/
24????{D12,?GET_PIN(A,6)},
25????{D13,?GET_PIN(A,5)},
26????{D14},?/*?I2C1-SDA?*/
27????{D15},?/*?I2C1-SCL?*/
28????{D16,?GET_PIN(C,13)},?/*?user?button?*/
29????{A0,?GET_PIN(A,0),?"adc1",?0},?/*?ADC?*/
30????{A1,?GET_PIN(A,1),?"adc1",?1},?/*?ADC?*/
31????{A2,?GET_PIN(A,4),?"adc1",?4},?/*?ADC?*/
32????{A3,?GET_PIN(B,0),?"adc1",?8},?/*?ADC?*/
33????{A4,?GET_PIN(C,1),?"adc1",?11},?/*?ADC?*/
34????{A5,?GET_PIN(C,0),?"adc1",?10},?/*?ADC?*/
35}
如上截取展示了IO編號和功能映射表，每一行用花括號包裹（實際是一個結構體）來建議一個IO的映射關系：
1{Arduino引腳編號,?RT-Thread引腳編號(通過GET_PIN宏獲取),?復用功能的設備名(PWM、ADC或DAC),?該復用功能設備的通道號}
其中，Arduino引腳編號，即是第一個參數，是必填的，D0 - Dx 或者是 A0 - Ax。注意一定要按先數字引腳后模擬引腳照順序來填寫。
RT-Thread引腳編號，即第二個參數，rt_pin_write中引腳編號填什么，這里就填什么，一般使用 GET_PIN 宏來獲取。注意：D0、D1以及I2C、SPI IO需要將此參數略過。
后兩個參數是復用功能IO才需要填寫的，普通引腳只需要略過即可。
4.1.4 arduino_pinout.h 文件的編寫
參考示例BSP：STM32L475 潘多拉板applications文件夾
該文件主要負責定義各種宏，包括：
D0、A0等引腳的數字宏，該宏一定要按照先數字引腳后模擬引腳的順序進行排號。
定義默認開啟的一些硬件功能，如下表所示：
1/*?pins?alias.?Must?keep?in?sequence?*/
2/*?按照先數字引腳后模擬引腳的順序從0開始，一定要按序排列?*/
3/*?可以按照板卡實際IO情況，靈活調整功能，不一定非得按照Arduino?UNO的引腳功能布局，但是建議按此布局設計?*/
4#define?D0???(0)
5#define?D1???(1)
6#define?D2???(2)
7#define?D3???(3)
8#define?D4???(4)
9#define?D5???(5)
10#define?D6???(6)
11#define?D7???(7)
12#define?D8???(8)
13#define?D9???(9)
14#define?D10??(10)
15#define?D11??(11)
16#define?D12??(12)
17#define?D13??(13)
18#define?D14??(14)
19#define?D15??(15)
20#define?D16??(16)
21#define?D17??(17)
22#define?D18??(18)
23#define?D19??(19)
24#define?D20??(20)
25#define?D21??(21)
26#define?D22??(22)
27#define?D23??(23)
28#define?D24??(24)
29#define?D25??(25)
30#define?D26??(26)
31#define?D27??(27)
32#define?D28??(28)
33#define?D29??(29)
34#define?D30??(30)
35#define?D31??(31)
36#define?D32??(32)
37#define?A0???(33)
38#define?A1???(34)
39#define?A2???(35)
40#define?A3???(36)
41#define?DAC0?(37)
42
43#define?F_CPU??80000000L?/*?CPU:?80MHz，定義CPU的主頻?*/
44#define?LED_BUILTIN??D22?/*?Default?Built-in?LED，定義Arduino內置LED的引腳編號?*/
45
46/*?定義I2C設備名稱，在使用Wire庫時會直接調用。可選，如果沒有I2C功能，不需要定義該宏?*/
47#define?RTDUINO_DEFAULT_IIC_BUS_NAME????????????"i2c4"
48
49/*?定義SPI設備名稱，在使用SPI庫時會直接調用。可選，如果沒有SPI功能，不需要定義該宏?*/
50#define?RTDUINO_DEFAULT_SPI_BUS_NAME????????????"spi2"
51
52/*?
53???定義高精度定時器設備名稱，該宏主要是提供us時基信號使用。
54???所有Cortex-M核MCU均不需要定義此宏，RTduino會自動調用systick來計算us級時間戳。
55???非Cortex-M核的MCU需要提供一個硬件定時器來提供us級時間戳。
56?*/
57#define?RTDUINO_DEFAULT_HWTIMER_DEVICE_NAME?????"timer7"
58
59/*?如果有串口2、串口3可以定義串口2、3的設備名稱，若沒有可直接不定義此宏?*/
60#define?RTDUINO_SERIAL2_DEVICE_NAME?????????????"uart2"
4.2 修改Kconfig文件
Kconfig文件位于BSP的board文件夾下：
參考示例BSP：
STM32F072 Nucleo板Kconfig | STM32L475 潘多拉板Kconfig
1menu?"Onboard?Peripheral?Drivers"
2????config?BSP_USING_STLINK_TO_USART
3????????bool?"Enable?STLINK?TO?USART?(uart2)"
4????????select?BSP_USING_UART
5????????select?BSP_USING_UART2
6????????default?y
7
8????#增加?BSP_USING_ARDUINO?配置選項
9????config?BSP_USING_ARDUINO
10????????bool?"Support?Arduino"
11????????select?PKG_USING_RTDUINO
12????????select?BSP_USING_STLINK_TO_USART
13????????select?BSP_USING_GPIO
14????????select?BSP_USING_ADC
15????????select?BSP_USING_ADC1
16????????select?BSP_USING_PWM
17????????select?BSP_USING_PWM2
18????????select?BSP_USING_PWM2_CH2
19????????select?BSP_USING_PWM2_CH3
20????????select?BSP_USING_PWM3
21????????select?BSP_USING_PWM3_CH1
22????????select?BSP_USING_PWM3_CH2
23????????select?BSP_USING_PWM16
24????????select?BSP_USING_PWM16_CH1
25????????select?BSP_USING_PWM17
26????????select?BSP_USING_PWM17_CH1
27????????select?BSP_USING_I2C
28????????select?BSP_USING_I2C1
29????????imply?RTDUINO_USING_SERVO
30????????imply?RTDUINO_USING_WIRE
31????????imply?RTDUINO_USING_ADAFRUIT
32????????default?n
33
34endmenu
Onboard Peripheral Drivers欄下增加 BSP_USING_ARDUINO 配置選項，并依賴相應的PWM、ADC、UART、I2C以及SPI等設備框架，滿足一鍵化開啟RTduino的能力。4.3 編寫Arduino引腳布局(pinout)的README說明文檔
示例：STM32F072 Nucleo的Arduino引腳布局說明文檔 | STM32L475潘多拉的Arduino引腳布局說明文檔該文檔需位于applications/arduino_pinout/README.md，主要介紹該BSP下的Arduino引腳編號和引腳功能，以及注意事項等。5 RTduino精簡模式（快速使用，無需適配特定BSP）
5.1 不使用setup-loop編程模型
setup() 和 loop() 函數是Arduino編程中非常經典的函數，當你在Arduino IDE中新建一個文件時，默認就提供了這兩個函數。這兩個函數RTduino是完全支持的（參見第4章），但是一些較為復雜或龐大的業務邏輯如果放在setup-loop函數中就會受到一些束縛。因此，可以在Env或者RT-Thread Studio的RT-Thread Settings中取消setup-loop編程模型：1RT-Thread?online?packages??--->
2????system?packages??--->
3?????????[*]?RTduino:?Arduino?Ecological?Compatibility?Layer??--->
4??????????????[*]???Don't?use?setup-loop?structure??--->
core/arduino_thread.c 中的 arduino_entry 線程函數中直接編程，或者在任意.cpp文件中調用Arduino API（不局限于Arduino線程，只要是.cpp文件下調用即可）。5.2 如何不用定義引腳映射表，更方便的使用RTduino？
通過上文，我們可以看到，RTduino軟件包并不是直接可以用的，需要RT-Thread BSP方面提供一些配套的支持，如引腳映射表（arduino_pinout）等。但是，如果用戶不想使用Arduino引腳（IO）相關的API（如analogRead等），只想借助RTduino軟件包，來直接兼容運行I2C芯片驅動庫、純軟件算法庫等和IO無關的函數和庫，如何快速的使用起來呢？用戶可以直接在Env或者RT-Thread Studio的RT-Thread Settings中選擇精簡模式 (Enable tiny mode)。在選擇精簡模式后，用戶就無需定義引腳映射表，直接就可以使用Arduino庫中的非IO相關的函數和庫了。開啟精簡模式后，會自動開啟 5.1 章節所介紹的不使用setup-loop編程模型選項，用戶可以在任意.cpp文件下使用Arduino API。1RT-Thread?online?packages??--->
2????system?packages??--->
3?????????[*]?RTduino:?Arduino?Ecological?Compatibility?Layer??--->
4??????????????-*-???Don't?use?setup-loop?structure
5??????????????[*]???Enable?tiny?mode??--->
5.3 常規模式（參見第4章）vs 精簡模式（參見第5章）
下表列舉了在兩種不同模式下，RTduino對Arduino API的兼容情況：
注：SPI庫目前還在施工中，暫不開放使用。
6 需要注意的事項
6.1 包含Arduino.h頭文件
調用到Arduino相關函數和宏的源文件，請包含Arduino.h頭文件，否則可能會報錯：
6.2 Keil AC5
如果使用Keil AC5環境，需要勾選GNU extension。AC6不需要。
6.3 啟用PWM不能調用pinMode函數，否則PWM會失效，ADC、DAC同理
1void?setup()?{
2??//Declaring?LED?pin?as?output
3??//pinMode(led_pin,?OUTPUT);?//不能設置為OUTPUT，否則PWM會失效
4}
5void?loop()?{
6??//Fading?the?LED
7??for(int?i=0;?i<255;?i++){
8????analogWrite(led_pin,?i);
9????delay(5);
10??}
11??for(int?i=255;?i>0;?i--){
12????analogWrite(led_pin,?i);
13????delay(5);
14??}
15}
因為底層已經將對應的PWM、ADC或DAC的IO設置為模擬輸入或者復用推挽，調用pinMode之后把IO模式改成了純輸入輸出，原有的PWM、ADC或DAC功能將無法使用。該問題無要修正，只需要知道調用analogRead和analogWrite的時候不需要設置pinMode即可。一旦調用pinMode，該引腳將喪失analogWrite或者analogRead功能，后續只能當做普通IO使用。
Arduino 官方文檔也是這么建議的：
1You?do?not?need?to?call?pinMode()?to?set?the?pin?as?an?output?before?calling?analogWrite().
2The?analogWrite?function?has?nothing?to?do?with?the?analog?pins?or?the?analogRead?function.
用戶如果對PWM、ADC或DAC引腳使用pinMode函數，在終端也會給出警告：
當然，如果用戶已經知道這樣做的后果，但是故意需要將PWM、ADC或DAC引腳通過pinMode函數轉為普通IO也是完全可以的。
6.4 Serial.begin
在很多Arduino例程中，都喜歡使用如下語句來初始化串口：
1??Serial.begin(9600);
這句話將串口默認初始化成波特率為9600. 但是在RT-Thread中，串口的初始化實際是有RT-Thread驅動框架負責的，并且默認波特率為115200. 因此如果調用Serial.begin(9600) 函數后，串口的波特率將會從默認的115200調整為9600。如果你的終端或者串口助手還保持在115200的波特率，那么接收數據將出現亂碼。
因此建議：
使用Serial.begin()代替Serial.begin(9600)。Serial.begin()無參數方法是RTduino的擴充方法，其表示跟隨使用RT-Thread串口配置，不重新配置串口。
7 貢獻與維護
7.1 項目倉庫地址
https://github.com/RTduino/RTduino
https://gitee.com/rtduino/RTduino
工商網監
評論