Welcome to python-apds9930’s documentation!¶
This module allows you to interface with an Avago APDS-9930 I2C ambient light and proximity sensor from Python.
The bindings are easy to use: just create an instance of the APDS9930 class passing the bus number as a parameter, and optionally the device’s I2C address, if it differs from the default (0x39, 57).
Almost all features are provided through properties, which can just be read or set to retrieve or send the value to/from the device.
Methods are provided to do some more complex operations that require
a minimum pre-initialization: enable_proximity_sensor()
and
enable_ambient_light_sensor()
. Those two sensors can also be enabled
manually by setting the required settings first and then setting
power
and proximity_sensor
or ambient_light_sensor
to True to turn
them on.
Classes¶
-
class
apds9930.
APDS9930
(bus, address=57)¶ Bases:
apds9930.APDS9930_I2C_Base
The APDS-9930 I2C interface class. Pass the
bus
number and, if it’s different from 0x39 (57), the deviceaddress
as arguments.The device is initialized with the default settings. bus must be an int curresponding to the number of the I2C bus you want to use.
address
is optional and is the I2C address of the device, if different from the default (0x39).-
ambient_light
¶ Ambient light value in lux (read-only).
-
ambient_light_gain
¶ Receiver gain for ambient light sensor. Good values are:
Value Gain apds9930.values
constant name0 1x AGAIN_1X
1 4x AGAIN_8X
2 16x AGAIN_16X
3 64x AGAIN_120X
-
ambient_light_int_high_threshold
¶ Ambient light interrupt high threshold.
-
ambient_light_int_low_threshold
¶ Ambient light interrupt low threshold.
-
ambient_light_interrupt
¶ If True, the device is asserting an ambient light interrupt. Set it to None to clear it.
-
ambient_light_sensor
¶ Enable or disable the ambient light sensor (mode, boolean).
-
ambient_to_lux
(ch0, ch1)¶ Accepts data from both channels and returns a value in lux (according to the datasheet).
-
ch0_light
¶ Light data from channel 0. Read-only.
-
ch1_light
¶ Light data from channel 1. Read-only.
-
clear_all_interrupts
()¶ Clear all interrupts.
-
dump_registers
()¶ Debug: read all the registers from the device and print them.
-
enable_ambient_light_interrupt
¶ Enable or disable the ambient light interrupt (mode, boolean).
-
enable_ambient_light_sensor
(interrupt=False)¶ Set all the needed values to turn on the ambient light sensor and turn it on. If interrupt is True, ALS interrupts will also be enabled.
-
enable_proximity_interrupt
¶ Enable or disable the proximity interrupt (mode, boolean).
-
enable_proximity_sensor
(interrupt=False)¶ Set all the needed values to turn on the proximity sensor and turn it on. If interrupt is True, proximity interrupts will also be enabled.
-
get_mode
(mode)¶ Gets the state of a specific feature in the ENABLE register. Good values for mode are:
Mode # POWER 0 AMBIENT_LIGHT 1 PROXIMITY 2 WAIT 3 AMBIENT_LIGHT_INT 4 PROXIMITY_INT 5 SLEEP_AFTER_INT 6 The specified feature is either enabled or disabled depending on whether the method returns True or False
-
id
¶ The ID of the device, stored in the ID register.
-
led_drive
¶ LED drive strength for proximity and ALS. Good values are:
Value LED Current apds9930.values
constant name0 100 mA LED_DRIVE_100MA
1 50 mA LED_DRIVE_50MA
2 25 mA LED_DRIVE_25MA
3 12.5 mA LED_DRIVE_12_5MA
-
mode
¶ The value of the ENABLE register, which stores the enabled features of the sensor. You should not set this property directly unless you know what you’re doing. Use
set_mode()
and/or the specific feature methods instead.
-
power
¶ Turn on or off the internal oscillator (mode, boolean).
-
proximity
¶ Proximity data. Read-only.
-
proximity_diode
¶ Diode used for proximity sensor. Good values are:
Value Diode selection 0 Reserved 1 Reserved 2 Use Ch1 diode 3 Reserved
-
proximity_gain
¶ Receiver gain for proximity detection. Good values are:
Value Gain apds9930.values
constant name0 1x PGAIN_1X
1 2x PGAIN_2X
2 4x PGAIN_4X
3 8x PGAIN_8X
-
proximity_int_high_threshold
¶ Proximity interrupt high threshold.
-
proximity_int_low_threshold
¶ Proximity interrupt low threshold.
-
proximity_interrupt
¶ If True, the device is asserting a proximity interrupt. Set it to None to clear it.
-
proximity_sensor
¶ Enable or disable the proximity sensor (mode, boolean).
-
set_mode
(mode, enable)¶ Like
get_mode()
, but changes the mode instead. Theenable
argument determines whether the feature specified by mode will be enabled or disabled. The method accepts one additional argument asmode
,Mode # ALL 7 which enables or disables all features at once.
The specified feature will either be enabled or disabled depending on whether
enable
is True or False
-
sleep_after_interrupt
¶ Enable or disable the sleep after interrupt feature. If True, the device will power down after an interrupt has been generated (mode, boolean).
-
wait_timer
¶ Enable or disable the wait timer feature (mode, boolean).
-
-
class
apds9930.
APDS9930_I2C_Base
(bus, address)¶ Base class for APDS9930 that provides basic I2C communication methods, specifically adapted for this device.
bus must be an integer curresponding to the I2C bus you want to use. address is the I2C address of the device.
-
close
()¶ Close the I2C bus.
-
read_block_data
(reg, len, mode=160)¶ Read a block with size len starting from the specified address.
-
read_byte
()¶ Read a byte from the I2C bus.
-
read_byte_data
(reg, mode=160)¶ Read a byte from the specified address.
-
write_block_data
(reg, data, mode=160)¶ Write a block starting from a specific register. Mode should be set to
AUTO_INCREMENT
, so that the device automatically selects the following register before writing the next byte.
-
write_byte
(data)¶ Write a byte to the specified address. Useful to interact with the COMMAND register directly.
-
write_byte_data
(reg, data, mode=160)¶ Write a byte to a specific register. mode can be found in apds9930.values, and can be
AUTO_INCREMENT
,REPEATED_BYTE
orSPECIAL_FN
. Check the device’s datasheet for more information.
-
-
exception
apds9930.
SensorError
¶ Bases:
exceptions.EnvironmentError
Raised when a non-I2C-specific error occurs (for example, the device ID is not recognized, which usually means the device is not hooked up properly).
If issues with the I2C occur, an IOError will be raised.
Constants¶
Constants and default values used by the library¶
These values are defined in the apds9930.values
module.
COMMAND register modes (see write_byte()
)¶
REPEATED_BYTE
= 0x80
AUTO_INCREMENT
= 0xA0
SPECIAL_FN
= 0xE0
APDS-9930 I2C address¶
APDS9930_I2C_ADDR
= 0x39
Acceptable device IDs¶
APDS9930_IDs
= [0x39]
APDS-9930 register addresses¶
APDS9930_ENABLE
= 0x00
APDS9930_ATIME
= 0x01
APDS9930_WTIME
= 0x03
APDS9930_AILTL
= 0x04
APDS9930_AILTH
= 0x05
APDS9930_AIHTL
= 0x06
APDS9930_AIHTH
= 0x07
APDS9930_PILTL
= 0x08
APDS9930_PILTH
= 0x09
APDS9930_PIHTL
= 0x0A
APDS9930_PIHTH
= 0x0B
APDS9930_PERS
= 0x0C
APDS9930_CONFIG
= 0x0D
APDS9930_PPULSE
= 0x0E
APDS9930_CONTROL
= 0x0F
APDS9930_ID
= 0x12
APDS9930_STATUS
= 0x13
APDS9930_Ch0DATAL
= 0x14
APDS9930_Ch0DATAH
= 0x15
APDS9930_Ch1DATAL
= 0x16
APDS9930_Ch1DATAH
= 0x17
APDS9930_PDATAL
= 0x18
APDS9930_PDATAH
= 0x19
APDS9930_POFFSET
= 0x1E
List for printing purposes and for iteration¶
REGISTERS
= {registers}
Bit fields¶
APDS9930_PON
= 0b00000001
APDS9930_AEN
= 0b00000010
APDS9930_PEN
= 0b00000100
APDS9930_WEN
= 0b00001000
APSD9930_AIEN
= 0b00010000
APDS9930_PIEN
= 0b00100000
APDS9930_SAI
= 0b01000000
Acceptable parameters for set_mode()
¶
POWER
= 0
AMBIENT_LIGHT
= 1
PROXIMITY
= 2
WAIT
= 3
AMBIENT_LIGHT_INT
= 4
PROXIMITY_INT
= 5
SLEEP_AFTER_INT
= 6
ALL
= 7
LED Drive values (led_drive
)¶
LED_DRIVE_100MA
= 0
LED_DRIVE_50MA
= 1
LED_DRIVE_25MA
= 2
LED_DRIVE_12_5MA
= 3
ALS Gain (AGAIN) values (ambient_light_gain
)¶
AGAIN_1X
= 0
AGAIN_8X
= 1
AGAIN_16X
= 2
AGAIN_120X
= 3
Default values¶
DEFAULT_ATIME
= 0xFF
DEFAULT_WTIME
= 0xFF
DEFAULT_PTIME
= 0xFF
DEFAULT_PPULSE
= 0x08
DEFAULT_POFFSET
= 0
DEFAULT_CONFIG
= 0
DEFAULT_PDRIVE
= LED_DRIVE_100MA
DEFAULT_PDIODE
= 2
DEFAULT_PGAIN
= PGAIN_8X
DEFAULT_AGAIN
= AGAIN_16X
DEFAULT_PILT
= 0
DEFAULT_PIHT
= 50
DEFAULT_AILT
= 0xFFFF
DEFAULT_AIHT
= 0
DEFAULT_PERS
= 0x22