|
sas_devel — Agent documentation
Operational guides for AI agents and maintainers: repository conventions, build/test workflow, and per-package agent notes.
|
Guidance for AI agents and contributors working in this repository.
sas_robot_driver_brov2 is a ROS 2 (jazzy) ament_cmake package from the SmartArmStack project. It implements the sas_core RobotDriver interface for the BlueROV2 and BlueROV2 Heavy. The vehicle is treated as a 6-DOF "robot": the driver consumes a target wrench (set_target_joint_torques, 6D), maps it through the thruster allocation matrix (TAM) to per-thruster forces, converts forces to PWM using the thrust curves, and publishes mavros_msgs/OverrideRCIn on the RC override topic (through realtime_tools). Joint-position commands are not supported.
rclcpp, sas_core, sas_common, sas_robot_driver, mavros_msgs, realtime_tools, eigen. Keep package.xml and CMakeLists.txt in sync when changing them, since build_ros2.sh in smart_arm_stack_ROS2 generates the .deb from package.xml through bloom.
There is no automated test suite. Build inside a SAS jazzy workspace with colcon build, then run the simulation as described in the README.md (Blue simulator plus ros2 launch sas_robot_driver_brov2 brov2_launch.py).
There is no local Doxyfile. API documentation is built by sas_devel, which includes this repository as a submodule. Keep Doxygen comments (@file, @brief) on public headers and use only Doxygen-compatible markdown in README.md.
Records the onboard camera of the simulated BlueROV2 (Blue, headless) while scripts/driver_wrench_example.py drives it through the SAS driver. Validated on Apple Silicon with Docker Desktop, where Blue runs emulated (amd64), so the sim only publishes about 5 fps.
Wait about 2 minutes, then check that ros2 topic echo /mavros/state --once (inside blue-sim) shows connected: true.
.agents/record.py subscribes to /camera/image_raw and writes an mp4 using OpenCV (already in the Blue image). Usage: python3 record.py <out.mp4> <seconds>.
Copy the recorder into the container, start it, then run the wrench test (it takes about two minutes). The script connects to brov2_1 by default, so it can be run directly (pass brov2_heavy_1 for the heavy launch):
The .mp4 is only finalized when the recorder exits, so wait for /tmp/rec.log to print frames <N> before copying it out with docker cp blue-sim:/tmp/wrench.mp4 ..
The sim runs slower than real time, so .agents/make_gif.sh retimes the frames to the achieved frame rate (N frames over the recording duration, e.g. 682 frames over 125 s is 5.46 fps), then bakes the README GIF (media/brov2_wrench_sim.gif, 3x speed to keep it small) with the host ffmpeg:
Check a few frames (for example with ffmpeg -ss 5 -i brov2_wrench_sim.mp4 -frames:v 1 f.png) to make sure the scene is rendered and changes over time. The camera sits at the water surface, so the view is sky and seabed.
Only the final GIF is committed; do not commit the intermediate .mp4 files.