RCWL-1601 Ultrasonic Distance Sensor — ROS2 Jazzy Driver (GPIO)

ROS2 Jazzy driver for the RCWL-1601 ultrasonic distance sensor using GPIO trigger/echo interface.

Features

• Publishes sensor_msgs/Range on rcwl1601/range
• fake_mode for testing without hardware (random Gaussian data)
• GPIO trigger/echo timing (BCM pin numbering)
• 3.3 V native operation — no voltage divider needed
• Handles timeout (no echo) as +Inf per REP 117
• Runtime publish_rate change via ros2 param set
• Calibration and reset services

Why this package?

There is also a libHCSR04 driver for HC-SR04. The RCWL-1601 offers different trade-offs:

Feature	HC-SR04 (libHCSR04)	RCWL-1601 (this package)
Operating voltage	5 V only	3.3 V native
Level shifter	Required for RPi	Not needed
Protocol	Trigger/echo (identical)	Trigger/echo (identical)
Range	2 ~ 400 cm	2 ~ 450 cm
Beam angle	~30°	~30°
Driver	C++	Python
Price	~$1-2	~$1-2

Choose libHCSR04 for C++ integration and 5 V systems. Choose this package for 3.3 V Raspberry Pi projects without voltage dividers.

Prerequisites

• ROS 2 Jazzy
• Python 3
• Real hardware only:
  • RPi.GPIO (pip install RPi.GPIO)
  • Raspberry Pi with GPIO access

Installation

cd ~/ros2_ws
colcon build --packages-select rcwl1601_range --symlink-install
source install/setup.bash

Usage

Launch (fake mode — default)

ros2 launch rcwl1601_range rcwl1601_launch.py

Run node directly

ros2 run rcwl1601_range rcwl1601_node.py

Real hardware (Raspberry Pi)

ros2 launch rcwl1601_range rcwl1601_launch.py \
  params_file:=path/to/your_params.yaml

Set fake_mode: false, trig_pin, and echo_pin in your YAML file.

Verify output

ros2 topic echo /rcwl1601/range

Parameters

Parameter	Type	Default	Description
fake_mode	bool	true	Generate random data without hardware
trig_pin	int	24	GPIO trigger pin (BCM numbering)
echo_pin	int	23	GPIO echo pin (BCM numbering)
publish_rate	float	10.0	Publishing rate in Hz (max ~20 Hz)
frame_id	string	ultrasonic_link	TF frame ID
min_range	float	0.02	Minimum detectable range (m)
max_range	float	4.50	Maximum detectable range (m)
field_of_view	float	0.5236	Sensor field of view (radians)

Services

Service	Type	Description
rcwl1601/calibrate	std_srvs/srv/Trigger	Collect samples for 2 s, report averages
rcwl1601/reset	std_srvs/srv/Trigger	Clear bias, reinitialize sensor

Package Structure

rcwl1601_range/
├── CMakeLists.txt
├── package.xml
├── config/
│   └── rcwl1601_params.yaml
├── launch/
│   └── rcwl1601_launch.py
├── rcwl1601_range/
│   ├── __init__.py
│   └── rcwl1601_driver.py
├── nodes/
│   └── rcwl1601_node.py
├── test/
│   └── test_rcwl1601_node.py
├── .gitignore
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Test Results

Tested on Ubuntu 24.04 (WSL2) with fake_mode: true.

Test Category	Test	Result
Topics	rcwl1601/range publishes sensor_msgs/Range	PASS
Topics	Range values within limits, ULTRASOUND type	PASS
Services	rcwl1601/calibrate returns success=True	PASS
Services	rcwl1601/reset returns success=True	PASS
Parameters	publish_rate runtime change	PASS
Shutdown	Clean exit	PASS
Linting	pep257, flake8, copyright, xmllint	PASS

License

MIT