# 活动界面

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

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

备注

事件界面将取代 mavlink_log_* 在 PX4 代码中调用，（以及 STATUS_TEXT 在 PX4 v1.12 之后的版本中，MAVLink 中的信息）用于事件通知。将有一个中间阶段两种方法都得到支持.

# 使用方法

# 基本

要使用 API，请添加此 include：

#包括 <px4_platform_common/events.h>；

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

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

# 向后兼容性

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

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

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

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

# 详细

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

uint8_t 参数1 = 0;
浮动 参数2 = -1.f;
/* 事件 * @description * 这是详细的事件描述。* - arg1 的值：{1}。* - arg2 的值：{2:.1}* <配置文件 name="dev"> *（本段仅向开发人员展示）。* 该行为可通过参数 <param>COM_EXAMPLE</param> 进行配置。* 文档链接：<a>https://px-4.com</a> */
活动::发送<；uint8_t, 浮动>；(活动::身份证("event_name"；),
	{活动::日志::错误, 活动::内部日志::信息}, 事件消息"；, 参数1, 参数2);

解释和要求：

/* 事件:该标记表示注释定义了以下事件的元数据。
事件名称：事件名称 (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 组件信息服务 (打开新窗口）.这样可以确保元数据始终与载具上运行的代码保持同步。

此过程与参数元数据.

← 控制器图飞行模式 →