Repository navigation
px4_events: add optional PX4 event decoding plugin - #2359
Conversation
Linking comment from old PR here. |
vooon
left a comment
There was a problem hiding this comment.
Yes, skeleton looks right.
except, i'd probably place libevents into a vendor subdirectory.
vooon
left a comment
There was a problem hiding this comment.
This PR should not touch FTP code.
62a44ba to
0f9953d
Compare
|
Fixed failing CI/CD case, and removed FTP code. This PR depends on #2361, it will not work without it. |
vooon
left a comment
There was a problem hiding this comment.
Thanks, a separate package is the right direction. A few things need to change before merge, the rest can be follow-ups.
Must fix
-
Acquisition does not recover after a dropped link (
src/plugins/px4_events/acquisition.cpp:169). On cancellation or an "uncertain" failure (timeout, disconnect)ftp/closeis skipped on purpose, but the FTP plugin keeps the path insession_file_map. After reconnectftp/openon the same path returnsEALREADY, which is neitherEBUSYnorEIO, so it is not retried. Decoding stays off until mavros restarts or someone callsftp/reset, and the PX4-side session leaks too. Please close (or reset) on these paths, or handleEALREADYon open. -
Configure hard-fails without the submodule (
CMakeLists.txt:39).FATAL_ERRORwhenvendor/libeventsis not checked out breakscolcon buildfor everyone who pullsros2without--recurse-submodules, and for release tarballs /git archiveexports, which carry an empty directory. Please make this not break the workspace build, and update the build instructions (AGENTS.md, README) for the submodule. -
No lint gate (
CMakeLists.txt:65). The package does not enableament_lint_autolikemavrosandmavros_extrasdo, so uncrustify/cpplint never run on it.px4_events.cpp:262and:301are already over 100 columns. -
Unrelated docs churn (
docs/plugins/std/index.json,docs/plugins/index.md). About 110 lines of regenerated output are not related to this PR, and the std index does not match the PR's sources (ftp~/listat line 308 vs 309 inftp.cpp). Please rebase on currentros2, regenerate, and keep the regenerated outputs in a separate commit.
Should fix (here or in a follow-up)
- Events from any component are decoded (
px4_events.cpp:307).handle_eventusesSystemAndOk, so an EVENT from a camera or companion with the same sysid is decoded with the autopilot's definitions and logged as "FCU: ...". Discovery already usesComponentAndOk. - One bad event definition rejects the whole file (
px4_events/decoder.cpp:243). The decoder throws on the first definition it cannot handle (float enum, arguments over 40 bytes, bad precision, duplicate id), so nothing is decoded for that firmware. Skipping that one event with a warning would be more robust. The cachevalidate()path has the same all-or-nothing behaviour. - Only the first decode failure is logged (
px4_events.cpp:149).RCLCPP_WARN_ONCEat a single call site is shared by all event ids and all decoders, while the message reads as per-id. - Metadata is decoded twice under the mutex (
px4_events/cache.cpp:192). Each file is XZ-decoded, JSON-parsed and built into aDecoderinMetadataCache::validateand again inAcquisition::file_finished_locked, withmutex_held. With up to 8 MiB of JSON this can stallhandle_eventon the MAVLink thread.
Simplifications
px4_events/xz_metadata.cpp:76: about 100 lines of hand-rolled XZ container parsing only to learn the output size.lzma_stream_decoder+lzma_codewithavail_outcapped at the limit gives the same bound, and accepts valid streams this parser rejects (stream padding, concatenated streams).px4_events/metadata.cpp:106: the bitwise CRC32 can be replaced by liblzma'slzma_crc32, which is already linked:~lzma_crc32(data, n, 0xFFFFFFFF)gives the MAVLink variant.
f2e0952 to
1053122
Compare
|
Thanks for the review, Addressed the review feedback as follows: Must fix
Should fix
Simplifications
|
vooon
left a comment
There was a problem hiding this comment.
Thanks, all four must-fix items from the previous review are resolved at 1053122, along with the component filter, per-event skipping, per-id warnings and both simplifications. This pass covered the previous findings and the main sources; I did not build it locally.
On item 1: sending ftp/close on cancel and on uncertain failures is enough, because the FTP plugin's close_file() erases its session entry even when the reply times out, so the next open does not hit EALREADY.
Non-blocking notes:
-
gendoc.shnow requires the submodule. It fails unlessmavros_px4_eventshas compile commands, and the package produces none whenvendor/libeventsis missing. Fine for now, but worth a line intools/README.mdif it is not there already. -
Skipped definitions log one WARN each at load. Firmware with many unsupported definitions will produce a burst; a single summary line would be quieter.
-
A missing
messageoreventskey still rejects the whole file. These throw from the JSON accessors indecoder.cppinstead of skipping the one event.
Follow-up, as you planned: metadata is still decoded twice with mutex_ held (MetadataCache::validate and Acquisition::file_finished_locked).
Summary
Adds optional PX4 EVENT decoding through a dedicated mavros_px4_events package and px4_events plugin.
The plugin translates event IDs and arguments into readable messages using firmware event definitions. It supports local definitions, automatic metadata discovery and acquisition over MAVLink FTP, and a persistent metadata cache.
Resolves #1990. This replaces the earlier core-integrated implementation in #2324 with the separate-package structure requested during review.
Depends on #2361. Its FTP fix is now removed, with tests updated accordingly. Please merge #2361 first.
Package structure
Core raw EVENT logging and status_event publication remain unchanged. The new plugin adds decoded logging, so raw and decoded messages can both appear. It does not introduce a replacement event topic. Sys Status will "double log" raw EVENTS which is something that can be revisited in a future PR.
Dependencies
libevents
libevents is pinned as a git submodule under mavros_px4_events/vendor/libevents and built into the plugin.
This removes the previous build-time-download vendor package. CI initializes submodules recursively. The submodule arrangement also follows the release-packaging approach suggested during review.
XZ decompression
Uses system liblzma through liblzma-dev, replacing xz_embedded_vendor.
Compressed metadata input is capped at 1 MiB, and uncompressed JSON at 8 MiB per file. liblzma has a separate 128 MiB decoder memory limit (as it briefly requests a large dictionary that it doesn't fill when interacting with most PX4 systems)
Operation
Automatic mode
Automatic mode is the default because decoding now lives in an optional package.
The plugin:
Acquisition uses cmd/command, ftp/open, ftp/read, and ftp/close. The command, ftp, and normal sys_status plugins should remain enabled.
Disconnect cancels automatic acquisition and clears automatically acquired definitions. Reconnection starts discovery again. Stale asynchronous completions are discarded.
Local mode
Local mode loads a supplied JSON or JSON.xz event-definition file without discovery, FTP acquisition, or persistent cache use.
The file is validated, but its correspondence to the connected firmware is the user's responsibility. Local definitions remain loaded across reconnects.
Failure behavior
Metadata discovery, validation, acquisition, or persistence failures leave core raw event logging available.
Unknown events remain visible through the unchanged core path. Unknown enum/bitmask values are retained in decoded output rather than silently discarded.
Parameters
Parameters belong to the plugin node, normally /mavros/px4_events. They are read-only after startup and require a restart to change.
Cache behavior
Container users can mount the cache directory on persistent storage to retain entries across container replacement.
Compatibility and validation
Metadata discovery supports both current and legacy advertisement messages.
FTP paths preserve advertised absolute paths. Relative paths are tried as advertised, with a single leading-slash retry after ENOENT for compatibility with the older PX4 behavior encountered during vehicle testing.
Metadata validation includes file-size limits, checksums, supported definitions, argument-layout checks, and a floating-point precision limit before rendering.
Automated tests
The package includes focused tests for:
CI initializes the libevents submodule and includes the new package in build/test coverage. Coverage reporting excludes vendored libevents sources.
Manual testing
I tested this against PX4 sim, as well as a ModalAI starling. Testing on previous implementation was also successful against a ModalAI Seeker.
Testing included cold/warm starts, local file mode, and various attempts to test systems edge cases including disconnecting halfway through discovery, intentionally corrupting a cache, disconnecting/reconnecting both vehicle and mavros, and injected false ftp file names. All tests successful, it failed gracefully (logged and self-disabled) in each situation.
ASan/UBSan testing was also performed during development.
Documentation
Adds package documentation covering installation, plugin loading, configuration, local mode, automatic acquisition, cache behavior, resource limits, and logging.
Extends the existing documentation generator with:
The extractor improvement also discovers the existing setpoint_accel.send_force parameter, which was previously absent from generated documentation. Its generated page and standard-plugin index are updated accordingly; this does not change runtime behavior.