TSL2561 Visible + IR Light Sensor — ROS2 Jazzy Driver (I2C)

ROS2 Jazzy driver for the TAOS/AMS TSL2561 digital light sensor over I2C, providing visible + infrared illuminance measurement.

Features

• Publishes sensor_msgs/Illuminance on tsl2561/illuminance
• fake_mode for testing without hardware (random Gaussian data)
• Dual-channel sensing: CH0 (visible + IR) and CH1 (IR only)
• Datasheet lux calculation formula (T/FN/CL package)
• Configurable integration time: 13 ms, 101 ms, 402 ms
• Configurable gain: 1x, 16x
• Runtime publish_rate change via ros2 param set
• Calibration and reset services

Why this package?

There is also a bh1750_light driver for BH1750. The TSL2561 offers different trade-offs:

Feature	BH1750 (bh1750_light)	TSL2561 (this package)
Channels	1 (visible)	2 (visible+IR, IR only)
Lux range	1–65535 lx	0.1–40000 lx
Resolution	1 / 0.5 / 4 lx	Depends on integration
Integration	Fixed per mode	13 ms / 101 ms / 402 ms
Gain	Fixed	1x / 16x
IR rejection	Hardware	Software (dual channel)
Price	~$1-2	~$2-4

Choose bh1750_light for simple lux readings with minimal setup. Choose this package for configurable gain/integration and IR-compensated measurements.

Prerequisites

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

Installation

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

Usage

Launch (fake mode — default)

ros2 launch tsl2561_light tsl2561_launch.py

Run node directly

ros2 run tsl2561_light tsl2561_node.py

Real hardware (Raspberry Pi)

ros2 launch tsl2561_light tsl2561_launch.py \
  params_file:=path/to/your_params.yaml

Set fake_mode: false, device_address, integration, and gain in your YAML file.

Verify output

ros2 topic echo /tsl2561/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 (float: 0x39, GND: 0x29, VDD: 0x49)
integration	string	402ms	Integration time: 13ms, 101ms, 402ms
gain	string	16x	Gain: 1x, 16x
publish_rate	float	2.0	Publishing rate in Hz
frame_id	string	light_link	TF frame ID

Services

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

Package Structure

tsl2561_light/
├── CMakeLists.txt
├── package.xml
├── config/
│   └── tsl2561_params.yaml
├── launch/
│   └── tsl2561_launch.py
├── tsl2561_light/
│   ├── __init__.py
│   └── tsl2561_driver.py
├── nodes/
│   └── tsl2561_node.py
├── test/
│   └── test_tsl2561_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	tsl2561/illuminance publishes sensor_msgs/Illuminance	PASS
Topics	Illuminance non-negative, correct frame_id	PASS
Services	tsl2561/calibrate returns success=True	PASS
Services	tsl2561/reset returns success=True	PASS
Parameters	publish_rate runtime change	PASS
Shutdown	Clean exit	PASS
Linting	pep257, flake8, copyright, xmllint	PASS

License

MIT