Arduino编程参考手册中文版.doc

Arduino编程参考手册
首页

54

程序结构
setup()
loop()
控制结构
if
if...else
for
switch case
while
do...while
break
continue
return
goto
相关语法
; 分号
{ 大括号
// 单行注释
/**/ 多行注释
#define 宏定义
#include 文件包含
算术运算符
= 赋值
+ (加)
- (减)
* (乘)
/ (除)
% (取模)
比较运算符
== 等于
!= (不等于)
< (小于)
> (大于)
<= (小于等于)
>= (大于等于)
布尔运算符
&& (逻辑与)
|| (逻辑或)
! (逻辑非)
指针运算符
* 指针运算符
& 地址运算符
位运算
& (位与)
| (位或)
^ (位异或)
~ (位非)
<< (左移)
>> (右移)
复合运算符
++ (自加)
-- (自减)
+= (复合加)
-= (复合减)
*= (复合乘)
/= (复合除)
&= (复合与)
|= (复合或)
范围
HIGH | LOW
INPUT | OUTPUT
true | false
整型常量
浮点数常量
数据类型
void
boolean
char
unsigned char
byte
int
unsigned int
word
long
unsigned long
float
double
string
String(c++)
array
数据类型转换
char()
byte()
int()
word()
long()
float()
变量作用域
变量作用域
static (静态变量)
volatile (易变变量)
const (不可改变变量)
辅助工具
sizeof() (sizeof运算符)
ASCII码表
数字I/O
pinMode()
digitalWrite()
digitalRead()
模拟I/O
analogReference()
analogRead()
analogWrite()
指高级I/O
shiftOut()
pulseIn()
时间
millis()
delay(ms)
delayMicroseconds(us)
数学库
min()
max()
abs()
constrain()
map()
pow()
sqrt()
三角函数
sin(rad)
cos(rad)
tan(rad)
随机数
randomSeed()
random()
random()
位操作
lowByte()
highByte()
bitRead()
bitWrite()
bitSet()
bitClear()
bit()
设置中断函数
attachInterrupt()
detachInterrupt()
interrupts()
noInterrupts()
串口通讯
begin()
available()
read()
flush
print()
println()
write()
peak()
serialEvent()

程序结构
(本节直译自Arduino官网最新Reference)
在Arduino中, 标准的程序入口main函数在内部被定义, 用户只需要关心以下两个函数:
setup()
当Arduino板起动时setup()函数会被调用。用它来初始化变量，引脚模式，开始使用某个库，等等。该函数在Arduino板的每次上电和复位时只运行一次。
loop()
在创建setup函数，该函数初始化和设置初始值，loop()函数所做事的正如其名，连续循环，允许你的程序改变状态和响应事件。可以用它来实时控制arduino板。
示例：
int buttonPin = 3;
void setup()
{
Serial.begin(9600); //初始化串口
pinMode(buttonPin, INPUT); //设置3号引脚为输入模式
}
void loop()
{
if (digitalRead(buttonPin) == HIGH)
serialWrite('H');
else
serialWrite('L');
delay(1000);
}

控制语句
if
if，用于与比较运算符结合使用，测试是否已达到某些条件，例如一个输入数据在某个范围之外。使用格式如下：
if (value > 50)
{
// 这里加入你的代码
}
该程序测试value是否大于50。如果是，程序将执行特定的动作。换句话说，如果圆括号中的语句为真，大括号中的语句就会执行。如果不是，程序将跳过这段代码。大括号可以被省略，如果这么做，下一行（以分号结尾）将成为唯一的条件语句。

if (x > 120) digitalWrite(LEDpin, HIGH);
if (x > 120)
digitalWrite(LEDpin, HIGH);
if (x > 120){ digitalWrite(LEDpin, HIGH); }
if (x > 120){
digitalWrite(LEDpin1, HIGH);
digitalWrite(LEDpin2, HIGH);
} // 都是正确的
圆括号中要被计算的语句需要一个或多个操作符。

if...else
与基本的if语句相比，由于允许多个测试组合在一起，if/else可以使用更多的控制流。例如，可以测试一个模拟量输入，如果输入值小于500，则采取一个动作，而如果输入值大于或等于500，则采取另一个动作。代码看起来像是这样：
if (pinFiveInput < 500)
{
// 动作A
}
else
{
// 动作B
}
else中可以进行另一个if测试，这样多个相互独立的测试就可以同时进行。每一个测试一个接一个地执行直到遇到一个测试为真为止。当发现一个测试条件为真时，与其关联的代码块就会执行，然后程序将跳到完整的if/else结构的下一行。如果没有一个测试被验证为真。缺省的else语句块，如果存在的话，将被设为默认行为，并执行。
注意：一个else if语句块可能有或者没有终止else语句块，同理。每个else if分支允许有无限多个。
if (pinFiveInput < 500)
{
// 执行动作A
}
else if (pinFiveInput >= 1000)
{
// 执行动作B
}
else
{
// 执行动作C
}
另外一种表达互斥分支测试的方式，是使用switch case语句。

for
for语句
描述
for语句用于重复执行被花括号包围的语句块。一个增量计数器通常被用来递增和终止循环。for语句对于任何需要重复的操作是非常有用的。常常用于与数组联合使用以收集数据/引脚。for循环的头部有三个部分：
for (初始化部分; 条件判断部分; 数据递增部分) {
//语句块
。。。
}
初始化部分被第一个执行，且只执行一次。每次通过这个循环，条件判断部分将被测试;如果为真，语句块和数据递增部分就会被执行,然后条件判断部分就会被再次测试，当条件测试为假时，结束循环。
示例：
//使用一个PWM引脚使LED灯闪烁
int PWMpin = 10; // LED在10号引脚串联一个470欧姆的电阻
void setup()
{
//这里无需设置
}
void loop()
{
for (int i=0; i <= 255; i++){
analogWrite(PWMpin, i);
delay(10);
}
}
编码提示：
C中的for循环比在其它计算机语言中发现的for循环要灵活的多，包括BASIC。三个头元素中的任何一个或全部可能被省略，尽管分号是必须的。而且初始化部分、条件判断部分和数据递增部分可以是任何合法的使用任意变量的C语句。且可以使用任何数据类型包括floats。这些不常用的类型用于语句段也许可以为一些罕见的编程问题提供解决方案。
例如，在递增部分中使用一个乘法将形成对数级增长：
for(int x = 2; x < 100; x = x * 1.5){
println(x);
}
输出: 2,3,4,6,9,13,19,28,42,63,94
另一个例子，在一个for循环中使一个LED灯渐渐地变亮和变暗：
void loop()
{
int x = 1;
for (int i = 0; i > -1; i = i + x){
analogWrite(PWMpin, i);
if (i == 255) x = -1; // 在峰值切换方向
delay(10);
}
}

switch case
switch case 语句
就像if语句，switch...case通过允许程序员根据不同的条件指定不同的应被执行的代码来控制程序流。特别地，一个switch语句对一个变量的值与case语句中指定的值进行比较。当一个case语句被发现其值等于该变量的值。就会运行这个case语句下的代码。
break关键字将中止并跳出switch语句段，常常用于每个case语句的最后面。如果没有break语句，switch语句将继续执行下面的表达式（“持续下降”）直到遇到break，或者是到达switch语句的末尾。
示例：
switch (var) {
case 1:
//当var等于1执行这里
break;
case 2:
//当var等于2执行这里
break;
default:
// 如果没有匹配项，将执行此缺省段
// default段是可选的
}
语法
switch (var) {
case label:
// statements
break;
case label:
// statements
break;
default:
// statements
}
参数
var: 与不同的case中的值进行比较的变量
label: 相应的case的值

while
while循环
描述：
while循环将会连续地无限地循环，直到圆括号（）中的表达式变为假。被测试的变量必须被改变，否则while循环将永远不会中止。这可以是你的代码，比如一个递增的变量，或者是一个外部条件，比如测试一个传感器。
语法：
while(expression){
// statement(s)
}
参数：
expression - 一个（布尔型）C语句，被求值为真或假
示例：
var = 0;
while(var < 200){
// 做两百次重复的事情
var++;
}

do...while
do循环
do循环与while循环使用相同方式工作，不同的是条件是在循环的末尾被测试的，所以do循环总是至少会运行一次。
do
{
// 语句块
} while (测试条件);
示例：
do
{
delay(50); // 等待传感器稳定
x = readSensors(); // 检查传感器的值
} while (x < 100);

break
break用于中止do，for，或while循环，绕过正常的循环条件。它也用于中止switch语句。
示例：
for (x = 0; x < 255; x ++)
{
digitalWrite(PWMpin, x);
sens = analogRead(sensorPin);
if (sens > threshold){ // bail out on sensor detect
x = 0;
break;
}
delay(50);
}

continue
continue语句跳过一个循环的当前迭代的余下部分。（do，for，或while）。通过检查循环测试条件它将继续进行随后的迭代。
示例：
for (x = 0; x < 255; x ++)
{
if (x > 40 && x < 120){ // create jump in values
continue;
}
digitalWrite(PWMpin, x);
delay(50);
}

return
终止一个函数，并向被调用函数并返回一个值，如果你想的话。
语法：
return;
return value; // both forms are valid
参数：
value: 任何类型的变量或常量
示例：
//一个函数，用于对一个传感器输入与一个阈值进行比较

int checkSensor(){
if (analogRead(0) > 400) {
return 1;
else{
return 0;
}
}
return 关键字对测试一段代码很方便，不需“注释掉”大段的可能是错误的代码。
void loop(){
//在此测试代码是个好想法
return;
// 这里是功能不正常的代码
// 这里的代码永远也不会执行
}

goto
在程序中转移程序流到一个标记点
语法：
label:
goto label; // sends program flow to the label
提示：
在C程序中不建议使用goto，而且一些C编程书的作者主张永远不要使用goto语句，但是明智地使用它可以 简化某些代码。许多程序员不赞成使用goto的原因是，无节制地使用goto语句很容易产生执行流混乱的很难被调试程序。 尽管如是说，仍然有很多使用goto语句而大大简化编码的实例。其中之一就是从一个很深的循环嵌套中跳出去，或者是if逻辑块，在某人些条件下。
示例：
for(byte r = 0; r < 255; r++){
for(byte g = 255; g > -1; g--){
for(byte b = 0; b < 255; b++){
if (analogRead(0) > 250){ goto bailout;}
// 其它语句。。。
}
}
}
bailout:

相关语法
分号
用于一个语句的结束
示例
int a = 13;
提示
忘记在一行的末尾加一个分号将产生一个编译器错误。该错误信息可能是明显的，且会提及丢失分号，但也许不会。如果出现一个不可理喻的或看起来不合逻辑的错误，其中一个首先要做的事就是检查分号丢失。编译器会在前一行的附近发出抱怨。

大括号
大括号（又称括弧或花括号）是C语言的主要组成部分。它们用在几个不同的结构中，大致如下，这可能会令初学者感到困惑。
一个左大括号必须有一个右大括号跟在后面。这是一个常被称为平衡括号的条件。Arduino IDE（集成开发环境）包含一个方便的特性以检验平衡大括号。只需选择一个大括号，甚至直接在一个大括号后面点击插入点，然后它的逻辑上的同伴就会高亮显示。
目前此功能有些许错误，因为IDE经常在文本中（错误地）发现一个已经被注释掉的大括号。
初级程序员，和从BASIC转到C的程序员常常发现使用大括号令人困惑或畏缩。毕竟，用同样的大括号在子例程（函数）中替换RETURN语句，在条件语句中替换ENDIF语句和在FOR循环中替换NEXT语句。
由于大括号的使用是如此的多样，当插入一个需要大括号的结构时，直接在打出开括号之后打出闭括号是个不错的编程实践。然后在大括号之间插入一些回车符，接着开始插入语句。你的大括号，还有你的态度，将永远不会变得不平衡。
不平衡的大括号常常导致古怪的，难以理解的编译器错误，有时在大型程序中很难查出。因为它们的多样的使用，大括号对于程序的语法也是极其重要的，对一个大括号移动一行或两行常常显著地影响程序的意义。
大括号的主要用法
//函数
void myfunction(datatype argument){
statements(s)
}

//循环
while (boolean expression)
{
statement(s)
}
do
{
statement(s)
} while (boolean expression);
for (initialisation; termination condition; incrementing expr)
{
statement(s)
}

//条件语句

if (boolean expression)
{
statement(s)
}
else if (boolean expression)
{
statement(s)
}
else
{
statement(s)
}

注释
注释是程序中的一些行，用于让自己或他人了解程序的工作方式。他们会被编译器忽略，而不会输出到控制器，所以它们不会占用Atmega芯片上的任何空间。
注释唯一的目的是帮助你理解（或记忆）你的程序是怎样工作的，或者是告知其他人你的程序是怎样工作的。标记一行为注释只有两种方式：
示例
x = 5; //这是一个单行注释。此斜线后的任何内容都是注释
//直到该行的结尾

/* 这是多行注释 - 用它来注释掉整个代码块
if (gwb == 0){ //在多行注释中使用单行注释是没有问题的
x = 3; /* 但是其中不可以使用另一个多行注释 - 这是不合法的 */
}

//别忘了加上“关闭”注释符 - 它们必须是平衡的
*/
提示
当实验代码时，“注释掉”你的程序的一部分来移除可能是错误的行是一种方便的方法。这不是把这些行从程序中移除，而是把它们放到注释中，所以编译器就会忽略它们。这在定位问题时，或者当程序无法编译通过且编译错误信息很古怪或没有帮助时特别有用。

define
#define 宏定义
宏定义是一个有用的C组件，它允许程序员在程序编译前给常量取一个名字。在arduino中定义的常量不会在芯片中占用任何程序空间。编译器在编译时会将这些常量引用替换为定义的值。
这虽然可能有些有害的副作用，举例来说，一个已被定义的常量名被包含在一些其它的常量或变量名中。那样的话该文本将被替换成被定义的数字（或文本）。
通常，用const关键字定义常量是更受欢迎的且用来代替#define会很有用。
Arduino宏定义与C宏定义有同样的语法
语法
#define constantName value
注意‘#’是必须的
示例：
#define ledPin 3
// 编译器在编译时会将任何提及ledPin的地方替换成数值3。
提示
#define语句的后面分号。如果你加了一个，编译器将会在进一步的页面引发奇怪的错误。
#define ledPin 3; // this is an error
类似地，包含一个等号通常也会在进一步的页面引发奇怪的编译错误。
#define ledPin = 3 // this is also an error

include
#include 包含
#include用于在你的sketch中包含外部的库。这使程序员可以访问一个巨大的标准C库（预定义函数集合）的集合。
AVR C库（AVR是Atmel芯片的一个基准，Arduino正是基于它）的主参考手册页在这里。
注意#include和#define相似，没有分号终止符，且如果你加了，编译器会产生奇怪的错误信息。
示例
该示例包含一个用于输出数据到程序空间闪存的库，而不是内存。这会为动态内存需求节省存储空间且使需要创建巨大的查找表变得更实际。
#include <avr/pgmspace.h>
prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456,
0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500};

算术运算符
赋值
=赋值运算符（单个等号）
把等号右边的值存储到等号左边的变量中。
在C语言中单个等号被称为赋值运算符。它与在代数课中的意义不同，后者象征等式或相等。赋值运算符告诉微控制器求值等号右边的变量或表达式，然后把结果存入等号左边的变量中。
示例
int sensVal; //声明一个名为sensVal的整型变量
senVal = analogRead(0); //存储（数字的）0号模拟引脚的输入电压值到sensVal
编程技巧
赋值运算符（=号）左边的变量需要能够保存存储在其中的值。如果它不足以大到容纳一个值，那个存储在该变量中的值将是错误的。
不要混淆赋值运算符[ = ]（单个等号）和比较运算符[ == ]（双等号），后者求值两个表达式是否相等。

加，减，乘，除
描述
这些运算符（分别）返回两人运算对象的和，差，积，商。这些操作受运算对象的数据类型的影响。所以，例如，9 / 4结果是2，如果9和2是整型数。这也意味着运算会溢出，如果结果超出其在相应的数据类型下所能表示的数。（例如，给整型数值32767加1结果是-32768）。如果运算对象是不同的类型，会用那个较大的类型进行计算。
如果其中一个数字（运算符）是float类型或double类型，将采用浮点数进行计算。
示例
y = y + 3;
x = x - 7;
i = j * 6;
r = r / 5;
语法
result = value1 + value2;
result = value1 - value2;
result = value1 * value2;
result = value1 / value2;
参数：
value1:任何变量或常量
value2:任何变量或常量
编程技巧：
要知道整型常量默认为int型，因此一些常量计算可能会溢出（例如：60 * 1000将产生负的结果）
选择一个大小足够大的变量以容纳你的最大的计算结果。
要知道你的变量在哪一点将会“翻转”且要知道在另一个方向上会发生什么，例如：（0 - 1）或（0 - 32768）。
对于数学需要分数，就使用浮点变量，但是要注意它们的缺点：占用空间大，计算速度慢。
使用强制类型转换符例如：（int)myFloat以在运行中转换一个变量到另一个类型。

取模
%（取模）
描述
计算一个数除以另一个数的余数。这对于保持一个变量在一个特定的范围很有用（例如：数组的大小）。
语法
result = dividend % divisor
参数
dividend: 被除数
divisor: 除数
结果：余数
示例
x = 7 % 5; // x now contains 2
x = 9 % 5; // x now contains 4
x = 5 % 5; // x now contains 0
x = 4 % 5; // x now contains 4
示例代码
/* update one value in an array each time through a loop */
int values[10];
int i = 0;
void setup() {}
void loop()
{
values[i] = analogRead(0);
i = (i + 1) % 10; // modulo operator rolls over variable
}

提示：
取模运算符不能用于浮点型数。

比较运算符
if(条件) and ==, !=, <, > (比较运算符)
if，用于和比较运算符联合使用，测试某一条件是否到达，例如一个输入超出某一数值。if条件测试的格式：
if (someVariable > 50)
{
// do something here
}

该程序测试someVariable是否大于50。如果是， 程序执行特定的动作。换句话说，如果圆括号中的语句为真，花括号中的语句就会运行。否则，程序跳过该代码。
if语句后的花括号可能被省略。如果这么做了，下一行（由分号定义的行）就会变成唯一的条件语句。
if (x > 120) digitalWrite(LEDpin, HIGH);
if (x > 120)
digitalWrite(LEDpin, HIGH);
if (x > 120){ digitalWrite(LEDpin, HIGH); }
if (x > 120){
digitalWrite(LEDpin1, HIGH);
digitalWrite(LEDpin2, HIGH);
} // all are correct
圆括号中被求值的语句需要使用一个或多个运算符：
比较运算符：
x == y (x is equal to y)
x != y (x is not equal to y)
x < y (x is less than y)
x > y (x is greater than y)
x <= y (x is less than or equal to y)
x >= y (x is greater than or equal to y)

警告：
小心偶然地使用单个等号（例如if(x = 10)）。单个等号是赋值运算符，这里设置x为10（将值10存入变量x）。改用双等号（例如if (x == 10)）,这个是比较运算符，用于测试x是否等于10。后者只在x等于10时返回真，但是前者将总是为真。
这是因为C如下求值语句if(x=10)：10分配给x（切记单个等号是赋值运算符），因此x现在为10。然后'if'条件求值10，其总是为真，由于任何非零数值都为真值。由此，if (x = 10)将总是求值为真，这不是使用if语句所期望的结果。另外，变量x将被设置为10，这也不是期望的操作。
if也可以是使用[if...else]的分支控制结构的一部分。

布尔运算符
它们可用于if语句中的条件
&& （逻辑与）
只有在两个操作数都为真时才返回真，例如：
if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // read two switches
// ...
}
只在两个输入都为高时返回真

|| （逻辑或）
任意一个为真时返回真，例如：
if (x > 0 || y > 0) {
// ...
}
x或y任意一个大于0时返回真
! （非）
当操作数为假时返回真，例如：
if (!x) {
// ...
}
若x为假返回真（即如果x等于0）

警告
确保你没有把布尔与运算符，&&（两个与符号）错认为按位与运算符&（单个与符号）。它们是完全不同的概念。
同样，不要混淆布尔或运算符||（双竖杠）与按位或运算符|（单竖杠）。
按位取反~（波浪号）看起来与布尔非!有很大不同（感叹号或程序员口中的“棒”），但是你仍然必须确保在什么地方用哪一个。
例如
if (a >= 10 && a <= 20){} // true if a is between 10 and 20

指针运算符
&（引用）和 *（间接引用）
指针对于Ｃ初学者来说是更复杂的对象之一。并且可能写大量的Arduino程序甚至都不会遇到指针。
无论如何，巧妙地控制特定的数据结构，使用指针可以简化代码，而且在自己工具箱中拥有熟练控制指针的知识是很方便的。

位运算
位与
按位与（&）
按位操作符在变量的位级执行运算。它们帮助解决各种常见的编程问题。以下大部分资料来自一个有关位数学的优秀教程，或许可以在这里找到。[1]
描述和语法
以下是所有这些运算符的描述和语法。更详细的资料或许可以在参考指南中找到。
按位与（&）
在C++中按位与运算符是单个与符号，
用于其它两个整型表达式之间使用。按位与运算独立地在周围的表达式的每一位上执行操作。根据这一规则：如果两个输入位都是1，结果输出1，否则输出0。表达这一思想的另一个方法是：
0 0 1 1 operand1
0 1 0 1 operand2
----------
0 0 0 1 (operand1 & operand2) - returned result

在Arduino中，int型是16位的。所以在两个整型表达式之间使用&将会导致16个与运算同时发生。代码片断就像这样：
int a = 92; // in binary: 0000000001011100
int b = 101; // in binary: 0000000001100101
int c = a & b; // result: 0000000001000100, or 68 in decimal.

在a和b的16位的每一位将使用按位与处理。且所有16位结果存入C中，以二进制存入的结果值01000100，即十进制的68。
按位与的其中一个最常用的用途是从一个整型数中选择特定的位，常被称为掩码屏蔽。看如下示例：

位或
按位或（|）
在C++中按位或运算符是垂直的条杆符号，|。就像&运算符，|独立地计算它周围的两个整型表达式的每一位。（当然）它所做的是不同的（操作)。两个输入位其中一个或都是1按位或将得到1，否则为0。换句话说：
0 0 1 1 operand1
0 1 0 1 operand2
----------
0 1 1 1 (operand1 | operand2) - returned result

这是一个使用一小断C++代码描述的按位或（运算）的例子：
int a = 92; // in binary: 0000000001011100
int b = 101; // in binary: 0000000001100101
int c = a | b; // result: 0000000001111101, or 125 in decimal.

按位与和按位或的一个共同的工作是在端口上进行程序员称之为读-改-写的操作。在微控制器中，每个端口是一个8位数字，每一位表示一个引脚的状态。写一个端口可以同时控制所有的引脚。
PORTD是内建的参照数字口0，1，2，3，4，5，6，7的输出状态的常量。如果一个比特位是1，那么该引脚置高。（引脚总是需要用pinMode()指令设置为输出模式）。所以如果我们写入PORTD = B00110001；我们就会让引脚2，3和7输出高。一个小小的问题是，我们同时也改变了某些引脚的0，1状态。这用于Arduino与串口通讯，所以我们可能会干扰串口通讯。
我们的程序规则是：
仅仅获取和清除我们想控制的与相应引脚对应的位（使用按位与）。
合并要修改的PORTD值与所控制的引脚的新值（使用按位或）。
int i; // counter variable
int j;
void setup(){
DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx)
// same as pinMode(pin, OUTPUT) for pins 2 to 7
Serial.begin(9600);
}
void loop(){
for (i=0; i<64; i++){
PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx)
j = (i << 2); // shift variable up to pins 2 - 7 - to avoid pins 0 and 1
PORTD = PORTD | j; // combine the port information with the new information for LED pins
Serial.println(PORTD, BIN); // debug to show masking
delay(100);
}
}

位异或
按位异或（^）
在C++中有一个有点不寻常的操作，它被称为按位异或，或者XOR（在英语中，通常读作“eks-or”）。按位异或运算符使用符号^。该运算符与按位或运算符“|”非常相似 ,唯一的不同是当输入位都为1时它返回0。
0 0 1 1 operand1
0 1 0 1 operand2
----------
0 1 1 0 (operand1 ^ operand2) - returned result

看待XOR的另一个视角是，当输入不同时结果为1，当输入相同时结果为0。
这里是一个简单的示例代码：

int x = 12; // bi