Add ultrasonic sensor

README.md

@@ -100,6 +100,55 @@ The node drives the pan and tilt servos over **I²C bus 1** (device address `0x2
 
 ---
 
+### Ultrasonic range sensor
+
+```
+                        ┌──────────────────────────────────────┐
+                        │          UltrasonicNode              │
+                        │                                      │
+                        │  Sensor off when no subscribers      │
+                        │  Sensor on  when subscribers > 0     │
+                        │  1 s warm-up after power-on          │
+                        │                                      │
+                        │         ▼                            │
+                        │   raspbot_v2_interface               │
+                        │   I²C bus 1, addr 0x2B               │
+                        │         ▼                            │
+                        │   /dev/i2c-1 ──────> HC-SR04 sensor  │
+                        │                                      │
+ /ultrasonic/range <────│  Range @ configurable rate           │
+ (sensor_msgs/Range)    │  radiation_type = ULTRASOUND         │
+                        │  range in metres (REP-117)           │
+                        └──────────────────────────────────────┘
+```
+
+#### Topics
+
+| Topic | Direction | Type | Description |
+|---|---|---|---|
+| `/ultrasonic/range` | Published | `sensor_msgs/Range` | Distance in metres. `+inf` when beyond max range, `-inf` when closer than min range (REP-117). Only published while subscribers are connected. |
+
+#### Parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `publish_rate_hz` | `10.0` | Sensor poll and publish rate |
+| `frame_id` | `'ultrasonic'` | `header.frame_id` on published messages |
+| `min_range_m` | `0.02` | Minimum valid range in metres |
+| `max_range_m` | `4.0` | Maximum valid range in metres |
+| `field_of_view` | `0.2618` | Sensor cone width in radians (~15°) |
+| `warmup_s` | `1.0` | Seconds to wait after powering the sensor on before publishing |
+
+#### Verifying range readings
+
+```bash
+ros2 topic echo /ultrasonic/range
+```
+
+The sensor will activate automatically when this command runs and deactivate when it is stopped.
+
+---
+
 ## Setting up the robot
 
 ### 1. Flash Raspberry Pi OS
@@ -199,6 +248,7 @@ Available launch arguments:
 | `max_speed` | `1.0` | Maximum motor speed in library units |
 | `pan_center_deg` | `90.0` | Pan angle at startup and shutdown (degrees) |
 | `tilt_center_deg` | `60.0` | Tilt angle at startup and shutdown (degrees) |
+| `ultrasonic_rate_hz` | `10.0` | Ultrasonic sensor publish rate (Hz) |
 
 ### Sending velocity commands from the host
 
@@ -262,7 +312,8 @@ ros2 topic echo /joint_states
 │       └── raspbot_v2/
 │           ├── __init__.py
 │           ├── motor_controller_node.py      # Differential-drive motor control
-│           └── camera_orientation_node.py    # Pan/tilt servo control
+│           ├── camera_orientation_node.py    # Pan/tilt servo control
+│           └── ultrasonic_node.py            # HC-SR04 range sensor
 └── raspbot_v2_interface/       # Vendored Yahboom hardware library
     └── Raspbot_Lib/
         └── Raspbot_Lib.py      # I²C driver (smbus, bus 1, addr 0x2B)