Rebase from 'debian/iron/naoqi_driver'

CHANGELOG.rst

@@ -2,6 +2,15 @@
 Changelog for package naoqi_driver
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+2.1.1 (2023-12-05)
+------------------
+* Drop testing of `foxy` and `galactic`
+* README: remove extraneous args in example
+* Update code and instructions about Docker
+* Fix build for humble
+* Improve README about audio service
+* Contributors: Victor Paléologue
+
 2.1.0 (2023-11-23)
 ------------------
 * New "Listen" action

README.md

@@ -8,14 +8,13 @@ This repo defines the __naoqi_driver__ package for ROS2. The driver is in charge
 The __naoqi_driver__ is a ROS node.
 It connects to a robot running NAOqi using libQi.
 
-It also listens to a libQi endpoint (specified by the option `qi_listen_url`).
-This endpoint should be public (*e.g.* `qi_listen_url:=0.0.0.0:0`)
-to enable collecting audio buffers remotely.
-It should be set to a local address (*e.g.* `qi_listen_url:=127.0.0.1:0`)
-when running on the robot.
-It can be disabled by setting `qi_listen_url:=` when audio is not required.
+To support the audio features, __naoqi_driver__ opens a libQi endpoint.
+It is set by default to `127.0.0.1:0` (random port on local host),
+so it should be set with the option `qi_listen_url`,
+*e.g.* `qi_listen_url:=0.0.0.0:0` to allow collecting audio buffers remotely.
 
-> Audio can be disabled in [boot_config.json](src/naoqi_driver2/share/boot_config.json).
+Audio features are enabled by default and can be disabled in
+[boot_config.json](src/naoqi_driver2/share/boot_config.json).
 
 
 ## Installation
@@ -88,6 +87,8 @@ assuming the author of the job has agreed to the license terms.
 
 ## Launch
 
+### Avoid interference with autonomous life
+
 To have full control of the robot with ROS,
 you may want to disable autonomous behaviors first:
 
@@ -97,20 +98,48 @@ qicli call ALAutonomousLife.setState disabled
 qicli call ALMotion.wakeUp
 ```
 
-The driver can be launched using the following command:
+
+### NAOqi 2.8 and lower
+
+The driver can be launched from a remote machine this way:
 
 ```sh
 source /opt/ros/<distro>/setup.bash # or source <ws>/install/setup.bash if built from source
-ros2 launch naoqi_driver naoqi_driver.launch.py nao_ip:=<robot_host>
+ros2 launch naoqi_driver naoqi_driver.launch.py nao_ip:=<robot_host> qi_listen_url:=0.0.0.0:0
 ```
 
+
+### NAOqi 2.9 and higher
+
 Username and password arguments are required
 for robots running NAOqi 2.9 or greater:
 
 ```sh
-ros2 launch naoqi_driver naoqi_driver.launch.py nao_ip:=<robot_host> nao_username:=nao nao_password:=<robot_password>
+ros2 launch naoqi_driver naoqi_driver.launch.py nao_ip:=<robot_host> nao_username:=nao nao_password:=<robot_password> qi_listen_url:=0.0.0.0:0
+```
+
+
+### From a Docker container
+
+If you run __naoqi_driver__ from a Docker container with audio features enabled,
+you must specify the libQi endpoint with, *e.g.* for port 56000:
+
+```sh
+source /opt/ros/<distro>/setup.bash # or source <ws>/install/setup.bash if built from source
+ros2 launch naoqi_driver naoqi_driver.launch.py nao_ip:=<robot_host> qi_listen_url:=0.0.0.0:56000
 ```
 
+Then you must [expose](https://docs.docker.com/engine/reference/commandline/run/#publish) it from the container.
+
+
+### On the robot or on the same machine
+
+If you run the driver directly from the robot (or your machine running a virtual robot),
+you can omit the options:
+
+```sh
+ros2 launch naoqi_driver naoqi_driver.launch.py
+```
 
 ## Check that the node is running correctly
 
@@ -181,10 +210,10 @@ angular:
 ## Development
 
 Check how to [install the driver from source](#installing-from-source),
-or use the [`Dockerfile`](Dockerfile) to get setup a reproducible dev environment:
+or use `docker compose` to get a more reproducible dev environment:
 
 ```sh
-docker build -t ros2-naoqi-driver .
+ROS_DISTRO=iron docker compose up dev --build
 ```
 
 > To get all logs in live and build debuggable binaries,
@@ -197,7 +226,7 @@ docker build -t ros2-naoqi-driver .
 > It works also when running tests:
 >
 > ```sh
-> colcon test --packages-skip nao_meshes pepper_meshes --event-handlers console_direct+ --ctest-args tests
+> colcon test --event-handlers console_direct+ --ctest-args tests
 > ```