活动界面

PX4 v1.13

活动界面 提供了一个全系统范围的事件通知应用程序接口，这些事件通过 MAVLink 活动服务 (全球监控系统和其他组件），并存储在 系统日志.

该界面可用于发布状态变化或任何其他类型的事件，包括上膛就绪、校准完成和达到目标起飞高度等。

信息

事件界面将取代 mavlink_log_* 在 PX4 代码中调用，（以及 STATUS_TEXT 在 PX4 v1.13 及更高版本中，事件通知使用的是 MAVLink 中的消息。中间会有一段 两种方法都得到支持.

使用方法

基本

要使用 API，请添加此 include：

#include <px4_platform_common/events.h>；

然后从所需的代码位置定义和发送事件：

活动::发送(活动::身份证("mymodule_test"；), 活动::日志::Info、 "测试消息"；);

向后兼容性

对于不支持事件接口的旧版 GCS，PX4 目前也会将所有事件作为 mavlink_log_* 说明文本 信息。此外，信息必须用附加的制表符 (\t)，这样较新的 GCS's 就可以忽略它，只显示事件。

因此，在添加事件时，一定要同时添加一个 mavlink_log_ 呼叫。例如

mavlink_log_info(mavlink_log_pub、 测试信息\t"；);
活动::发送(活动::身份证("mymodule_test"；), 活动::日志::Info、 "测试消息"；);

所有这些 mavlink_log_ 调用将在下一个版本发布后删除。

详细

上面是一个最小的例子，这是一个更广泛的例子：

uint8_t 参数1 = 0;
浮动 参数2 = -1.f;
/* 事件
 * @描述
 * 这是详细的活动说明。
 *
 * arg1 的值： {1}
 * arg2 的值：{2:.1}
 *
 * <配置文件 name="dev">；
 * 本段内容仅供开发人员参考）。
 * 可以使用参数<param>COM_EXAMPLE</param>配置该行为。
 * </profile>；
 *
 * 文档链接：<a>https://px-4.com</a>；
 */
活动::发送<；uint8_t, 浮动>(活动::身份证("event_name"；),
	{活动::日志::Error、 活动::内部日志::Info}、 事件消息"；, arg1, arg2）；

解释和要求：

• /* 事件:该标记表示注释定义了以下事件的元数据。

• 事件名称：事件名称 (events::ID(event_name)).

  • 在整个 PX4 源代码中必须是唯一的。一般情况下，以模块名称或较大模块的源文件作为前缀。
  • 必须是有效的变量名，即不能包含空格、冒号等。
  • 从该名称中，使用哈希函数得出一个 24 位的事件 ID。这意味着只要事件名称保持不变，ID 也会保持不变。

• 日志级别:

  • 有效日志级别与 MAVLink 中使用的相同。 MAV_SEVERITY 枚举。按重要性递减顺序排列如下：

    紧急情况
    警报
    关键、
    错误、
    警告
    通知
    信息
    调试、
    失能、

  - 上面我们分别指定了外部日志级别和内部日志级别，它们分别是显示给 GCS 用户和日志文件的级别：{events::Log::Error，events::LogInternal::Info}`。
    在大多数情况下，您只需传递一个日志级别，该级别将同时用于外部和内部情况。
  在某些情况下，使用两种不同的日志级别是合理的。
  例如，一个 RTL 故障安全操作：用户应将其视为警告/错误，而在日志中，它是一个预期的系统响应，因此可将其设置为 "信息"。

• 活动信息:

  • 事件的单行简短信息。它可能包含参数的模板占位符（例如 {1}).更多信息请参见下文。

• 活动说明:

  • 详细的、可选的事件描述。
  • 可以是多行/段。
  • 它可能包含参数的模板占位符（例如 {2})和支持的标记（见下文）

参数和枚举

事件可以有一组固定的参数，这些参数可以使用模板占位符（例如 {2:.1m} - 见下一节）。

有效类型： uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t 和 浮动.

您也可以使用枚举作为参数：

• PX4 特有的/自定义的事件枚举应在 src/lib/events/enums.json的形式作为事件参数。 events::send<events::px4::enums::my_enum_t>(...).
• MAVLink "common" 事件定义在 mavlink/libevents/events/common.json 的形式作为事件参数。 events::send<events::common::enums::my_enum_t>(...).

文本格式

事件信息描述的文本格式：

• 字符可以用

  这些必须被转义：'（'），'（<'），'（'）。

• 支持的标签

  • 人物简介 <配置文件 name="[!]NAME">CONTENT</profile>；

    内容 只有当名称与配置的配置文件相匹配时，才会显示。例如，这可用于向最终用户隐藏开发人员信息。

  • URLs： <a[href="URL"]>内容</a>；.如果 href 未设置，则使用 内容 作为 网址 （即<a>https://px-4.com</a>； 解释为 <a href="https://px-4.com">https://px-4.com</a>；)

  • 参数 <参数>PARAM_NAME</param>；

  • 不允许使用同一类型的嵌套标记

• 参数：遵循 python 语法的模板占位符，索引以 1 为基础（而不是 0）

  • 一般形式： {arg_idx[:.num_decimal_digits][unit]}

    单位：

    • m：水平距离，以米为单位
    • m_v： 垂直距离，以米为单位
    • m^2：面积，单位 m^2
    • m/s：速度，单位 m/s
    • C：温度（摄氏度

  • 十进制位数 只适用于实数参数。

记录

根据内部日志级别记录事件，以及 飞行回顾 显示事件。

信息

飞行审查根据 PX4 主文件下载元数据，因此如果主文件中还没有定义，则只能显示事件 ID。

实施情况

在 PX4 生成过程中，编译器只将代码直接添加到二进制文件中（即事件 ID、日志级别和任何参数）。

所有事件的元数据都包含在一个单独的 JSON 元数据文件中（使用 python 脚本扫描整个源代码以查找事件调用）。

向全球监控系统发布事件元数据

事件元数据 JSON 文件被编入固件（和/或托管在互联网上），并通过 MAVLink 组件元数据服务.这样可以确保元数据始终与载具上运行的代码保持同步。

此过程与 参数元数据.更多信息，请参见 PX4 元数据（翻译 & 出版）