第 2.1 节

Arduino常用库函数和速学参考

作者

董佳辉

协作者

毛婧秋

发布于 2023/10/09更新于 2026/08/20

1.Arduino简介

Arduino包含硬件和软件两部分。

硬件是指Arduino公司推出的各种型号单片机，软件则是公司推出的一个嵌入式项目开发平台，该平台使用C++简化而来的Arduino语言。

2.常用内置函数

(1)初始化引脚

/*@brief 用于配置数字引脚的输入输出模式
 *@pin   数字引脚编号
 *@mode  输入或输出模式 */
 //mode可以写OUTPUT(输出模式)、INPUT(输入模式)
pinMode(pin,mode)

/*代码示例*/

//定义引脚
int led_pin = 12;
//设定引脚模式：输出模式
pinMode(led_pin,OUTPUT);

输入数字信号：

与输出不同的是，当我们想要配置INPUT模式输入数字信号的时候，我们需要配置“上下拉电阻”（输入模拟信号不用）。

这样是为了确定初始电平状态，继而提高电路稳定性，避免误操作等。选择“上拉电阻”，GPIO引脚初始默认为高电平，选择“下拉电阻”，GPIO引脚初始默认为低电平。

代码书写：

pinMode(led_pin,INPUT_PULLUP); //设置输入模式和上拉电阻

pinMode(led_pin,INPUT_PULLDOWN); //设置输入模式和下拉电阻

(2)改变电平/数字信号值

/*@brief  用于在数字引脚上写入电平/数字信号值。
 *@pin    数字引脚编号
 *@Value  写入的值。 */
 //Value可以写0、1，或者它们对应的宏定义LOW、HIGH
digitalWrite(pin,Value)



/*@brief  用于读取数字引脚上的电平/数字信号值 */
digitalRead(pin)

/*代码示例*/
//点亮小灯

int led_pin = 12;

void setup(){
  //设定引脚模式：输出模式
  pinMode(led_pin,OUTPUT);

  digitalWrite(led_pin,HIGH);
  }

void loop(){
  }

(3)延时函数

delay(ms)

/*代码示例*/
//延时1s
delay(1000)

(4)串口

/*@brief 用于初始化串口通信
 *@baud  波特率 */
 Serial.begin(baud)



 /*@brief 用于将数据打印到串口监视器中
  *@data  数字、字符串或其他数据类型 */
 Serial.println(data)

(5)模拟信号

/*@brief 用于读取模拟引脚上的模拟值(0~1023)
 *@pin   模拟引脚的编号 */
analogRead(pin);



/*@brief 用于输出模拟值(0~255)
 *@pin   引脚编号
 *@value 输出的值 */
analogWrite(pin,Value);

(6)LEDC控制函数

LEDC控制函数具体如何使用，请见此处：Arduino常用库函数和速学参考

// 设置 LEDC 通道对应的频率和计数位数（占空比分辨率），返回最终频率
// 分辨率是最小占空比
// 比如说我们传入分辨率为8，那么最终频率就是2^8=256
uint32_t    ledcSetup(uint8_t channel, uint32_t freq, uint8_t resolution_bits);

// 指定通道输出一定占空比波形
void        ledcWrite(uint8_t channel, uint32_t duty);

// 类似于 arduino 的 tone ，当外接无源蜂鸣器的时候可以发出某个声音（根据频率不同而不同）
uint32_t    ledcWriteTone(uint8_t channel, uint32_t freq);

//  该方法是上面方法的进一步封装，可以直接输出指定调式和音阶声音的信号
uint32_t    ledcWriteNote(uint8_t channel, note_t note, uint8_t octave);

// 返回指定通道占空比的值
uint32_t    ledcRead(uint8_t channel);

// 返回指定通道当前频率（如果当前占空比为0 则该方法返回0）
uint32_t    ledcReadFreq(uint8_t channel);

// 将 LEDC 通道绑定到指定 IO 口上以实现输出
void        ledcAttachPin(uint8_t pin, uint8_t channel);

// 解除 IO 口的 LEDC 功能
void        ledcDetachPin(uint8_t pin);

3.代码示例

1.呼吸灯

(1)analog函数输出模拟值实现

//实现呼吸灯(analog函数输出模拟值实现)

#define LED_PIN 12

void setup(){
    pinMode(LED_PIN,OUTPUT);
   }



void loop(){
    //实现渐亮的效果
    for(int i=0;i<256;i++){
       analogWrite(LED_PIN,i);
       delay(10);
       }

    //实现渐灭效果
    for(int i=255;i>=0;i--){
       analogWrite(LED_PIN,i);
       delay(10);
       }
  }

(2)输出PWM信号实现

这里使用ESP32做示范，使区分analog函数输出与PWM信号输出两种方式的不同。

在ESP32上，有一个LEDC外设模块，是专门用于输出PWM信号的。LEDC可以生成16路通道(0~15)，分为高低速两组。

Arduino内置有LEDC模块的控制函数。

LEDC产生PWM过程：

使用 ledcSetup() 函数建立 LEDC 通道；

通过 ledcAttachPin() 将 GPIO 口与 LEDC 通道关联；

通过 ledcWrite()、ledcWriteTone()、ledcWriteNote()设置频率、设置蜂鸣器音调等等

通过 ledcDetachPin() 解除 GPIO 口与 LEDC 通道的关联

//实现呼吸灯(PWM信号输出实现)

#define FREQ        2000        //频率
#define CHANNEL     0           //通道号
#define RESOLUTION  8           //分辨率(最小占空比)
#define LED         12          //LED引脚


void setup()
{   /*设置通道*/
    ledcSetup(CHANNEL,FREQ,RESOLUTION);
    /*将通道与对应的引脚连接*/
    ledcAttachPin(LED,CHANNEL);
}



void loop()
{
    //逐渐变亮
    for(int i=0;i<pow(2,RESOLUTION);i++)
    {   /*输出PWM*/
        ledcWrite(CHANNEL,i);  //(其实也是输出模拟信号对应的逻辑值)
        delay(5);
    }

    //逐渐变暗
    for(int i=pow(2,RESOLUTION)-1;i>=0;i--)
    {   /*输出PWM*/
        ledcWrite(CHANNEL,i);
        delay(5);
    }
}

2.串口监视器打印

To be continued

3.舵机

4.第三方库函数

1.如何在Arduino中添加库文件

——通过文件复制的方式直接添加

（1）添加到Arduino IDE

将.h或.c文件或examples文件夹，复制粘贴到Aruduino安装路径下的Libraries文件夹下，重启Arduino IDE即可完成添加。

（2）只添加到项目

这种方式适合一些专一性大的库，开发者只想该库用于这个项目，而不想被其他项目使用，从而导致库冲突或者include使用了错误的库。
这种条件下，可以把库文件复制到.ino文件同级目录下，在include时使用 #include "/src/WiFi.h"包含路径，
而且优先在项目下搜索库文件进行引用。

2."ESP32Servo.h"

By Kevin Harrington

是能让我们更加方便地操控舵机的第三方库函数。可以在Arduino IDE中直接搜索到。

5.使用Vscode中的PIO平台开发

内容摘自https://docs.geeksman.com/esp32/Arduino/13.esp32-arduino-platformio.html

1.PIO的主要特点和优势

PlatformIO 的主要特点和优势包括：

1.跨平台支持：

可以在 Windows、Mac 和 Linux 等操作系统上运行，并支持多种开发板和处理器架构。(Arduino\ESP8266\ESP32\Raspberry Pi等和 Arduino框架\ESP-IDF\STM32Cube等)

2.统一的开发环境：

提供了集成开发环境（IDE）插件，如可以·在VS Code、Clion 等上运行，使开发者可以在一个统一的界面中进行代码编辑、编译、调试和上传。

3.库管理和依赖管理：

内置了强大的库管理器，可以方便地搜索、安装和更新开源库，同时支持管理项目的依赖关系。

4.丰富的功能：

支持代码自动完成、语法检查、固件升级、调试器、单元测试等功能，提供了全面的开发工具和功能。

5.强大的扩展性：

可以通过插件系统扩展功能，支持自定义构建脚本、添加新的开发板和框架等。

6.社区支持：

PlatformIO 拥有活跃的社区，开发者可以在社区中获取技术支持、交流经验和分享项目。

2.操作步骤

a.安装 VSCode

前往 VSCode 官网，建议下载 System Installer 版本的安装包，该版本安装在非用户目录，例如 C 盘根目录。

$RTcFbhkNNoIyzVxMszWcvbdYn2g\.png$

下载完毕后进行安装，安装时建议按如下进行勾选。

$Yy0wbogl6oiXbExKl9FcLeDRnef\.png$

安装完毕后打开软件，安装中文插件。

$RN40bx6KxoC4Pyxa6ZJcX5URnqf\.png$

b.安装 PlatformIO 插件

在 VSCode 中根据下图步骤安装 PlatformIO IDE 插件。

$T72AbxF0rozVFpxiab4cHGYznbg\.png$

插件安装完毕后，VSCode 右下角会出现 PlatformIO 的下载进程，等待其下载完毕后即可。由于 PlatformIO 的服务器在国外，下载速度特别慢，耐心等待即可。

下载完毕后，PlatformIO 只下载了公共的数据包，没有下载特定板子的数据包，因此如需使用他人的工程，需依照该工程所用芯片新建一个工程，在第一次新建工程时，PlatformIO 会下载好该工程所需的文件。

假设需运行的工程所使用的芯片为 ESP32，使用的框架为 arduino，那么在第一次运行该工程前需先按照如下步骤新建一次工程，只有第一次需要，后续就可以直接运行了。

点击 VSCode 左下角的桌面图标。

$SIaCbYLNro56XPxXK6gc5NqYnnb\.png$

点击 New Project，即可创建新项目。

$BEGbbxAozoZSc1x17u6cgsW4ntf\.png$

设置项目的名称，选择开发板型号，开发框架以及项目路径。

$DN49bPSgmoziQ1xY0JGcR3g5nbi\.png$

点击 Finish 后，需要较长的一段时间，此阶段 PlatformIO 会下载该工程所需的文件，新建完成后，即可关闭此工程（直接关闭 VSCode 软件）。接着打开我们所需运行的工程即可（在工程路径下，鼠标右键后，选择通过 Code 打开）。

左下角的图标含义如图。

$QVByb09lwoDm9HxftxZcXHSfnPb\.png$

c.如何使用 PlatformIO

当使用 PlatformIO 创建 ESP32 Arduino 项目时，项目目录的结构通常如下所示：

$LwW4bMsiZoH0odxQ9nLcvVxbnwf\.png$

.pio：该文件夹是 PlatformIO 的工作目录，包含编译生成的二进制文件、日志文件等。
.vscode：如果你在 VSCode 中使用 PlatformIO 插件，该文件夹包含了与项目相关的配置文件，如任务配置、调试配置等。
include：存放头文件。
lib：该文件夹用于存放项目依赖的库文件。你可以通过 PlatformIO 的库管理器安装所需的库，并它们会自动下载到该文件夹。
src：该文件夹是存放源代码的主目录。你的主要代码文件（通常是.cpp和.h文件）应放在这个目录下。
test：用于存放项目的测试代码和测试数据。这个目录通常用于编写单元测试或集成测试的代码，用于验证项目的功能和逻辑是否正确。
.gitignore：如果你使用版本控制系统如Git进行项目管理，你可以在这个文件中指定需要忽略的文件和文件夹。
platformio.ini：这是 PlatformIO 的配置文件，用于指定项目的配置选项，如目标硬件平台、编译选项、上传设置等。

在 PlatformIO 创建的项目中，lib 和 include 目录都是用于存放代码文件的特定目录。它们的区别如下：

lib 目录：用于存放项目的依赖库文件。在这个目录下，可以放置项目需要引用的第三方库或自己编写的库。这些库文件通常是以源代码的形式提供，可以是单个文件或多个文件的集合。在构建过程中，这些库文件会被编译并链接到项目中。
include 目录：用于存放项目的头文件。头文件包含了函数、类、变量的声明，供其他源文件在编译时引用。在这个目录下，可以放置项目自定义的头文件，或者是一些需要被其他文件引用的第三方库的头文件。在编译过程中，编译器会在该目录下查找所需的头文件。

总结一下，lib 目录主要用于存放项目的依赖库文件，而 include 目录用于存放项目的头文件。这样的组织结构可以方便地管理项目所需的库文件和头文件，并在构建过程中正确引用和链接它们。

d.书写代码

主要的代码，我们可以写在 main.cpp 中，src 目录下的 main.cpp 文件基本等同于 Arduino IDE 中创建的 .ino 文件。

只不过，在 main.cpp 文件的第一行需要 #include <Arduino.h>，其余的代码部分内容一致，我们可以直接把上节课读取串口输入的代码复制过来，但是不要忘了 #include <Arduino.h>。

#include <Arduino.h>
#include <LiquidCrystal_I2C.h>


LiquidCrystal_I2C lcd(0x27, 16, 2); // set the LCD address to 0x27 for a 16 chars and 2 line display

void setup()
{
  lcd.init(); // initialize the lcd
  lcd.backlight();
  Serial.begin(9600);
}

void loop()
{
  // when characters arrive over the serial port...
  if (Serial.available())
  {
    // wait a bit for the entire message to arrive
    delay(100);
    // clear the screen
    lcd.clear();
    // read all the available characters
    while (Serial.available() > 0)
    {
      // display each character to the LCD
      lcd.write(Serial.read());
    }
  }
}

想要运行该程序，可以点击左下角的或者右上角的上传选项，或者使用快捷键 ctrl + alt + u

这时候，我们还没有导入 LiquidCrystal_I2C 库，所以，代码会运行失败，想要在 PlatformIO 中导入第三方库比 Arduino IDE 方便的多，我们可以打开 PlatformIO Home 页面，点击 libraries，输入我们想要导入的库名称，添加到项目中即可。

$RqmVbXutNouFlDxZXsbcrOmgnhc\.png$

PlatformIO 还会非常贴心的给你一个使用示例，

$OjD5bhfhdoFcA6xD7jEcOtjWnCh\.png$

所以，如果你想要使用 ESP32 在 Arduino 框架下实现一个稍微复杂一点的项目的话，Platform 是你最佳的选择。