第一个应用程序教程(Hello Sky)

官网英文原文地址：http://dev.px4.io/tutorial-hello-sky.html

本教程详细解释了如何创建一个新的板载应用程序，以及如何运行它。

前提条件

  • Pixhawk 或者 Snapdragon兼容的自驾仪
  • 安装PX4 工具链
  • Github 账号 (免费注册)

第一步：文件设置

为了更方便的管理你的个人代码和上传更新到原始代码仓库，强烈建议使用fork命令通过GIT版本控制系统得到一个新的PX4固件。

  • 在github上注册一个账户；
  • 登陆px4的固件托管网址，然后点击右上方的FORK按钮；
  • 点击到你fork后的站点，复制你的私人PX4代码仓库的URL地址。
  • 克隆你的代码仓库到你的硬盘中，在命令行中输入：
    git clone https://github.com/<youraccountname>/Firmware.git
    对于windows用户，请参考github帮助中的介绍。例如在github创建的官方应用程序中使用fork/clone命令克隆仓库到本地硬盘中。
  • 更新px4代码包含的git子模块：运行命令行工具（在windows上运行PX4终端）
  1. cd Firmware
  2. git submodule init
  3. git submodule update --recursive

打开你本地硬盘克隆的软件仓库的Firmware/src/examples/文件夹，查看里面的文件。

第二步：最小的应用

在Firmware/src/examples/px4_simple_app下，创建一个新的C语言文件px4_simple_app.c。(该文件已存在，你可以直接删掉它，来完全自主编辑学习。)

从默认头文件和main主函数开始，编辑这个文件。

注意这个文件中的代码风格，所有PX4的软件版本都将遵守这个风格。

  1. /****************************************************************************
  2.  *
  3.  *   Copyright (c) 2012-2015 PX4 Development Team. All rights reserved.
  4.  *
  5.  * Redistribution and use in source and binary forms, with or without
  6.  * modification, are permitted provided that the following conditions
  7.  * are met:
  8.  *
  9.  * 1. Redistributions of source code must retain the above copyright
  10.  *    notice, this list of conditions and the following disclaimer.
  11.  * 2. Redistributions in binary form must reproduce the above copyright
  12.  *    notice, this list of conditions and the following disclaimer in
  13.  *    the documentation and/or other materials provided with the
  14.  *    distribution.
  15.  * 3. Neither the name PX4 nor the names of its contributors may be
  16.  *    used to endorse or promote products derived from this software
  17.  *    without specific prior written permission.
  18.  *
  19.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22.  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  23.  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24.  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25.  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  26.  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27.  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28.  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  29.  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30.  * POSSIBILITY OF SUCH DAMAGE.
  31.  *
  32.  ****************************************************************************/
  34. /**
  35.  * @file px4_simple_app.c
  36.  * Minimal application example for PX4 autopilot
  37.  *
  38.  * @author Example User <mail@example.com>
  39.  */
  41. #include <px4_config.h>
  42. #include <px4_tasks.h>
  43. #include <px4_posix.h>
  44. #include <unistd.h>
  45. #include <stdio.h>
  46. #include <poll.h>
  47. #include <string.h>
  49. #include <uORB/uORB.h>
  50. #include <uORB/topics/sensor_combined.h>
  51. #include <uORB/topics/vehicle_attitude.h>
  53. __EXPORT int px4_simple_app_main(int argc, char *argv[]);
  55. int px4_simple_app_main(int argc, char *argv[])
  56. {
  57.     PX4_INFO("Hello Sky!");
  58.     return OK;
  59. }

第三步：在NuttShell中注册应用程序，然后编译

现在应用程序已经完成并且能够运行，但还没有注册成NuttShell命令行工具。如果想要将应用程序编译到固件中，将它加到下面的模块编译列表中：

在你的应用程序的下面的文件中添加一行：

examples/px4_simple_app

编译它：

  • Pixhawk v1/2: make px4fmu-v2_default
  • Pixhawk v3: make px4fmu-v4_default

第四步：上传并且测试应用程序

使能uploader然后重置开发板：

  • Pixhawk v1/2: make px4fmu-v2_default upload
  • Pixhawk v3: make px4fmu-v4_default upload

在你重置开发板之前，会在后面打印如下的编译信息：

Loaded firmware for X,X, waiting for the bootloader...

一旦开发板重置成功并且应用程序上传成功，打印信息：

  1. Erase  : [====================] 100.0%
  2. Program: [====================] 100.0%
  3. Verify : [====================] 100.0%
  4. Rebooting.
  6. [100%] Built target upload

连接到终端

现在通过串口或USB连接到系统命令行终端（新手玩家第一次进行USB或者串口连接系统命令行终端，请点开上面的链接，按照要求进行系统控制台安装，安装完毕后，输入回车键打开终端（linux）或者命令行工具（windows））。点击回车键能打开shell命令行工具：

  1.   nsh>

输入“help”然后回车

  1.   nsh> help
  2.     help usage:  help [-v] [<cmd>]
  4.     [           df          kill        mkfifo      ps          sleep       
  5.     ?           echo        losetup     mkrd        pwd         test        
  6.     cat         exec        ls          mh          rm          umount      
  7.     cd          exit        mb          mount       rmdir       unset       
  8.     cp          free        mkdir       mv          set         usleep      
  9.     dd          help        mkfatfs     mw          sh          xd          
  11.   Builtin Apps:
  12.     reboot
  13.     perf
  14.     top
  15.     ..
  16.     px4_simple_app
  17.     ..
  18.     sercon
  19.     serdis

现在‘px4_simple_app’已经是一个可用的命令了。输入px4_simple_app命令然后回车：

  1.   nsh> px4_simple_app
  2.   Hello Sky!

现在应用程序已经成功注册到系统中，能够被扩展并且运行一些有用的任务。

第五步：读取传感器数据

为了实现一些功能，应用程序需要读取传感器的输入然后反应到对电机或者舵机的输出中。注意在这里，PX平台真正的硬件抽象的概念在这里体现—-当硬件平台或者传感器更新，完全不需要更新你的应用程序或者更新传感器驱动程序。

在PX4中，应用程序间发送的单独的消息叫做“topics”，在本教程中，我们关心的话题是“多传感器间的uORB消息机制”（sensor_combined topic）。这些消息机制使得整个系统能够同步传感器数据。

订阅一个话题是非常迅速并且简洁的：

  1. #include <uORB/topics/sensor_combined.h>
  2. ..
  3. int sensor_sub_fd = orb_subscribe(ORB_ID(sensor_combined));

“sensor_sub_fd” 是一个文件描述符，可以用来非常高效地实现对新数据的阻塞式等待。当前线程进入休眠状态，当新数据可用时，它自动地被调度程序唤醒 ，因此在数据等待时， 不会占用任何CPU资源。为了实现这个功能，我们使用poll()函数[http://pubs.opengroup.org/onlinepubs/007908799/xsh/poll.html]，即POSIX系统调用。

在消息读取中加入“poll()”机制：

  1. #include <poll.h>
  2. #include <uORB/topics/sensor_combined.h>
  3. ..
  4. int sensor_sub_fd = orb_subscribe(ORB_ID(sensor_combined));
  6. /* one could wait for multiple topics with this technique, just using one here */
  7. px4_pollfd_struct_t fds[] = {
  8.     { .fd = sensor_sub_fd,   .events = POLLIN },
  9. };
  11. while (true) {
  12.     /* wait for sensor update of 1 file descriptor for 1000 ms (1 second) */
  13.     int poll_ret = px4_poll(fds, 1, 1000);
  14. ..
  15.     if (fds[0].revents & POLLIN) {
  16.         /* obtained data for the first file descriptor */
  17.         struct sensor_combined_s raw;
  18.         /* copy sensors raw data into local buffer */
  19.         orb_copy(ORB_ID(sensor_combined), sensor_sub_fd, &raw);
  20.         printf("[px4_simple_app] Accelerometer:\t%8.4f\t%8.4f\t%8.4f\n",
  21.                     (double)raw.accelerometer_m_s2[0],
  22.                     (double)raw.accelerometer_m_s2[1],
  23.                     (double)raw.accelerometer_m_s2[2]);
  24.     }
  25. }

编译应用程序：

  1.   make

第六步：测试uORB消息读取机制

最后一步，开始你的应用程序，并且切换到后台应用。

  1.   px4_simple_app &

你的应用程序会向串口输出当前传感器的值：

  1.   [px4_simple_app] Accelerometer:   0.0483          0.0821          0.0332
  2.   [px4_simple_app] Accelerometer:   0.0486          0.0820          0.0336
  3.   [px4_simple_app] Accelerometer:   0.0487          0.0819          0.0327
  4.   [px4_simple_app] Accelerometer:   0.0482          0.0818          0.0323
  5.   [px4_simple_app] Accelerometer:   0.0482          0.0827          0.0331
  6.   [px4_simple_app] Accelerometer:   0.0489          0.0804          0.0328

它会在输出5次数据后退出。下一篇教程中会介绍如何编写一个能通过命令行控制的后台应用。

第七部：打印数据

为了能获取到计算后的数据，下一步就是“打印”这些结果。如果我们知道某一个消息是使用mavlink协议转发给地面控制站的，我们就可以通过这个消息去查看结果。例如我们通过这个方法来获得高度信息的消息。

接口非常简单:初始化消息的结构体，然后公告这条消息：

  1. #include <uORB/topics/vehicle_attitude.h>
  2. ..
  3. /* advertise attitude topic */
  4. struct vehicle_attitude_s att;
  5. memset(&att, 0, sizeof(att));
  6. orb_advert_t att_pub_fd = orb_advertise(ORB_ID(vehicle_attitude), &att);

在主循环中，当消息准备好时，打印这条消息。

  1. orb_publish(ORB_ID(vehicle_attitude), att_pub_fd, &att);

修改后的完整的示例代码如下：

  1. #include <px4_config.h>
  2. #include <px4_tasks.h>
  3. #include <px4_posix.h>
  4. #include <unistd.h>
  5. #include <stdio.h>
  6. #include <poll.h>
  7. #include <string.h>
  9. #include <uORB/uORB.h>
  10. #include <uORB/topics/sensor_combined.h>
  11. #include <uORB/topics/vehicle_attitude.h>
  13. __EXPORT int px4_simple_app_main(int argc, char *argv[]);
  15. int px4_simple_app_main(int argc, char *argv[])
  16. {
  17.     PX4_INFO("Hello Sky!");
  19.     /* subscribe to sensor_combined topic */
  20.     int sensor_sub_fd = orb_subscribe(ORB_ID(sensor_combined));
  21.     orb_set_interval(sensor_sub_fd, 1000);
  23.     /* advertise attitude topic */
  24.     struct vehicle_attitude_s att;
  25.     memset(&att, 0, sizeof(att));
  26.     orb_advert_t att_pub = orb_advertise(ORB_ID(vehicle_attitude), &att);
  28.     /* one could wait for multiple topics with this technique, just using one here */
  29.     px4_pollfd_struct_t fds[] = {
  30.         { .fd = sensor_sub_fd,   .events = POLLIN },
  31.         /* there could be more file descriptors here, in the form like:
  32.          * { .fd = other_sub_fd,   .events = POLLIN },
  33.          */
  34.     };
  36.     int error_counter = 0;
  38.     for (int i = 0; i < 5; i++) {
  39.         /* wait for sensor update of 1 file descriptor for 1000 ms (1 second) */
  40.         int poll_ret = px4_poll(fds, 1, 1000);
  42.         /* handle the poll result */
  43.         if (poll_ret == 0) {
  44.             /* this means none of our providers is giving us data */
  45.             PX4_ERR("[px4_simple_app] Got no data within a second");
  47.         } else if (poll_ret < 0) {
  48.             /* this is seriously bad - should be an emergency */
  49.             if (error_counter < 10 || error_counter % 50 == 0) {
  50.                 /* use a counter to prevent flooding (and slowing us down) */
  51.                 PX4_ERR("[px4_simple_app] ERROR return value from poll(): %d"
  52.                        , poll_ret);
  53.             }
  55.             error_counter++;
  57.         } else {
  59.             if (fds[0].revents & POLLIN) {
  60.                 /* obtained data for the first file descriptor */
  61.                 struct sensor_combined_s raw;
  62.                 /* copy sensors raw data into local buffer */
  63.                 orb_copy(ORB_ID(sensor_combined), sensor_sub_fd, &raw);
  64.                 PX4_WARN("[px4_simple_app] Accelerometer:\t%8.4f\t%8.4f\t%8.4f",
  65.                        (double)raw.accelerometer_m_s2[0],
  66.                        (double)raw.accelerometer_m_s2[1],
  67.                        (double)raw.accelerometer_m_s2[2]);
  69.                 /* set att and publish this information for other apps */
  70.                 att.roll = raw.accelerometer_m_s2[0];
  71.                 att.pitch = raw.accelerometer_m_s2[1];
  72.                 att.yaw = raw.accelerometer_m_s2[2];
  73.                 orb_publish(ORB_ID(vehicle_attitude), att_pub, &att);
  74.             }
  76.             /* there could be more file descriptors here, in the form like:
  77.              * if (fds[1..n].revents & POLLIN) {}
  78.              */
  79.         }
  80.     }
  81.     PX4_INFO("exiting");
  83.     return 0;
  84. }

第八步：运行整个示例

运行你的应用程序：

  1.   px4_simple_app

如果打开QGroundControl，你就能通过实时绘图程序(Tools -> Analyze)来获得实时的传感器数据。
If you start QGroundControl, you can check the sensor values in the realtime plot (Tools -> Analyze)

小结

这个教程包含了所有开发一个PX4应用程序需要的东西。关于uORB消息机制的详细信息参见可以从这里)获得 。所有的头文件都已经良好的注释作为参考。