?

1 簡介

1.1 已經支持Arduino生態兼容層的RT-Thread BSP

注：RTduino也可以無需適配特定BSP，直接運行在任意RT-Thread BSP上，請參考第5章-RTduino精簡模式。

2 如何使用本兼容層

2.1 參考資料

• 2022年RT-Thread全球開發者大會報告視頻

2.2 工程的創建和導入

點擊完成(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函數在哪里？

2.5 點一個LED燈吧！

 1#include?
 2
 3void?setup(void)
 4{
 5????//?put?your?setup?code?here,?to?run?once:
 6????pinMode(LED_BUILTIN,?OUTPUT);
 7}
 8
 9void?loop(void)
10{
11????//?put?your?main?code?here,?to?run?repeatedly:
12????digitalWrite(LED_BUILTIN,?!digitalRead(LED_BUILTIN));
13????Serial.println("Hello?Arduino!");
14????delay(100);
15}

可以看到，板載的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工程（以潘多拉板為例）

?

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庫時會直接調用?？蛇x，如果沒有I2C功能，不需要定義該宏?*/
47#define?RTDUINO_DEFAULT_IIC_BUS_NAME????????????"i2c4"
48
49/*?定義SPI設備名稱，在使用SPI庫時會直接調用?？蛇x，如果沒有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

4.3 編寫Arduino引腳布局(pinout)的README說明文檔

5 RTduino精簡模式（快速使用，無需適配特定BSP）

5.1 不使用setup-loop編程模型

1RT-Thread?online?packages??--->
2????system?packages??--->
3?????????[*]?RTduino:?Arduino?Ecological?Compatibility?Layer??--->
4??????????????[*]???Don't?use?setup-loop?structure??--->

5.2 如何不用定義引腳映射表，更方便的使用RTduino？

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