# 活动界面

活动界面 提供了一个全系统范围的事件通知应用程序接口,这些事件通过 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浮动.

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

# 文本格式

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

  • 字符可以用

    这些必须转义:'\\'、'\<'、'\{'。

  • 支持的标签

    • 人物简介 <配置文件 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 组件信息服务 (打开新窗口).这样可以确保元数据始终与载具上运行的代码保持同步。

此过程与 参数元数据.