Повідомлення uORB

Введення

uORB - це асинхронний publish() / subscribe() API для обміну повідомленнями, який використовується для міжпотокового / міжпроцесного зв'язку.

Подивіться посібник, щоб дізнатися, як його використовувати в C++.

uORB автоматично запускається при завантаженні, оскільки багато програм залежать від нього. Запускається за допомогою uorb start. Модульні тести можна запустити за допомогою uorb_tests.

Додавання нової теми

Нові теми uORB можуть бути додані або в основний репозиторій PX4/PX4-Autopilot, або до визначень повідомлень поза деревом. Для отримання інформації щодо додавання визначень повідомлень uORB поза деревом, див. цей розділ.

Щоб додати нову тему, вам потрібно створити новий файл .msg у каталозі msg/ та додати назву файлу до списку msg/CMakeLists.txt. З цього автоматично генерується потрібний C/C++ код.

Подивіться на існуючі файли msg для визначення підтримуваних типів. Повідомлення також можна використовувати вкладеним в інші повідомлення.

До кожної згенерованої структури C/C++, буде додано поле uint64_t timestamp. Це використовується в логері, тому переконайтеся, що він заповнюється при публікації повідомлення.

Щоб використовувати тему у коді, додайте заголовок:

#include <uORB/topics/topic_name.h>

Додавши рядок, подібний наступному у файлі .msg, одне визначення повідомлення може бути використане для кількох незалежних тем:

# TOPICS mission offboard_mission onboard_mission

Потім у коді використовуйте їх як ідентифікатор теми: ORB_ID(offboard_mission).

Публікація

Публікацію теми можна виконати з будь-якого місця в системі, включаючи контекст переривання (функції, які викликаються API hrt_call). Однак, перш ніж публікувати тему в контексті переривання, її потрібно оголосити і опублікувати поза контекстом переривання (принаймні, один раз).

Перелік тем та їх прослуховування

Команда listener доступна лише на Pixracer (FMUv4) та Linux / OS X.

Щоб перерахувати всі теми, перерахуйте файлові дескриптори:

ls /obj

Щоб прослухати зміст однієї теми з 5 повідомлень, запустіть команду прослуховувач:

listener sensor_accel 5

На виході виводиться n-кратний вміст теми:

TOPIC: sensor_accel #3
timestamp: 84978861
integral_dt: 4044
error_count: 0
x: -1
y: 2
z: 100
x_integral: -0
y_integral: 0
z_integral: 0
temperature: 46
range_m_s2: 78
scaling: 0

TOPIC: sensor_accel #4
timestamp: 85010833
integral_dt: 3980
error_count: 0
x: -1
y: 2
z: 100
x_integral: -0
y_integral: 0
z_integral: 0
temperature: 46
range_m_s2: 78
scaling: 0

TIP

На системах на основі NuttX (Pixhawk, Pixracer і т.д.) команду listener можна викликати з консолі MAVLink QGroundControl для перевірки значень датчиків та інших тем. Це потужний інструмент для відлагодження, оскільки його можна використовувати навіть тоді, коли QGC підключений через бездротове з'єднання (наприклад, коли транспортний засіб летить). Для отримання додаткової інформації дивіться: Відлагодження сенсорів/тем.

Команда uorb top

Команда uorb top показує частоту публікації кожної теми в реальному часі:

update: 1s, num topics: 77
TOPIC NAME                        INST #SUB #MSG #LOST #QSIZE
actuator_armed                       0    6    4     0 1
actuator_controls_0                  0    7  242  1044 1
battery_status                       0    6  500  2694 1
commander_state                      0    1   98    89 1
control_state                        0    4  242   433 1
ekf2_innovations                     0    1  242   223 1
ekf2_timestamps                      0    1  242    23 1
estimator_status                     0    3  242   488 1
mc_att_ctrl_status                   0    0  242     0 1
sensor_accel                         0    1  242     0 1
sensor_accel                         1    1  249    43 1
sensor_baro                          0    1   42     0 1
sensor_combined                      0    6  242   636 1

Колонки: назва теми, індекс, кількість підписників, частота публікації в Гц, кількість втрачених повідомлень за секунду (для всіх підписників разом) і розмір черги.

Multi-instance

uORB надає механізм публікації декількох незалежних екземплярів однієї теми за допомогою orb_advertise_multi. Він поверне публікувачу індекс екземпляра. Після цього підписник має вибрати, на який екземпляр підписатися за допомогою orb_subscribe_multi (orb_subscribe підписує на перший екземпляр). Наявність декількох екземплярів корисна, наприклад, якщо система має кілька сенсорів одного типу.

Переконайтеся, що ви не змішуєте orb_advertise_multi і orb_advertise для однієї теми.

Повний API задокументовано в platforms/common/uORB/uORBManager.hpp.

Message/Field Deprecation

Оскільки існують зовнішні інструменти, що використовують повідомлення uORB з файлів журналів, такі як Flight Review, при оновленні існуючих повідомлень необхідно враховувати певні аспекти:

• Зміна існуючих полів або повідомлень, на які покладаються зовнішні інструменти, зазвичай є прийнятною, якщо для оновлення є вагомі причини. Зокрема, для внесення змін до Flight Review, Flight Review має бути оновлено до того, як код буде об'єднано з master.
• Для того, щоб зовнішні інструменти могли надійно розрізняти дві версії повідомлень, необхідно виконати наступні кроки:
  • Вилучені або перейменовані повідомлення слід додати до списку deprecated_msgs у msg/CMakeLists.txt, а файл .msg слід видалити.
  • Видалені або перейменовані поля повинні бути закоментовані та позначені як застарілі. Наприклад, uint8 quat_reset_counter стане # DEPRECATED: uint8 quat_reset_counter. Це робиться для того, щоб гарантувати, що видалені поля (або повідомлення) не будуть додані повторно в майбутньому.
  • У разі семантичної зміни (наприклад, одиниця виміру змінюється з градусів на радіани), поле також має бути перейменоване, а попереднє позначене як застаріле, як зазначено вище.