Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Быстрый старт

Если вы уже знакомы с Arduino и у вас есть опыт, то для вас на этой странице собраны краткая теория работы RosDuino, ссылки на репозитории и документацию, а также готовые шаблоны всех базовых возможностей библиотеки без лишних деталей. Если у вас уже настроены Arduino IDE 2 и ROS 2, эту страницу можно использовать как шпаргалку по API RosDuino.


Репозитории и документация RosDuino

Все примеры ниже также доступны прямо в меню Arduino IDE: Файл → Примеры → RosDuino.


Как устроена работа RosDuino

Система состоит из двух частей, соединённых по последовательному порту USB (115200 бод):

  1. Библиотека rosduino_arduino на плате (#include <RosDuino.h>): превращает плату в узел ROS 2. Скетч объявляет имя узла в ros.begin("имя_узла"), а в loop() вызывает ros.update(). Подробная установка разобрана в уроке 1.
  2. Узел rosduino_agent на компьютере с Ubuntu: открывает порт платы и создаёт в графе ROS 2 её топики и сервисы. При подключении плата сама сообщает агенту, какие топики и сервисы ей нужны, поэтому пересобирать или перенастраивать агент при смене скетча не требуется. Сборка агента разобрана в уроке 4.
flowchart LR
    MCU["Плата + RosDuino.h"] <-.-> SP(["Serial порт (USB)"])
    SP <-.-> Agent
    subgraph PC["Компьютер с Ubuntu"]
        Agent["rosduino_agent"] <--> ROS2["Топики, сервисы и журнал ROS 2"]
    end
    style SP fill:#fef3c7,stroke:#d97706,stroke-width:2px,stroke-dasharray: 5 5,color:#78350f
    style PC fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#0f172a

Топики и сервисы: в чём разница

  • Топик (Topic) — непрерывный односторонний канал передачи сообщений (Message). Узел-издатель публикует данные в топик (ros.publish()), а узел-подписчик принимает их в функции-обработчике (ros.subscribe()). Используется для потока показаний датчиков и регулярных команд (подробнее в уроке 4 и уроке 5).
  • Сервис (Service) — удалённый вызов функции по схеме «запрос — ответ» (Request / Response). Клиент передаёт входные параметры в srv.request, а сервер выполняет функцию и возвращает результат в srv.response. Плата может быть как сервером (ros.service()), так и клиентом (ros.call()) (подробнее в уроке 6).

Запуск агента и три главных правила

Во всех примерах ниже агент запускается на компьютере в Терминале 1 (или через launch-файл rosduino_agent.launch.py):

ros2 run rosduino_agent rosduino_agent --port /dev/ttyACM0
  1. Не используйте Serial.print() и держите закрытой утилиту мониторинга порта в Arduino IDE — порт занят протоколом RosDuino.
  2. Останавливайте агент (Ctrl+C) перед загрузкой нового скетча в плату.
  3. Не используйте delay() в loop() — вызывайте ros.update() на каждом проходе, а для периодических действий используйте rosduino::Timer.

Базовые примеры API RosDuino

1. Подписка на топик (ros.subscribe)

Исходник в библиотеке: examples/Simple/Led/Led.ino (расширенный вариант: examples/Full/Blink/Blink.ino), подробный разбор — в уроке 4.

Плата создаёт узел /led_board, подписывается на топик /led (std_msgs/msg/Bool) и управляет светодиодом D48. Тип топика определяется автоматически по аргументу функции onLed:

#include <RosDuino.h>
#include <std_msgs/msg/Bool.h>

const int LED_PIN = 48;

void onLed(std_msgs::Bool msg) {
  digitalWrite(LED_PIN, msg.data ? HIGH : LOW);
}

void setup() {
  pinMode(LED_PIN, OUTPUT);
  ros.begin("led_board");
  ros.subscribe("led", onLed);
}

void loop() {
  ros.update();
}

Проверка в Терминале 2:

ros2 topic pub --once /led std_msgs/msg/Bool "{data: true}"
ros2 topic pub --once /led std_msgs/msg/Bool "{data: false}"

2. Публикация показаний датчика по таймеру (ros.publish и rosduino::Timer)

Исходник в библиотеке: examples/Simple/LightSensor/LightSensor.ino (потоковый опрос кнопки: examples/Simple/ButtonSimple/ButtonSimple.ino; расширенные варианты: examples/Full/PubSub/PubSub.ino и examples/Full/NanoBasic/NanoBasic.ino), подробный разбор — в уроке 5.

Плата каждые 100 мс (10 Гц) по неблокирующему таймеру rosduino::Timer считывает сигнал на A8 и публикует его в топик /analog_signal (std_msgs/msg/Int32). Для периодического датчика отдельная регистрация не нужна: первый вызов ros.publish() создаёт топик (пропуская самый первый отсчёт), а все следующие показания сразу уходят в ROS 2:

#include <RosDuino.h>
#include <std_msgs/msg/Int32.h>

std_msgs::Int32 msg;
rosduino::Timer timer(100);  // каждые 100 мс (10 Гц)

void setup() {
  ros.begin("sensor_board");
}

void loop() {
  ros.update();
  if (timer.check()) {
    msg.data = analogRead(A8);
    ros.publish("analog_signal", msg);
  }
}

Проверка в Терминале 2:

ros2 topic echo /analog_signal
ros2 topic hz /analog_signal

3. Одиночные события кнопки (ros.advertise)

Исходник в библиотеке: examples/Simple/ButtonOnce/ButtonOnce.ino (расширенный вариант: examples/Full/ButtonPub/ButtonPub.ino), подробный разбор — в уроке 5.

Если скетч отправляет сообщение только при изменении состояния кнопки D28, в setup() после ros.begin() вызывается ros.advertise("button", pressed). Переменная pressed при этом не публикуется — она только задаёт тип топика (std_msgs/msg/Bool). Благодаря этому топик /button сразу виден в ros2 topic list, а самое первое нажатие не теряется:

#include <RosDuino.h>
#include <std_msgs/msg/Bool.h>

const int BUTTON_PIN = 28;

std_msgs::Bool pressed;
bool wasPressed = false;
rosduino::Timer timer(50);  // каждые 50 мс (антидребезг)

void setup() {
  pinMode(BUTTON_PIN, INPUT);
  wasPressed = (digitalRead(BUTTON_PIN) == HIGH);
  ros.begin("button");
  ros.advertise("button", pressed);
}

void loop() {
  ros.update();
  if (timer.check()) {
    pressed.data = (digitalRead(BUTTON_PIN) == HIGH);
    if (pressed.data != wasPressed) {
      wasPressed = pressed.data;
      ros.publish("button", pressed);
    }
  }
}

Проверка в Терминале 2:

ros2 topic echo /button

4. Сервер сервиса на плате (ros.service)

Исходники в библиотеке: examples/Simple/LedService/LedService.ino и examples/Simple/AddServer/AddServer.ino (расширенный вариант: examples/Full/ServiceServer/ServiceServer.ino), подробный разбор — в уроке 6 (сервер сервиса).

Плата предоставляет сервис /set_led (std_srvs/srv/SetBool): принимает параметр в srv.request.data, включает или выключает светодиод D48 и записывает результат работы в srv.response:

#include <RosDuino.h>
#include <std_srvs/srv/SetBool.h>

const int LED_PIN = 48;

void onSetLed(std_srvs::SetBool& srv) {
  digitalWrite(LED_PIN, srv.request.data ? HIGH : LOW);
  srv.response.success = true;
  srv.response.message = "done";
}

void setup() {
  pinMode(LED_PIN, OUTPUT);
  ros.begin("led_service");
  ros.service("set_led", onSetLed);
}

void loop() {
  ros.update();
}

Проверка в Терминале 2:

ros2 service call /set_led std_srvs/srv/SetBool "{data: true}"

5. Клиент сервиса на плате (ros.call)

Исходник в библиотеке: examples/Simple/AddClient/AddClient.ino (расширенный вариант: examples/Full/ServiceClient/ServiceClient.ino), подробный разбор — в уроке 6 (клиент сервиса).

Плата раз в 2 с асинхронно вызывает внешний сервис /add_two_ints (example_interfaces/srv/AddTwoInts) на компьютере, передавая слагаемые в adder.request, и зажигает D48 при получении ответа в onAnswer:

#include <RosDuino.h>
#include <example_interfaces/srv/AddTwoInts.h>

const int LED_PIN = 48;
example_interfaces::AddTwoInts adder;
rosduino::Timer timer(2000);

void onAnswer(example_interfaces::AddTwoInts& srv) {
  digitalWrite(LED_PIN, (srv.response.sum == 5) ? HIGH : LOW);
}

void setup() {
  pinMode(LED_PIN, OUTPUT);
  ros.begin("add_client");
}

void loop() {
  ros.update();
  if (ros.connected() && timer.check()) {
    adder.request.a = 2;
    adder.request.b = 3;
    ros.call("add_two_ints", adder, onAnswer);
  }
}

Запуск тестового сервера в Терминале 2:

ros2 run demo_nodes_cpp add_two_ints_server

6. Журнал /rosout и время ROS 2 (ros.logInfo и ros.now)

Исходник в библиотеке: examples/Full/TimeAndLog/TimeAndLog.ino (отладка на втором порту Serial1: examples/Simple/LedSerial1/LedSerial1.ino), подробный разбор — в уроке 7.

Вместо Serial.println() отладочные сообщения отправляются в /rosout методами ros.logDebug(), ros.logInfo(), ros.logWarn(), ros.logError(), ros.logFatal(), а синхронизированное с компьютером время запрашивается через ros.now():

#include <RosDuino.h>

rosduino::Timer timer(1000);

void setup() {
  ros.begin("time_and_log");
}

void loop() {
  ros.update();
  if (ros.connected() && timer.check()) {
    builtin_interfaces::msg::Time t = ros.now();
    ros.logInfo(t.sec != 0 ? F("time ok") : F("time unset"));
  }
}

Просмотр журнала и диагностики связи в Терминале 2:

ros2 topic echo /rosout
ros2 topic echo /diagnostics --field status --once

Сводка основных функций простого API

Вызов в скетчеНазначениеГде разобрано в курсе
ros.begin("node_name")Инициализирует порт (115200 бод) и задаёт имя узла ROS 2Урок 4
ros.update()Обрабатывает входящие и исходящие пакеты в loop()Урок 4
ros.connected()Возвращает true, когда связь с rosduino_agent установленаУрок 5
ros.advertise("topic", msg)Заранее создаёт топик по типу переменной msg без отправки сообщенияУрок 5
ros.publish("topic", msg)Публикует сообщение msg в топикУрок 5
ros.subscribe("topic", cb)Подписывается на топик и вызывает функцию cb(msg)Урок 4
ros.service("srv_name", cb)Регистрирует сервер сервиса на плате с обработчиком cb(srv)Урок 6
ros.call("srv_name", srv, cb)Неблокирующе вызывает внешний сервис ROS 2Урок 6
ros.logInfo(F("text"))Отправляет запись в системный журнал /rosoutУрок 7
ros.now()Возвращает синхронизированное время builtin_interfaces::msg::TimeУрок 7
rosduino::Timer t(ms); t.check()Неблокирующий таймер с периодом ms миллисекундУрок 5

Назад: Введение.
Дальше: Платы v1 и v2 или Урок 1. Подготовка рабочего места.