?

1 簡介

1.1 已經(jīng)支持Arduino生態(tài)兼容層的RT-Thread BSP

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

2 如何使用本兼容層

2.1 參考資料

• 2022年RT-Thread全球開發(fā)者大會(huì)報(bào)告視頻

2.2 工程的創(chuàng)建和導(dǎo)入

點(diǎn)擊完成(Finish)，稍等片刻即可完成工程導(dǎo)入。

導(dǎo)入成功之后，雙擊RT-Thread Settings，進(jìn)入到RT-Thread工程配置界面，點(diǎn)擊<<按鈕，進(jìn)入到詳細(xì)配置頁面：

?

點(diǎn)擊Hardware，選擇Support Arduino，只需要點(diǎn)一下即可，其他依賴項(xiàng)會(huì)自動(dòng)處理。然后點(diǎn)擊小錘子按鈕進(jìn)行編譯，RT-Thread Studio會(huì)自動(dòng)保存你當(dāng)前的配置并下載RTduino軟件包以及依賴項(xiàng)軟件包，并將這些軟件包加入到工程中，最后自動(dòng)編譯整個(gè)工程。

總的來講，你只需要選擇Support Arduino，并點(diǎn)一下小錘子按鈕，就坐等編譯成功即可。

至此，RTduino軟件包安裝完成，此BSP工程已經(jīng)具備了兼容Arduino生態(tài)的能力。

2.3 RTduino文件夾目錄結(jié)構(gòu)

RTduino軟件包包含有兩個(gè)主要的文件夾：core和libraries。

• core文件夾主要是提供Arduino內(nèi)置的所有的API函數(shù)，例如analogWrite、analogRead函數(shù)等等，這些函數(shù)可以在Arduino官方找到詳細(xì)的介紹。

• libraries文件夾是Arduino庫所在文件夾。其中：

• buildin文件夾下存放著Arduino內(nèi)置的一些庫，例如Servo舵機(jī)驅(qū)動(dòng)庫，Wire I2C驅(qū)動(dòng)庫等等；

• user文件夾是用戶文件夾，這是對用戶來說很重要的一個(gè)文件夾，里邊默認(rèn)是空的，用戶可以把下載好的Arduino庫拖入到此文件夾中來，在下個(gè)章節(jié)會(huì)細(xì)說這個(gè)操作。

2.4 Arduino經(jīng)典的setup和loop函數(shù)在哪里？

2.5 點(diǎn)一個(gè)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燈已經(jīng)開始閃爍，串口開始輸出了。

注意：

?

由于RT-Thread的main.c文件內(nèi)，也會(huì)默認(rèn)閃爍一個(gè)LED燈，如果板子上只有一個(gè)LED燈的話，兩個(gè)線程會(huì)發(fā)生干涉。但是你會(huì)發(fā)現(xiàn)這個(gè)LED的閃爍速度明顯變快了。因?yàn)閙ain.c那邊的閃爍周期是1000ms，上面這個(gè)例程是200ms。

?

如果你用潘多拉板，main.c閃爍的是紅燈，RTduino兼容層的Arduino程序默認(rèn)閃爍的是綠色的燈，二者不會(huì)發(fā)生干擾。

2.6 具體Arduino引腳分布信息

由于每個(gè)BSP的板子設(shè)計(jì)、以及芯片型號(hào)等，引腳分布是有區(qū)別的，因此需要到指定BSP的applications/arduino文件夾下的README.md文件查看詳細(xì)信息。例如：

STM32L475潘多拉板的Arduino引腳布局的詳細(xì)說明 | STM32F072 Nucleo板的Arduino引腳布局的詳細(xì)說明

3 Arduino庫的導(dǎo)入和使用

3.1 術(shù)語說明

軟件包：英文為 software package，是指RT-Thread社區(qū)所屬維護(hù)的第三方擴(kuò)展，是RT-Thread原生生態(tài)一部分。

庫：英文為library，是指Arduino社區(qū)所屬維護(hù)的第三方擴(kuò)展，是Arduino原生生態(tài)一部分。

庫和軟件包其實(shí)是一個(gè)意思，只不過兩個(gè)社區(qū)叫法不一樣。

3.2 RTduino兼容層對Arduino庫的兼容情況

目前RTduino兼容層可以實(shí)現(xiàn)對Arduino純軟件類（例如算法類、數(shù)據(jù)處理類等）、串口相關(guān)、I2C傳感器相關(guān)的庫做到100%兼容。

支持的詳細(xì)情況和計(jì)劃，請查看：

https://github.com/RTduino/RTduino/discussions/26

3.3 導(dǎo)入一個(gè)Arduino庫到RT-Thread工程（以潘多拉板為例）

?

3.4 RTduino內(nèi)置庫

在RTduino中內(nèi)置了兩類庫，方便用戶直接使用。

一類是在Arduino中原生內(nèi)建(buildin)的庫，存放于 libraries/buildin 文件夾內(nèi)。具體如下表所示：

4 如何給某個(gè)BSP適配RTduino

4.1 創(chuàng)建文件夾和文件

需要在某個(gè)BSP的applications文件夾下創(chuàng)建如下文件、文件夾：

參考示例BSP：STM32F072 Nucleo板applications文件夾 | STM32L475 潘多拉板applications文件夾

4.1.1 arduino_main.cpp文件

該文件是Arduino的編程入口，提供setup和loop函數(shù)。在loop函數(shù)默認(rèn)以200ms為周期，閃爍Arduino內(nèi)建LED燈（LED_BUILTIN）。如果該BSP默認(rèn)支持SPI功能且為UNO引腳布局，由于SPI和LED_BUILTIN可能存在沖突(D13)，可以在loop函數(shù)內(nèi)以 Serial.println("Hello Arduino "); 代替頻閃LED（例如STM32F401 Nucleo板）。

4.1.2 arduino_pinout文件夾

需要在applications文件夾下創(chuàng)建arduino_pinout文件夾，這個(gè)文件夾主要包含 arduino_pinout.c 和 arduino_pinout.h 兩個(gè)關(guān)鍵的文件，這兩個(gè)文件是對接的關(guān)鍵。用戶只需要做好這兩個(gè)文件，即可完成與RTduino的對接。

同時(shí)，這個(gè)文件夾內(nèi)也需要SConscript腳本文件，以及提供Arduino引腳布局的README說明文檔。請參照上面的示例BSP來完成對這兩個(gè)文件的編寫。

4.1.3 arduino_pinout.c 文件的編寫

arduino_pinout.c 內(nèi)需要完成一個(gè)IO編號(hào)和功能的映射表。由于Arduino的習(xí)慣是采用1-13 (D0-D13) 以及 A0-A5的引腳編號(hào)，而正規(guī)的MCU的引腳編號(hào)一般都是PA1之類，因此需要將MCU真正的引腳編號(hào)與Arduino引腳編號(hào)映射起來。

以下段代碼來舉例講解：

 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/*?按照先數(shù)字引腳后模擬引腳的順序從0開始，一定要按序排列?*/
 9/*?可以按照板卡實(shí)際IO情況，靈活調(diào)整功能，不一定非得按照Arduino?UNO的引腳功能布局，但是建議按此布局設(shè)計(jì)?*/
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編號(hào)和功能映射表，每一行用花括號(hào)包裹（實(shí)際是一個(gè)結(jié)構(gòu)體）來建議一個(gè)IO的映射關(guān)系：

1{Arduino引腳編號(hào),?RT-Thread引腳編號(hào)(通過GET_PIN宏獲取),?復(fù)用功能的設(shè)備名(PWM、ADC或DAC),?該復(fù)用功能設(shè)備的通道號(hào)}

其中，Arduino引腳編號(hào)，即是第一個(gè)參數(shù)，是必填的，D0 - Dx 或者是 A0 - Ax。注意一定要按先數(shù)字引腳后模擬引腳照順序來填寫。

RT-Thread引腳編號(hào)，即第二個(gè)參數(shù)，rt_pin_write中引腳編號(hào)填什么，這里就填什么，一般使用 GET_PIN 宏來獲取。注意：D0、D1以及I2C、SPI IO需要將此參數(shù)略過。

后兩個(gè)參數(shù)是復(fù)用功能IO才需要填寫的，普通引腳只需要略過即可。

4.1.4 arduino_pinout.h 文件的編寫

參考示例BSP：STM32L475 潘多拉板applications文件夾

該文件主要負(fù)責(zé)定義各種宏，包括：

D0、A0等引腳的數(shù)字宏，該宏一定要按照先數(shù)字引腳后模擬引腳的順序進(jìn)行排號(hào)。

定義默認(rèn)開啟的一些硬件功能，如下表所示：

 1/*?pins?alias.?Must?keep?in?sequence?*/
 2/*?按照先數(shù)字引腳后模擬引腳的順序從0開始，一定要按序排列?*/
 3/*?可以按照板卡實(shí)際IO情況，靈活調(diào)整功能，不一定非得按照Arduino?UNO的引腳功能布局，但是建議按此布局設(shè)計(jì)?*/
 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內(nèi)置LED的引腳編號(hào)?*/
45
46/*?定義I2C設(shè)備名稱，在使用Wire庫時(shí)會(huì)直接調(diào)用?？蛇x，如果沒有I2C功能，不需要定義該宏?*/
47#define?RTDUINO_DEFAULT_IIC_BUS_NAME????????????"i2c4"
48
49/*?定義SPI設(shè)備名稱，在使用SPI庫時(shí)會(huì)直接調(diào)用?？蛇x，如果沒有SPI功能，不需要定義該宏?*/
50#define?RTDUINO_DEFAULT_SPI_BUS_NAME????????????"spi2"
51
52/*?
53???定義高精度定時(shí)器設(shè)備名稱，該宏主要是提供us時(shí)基信號(hào)使用。
54???所有Cortex-M核MCU均不需要定義此宏，RTduino會(huì)自動(dòng)調(diào)用systick來計(jì)算us級(jí)時(shí)間戳。
55???非Cortex-M核的MCU需要提供一個(gè)硬件定時(shí)器來提供us級(jí)時(shí)間戳。
56?*/
57#define?RTDUINO_DEFAULT_HWTIMER_DEVICE_NAME?????"timer7"
58
59/*?如果有串口2、串口3可以定義串口2、3的設(shè)備名稱，若沒有可直接不定義此宏?*/
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?配置選項(xiàng)
 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 常規(guī)模式（參見第4章）vs 精簡模式（參見第5章）

下表列舉了在兩種不同模式下，RTduino對Arduino API的兼容情況：

注：SPI庫目前還在施工中，暫不開放使用。

6 需要注意的事項(xiàng)

6.1 包含Arduino.h頭文件

調(diào)用到Arduino相關(guān)函數(shù)和宏的源文件，請包含Arduino.h頭文件，否則可能會(huì)報(bào)錯(cuò)：

6.2 Keil AC5

如果使用Keil AC5環(huán)境，需要勾選GNU extension。AC6不需要。

6.3 啟用PWM不能調(diào)用pinMode函數(shù)，否則PWM會(huì)失效，ADC、DAC同理

 1void?setup()?{
 2??//Declaring?LED?pin?as?output
 3??//pinMode(led_pin,?OUTPUT);?//不能設(shè)置為OUTPUT，否則PWM會(huì)失效
 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}

因?yàn)榈讓右呀?jīng)將對應(yīng)的PWM、ADC或DAC的IO設(shè)置為模擬輸入或者復(fù)用推挽，調(diào)用pinMode之后把IO模式改成了純輸入輸出，原有的PWM、ADC或DAC功能將無法使用。該問題無要修正，只需要知道調(diào)用analogRead和analogWrite的時(shí)候不需要設(shè)置pinMode即可。一旦調(diào)用pinMode，該引腳將喪失analogWrite或者analogRead功能，后續(xù)只能當(dāng)做普通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函數(shù)，在終端也會(huì)給出警告：

當(dāng)然，如果用戶已經(jīng)知道這樣做的后果，但是故意需要將PWM、ADC或DAC引腳通過pinMode函數(shù)轉(zhuǎn)為普通IO也是完全可以的。

6.4 Serial.begin

在很多Arduino例程中，都喜歡使用如下語句來初始化串口：

1??Serial.begin(9600);

這句話將串口默認(rèn)初始化成波特率為9600. 但是在RT-Thread中，串口的初始化實(shí)際是有RT-Thread驅(qū)動(dòng)框架負(fù)責(zé)的，并且默認(rèn)波特率為115200. 因此如果調(diào)用Serial.begin(9600) 函數(shù)后，串口的波特率將會(huì)從默認(rèn)的115200調(diào)整為9600。如果你的終端或者串口助手還保持在115200的波特率，那么接收數(shù)據(jù)將出現(xiàn)亂碼。

因此建議：

使用Serial.begin()代替Serial.begin(9600)。Serial.begin()無參數(shù)方法是RTduino的擴(kuò)充方法，其表示跟隨使用RT-Thread串口配置，不重新配置串口。

7 貢獻(xiàn)與維護(hù)

7.1 項(xiàng)目倉庫地址

https://github.com/RTduino/RTduino

https://gitee.com/rtduino/RTduino