isl29125/lib.rs
1//! This is a platform agnostic Rust driver for the low-power digital RGB color
2//! light sensor with IR blocking filter using the [`embedded-hal`] traits.
3//!
4//! [`embedded-hal`]: https://github.com/rust-embedded/embedded-hal
5//!
6//! This driver allows you to:
7//! - Read all colors. See: [`read()`].
8//! - Read red/green/blue colors individually. See: [`red()`].
9//! - Set operating mode. See: [`set_operating_mode()`].
10//! - Set ADC resolution. See: [`set_resolution()`].
11//! - Set RGB data sensing range. See: [`set_range()`].
12//! - Set IR filtering. See: [`set_ir_filtering()`].
13//! - Read the status flags. See: [`status()`].
14//! - Clear the status flags. See: [`clear_status()`].
15//! - Read the device ID. See: [`device_id()`].
16//! - Perform a software reset. See: [`reset()`].
17//! - Interrupts:
18//! - Set interrupt thresholds. See: [`set_interrupt_thresholds()`].
19//! - Set interrupt threshold assignment. See: [`set_interrupt_threshold_assignment()`].
20//! - Set the fault count. See: [`set_fault_count()`].
21//! - Set interrupt pin mode. See: [`set_interrupt_pin_mode()`].
22//! - Enable/Disable generating an interrupt after a conversion is done. See: [`enable_interrupt_on_conversion_done()`].
23//!
24//! [`read()`]: struct.Isl29125.html#method.read
25//! [`red()`]: struct.Isl29125.html#method.red
26//! [`set_operating_mode()`]: struct.Isl29125.html#method.set_operating_mode
27//! [`set_resolution()`]: struct.Isl29125.html#method.set_resolution
28//! [`set_range()`]: struct.Isl29125.html#method.set_range
29//! [`set_ir_filtering()`]: struct.Isl29125.html#method.set_ir_filtering
30//! [`status()`]: struct.Isl29125.html#method.status
31//! [`clear_status()`]: struct.Isl29125.html#method.clear_status
32//! [`device_id()`]: struct.Isl29125.html#method.device_id
33//! [`reset()`]: struct.Isl29125.html#method.reset
34//! [`set_interrupt_thresholds()`]: struct.Isl29125.html#method.set_interrupt_thresholds
35//! [`set_interrupt_threshold_assignment()`]: struct.Isl29125.html#method.set_interrupt_threshold_assignment
36//! [`set_fault_count()`]: struct.Isl29125.html#method.set_fault_count
37//! [`set_interrupt_pin_mode()`]: struct.Isl29125.html#method.set_interrupt_pin_mode
38//! [`enable_interrupt_on_conversion_done()`]: struct.Isl29125.html#method.enable_interrupt_on_conversion_done
39//!
40//!
41//! <!-- TODO
42//! [Introductory blog post](TODO)
43//! -->
44//!
45//! ## The device
46//!
47//! The ISL29125 is a low power, high sensitivity, RED, GREEN and BLUE color
48//! light sensor (RGB) with an I2C (SMBus compatible) interface. Its
49//! state-of-the-art photodiode array provides an accurate RGB spectral
50//! response and excellent light source to light source variation (LS2LS).
51//!
52//! The ISL29125 is designed to reject IR in light sources allowing the device
53//! to operate in environments from sunlight to dark rooms. The integrating
54//! ADC rejects 50Hz and 60Hz flicker caused by artificial light sources.
55//! A selectable range allows the user to optimize sensitivity suitable for
56//! the specific application. In normal operation mode the device consumes
57//! 56μA, which reduces to 0.5μA in power-down mode.
58//!
59//! The ISL29125 supports hardware and software user programmable interrupt
60//! thresholds. The Interrupt persistency feature reduces false trigger
61//! notification.
62//!
63//! Datasheet: [ISL29125](https://www.renesas.com/eu/en/www/doc/datasheet/isl29125.pdf)
64//!
65//! ## Usage examples (see also examples folder)
66//!
67//! To use this driver, import this crate and an `embedded_hal` implementation,
68//! then instantiate the device.
69//!
70//! Please find additional examples using hardware in this repository: [driver-examples]
71//!
72//! [driver-examples]: https://github.com/eldruin/driver-examples
73//!
74//! ### Enable reading RGB and print the values
75//!
76//! ```no_run
77//! extern crate linux_embedded_hal as hal;
78//! use isl29125::{Isl29125, OperatingMode};
79//!
80//! # fn main() {
81//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
82//! let mut sensor = Isl29125::new(dev);
83//! sensor
84//! .set_operating_mode(OperatingMode::RedGreenBlue)
85//! .unwrap();
86//! loop {
87//! let m = sensor.read().unwrap();
88//! println!("R: {}, G: {}, B: {}", m.red, m.green, m.blue);
89//! }
90//! # }
91//! ```
92//!
93//! ### Measure only the red color
94//!
95//! ```no_run
96//! extern crate linux_embedded_hal as hal;
97//! use isl29125::{Isl29125, OperatingMode};
98//!
99//! # fn main() {
100//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
101//! let mut sensor = Isl29125::new(dev);
102//! sensor
103//! .set_operating_mode(OperatingMode::RedOnly)
104//! .unwrap();
105//! loop {
106//! let red = sensor.red().unwrap();
107//! println!("Red: {}", red);
108//! }
109//! # }
110//! ```
111//!
112//! ### Print the green color when the thresholds are exceeded 4 times
113//!
114//! ```no_run
115//! extern crate linux_embedded_hal as hal;
116//! use isl29125::{
117//! Isl29125, OperatingMode, FaultCount, InterruptThresholdAssignment
118//! };
119//!
120//! # fn main() {
121//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
122//! let mut sensor = Isl29125::new(dev);
123//! sensor
124//! .set_operating_mode(OperatingMode::GreenOnly)
125//! .unwrap();
126//! let ita = InterruptThresholdAssignment::Green;
127//! sensor.set_interrupt_threshold_assignment(ita).unwrap();
128//! sensor.set_fault_count(FaultCount::Four).unwrap();
129//! sensor.set_interrupt_thresholds(150, 8500).unwrap();
130//! loop {
131//! while !sensor.status().unwrap().interrupt_triggered {}
132//! let green = sensor.green().unwrap();
133//! println!("Green: {}", green);
134//! }
135//! # }
136//! ```
137//!
138//! ### Set the IR filtering
139//!
140//! ```no_run
141//! extern crate linux_embedded_hal as hal;
142//! use isl29125::{Isl29125, IRFilteringRange};
143//!
144//! # fn main() {
145//! let dev = hal::I2cdev::new("/dev/i2c-1").unwrap();
146//! let mut sensor = Isl29125::new(dev);
147//! sensor
148//! .set_ir_filtering(IRFilteringRange::Lower(35))
149//! .unwrap();
150//! # }
151//! ```
152//!
153#![deny(unsafe_code, missing_docs)]
154#![no_std]
155
156mod device_impl;
157mod types;
158pub use crate::types::{
159 ConversionStatus, Error, FaultCount, IRFilteringRange, InterruptPinMode,
160 InterruptThresholdAssignment, Measurement, OperatingMode, Range, Resolution, Status,
161};
162mod register_address;
163use crate::register_address::{BitFlags, Register};
164
165/// ISL29125 device driver
166#[derive(Debug)]
167pub struct Isl29125<I2C> {
168 i2c: I2C,
169 config1: Config,
170 config3: Config,
171}
172
173#[derive(Debug, Default, Clone, Copy)]
174struct Config {
175 bits: u8,
176}