ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
as734x.h
Go to the documentation of this file.
1#pragma once
2
3#include <array>
4#include <cstdint>
5
7#include "esphome/core/hal.h"
10#ifdef USE_AS734X_RGB
12#endif
13
14namespace esphome::as734x {
15
31
32static constexpr uint8_t GAIN_COUNT = 13; // entries in Gain, for sizing the correction tables
33static constexpr uint8_t NUM_BANDS = 13; // band order of BANDS_43 in __init__.py
34
35// What the published basic counts are divided by. The clear channel is wideband, so it is roughly
36// the size of all the bands together, and the near infrared channel outgrows them under daylight.
37// Dividing by the largest of every channel therefore leaves the visible bands squeezed into the
38// bottom of the range.
39enum class Normalization : uint8_t {
40 NORMALIZATION_NONE, // publish absolute basic counts
41 NORMALIZATION_ALL, // largest of every channel
42 NORMALIZATION_BANDS, // largest of the visible bands only
43 NORMALIZATION_CLEAR, // the wideband clear channel
44};
45
46// Nominal centre wavelengths in nanometres bound the visible bands. The clear channel is wideband
47// and has no single centre wavelength, so it is marked with zero instead.
48static constexpr uint16_t VISIBLE_MIN_NM = 380;
49static constexpr uint16_t VISIBLE_MAX_NM = 700;
50static constexpr uint16_t WIDEBAND_NM = 0;
51static constexpr uint16_t ABSENT_NM = 0xFFFF; // band this chip does not have
52
53// Luminous efficacy at 555 nm, for turning photopic irradiance into lux.
54static constexpr float LUMENS_PER_WATT = 683.002f;
55
56// How much one basic count of a band contributes to each integrated quantity. The factors come
57// from the manufacturer's golden-device calibration, convolved for a reconstructed spectrum.
59 float irradiance_photopic; // weighted by the CIE 1931 V(lambda) curve
60 float irradiance_par; // 400-700 nm only
61 float ppfd; // 400-700 nm only, scaled by 1e3 before publishing
62};
63
64// CIE 1931 tristimulus contribution of one basic count of a band.
66 float x;
67 float y;
68 float z;
69};
70
72struct ChipInfo {
73 const char *name;
74 const i2c::I2CRegValue *init; // written in order; the bank is selected per register address
75 const uint8_t *smux; // AS7341: SMUX RAM image per step; AS7343: the three chain images
76 const uint8_t *readout; // per step, the ADC slot of each band (0xFF: not read in this step)
77 const uint16_t *wavelengths; // per band, WIDEBAND_NM for clear and ABSENT_NM for a missing band
78 const float *gain_correction; // GAIN_COUNT entries, or GAIN_COUNT * NUM_BANDS when per band
80 const ChannelTristimulus *tristimulus; // per band
81 uint8_t init_count;
82 uint8_t astep_reg;
83 uint8_t cfg0_reg;
84 uint8_t cfg1_reg;
85 uint8_t status2_reg;
86 uint8_t id_reg;
87 uint8_t id_mask;
88 uint8_t id_value;
89 uint8_t led_reg; // LED driver register (0: this chip has no LED control)
90 uint8_t led_sel_reg; // register whose LED_SEL bit hands the pin to the driver (0: not needed)
91 uint8_t adc_slots; // 16-bit data registers read after ASTATUS
92 uint8_t smux_steps; // measurements per update
94 uint8_t smux_len; // bytes per SMUX image
95 bool auto_smux; // the chip cycles its SMUX itself after a one-time chain setup
96 bool gain_correction_per_band; // the correction table is indexed by gain and band, not gain alone
97 uint8_t extra_clear_slot; // averaged into the clear band (0xFF: none)
98};
99
100#ifdef USE_AS7341
101extern const ChipInfo AS7341_CHIP;
102#endif
103#ifdef USE_AS7343
104extern const ChipInfo AS7343_CHIP;
105extern const ChipInfo TCS3448_CHIP;
106#endif
107
109#ifdef USE_AS734X_RGB
110 SUB_TEXT_SENSOR(rgb_hex)
111#endif
112
113 public:
114 // Channel correction is multiplicative, so it starts at unity rather than zero in case no
115 // calibration is configured.
116 explicit AS734XComponent(const ChipInfo *chip) : chip_(chip) { this->channel_correction_.fill(1.0f); }
117
118 void setup() override;
119 void dump_config() override;
120 void update() override;
121 void loop() override;
122
123 void set_gain(Gain gain) { this->gain_ = gain; }
124 void set_atime(uint8_t atime) { this->atime_ = atime; }
125 void set_astep(uint16_t astep) { this->astep_ = astep; }
126
128 void enable_led(bool enable);
129
130 // Calibration applied while turning raw counts into basic counts.
131 void set_dark_current(const std::array<float, NUM_BANDS> &values) { this->dark_current_ = values; }
132 void set_channel_correction(const std::array<float, NUM_BANDS> &values) { this->channel_correction_ = values; }
133 void set_glass_attenuation_factor(float factor) { this->glass_attenuation_factor_ = factor; }
134
136 void set_basic_counts_normalization(Normalization normalization) { this->normalization_ = normalization; }
137
138 void set_counts_sensor(sensor::Sensor *sensor, uint8_t band) { this->sensors_[band] = sensor; }
139 void set_basic_counts_sensor(sensor::Sensor *sensor, uint8_t band) { this->basic_counts_sensors_[band] = sensor; }
140
141 SUB_SENSOR(saturation_level)
142 SUB_SENSOR(illuminance)
143 SUB_SENSOR(irradiance_photopic)
144 SUB_SENSOR(irradiance_par)
145 SUB_SENSOR(ppfd)
146 SUB_SENSOR(color_temperature)
147
148 protected:
149 bool select_bank_(uint8_t reg);
150 bool update_bits_(uint8_t reg, uint8_t mask, bool value);
151 bool write_exposure_();
152 bool start_step_();
153 void read_step_();
154 void abort_measurement_(const LogString *reason);
155 void calculate_basic_counts_();
156 void publish_light_metrics_();
157 void publish_color_();
158 void publish_measurement_();
159 void publish_basic_counts_();
160 float normalization_divisor_() const;
161
162 std::array<sensor::Sensor *, NUM_BANDS> sensors_{};
163 std::array<sensor::Sensor *, NUM_BANDS> basic_counts_sensors_{};
164 std::array<float, NUM_BANDS> dark_current_{};
165 std::array<float, NUM_BANDS> channel_correction_;
166 std::array<float, NUM_BANDS> basic_counts_{};
167 std::array<uint16_t, NUM_BANDS> raw_counts_{};
168 const ChipInfo *chip_; // in flash, read field by field with progmem_memcpy
169 uint32_t start_ms_{0};
170 uint32_t integration_ms_{0};
171 uint32_t timeout_ms_{0};
172 float glass_attenuation_factor_{1.0f};
173 float max_basic_count_{0.0f}; // largest of every channel
174 float max_band_basic_count_{0.0f}; // largest of the visible bands only
175 float clear_basic_count_{0.0f}; // the wideband clear channel
176 uint16_t astep_{0};
177 uint16_t peak_raw_count_{0}; // highest ADC value of this measurement, before the clear channels are averaged
178 // What the running measurement was started with, so the maths matches the data even if the
179 // configuration is changed while a measurement is in flight.
180 uint16_t reading_astep_{0};
181 Gain reading_gain_{GAIN_1X};
182 uint8_t reading_atime_{0};
183 enum class State : uint8_t { STATE_IDLE, STATE_WAIT_SMUX, STATE_READ_DATA } state_{State::STATE_IDLE};
185 Gain gain_{GAIN_1X};
186 uint8_t atime_{0};
187 uint8_t step_{0};
188 bool bank_low_{true}; // unknown until setup() writes CFG0
189};
190
191} // namespace esphome::as734x
This class simplifies creating components that periodically check a state.
Definition component.h:532
This Class provides the methods to read/write bytes from/to an i2c device.
Definition i2c.h:144
I2CRegister reg(uint8_t a_register)
calls the I2CRegister constructor
Definition i2c.h:164
Base-class for all sensors.
Definition sensor.h:48
AlsGain501 gain
const ChipInfo TCS3448_CHIP
const ChipInfo AS7341_CHIP
const ChipInfo AS7343_CHIP
uint32_t value
Definition hal.cpp:41
static void uint32_t
Per-chip constants, stored in flash. The pointed-to tables are in flash too.
Definition as734x.h:72
const uint16_t * wavelengths
Definition as734x.h:77
const uint8_t * smux
Definition as734x.h:75
const ChannelTristimulus * tristimulus
Definition as734x.h:80
const char * name
Definition as734x.h:73
const i2c::I2CRegValue * init
Definition as734x.h:74
const uint8_t * readout
Definition as734x.h:76
const ChannelContribution * contributions
Definition as734x.h:79
const float * gain_correction
Definition as734x.h:78
One register write for I2CDevice::write_registers(); tables of these may live in PROGMEM.
Definition i2c.h:18