Arduino平台软硬件原理及使用——开源库的使用

洪博hopes2024-06-29 15:34

文章目录：

一、库文件的下载及导入

二、库文件源代码说明

三、库文件应用举例

一、库文件的下载及导入

有关arduino开源库的导入有两种方案：

1.第一种方案需要借助arduino.cc网站来进行查询下载，然后在Arduino软件中进行导入。

2.第二种方案则只需要使用较新版本的Arduino软件（2.2版本之后），在软件中可以直接搜索并导入开源库。

1.在Arduino.cc进行导入库

首先在网页地址框直接输入arduino.cc便可进入网站：

然后点击上方【DOCUMENTATION】选项：

在此页面点击左侧【Libraries】选项，便可进入官方收录的库文件页面：

选择要用的库文件的类目，这里以【display】为例：

然后点击具体的库文件，以【LiquidCrystal】为例：

进入库文件下载目录后，直接点击要用的版本号即可直接下载。

下载完成后如果不是压缩包，最好压缩成zip文件：

最后打开Arduino软件，选择【项目】-【导入库】-【添加.ZIP库】然后选择对应的zip文件即可导入成功。

2.使用Arduino软件导入库

上述方案较为复杂，所以建议使用较新版本的Arduino软件直接导入库：

在此版本的软件中直接点选左侧的"书籍"样式的图标（其表示为库文件），然后直接在搜索框查找要使用的库文件名，选择对应库文件及版本点击安装即可。

这种方案则最为简洁，当然有些时候要使用的库在软件中查询不到，此时就需要采用第一种方案进行导入。

2、库文件源代码说明

如上图所示，一般库文件中会有如上几个文件（会存在些许不同）。

1.示例程序的使用

example文件即为【示例】，这里面会有开源文件贡献者编写的几个示例程序，用于帮助学习者理解库的使用：

当然只要将库文件导入过Arduino中，也可以在Arduino软件中打开相应的示例程序：

2.【.h文件】及【.cpp】文件说明

在【src】文件夹中存在以下两个文件：

【.h】后缀我们称之为头文件 ，【.cpp】后缀我们称之为源文件

头文件 通常包含类声明 、函数原型 、宏定义 和全局变量声明等。它们的目的是提供一种方式来共享代码，并确保在多个源文件中使用一致的声明：

cpp 复制代码 
/*
  HCSR04 - Library for arduino, for HC-SR04 ultrasonic distance sensor.
  Created by Dirk Sarodnick, 2020.
*/

#ifndef HCSR04_H
#define HCSR04_H

#include "Arduino.h"

#define HCSR04_INVALID_RESULT  -1;
#define HCSR04_NO_TRIGGER      -2;
#define HCSR04_NO_ECHO         -3;

class HCSR04Sensor {
	public:
		HCSR04Sensor();
		~HCSR04Sensor();

		typedef enum eUltraSonicUnlock {
			unlockSkip = 0,
			unlockMaybe = 1,
			unlockForced = 2
		} eUltraSonicUnlock_t;
		
		void begin(uint8_t triggerPin, uint8_t echoPin) { begin(triggerPin, new uint8_t[1]{ echoPin }, 1); }
		void begin(uint8_t triggerPin, uint8_t* echoPins, uint8_t echoCount) { begin(triggerPin, echoPins, echoCount, 100000, eUltraSonicUnlock_t::unlockSkip); }
		void begin(uint8_t triggerPin, uint8_t echoPin, uint32_t timeout, eUltraSonicUnlock_t unlock) { begin(triggerPin, new uint8_t[1]{ echoPin }, 1, timeout, unlock); }
		void begin(uint8_t triggerPin, uint8_t* echoPins, uint8_t echoCount, uint32_t timeout, eUltraSonicUnlock_t unlock) { begin(triggerPin, echoPins, echoCount, timeout, 10, 10, unlock); }
		void begin(uint8_t triggerPin, uint8_t* echoPins, uint8_t echoCount, uint32_t timeout, uint16_t triggerTime, uint16_t triggerWait, eUltraSonicUnlock_t unlock);
		void end();
		
		long* measureMicroseconds() { measureMicroseconds(lastMicroseconds); return lastMicroseconds; }
		void measureMicroseconds(long* results);

		double* measureDistanceMm() { measureDistanceMm(defaultTemperature, lastDistances); return lastDistances; }
		void measureDistanceMm(double* results) { measureDistanceMm(defaultTemperature, results == NULL ? lastDistances : results); }
		double* measureDistanceMm(float temperature) { measureDistanceMm(temperature, lastDistances); return lastDistances; }
		void measureDistanceMm(float temperature, double* results);

		double* measureDistanceCm() { measureDistanceCm(defaultTemperature, lastDistances); return lastDistances; }
		void measureDistanceCm(double* results) { measureDistanceCm(defaultTemperature, results == NULL ? lastDistances : results); }
		double* measureDistanceCm(float temperature) { measureDistanceCm(temperature, lastDistances); return lastDistances; }
		void measureDistanceCm(float temperature, double* results);

		double* measureDistanceIn() { measureDistanceIn(defaultTemperature, lastDistances); return lastDistances; }
		void measureDistanceIn(double* results) { measureDistanceIn(defaultTemperature, results == NULL ? lastDistances : results); }
		double* measureDistanceIn(float temperature) { measureDistanceIn(temperature, lastDistances); return lastDistances; }
		void measureDistanceIn(float temperature, double* results);
		
		static void triggerInterrupt0(void);
		static void triggerInterrupt1(void);
		static void triggerInterrupt2(void);
		static void triggerInterrupt3(void);
		static void triggerInterrupt4(void);
		static void triggerInterrupt5(void);
		static void triggerInterrupt6(void);
		static void triggerInterrupt7(void);
		static void triggerInterrupt8(void);
		static void triggerInterrupt9(void);
		
		static void echoInterrupt0(void);
		static void echoInterrupt1(void);
		static void echoInterrupt2(void);
		static void echoInterrupt3(void);
		static void echoInterrupt4(void);
		static void echoInterrupt5(void);
		static void echoInterrupt6(void);
		static void echoInterrupt7(void);
		static void echoInterrupt8(void);
		static void echoInterrupt9(void);
	
	private:
		float defaultTemperature = 19.307;
		long* lastMicroseconds;
		double* lastDistances;

		uint32_t timeout;
		uint16_t triggerTime = 10; // HC-SR04 needs at least 10�s trigger. Others may need longer trigger pulses.
		uint16_t triggerWait = 10; // HC-SR04 sends its signal about 200�s. We only wait a small amount to reduce interference, but to not miss anything on slower clock speeds.
		volatile uint8_t triggerPin;
		volatile unsigned long* volatile triggerTimes;
		
		uint8_t echoCount;
		volatile int16_t* volatile echoStages;
		volatile int16_t* volatile echoInts;
		volatile int16_t* volatile echoPorts;
		volatile unsigned long* volatile echoTimes;
		
		void triggerInterrupt(uint8_t);
		void echoInterrupt(uint8_t);
		void unlockSensors(eUltraSonicUnlock_t, uint8_t*);
};

extern HCSR04Sensor HCSR04;

#endif // HCSR04_H

源文件包含了实现代码，即函数和方法的定义。它们通常包含与头文件对应的实现：

cpp 复制代码 
/*
  HCSR04 - Library for arduino, for HC-SR04 ultrasonic distance sensor.
  Created by Dirk Sarodnick, 2020.
*/

#include "Arduino.h"
#include "HCSR04.h"

HCSR04Sensor::HCSR04Sensor() {}
HCSR04Sensor::~HCSR04Sensor() { this->end(); }

void HCSR04Sensor::begin(uint8_t triggerPin, uint8_t* echoPins, uint8_t echoCount, uint32_t timeout, uint16_t triggerTime, uint16_t triggerWait, eUltraSonicUnlock_t unlock) {
	if (this->echoCount != echoCount) this->end();
	
	this->triggerPin = triggerPin;
	pinMode(triggerPin, OUTPUT);

	this->timeout = timeout;
	this->triggerTime = triggerTime;
	this->triggerWait = triggerWait;
	this->echoCount = echoCount;
	
	if (this->lastMicroseconds == NULL) this->lastMicroseconds = new long[echoCount];
	if (this->lastDistances == NULL) this->lastDistances = new double[echoCount];
	
	if (this->triggerTimes == NULL) this->triggerTimes = new unsigned long[echoCount];
	if (this->echoTimes == NULL) this->echoTimes = new unsigned long[echoCount];

	if (this->echoStages == NULL) this->echoStages = new int16_t[echoCount];
	if (this->echoInts == NULL) this->echoInts = new int16_t[echoCount];
	if (this->echoPorts == NULL) this->echoPorts = new int16_t[echoCount];

	for (uint8_t i = 0; i < this->echoCount; i++) {
		this->triggerTimes[i] = 0;
		this->echoTimes[i] = 0;

		int16_t interrupt = digitalPinToInterrupt(echoPins[i]);
		if (interrupt == NOT_AN_INTERRUPT) {
			this->echoStages[i] = -1;
			this->echoInts[i] = -1;
			this->echoPorts[i] = echoPins[i];
		} else {
			this->echoStages[i] = 0;
			this->echoInts[i] = interrupt;
			this->echoPorts[i] = -1;
		}

		pinMode(echoPins[i], INPUT);
	}
	
	// Unlock sensors that are possibly in a locked state, if this feature is enabled.
	this->unlockSensors(unlock, echoPins);
}

void HCSR04Sensor::end() {
	if (this->lastMicroseconds != NULL) delete []this->lastMicroseconds;
	if (this->lastDistances != NULL) delete []this->lastDistances;
	if (this->triggerTimes != NULL) delete []this->triggerTimes;
	if (this->echoTimes != NULL) delete []this->echoTimes;
	
	if (this->echoPorts != NULL) delete []this->echoPorts;
	if (this->echoInts != NULL) delete []this->echoInts;
	if (this->echoStages != NULL) delete []this->echoStages;
	
	this->lastMicroseconds = NULL;
	this->lastDistances = NULL;
	this->triggerTimes = NULL;
	this->echoTimes = NULL;
	this->echoPorts = NULL;
	this->echoInts = NULL;
	this->echoStages = NULL;
}

void HCSR04Sensor::measureMicroseconds(long* results) {
	if (results == NULL) results = this->lastMicroseconds;

	bool finished = true;
	bool waiting = true;
	unsigned long startMicros = micros();
	unsigned long currentMicros = 0;
	unsigned long elapsedMicros = 0;

	// Make sure that trigger pin is LOW.
	digitalWrite(triggerPin, LOW);
	delayMicroseconds(4);
	
	// Hold trigger HIGH for 10 microseconds (default), which signals the sensor to measure distance.
	digitalWrite(triggerPin, HIGH);
	delayMicroseconds(this->triggerTime);

	// Set trigger LOW again and wait to give the sensor time for sending the signal without interference
	digitalWrite(triggerPin, LOW);
	delayMicroseconds(this->triggerWait);
	
	// Attach interrupts to echo pins for the starting point
	for (uint8_t i = 0; i < this->echoCount; i++) {
		if (this->echoInts[i] >= 0 && this->echoStages[i] == 0) {
			this->echoStages[i] = 1;
			switch (i) {
				case 0: attachInterrupt(this->echoInts[i], &triggerInterrupt0, RISING); break;
				case 1: attachInterrupt(this->echoInts[i], &triggerInterrupt1, RISING); break;
				case 2: attachInterrupt(this->echoInts[i], &triggerInterrupt2, RISING); break;
				case 3: attachInterrupt(this->echoInts[i], &triggerInterrupt3, RISING); break;
				case 4: attachInterrupt(this->echoInts[i], &triggerInterrupt4, RISING); break;
				case 5: attachInterrupt(this->echoInts[i], &triggerInterrupt5, RISING); break;
				case 6: attachInterrupt(this->echoInts[i], &triggerInterrupt6, RISING); break;
				case 7: attachInterrupt(this->echoInts[i], &triggerInterrupt7, RISING); break;
				case 8: attachInterrupt(this->echoInts[i], &triggerInterrupt8, RISING); break;
				case 9: attachInterrupt(this->echoInts[i], &triggerInterrupt9, RISING); break;
			}
		}
	}
	
	// Wait until all echos are returned or timed out.
	while(true) {
		delayMicroseconds(1);
		
		finished = true;
		waiting = true;
		currentMicros = micros();
		elapsedMicros = currentMicros - startMicros;

		for (uint8_t i = 0; i < this->echoCount; i++) {
			waiting &= elapsedMicros < this->timeout || (this->triggerTimes[i] > 0 && this->echoTimes[i] == 0 && (currentMicros - this->triggerTimes[i]) < this->timeout);

			if (this->echoPorts[i] >= 0 && this->triggerTimes[i] == 0) {
				if (digitalRead(this->echoPorts[i]) == HIGH) this->triggerTimes[i] = micros();
			}

			if (this->triggerTimes[i] > 0 || !waiting) {
				if (this->echoInts[i] >= 0 && (this->echoStages[i] == 1 || !waiting)) {
					if (this->echoStages[i] == 1) this->echoStages[i] = 2;
					detachInterrupt(this->echoInts[i]);
				}
			} else finished &= false;

			if (this->echoInts[i] >= 0 && this->triggerTimes[i] > 0 && this->echoStages[i] == 2 && waiting) {
				this->echoStages[i] = 3;
				switch (i) {
					case 0: attachInterrupt(this->echoInts[i], &echoInterrupt0, FALLING); break;
					case 1: attachInterrupt(this->echoInts[i], &echoInterrupt1, FALLING); break;
					case 2: attachInterrupt(this->echoInts[i], &echoInterrupt2, FALLING); break;
					case 3: attachInterrupt(this->echoInts[i], &echoInterrupt3, FALLING); break;
					case 4: attachInterrupt(this->echoInts[i], &echoInterrupt4, FALLING); break;
					case 5: attachInterrupt(this->echoInts[i], &echoInterrupt5, FALLING); break;
					case 6: attachInterrupt(this->echoInts[i], &echoInterrupt6, FALLING); break;
					case 7: attachInterrupt(this->echoInts[i], &echoInterrupt7, FALLING); break;
					case 8: attachInterrupt(this->echoInts[i], &echoInterrupt8, FALLING); break;
					case 9: attachInterrupt(this->echoInts[i], &echoInterrupt9, FALLING); break;
				}
			}

			if (this->echoPorts[i] >= 0 && this->triggerTimes[i] > 0 && this->echoTimes[i] == 0) {
				if (digitalRead(this->echoPorts[i]) == LOW) this->echoTimes[i] = micros();
			}
			
			if ((this->triggerTimes[i] > 0 && this->echoTimes[i] > 0) || !waiting) {
				if (this->echoInts[i] >= 0 && (this->echoStages[i] == 3 || !waiting)) {
					if (this->echoStages[i] == 3) this->echoStages[i] = 4;
					detachInterrupt(this->echoInts[i]);
				}
			} else finished &= false;
		}
		
		if (!waiting || finished) break;
	}
	
	// Determine the durations of each sensor.
	for (uint8_t i = 0; i < this->echoCount; i++) {
		if (this->echoInts[i] >= 0) this->echoStages[i] = 0;
		if (this->triggerTimes[i] > 0 && this->echoTimes[i] > 0) {
			long resultTime = this->echoTimes[i] - this->triggerTimes[i];
			results[i] = resultTime > 0 ? resultTime : HCSR04_INVALID_RESULT;
		} else if (this->triggerTimes[i] > 0) {
			results[i] = HCSR04_NO_ECHO;
		} else {
			results[i] = HCSR04_NO_TRIGGER;
		}

		this->triggerTimes[i] = 0;
		this->echoTimes[i] = 0;
	}
}

void HCSR04Sensor::measureDistanceMm(float temperature, double* results) {
	if (results == NULL) results = this->lastDistances;

	double speedOfSoundInMmPerMs = (331.3 + 0.606 * temperature) / 1000; // Cair ≈ (331.3 + 0.606 ⋅ ϑ) m/s
	long* times = measureMicroseconds();
	
	// Calculate the distance in mm for each result.
	for (uint8_t i = 0; i < this->echoCount; i++) {
		double distanceMm = times[i] / 2.0 * speedOfSoundInMmPerMs;
		if (distanceMm < 10 || distanceMm > 4000) {
			results[i] = HCSR04_INVALID_RESULT;
		} else {
			results[i] = distanceMm;
		}
	}
}

void HCSR04Sensor::measureDistanceCm(float temperature, double* results) {
	if (results == NULL) results = this->lastDistances;

	double speedOfSoundInCmPerMs = (331.3 + 0.606 * temperature) / 1000 / 10; // Cair ≈ (331.3 + 0.606 ⋅ ϑ) m/s
	long* times = measureMicroseconds();
	
	// Calculate the distance in cm for each result.
	for (uint8_t i = 0; i < this->echoCount; i++) {
		double distanceCm = times[i] / 2.0 * speedOfSoundInCmPerMs;
		if (distanceCm < 1 || distanceCm > 400) {
			results[i] = HCSR04_INVALID_RESULT;
		} else {
			results[i] = distanceCm;
		}
	}
}

void HCSR04Sensor::measureDistanceIn(float temperature, double* results) {
	if (results == NULL) results = this->lastDistances;

	double speedOfSoundInCmPerMs = (331.3 + 0.606 * temperature) * 39.37007874 / 1000 / 1000; // Cair ≈ (331.3 + 0.606 ⋅ ϑ) m/s
	long* times = measureMicroseconds();

	// Calculate the distance in cm for each result.
	for (uint8_t i = 0; i < this->echoCount; i++) {
		double distanceIn = times[i] / 2.0 * speedOfSoundInCmPerMs;
		if (distanceIn < 1 || distanceIn > 157.4804) {
			results[i] = HCSR04_INVALID_RESULT;
		}
		else {
			results[i] = distanceIn;
		}
	}
}

void HCSR04Sensor::unlockSensors(eUltraSonicUnlock_t unlock, uint8_t* echoPins) {
	if (unlock == eUltraSonicUnlock_t::unlockSkip) return;
	bool hasLocked = false;

	// Check if any sensor is in a locked state and unlock it if necessary.
	for (uint8_t i = 0; echoPins[i] != 0; i++) {
		if (unlock == eUltraSonicUnlock_t::unlockMaybe && digitalRead(echoPins[i]) == LOW) continue;
		pinMode(echoPins[i], OUTPUT);
		digitalWrite(echoPins[i], LOW);
		hasLocked = true;
	}
	
	if (hasLocked) delay(100);

	// Revert the pinMode after potential unlocking.
	for (uint8_t i = 0; echoPins[i] != 0; i++) {
		pinMode(echoPins[i], INPUT);
	}
	
	if (hasLocked) delay(100);
}

void HCSR04Sensor::triggerInterrupt(uint8_t index) {
	if (this->triggerTimes[index] == 0) this->triggerTimes[index] = micros();
}

void HCSR04Sensor::echoInterrupt(uint8_t index) {
	if (this->triggerTimes[index] > 0 && this->echoTimes[index] == 0) this->echoTimes[index] = micros();
}

void HCSR04Sensor::triggerInterrupt0() { HCSR04.triggerInterrupt(0); }
void HCSR04Sensor::triggerInterrupt1() { HCSR04.triggerInterrupt(1); }
void HCSR04Sensor::triggerInterrupt2() { HCSR04.triggerInterrupt(2); }
void HCSR04Sensor::triggerInterrupt3() { HCSR04.triggerInterrupt(3); }
void HCSR04Sensor::triggerInterrupt4() { HCSR04.triggerInterrupt(4); }
void HCSR04Sensor::triggerInterrupt5() { HCSR04.triggerInterrupt(5); }
void HCSR04Sensor::triggerInterrupt6() { HCSR04.triggerInterrupt(6); }
void HCSR04Sensor::triggerInterrupt7() { HCSR04.triggerInterrupt(7); }
void HCSR04Sensor::triggerInterrupt8() { HCSR04.triggerInterrupt(8); }
void HCSR04Sensor::triggerInterrupt9() { HCSR04.triggerInterrupt(9); }

void HCSR04Sensor::echoInterrupt0() { HCSR04.echoInterrupt(0); }
void HCSR04Sensor::echoInterrupt1() { HCSR04.echoInterrupt(1); }
void HCSR04Sensor::echoInterrupt2() { HCSR04.echoInterrupt(2); }
void HCSR04Sensor::echoInterrupt3() { HCSR04.echoInterrupt(3); }
void HCSR04Sensor::echoInterrupt4() { HCSR04.echoInterrupt(4); }
void HCSR04Sensor::echoInterrupt5() { HCSR04.echoInterrupt(5); }
void HCSR04Sensor::echoInterrupt6() { HCSR04.echoInterrupt(6); }
void HCSR04Sensor::echoInterrupt7() { HCSR04.echoInterrupt(7); }
void HCSR04Sensor::echoInterrupt8() { HCSR04.echoInterrupt(8); }
void HCSR04Sensor::echoInterrupt9() { HCSR04.echoInterrupt(9); }

HCSR04Sensor HCSR04;

三、库文件应用举例

下文以超声波传感器 的库HCSR04 来进行举例（仅说明代码用法，不作实物接线）

在导入HCSR04库之后，可打开库文件中的实例：

c 复制代码 
#include <HCSR04.h>

HCSR04 hc(5, 6); //initialisation class HCSR04 (trig pin , echo pin)
                 //初始化超声波传感器，即表明接口号。

void setup()
{
    Serial.begin(9600);  //串口初始化
}

void loop()
{
    Serial.println(hc.dist()); // return curent distance in serial
                               // hc.dist()会返回超声波传感器检测的距离数据
    delay(60);                 // 延时60毫秒
}

具体实例可参考文章------Arduino项目式编程教学第四章------超声波测距

如果想要了解此库文件下的方法，则可以在Arduino软件中，按住【Alt / cmd】键，然后使用鼠标点击对应的库文件名，即可打开其头文件 ：

在头文件中，可以阅读文件贡献者做出的注释来了解此库文件中可供使用的方法。

相关推荐
阑梦清川5 分钟前
C++多态~~的两个特殊情况
开发语言·c++
Star Patrick23 分钟前
算法训练（leetcode）第二十二天 | 491. 非递减子序列、全排列、47. 全排列 II
c++·算法·leetcode
一眼万里*e1 小时前
c++ const关键字
c++
2401_828014951 小时前
无线领夹麦克风哪个牌子好？揭秘领夹麦克风哪个品牌音质最好
java·c++·python·php
zeruns8021 小时前
开源205W桌面充电器，140W+65W升降压PD3.1快充模块(2C+1A口)，IP6557+IP6538
科技·嵌入式硬件·开源·智能硬件·充电器·快充·英集芯
阿维同学1 小时前
今天不看明天付费------中国AGI（人工智能）的发展趋势
汇编·人工智能·ai·云原生·开源·agi
liuyunluoxiao2 小时前
模拟实现string【C++】
c++
2301_796982142 小时前
django开源电子文档管理系统_Django简介、ORM、核心模块
python·django·开源
vegetablesssss2 小时前
(七)glDrawArry绘制
c++·图形渲染·opengl
且听吟风°2 小时前
32 lambda表达式
开发语言·c++
热门推荐
01Coze扣子平台完整体验和实践（附国内和国际版对比）02组基轨迹建模 GBTM的介绍与实现（Stata 或 R）03【经验分享】Ubuntu22.04安装微信(linux官方版)04yolov8实战第五天——yolov8+ffmpg实时视频流检测并进行实时推流——（推流，保姆教学）05【立创EDA-PCB设计基础】6.布线铺铜实战及细节详解06浏览器插件——ModHeader 的分享和学习072025张宇考研数学，百度网盘视频课+36讲PDF讲义+真题08通达信神奇九转指标原理及选股公式，无未来函数，数字不消失09npm使用国内淘宝镜像（最新地址）1051-2 万字长文，深度解读端到端自动驾驶的挑战和前沿