diff --git a/doc/lwc-doc/docs/realtime-fri.en.md b/doc/lwc-doc/docs/realtime-fri.en.md new file mode 100644 index 0000000..db2998d --- /dev/null +++ b/doc/lwc-doc/docs/realtime-fri.en.md @@ -0,0 +1,84 @@ +# FIFO priority for FRI + +## Why it is needed + +FRI exchanges a position command on every cycle. With a 10 ms period, a new packet should be handled about every 10 ms. The regular Linux scheduler can delay the control thread behind other processes. The log then contains messages such as: + +```text +Could not enable FIFO RT scheduling: Operation not permitted +Overrun might occur ... Read time: 11500 us +``` + +`SCHED_FIFO` is Linux scheduling for threads with fixed priority. This project requests priority 50 for `controller_manager` and priority 80 for the FRI worker. The FRI worker receives the higher priority so it can receive a KUKA packet and send the reply on time. + +Configure this on the **ROS 2 computer** that runs `cobot run`. It does not require changes to the Sunrise Cabinet or `cobot-setting.yaml`. + +## Ubuntu 24.04 setup + +On the ROS 2 computer, run these commands as the user who starts `cobot`: + +```bash +sudo groupadd -f realtime +sudo usermod -aG realtime "$USER" +sudo tee /etc/security/limits.d/99-ros2-realtime.conf >/dev/null <<'EOF' +@realtime soft rtprio 99 +@realtime soft priority 99 +@realtime soft memlock unlimited +@realtime hard rtprio 99 +@realtime hard priority 99 +@realtime hard memlock unlimited +EOF +``` + +Log out of the desktop session completely and log in again, or reboot. An already open terminal does not receive the new group and limits. + +## Verification + +In a new terminal, verify the group and limits: + +```bash +id -nG | tr ' ' '\n' | grep -x realtime +ulimit -r +ulimit -l +``` + +The expected output is `realtime`, then `99`, then `unlimited`. + +Start FRI without commanding robot motion and check the log for: + +```text +FRI worker uses FIFO priority 80 +``` + +You can also inspect the policies of all threads in the process: + +```bash +PID=$(pgrep -n ros2_control_node) +ps -L -p "$PID" -o pid,tid,cls,rtprio,pri,comm +``` + +Realtime threads have `FF` in the `CLS` column. The FRI worker has `RTPRIO` 80 and the `controller_manager` main loop has 50. + +!!! warning "Before the first motion" + First confirm that FRI connects and that the log contains `FRI worker uses FIFO priority 80`. Then make a short move at speed 0.1 with an operator supervising. FIFO reduces jitter on the computer; it does not replace network checks, robot limits, or a clear work area. + +## If setup does not work + +- If `realtime` is missing from `id`, log out and log in again. +- If `ulimit -r` is less than 80, check `/etc/security/limits.d/99-ros2-realtime.conf` and that PAM loads `pam_limits.so`. +- If the log still says `Operation not permitted`, make sure `cobot run` is started by the same user passed to `usermod`. +- A Python virtualenv needs no extra setup: permissions are assigned to the user and inherited by Python. +- Docker requires `--cap-add=sys_nice --ulimit rtprio=99 --ulimit memlock=-1`. + +## Rollback + +To remove the setup, run: + +```bash +sudo rm /etc/security/limits.d/99-ros2-realtime.conf +sudo gpasswd -d "$USER" realtime +``` + +After logging in again, processes use the regular Linux scheduler. + +See the official [ros2_control documentation](https://control.ros.org/jazzy/doc/ros2_control/controller_manager/doc/userdoc.html#determinism) for controller-manager priorities and limits. diff --git a/doc/lwc-doc/docs/realtime-fri.md b/doc/lwc-doc/docs/realtime-fri.md new file mode 100644 index 0000000..71bc39f --- /dev/null +++ b/doc/lwc-doc/docs/realtime-fri.md @@ -0,0 +1,84 @@ +# FIFO-приоритет для FRI + +## Зачем это нужно + +FRI передаёт позиционную команду каждый цикл. При выбранном периоде 10 мс новый пакет должен обрабатываться примерно каждые 10 мс. Обычный планировщик Linux может задержать поток другим процессом. В журнале это видно по сообщениям: + +```text +Could not enable FIFO RT scheduling: Operation not permitted +Overrun might occur ... Read time: 11500 us +``` + +`SCHED_FIFO` — политика планировщика Linux для потоков с фиксированным приоритетом. В проекте `controller_manager` запрашивает приоритет 50, а FRI-поток — 80. Поток FRI получает более высокий приоритет, чтобы вовремя принять пакет KUKA и отправить ответ. + +Настройку выполняют **на компьютере с ROS 2**, с которого запускается `cobot run`. Sunrise Cabinet и `cobot-setting.yaml` менять для этого не нужно. + +## Настройка Ubuntu 24.04 + +Выполните на компьютере с ROS 2 под пользователем, который запускает `cobot`: + +```bash +sudo groupadd -f realtime +sudo usermod -aG realtime "$USER" +sudo tee /etc/security/limits.d/99-ros2-realtime.conf >/dev/null <<'EOF' +@realtime soft rtprio 99 +@realtime soft priority 99 +@realtime soft memlock unlimited +@realtime hard rtprio 99 +@realtime hard priority 99 +@realtime hard memlock unlimited +EOF +``` + +Затем полностью выйдите из графического сеанса и войдите снова либо перезагрузите компьютер. Открытый терминал не получает новую группу и лимиты. + +## Проверка + +В новом терминале проверьте группу и лимиты: + +```bash +id -nG | tr ' ' '\n' | grep -x realtime +ulimit -r +ulimit -l +``` + +Ожидаемый результат: первая команда выводит `realtime`, вторая — `99`, третья — `unlimited`. + +Запустите FRI без движения робота и убедитесь, что в журнале есть: + +```text +FRI worker uses FIFO priority 80 +``` + +После запуска можно дополнительно посмотреть политики всех потоков процесса: + +```bash +PID=$(pgrep -n ros2_control_node) +ps -L -p "$PID" -o pid,tid,cls,rtprio,pri,comm +``` + +Для потоков реального времени в столбце `CLS` будет `FF`; у FRI-потока `RTPRIO` равен 80, у основного цикла `controller_manager` — 50. + +!!! warning "Перед первым движением" + Сначала проверьте успешное подключение FRI и строку `FRI worker uses FIFO priority 80`. Затем выполните короткое перемещение на скорости 0.1 при наблюдении оператора. FIFO уменьшает jitter компьютера, но не отменяет контроль сети, ограничений робота и рабочей зоны. + +## Если настройка не сработала + +- Если `realtime` отсутствует в выводе `id`, выйдите из системы и войдите снова. +- Если `ulimit -r` меньше 80, проверьте файл `/etc/security/limits.d/99-ros2-realtime.conf` и наличие `pam_limits.so` в конфигурации PAM. +- Если лог всё ещё сообщает `Operation not permitted`, убедитесь, что `cobot run` запущен тем же пользователем, для которого выполнен `usermod`. +- В Python virtualenv дополнительных действий не требуется: права задаются пользователю и наследуются процессом Python. +- Для Docker нужны права контейнера: `--cap-add=sys_nice --ulimit rtprio=99 --ulimit memlock=-1`. + +## Откат + +Чтобы удалить настройку, выполните: + +```bash +sudo rm /etc/security/limits.d/99-ros2-realtime.conf +sudo gpasswd -d "$USER" realtime +``` + +После повторного входа процессы снова будут работать с обычным планировщиком Linux. + +Подробнее о лимитах и приоритете `controller_manager` — в [документации ros2_control](https://control.ros.org/jazzy/doc/ros2_control/controller_manager/doc/userdoc.html#determinism). diff --git a/doc/lwc-doc/mkdocs.yml b/doc/lwc-doc/mkdocs.yml index 7b5a13b..cf99b07 100644 --- a/doc/lwc-doc/mkdocs.yml +++ b/doc/lwc-doc/mkdocs.yml @@ -141,5 +141,6 @@ nav: - Меню IO Group: sunrise/kuka/features/io-group.md - Решение проблем: + - Реальное время FRI: realtime-fri.md - Ошибка конфигурации: troubleshooting/config-error.md - Ошибка SSL (rosdep/setup): troubleshooting/ssl-error.md