APDS9306 Ambient Light Sensor

CODEOWNERS

@@ -37,6 +37,7 @@ esphome/components/am43/sensor/* @buxtronix
 esphome/components/analog_threshold/* @ianchi
 esphome/components/animation/* @syndlex
 esphome/components/anova/* @buxtronix
+esphome/components/apds9306/* @aodrenah
 esphome/components/api/* @OttoWinter
 esphome/components/as5600/* @ammmze
 esphome/components/as5600/sensor/* @ammmze

esphome/components/apds9306/__init__.py

@@ -0,0 +1,4 @@
+# Based on this datasheet:
+# https://www.mouser.ca/datasheet/2/678/AVGO_S_A0002854364_1-2574547.pdf
+
+CODEOWNERS = ["@aodrenah"]

esphome/components/apds9306/apds9306.cpp

@@ -0,0 +1,150 @@
+// Based on this datasheet:
+// https://www.mouser.ca/datasheet/2/678/AVGO_S_A0002854364_1-2574547.pdf
+
+#include "apds9306.h"
+#include "esphome/core/log.h"
+#include "esphome/core/helpers.h"
+
+namespace esphome {
+namespace apds9306 {
+
+static const char *const TAG = "apds9306";
+
+enum { // APDS9306 registers
+ APDS9306_MAIN_CTRL = 0x00,
+ APDS9306_ALS_MEAS_RATE = 0x04,
+ APDS9306_ALS_GAIN = 0x05,
+ APDS9306_PART_ID = 0x06,
+ APDS9306_MAIN_STATUS = 0x07,
+ APDS9306_CLEAR_DATA_0 = 0x0A, // LSB
+ APDS9306_CLEAR_DATA_1 = 0x0B,
+ APDS9306_CLEAR_DATA_2 = 0x0C, // MSB
+ APDS9306_ALS_DATA_0 = 0x0D, // LSB
+ APDS9306_ALS_DATA_1 = 0x0E,
+ APDS9306_ALS_DATA_2 = 0x0F, // MSB
+ APDS9306_INT_CFG = 0x19,
+ APDS9306_INT_PERSISTENCE = 0x1A,
+ APDS9306_ALS_THRES_UP_0 = 0x21, // LSB
+ APDS9306_ALS_THRES_UP_1 = 0x22,
+ APDS9306_ALS_THRES_UP_2 = 0x23, // MSB
+ APDS9306_ALS_THRES_LOW_0 = 0x24, // LSB
+ APDS9306_ALS_THRES_LOW_1 = 0x25,
+ APDS9306_ALS_THRES_LOW_2 = 0x26, // MSB
+ APDS9306_ALS_THRES_VAR = 0x27
+};
+
+#define APDS9306_ERROR_CHECK(func, error) \
+ if (!(func)) { \
+ ESP_LOGE(TAG, error); \
+ this->mark_failed(); \
+ return; \
+ }
+#define APDS9306_WARNING_CHECK(func, warning) \
+ if (!(func)) { \
+ ESP_LOGW(TAG, warning); \
+ this->status_set_warning(); \
+ return; \
+ }
+#define APDS9306_WRITE_BYTE(reg, value) \
+ ESP_LOGV(TAG, "Writing 0x%02x to 0x%02x", value, reg); \
+ if (!this->write_byte(reg, value)) { \
+ ESP_LOGE(TAG, "Failed writing 0x%02x to 0x%02x", value, reg); \
+ this->mark_failed(); \
+ return; \
+ }
+
+void APDS9306::setup() {
+ ESP_LOGCONFIG(TAG, "Setting up APDS9306...");
+
+ uint8_t id;
+ if (!this->read_byte(APDS9306_PART_ID, &id)) { // Part ID register
+ this->error_code_ = COMMUNICATION_FAILED;
+ this->mark_failed();
+ return;
+ }
+
+ if (id != 0xB1 && id != 0xB3) { // 0xB1 for APDS9306 0xB3 for APDS9306-065
+ this->error_code_ = WRONG_ID;
+ this->mark_failed();
+ return;
+ }
+
+ // ALS resolution and measurement, see datasheet or init.py for options
+ uint8_t als_meas_rate = ((this->bit_width_ & 0x07) << 4) | (this->measurement_rate_ & 0x07);
+ APDS9306_WRITE_BYTE(APDS9306_ALS_MEAS_RATE, als_meas_rate);
+
+ // ALS gain, see datasheet or init.py for options
+ uint8_t als_gain = (this->gain_ & 0x07);
+ APDS9306_WRITE_BYTE(APDS9306_ALS_GAIN, als_gain);
+
+ // Set to standby mode
+ APDS9306_WRITE_BYTE(APDS9306_MAIN_CTRL, 0x00);
+
+ // Check for data, clear main status
+ uint8_t status;
+ APDS9306_WARNING_CHECK(this->read_byte(APDS9306_MAIN_STATUS, &status), "Reading MAIN STATUS failed.");
+
+ // Set to active mode
+ APDS9306_WRITE_BYTE(APDS9306_MAIN_CTRL, 0x02);
+
+ ESP_LOGCONFIG(TAG, "setup complete");
+}
+
+void APDS9306::dump_config() {
+ LOG_SENSOR("", "apds9306", this);
+ LOG_I2C_DEVICE(this);
+
+ if (this->is_failed()) {
+ switch (this->error_code_) {
+ case COMMUNICATION_FAILED:
+ ESP_LOGE(TAG, "Communication with APDS9306 failed!");
+ break;
+ case WRONG_ID:
+ ESP_LOGE(TAG, "APDS9306 has invalid id!");
+ break;
+ default:
+ ESP_LOGE(TAG, "Setting up APDS9306 registers failed!");
+ break;
+ }
+ }
+
+ ESP_LOGCONFIG(TAG, " Gain: %f", gain_val_[gain_]);
+ ESP_LOGCONFIG(TAG, " Measurement rate: %f", measurement_time_[measurement_rate_]);
+ ESP_LOGCONFIG(TAG, " Measurement Resolution/Bit width: %d", bit_width_val_[bit_width_]);
+
+ LOG_UPDATE_INTERVAL(this);
+}
+
+void APDS9306::update() {
+ // Check for new data
+ uint8_t status;
+ APDS9306_WARNING_CHECK(this->read_byte(APDS9306_MAIN_STATUS, &status), "Reading MAIN STATUS failed.");
+
+ this->status_clear_warning();
+
+ if (!(status &= 0b00001000)) { // No new data
+ return;
+ }
+
+ // Set to standby mode
+ APDS9306_WRITE_BYTE(APDS9306_MAIN_CTRL, 0x00);
+
+ // Clear MAIN STATUS
+ APDS9306_WARNING_CHECK(this->read_byte(APDS9306_MAIN_STATUS, &status), "Reading MAIN STATUS failed.");
+
+ uint8_t als_data[3];
+ APDS9306_WARNING_CHECK(this->read_bytes(APDS9306_ALS_DATA_0, als_data, 3), "Reading ALS data has failed.");
+
+ // Set to active mode
+ APDS9306_WRITE_BYTE(APDS9306_MAIN_CTRL, 0x02);
+
+ uint32_t light_level = 0x00 | encode_uint24(als_data[2], als_data[1], als_data[0]);
+
+ float lux = (light_level / this->gain_val_[gain_]) * (100.0f / this->measurement_time_[measurement_rate_]);
+
+ ESP_LOGD(TAG, "Got illuminance=%.1flx from", lux);
+ this->publish_state(lux);
+}
+
+} // namespace apds9306
+} // namespace esphome

esphome/components/apds9306/apds9306.h

@@ -0,0 +1,39 @@
+// Based on this datasheet:
+// https://www.mouser.ca/datasheet/2/678/AVGO_S_A0002854364_1-2574547.pdf
+
+#pragma once
+
+#include "esphome/components/i2c/i2c.h"
+#include "esphome/core/component.h"
+#include "esphome/components/sensor/sensor.h"
+
+namespace esphome {
+namespace apds9306 {
+
+class APDS9306 : public sensor::Sensor, public PollingComponent, public i2c::I2CDevice {
+ public:
+ void setup() override;
+ float get_setup_priority() const override { return setup_priority::BUS; }
+ void dump_config() override;
+ void update() override;
+ void set_bit_width(uint8_t bit_width) { this->bit_width_ = bit_width; }
+ void set_measurement_rate(uint8_t measurement_rate) { this->measurement_rate_ = measurement_rate; }
+ void set_ambient_light_gain(uint8_t gain) { this->gain_ = gain; }
+
+ protected:
+ enum ErrorCode {
+ NONE = 0,
+ COMMUNICATION_FAILED,
+ WRONG_ID,
+ } error_code_{NONE};
+
+ uint8_t bit_width_;
+ uint8_t bit_width_val_[6] = {20, 19, 18, 17, 16, 13};
+ uint8_t measurement_rate_;
+ float measurement_time_[7] = {25, 50, 100, 200, 500, 1000, 2000};
+ uint8_t gain_;
+ float gain_val_[5] = {1, 3, 6, 9, 18};
+};
+
+} // namespace apds9306
+} // namespace esphome

esphome/components/apds9306/sensor.py

@@ -0,0 +1,85 @@
+# Based on this datasheet:
+# https://www.mouser.ca/datasheet/2/678/AVGO_S_A0002854364_1-2574547.pdf
+
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import i2c, sensor
+from esphome.const import (
+ CONF_GAIN,
+ DEVICE_CLASS_ILLUMINANCE,
+ ICON_LIGHTBULB,
+ STATE_CLASS_MEASUREMENT,
+ UNIT_LUX,
+)
+
+DEPENDENCIES = ["i2c"]
+
+CONF_APDS9306_ID = "apds9306_id"
+CONF_BIT_WIDTH = "bit_width"
+CONF_MEASUREMENT_RATE = "measurement_rate"
+
+MEASUREMENT_BIT_WIDTHS = {
+ 20: 0,
+ 19: 1,
+ 18: 2,
+ 17: 3,
+ 16: 4,
+ 13: 5,
+}
+
+MEASUREMENT_RATES = {
+ 25: 0,
+ 50: 1,
+ 100: 2,
+ 200: 3,
+ 500: 4,
+ 1000: 5,
+ 2000: 6,
+}
+
+AMBIENT_LIGHT_GAINS = {
+ 1: 0,
+ 3: 1,
+ 6: 2,
+ 9: 3,
+ 18: 4,
+}
+
+apds9306_nds = cg.esphome_ns.namespace("apds9306")
+APDS9306 = apds9306_nds.class_(
+ "APDS9306", sensor.Sensor, cg.PollingComponent, i2c.I2CDevice
+)
+
+CONFIG_SCHEMA = (
+ sensor.sensor_schema(
+ APDS9306,
+ unit_of_measurement=UNIT_LUX,
+ accuracy_decimals=1,
+ device_class=DEVICE_CLASS_ILLUMINANCE,
+ state_class=STATE_CLASS_MEASUREMENT,
+ icon=ICON_LIGHTBULB,
+ )
+ .extend(
+ {
+ cv.Optional(CONF_GAIN, default="1"): cv.enum(AMBIENT_LIGHT_GAINS, int=True),
+ cv.Optional(CONF_BIT_WIDTH, default="18"): cv.enum(
+ MEASUREMENT_BIT_WIDTHS, int=True
+ ),
+ cv.Optional(CONF_MEASUREMENT_RATE, default="100"): cv.enum(
+ MEASUREMENT_RATES, int=True
+ ),
+ }
+ )
+ .extend(cv.polling_component_schema("60s"))
+ .extend(i2c.i2c_device_schema(0x52))
+)
+
+
+async def to_code(config):
+ var = await sensor.new_sensor(config)
+ await cg.register_component(var, config)
+ await i2c.register_i2c_device(var, config)
+
+ cg.add(var.set_bit_width(config[CONF_BIT_WIDTH]))
+ cg.add(var.set_measurement_rate(config[CONF_MEASUREMENT_RATE]))
+ cg.add(var.set_ambient_light_gain(config[CONF_GAIN]))

tests/components/apds9306/common.yaml

@@ -0,0 +1,12 @@
+i2c:
+ - id: i2c_apds9306
+ scl: ${scl_pin}
+ sda: ${sda_pin}
+
+sensor:
+ - platform: apds9306
+ name: "APDS9306 Light Level"
+ gain: 3
+ bit_width: 16
+ measurement_rate: 2000
+ update_interval: 60s

tests/components/apds9306/test.esp32-c3-idf.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO5
+ sda_pin: GPIO4
+
+<<: !include common.yaml

tests/components/apds9306/test.esp32-c3.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO5
+ sda_pin: GPIO4
+
+<<: !include common.yaml

tests/components/apds9306/test.esp32-idf.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO22
+ sda_pin: GPIO21
+
+<<: !include common.yaml

tests/components/apds9306/test.esp32.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO22
+ sda_pin: GPIO21
+
+<<: !include common.yaml

tests/components/apds9306/test.esp8266.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO5
+ sda_pin: GPIO4
+
+<<: !include common.yaml

tests/components/apds9306/test.rp2040.yaml

@@ -0,0 +1,5 @@
+substitutions:
+ scl_pin: GPIO5
+ sda_pin: GPIO4
+
+<<: !include common.yaml