Docs » Learning the ArduPilot Codebase » Library Example Sketches

原文：http://ardupilot.org/dev/docs/learning-ardupilot-the-example-sketches.html

Library Example Sketches

为自己探索代码的第一步是为库使用示例草图。按照 arduino 的传统, 我们对大多数库都有示例草图。”草图” 只是一个主程序, 以 cpp 文件的形式编写。
了解 ArduPilot 中使用的库 API 和约定对于理解代码是非常重要的。因此, 使用库示例草图是入门的好方法。作为一个开始, 您应该阅读、生成和运行以下库的示例草图:

libraries/AP_GPS/examples/GPS_AUTO_test
libraries/AP_InertialSensor/examples/INS_generic
libraries/AP_Compass/examples/AP_Compass_test
libraries/AP_Baro/examples/BARO_generic
libraries/AP_AHRS/examples/AHRS_Test

例如, 以下内容将在 Pixhawk 上生成并安装 AP_GPS 示例草绘:

cd $ARDUPILOT_HOME # the top-level of an AruPilot repository
./waf configure --board=px4-v2
./waf build --target examples/INS_generic --upload

waf 可以列出它可以生成的示例:

cd $ARDUPILOT_HOME
./waf list | grep 'examples'

上传了示例后, 您可以通过附加到控制台来查看输出。控制台的种类取决于主板的类型。在 PX4 板上 (ie。PX4v1 和 Pixhawk) 它是 USB 连接器。因此, 只需连接到 USB 设备与您最喜爱的串行程序 (波特不要紧)。
例如, 如果您安装了 mavproxy, 则可以这样做以连接到 Linux 上的 Pixhawk:

mavproxy.py --setup --master /dev/serial/by-id/usb-3D_Robotics_PX4_FMU_v2.x_0-if00

使用–setup 选项将 mavproxy 转换为原始串行模式, 而不是经过处理的 MAVLink 模式。这就是你需要的例子草图。

Understanding the example sketch code

当您阅读示例草图代码 (如 GPS_AUTO_test 代码) 时, 您会注意到一些最初可能看起来很奇怪的事情:

将 “hal” 变量声明为引用
代码是相当粗糙, 并没有好评
setup() and loop()函数

The hal reference

每个使用 AP_HAL 功能的文件都需要声明 HAL 引用。可以访问 AP_HAL: HAL 对象, 它提供对所有硬件特定功能的访问, 包括将消息打印到控制台、休眠和与 I2C 和 SPI 总线通信。
实际的 hal 变量被埋葬在主板特定的 AP_HAL_XXX 库中。每个文件中的引用只是提供了一个方便的方法来获取 hal。
最常用的 hal 函数有:

hal.console->printf() 打印字符串
AP_HAL::millis()和AP_HAL::micros() 获得启动后的时间
hal.scheduler->delay()和hal.scheduler->delay_microseconds() 休眠一段时间
hal.gpio->pinMode(), hal.gpio->read() 和hal.gpio->write() 用于访问 GPIO 引脚
hal.i2c用于访问 I2C
hal.spi用于访问 SPI

现在, 请在libraries/AP_HAL 目录中查看 HAL 上可用的功能的完整列表。

The setup() and loop() functions

您会注意到, 每个草图都有一个setup() 函数和loop() 函数。当主板启动时, 将调用setup() 函数。实际的调用来自于每个主板的 hal 内部, 因此 main() 函数被放在 hal 内部, 然后在主板特定的启动完成后调用setup()程序。
setup() 函数只调用一次,用于初始化库, 并可能打印一个 “hello” 横幅来显示它正在启动。
在setup() 完成后, loop() 函数被连续调用 (通过 AP_HAL 中的主代码)。sketch 的主要工作通常在loop() 函数中。
请注意, 这个setup()/loop() 复杂的板子程序的冰山一角。它会使 ArduPilot 像是单线程, 但实际上有更多的在下面, 并在板上(如 PX4 和 Linux 基板) 实际上会有大量的实时线程启动了。请参见下面关于理解 ArduPilot 线程的部分。

The AP_HAL_MAIN() macro

在每个sketch 的底部, 你会注意到这样一行额外的代码:

扫描二维码关注公众号，回复： 3564964 查看本文章

AP_HAL_MAIN();

这是一个 hal 宏, 它生成必要的代码来声明 c++ 主函数, 以及 hal 的任何板级初始化代码。你很少需要担心它是如何工作的, 但是如果你很好奇, 你可以在每个 HAL 的 AP_HAL_XXX 目录中寻找 #define。它通常在 AP_HAL_XXX_Main。

Rough Example code

你会注意到, 示例是相当粗糙, 并严重缺乏注释。这是您为代码做出贡献的机会!当您阅读示例草图并探索它们的工作方式时, 可以向代码中添加一些注释, 以解释 api, 然后提交请求, 以便其他人可以从您的学习中获益。