Events Interface

The Events Interface provides a system-wide API for notification of events, which are published to GCSs via the MAVLink Events Service (to GCSs and other components) and also stored in system logs.

The interface can be used for publishing events for state changes or any other type of occurrence, including things like arming readiness, calibration completion, and reaching the target takeoff height.

:::note The events interface will replace the use of mavlink_log_* calls in PX4 code, (and STATUS_TEXT messages in MAVLink) for event notification in the release after PX4 v1.12. There will be an intermediate period where both approaches are supported. :::

Usage

Basic

To use the API, add this include:

#include <px4_platform_common/events.h>

And then define and send the event from the desired code location:

events::send(events::ID("mymodule_test"), events::Log::Info, "Test Message");

Backward compatibility

For older GCS versions without events interface support, PX4 currently sends out all events also as mavlink_log_* STATUSTEXT message. In addition, the message must be tagged with an appended tab () so that newer GCS's can ignore that and only show the event.

So whenever adding an event, be sure to also add a mavlink_log_ call. For example:

mavlink_log_info(mavlink_log_pub, "Test Message\t");
events::send(events::ID("mymodule_test"), events::Log::Info, "Test Message");

All such mavlink_log_ calls will be removed after the next release.

Detailed

The above is a minimal example, this is a more extensive one:

uint8_t arg1 = 0;
float arg2 = -1.f;
/* EVENT
 * @description
 * This is the detailed event description.
 *
 * - value of arg1: {1}
 * - value of arg2: {2:.1}
 *
 * <profile name="dev">
 * (This paragraph is only meant to be shown to developers).
 * This behavior can be configured with the parameter <param>COM_EXAMPLE</param>.
 * </profile>
 *
 * Link to documentation: <a>https://docs.px4.io</a>
 */
events::send<uint8_t, float>(events::ID("event_name"),
	{events::Log::Error, events::LogInternal::Info}, "Event Message", arg1, arg2);

Explanations and requirements:

• /* EVENT: This tag indicates that a comment defines metadata for the following event.

• event_name: the event name (events::ID(event_name)).

  • must be unique within the whole source code of PX4. As a general convention, prefix it with the module name, or the source file for larger modules.

  • must be a valid variable name, i.e. must not contain spaces, colons, etc.

  • from that name, a 24 bit event ID is derived using a hash function. This means as long as the event name stays the same, so will the ID.

• Log Level:

  • valid log levels are the same as used in the MAVLink MAV_SEVERITY enum. In order of descending importance these are:

    Emergency,
    Alert,
    Critical,
    Error,
    Warning,
    Notice,
    Info,
    Debug,
    Disabled,

  • Above we specify a separate external and internal log level, which are the levels displayed to GCS users and in the log file, respectively: {events::Log::Error, events::LogInternal::Info}. For the majority of cases you can pass a single log level, and this will be used for both exernal and internal cases. There are cases it makes sense to have two different log levels. For example an RTL failsafe action: the user should see it as Warning/Error, whereas in the log, it is an expected system response, so it can be set to Info.

• Event Message:

  • Single-line, short message of the event. It may contain template placeholders for arguments (e.g. {1}). For more information see below.

• Event Description:

  • Detailed, optional event description.

  • Can be multiple lines/paragraphs.

  • It may contain template placeholders for arguments (e.g. {2}) and supported tags (see below)

Arguments and Enums

Events can have a fixed set of arguments that can be inserted into the message or description using template placeholders (e.g. {2:.1m} - see next section).

Valid types: uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t and float.

You can also use enumerations as arguments:

• PX4-specific/custom enumerations for events should be defined in src/lib/events/enums.json, and can then be used as event argument in the form of events::send<events::px4::enums::my_enum_t>(...).
• MAVLink "common" events are defined in mavlink/libevents/events/common.json and can be used as event argument in the form of events::send<events::common::enums::my_enum_t>(...).

Text format

Text format for event message description:

• characters can be escaped with \

  These have to be escaped: '\\', '\<', '\{'.

• supported tags:

  • Profiles: <profile name="[!]NAME">CONTENT</profile>

    CONTENT will only be shown if the name matches the configured profile. This can be used for example to hide developer information from end-users.

  • URLs: <a [href="URL"]>CONTENT</a>. If href is not set, use CONTENT as URL (i.e.<a>https://docs.px4.io</a> is interpreted as <a href="https://docs.px4.io">https://docs.px4.io</a>)

  • Parameters: <param>PARAM_NAME</param>

  • no nested tags of the same type are allowed

• arguments: template placeholders that follow python syntax, with 1-based indexing (instead of 0)

  • general form: {ARG_IDX[:.NUM_DECIMAL_DIGITS][UNIT]}

    UNIT:

    • m: horizontal distance in meters

    • m_v: vertical distance in meters

    • m^2: area in m^2

    • m/s: speed in m/s

    • C: temperature in degrees celsius

  • NUM_DECIMAL_DIGITS only makes sense for real number arguments.

Logging

Events are logged according to the internal log level, and Flight Review displays events.

:::note Flight review downloads metadata based on PX4 master, so if a definition is not yet on master, it will only be able to display the event ID. :::

Implementation

During PX4 build, only the code is added directly to the binary by the compiler (i.e. the event ID, log level(s) and any arguments).

The metadata for all events is built into a separate JSON metadata file (using a python script that scans the whole source code for event calls).

Publishing Event Metadata to a GCS

The event metadata JSON file is compiled into firmware (or hosted on the Internet), and made available to ground stations via the MAVLink Component Information service. This ensures that metadata is always up-to-date with the code running on the vehicle.

This process is the same as for parameter metadata.