APDS-9960 Proximity/Color/ALS Sensor — ROS2 Jazzy Driver (I2C)

ROS2 Jazzy driver for the Broadcom APDS-9960 multi-function sensor over I2C, providing proximity detection, RGB color sensing, and ambient light measurement.

Features

• Publishes sensor_msgs/Range on apds9960/proximity (IR proximity, INFRARED type)
• Publishes std_msgs/ColorRGBA on apds9960/color (normalised R/G/B, clear as alpha)
• Publishes sensor_msgs/Illuminance on apds9960/illuminance (lux from ALS)
• fake_mode for testing without hardware (random Gaussian data)
• Configurable ALS gain: 1x, 4x, 16x, 64x
• Configurable proximity gain: 1x, 2x, 4x, 8x
• Configurable LED drive strength: 100 mA, 50 mA, 25 mA, 12.5 mA
• Runtime publish_rate change via ros2 param set
• Calibration and reset services

Prerequisites

• ROS 2 Jazzy
• Python 3
• Real hardware only:
  • smbus2 (pip install smbus2)
  • APDS-9960 breakout board (I2C)

Installation

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

Usage

Launch (fake mode — default)

ros2 launch apds9960_sensor apds9960_launch.py

Run node directly

ros2 run apds9960_sensor apds9960_node.py

Real hardware (Raspberry Pi)

ros2 launch apds9960_sensor apds9960_launch.py \
  params_file:=path/to/your_params.yaml

Set fake_mode: false in your YAML file.

Verify output

ros2 topic echo /apds9960/proximity
ros2 topic echo /apds9960/color
ros2 topic echo /apds9960/illuminance

Parameters

Parameter	Type	Default	Description
fake_mode	bool	true	Generate random data without hardware
i2c_bus	int	1	I2C bus number (/dev/i2c-N)
device_address	int	0x39	I2C address (fixed for APDS-9960)
als_gain	string	4x	ALS gain: 1x, 4x, 16x, 64x
prox_gain	string	4x	Proximity gain: 1x, 2x, 4x, 8x
led_drive	string	100mA	LED drive: 100mA, 50mA, 25mA, 12.5mA
atime_ms	float	103.0	ALS integration time in ms
publish_rate	float	5.0	Publishing rate in Hz
frame_id	string	apds9960_link	TF frame ID
prox_min_range	float	0.01	Minimum proximity range (m)
prox_max_range	float	0.10	Maximum proximity range (m)

Topics

Topic	Type	Description
apds9960/proximity	sensor_msgs/Range	IR proximity (mapped to 1-10 cm)
apds9960/color	std_msgs/ColorRGBA	Normalised R/G/B, clear as alpha
apds9960/illuminance	sensor_msgs/Illuminance	Ambient light in lux

Services

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

Package Structure

apds9960_sensor/
├── CMakeLists.txt
├── package.xml
├── config/
│   └── apds9960_params.yaml
├── launch/
│   └── apds9960_launch.py
├── apds9960_sensor/
│   ├── __init__.py
│   └── apds9960_driver.py
├── nodes/
│   └── apds9960_node.py
├── test/
│   └── test_apds9960_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	apds9960/proximity publishes sensor_msgs/Range	PASS
Topics	Proximity values valid, INFRARED type	PASS
Topics	apds9960/color publishes std_msgs/ColorRGBA	PASS
Topics	apds9960/illuminance publishes sensor_msgs/Illuminance	PASS
Services	apds9960/calibrate returns success=True	PASS
Services	apds9960/reset returns success=True	PASS
Parameters	publish_rate runtime change	PASS
Shutdown	Clean exit	PASS
Linting	pep257, flake8, copyright, xmllint	PASS

License

MIT