ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
as734x.cpp
Go to the documentation of this file.
1#include "as734x.h"
2#include "color_helpers.h"
5#include "esphome/core/log.h"
7
8#include <algorithm>
9#include <cstdio>
10
11namespace esphome::as734x {
12
13ESPHOME_LOG_TAG(TAG, "as734x");
14
15// Registers and bits shared by both chips
16static constexpr uint8_t REG_ENABLE = 0x80;
17static constexpr uint8_t REG_ATIME = 0x81;
18static constexpr uint8_t REG_ASTATUS = 0x94;
19static constexpr uint8_t ENABLE_PON = 0x01;
20static constexpr uint8_t ENABLE_SP_EN = 0x02;
21static constexpr uint8_t ENABLE_SMUX_EN = 0x10;
22static constexpr uint8_t CFG0_REG_BANK = 0x10;
23static constexpr uint8_t BANK_SPLIT = 0x80; // registers below this need REG_BANK set
24static constexpr uint8_t STATUS2_AVALID = 0x40;
25static constexpr uint8_t ASTATUS_ASAT = 0x80;
26static constexpr uint8_t LED_ACT = 0x80; // LED driver on, in the chip's LED register
27static constexpr uint8_t CONFIG_LED_SEL = 0x08;
28
29static constexpr uint8_t AS7341_CFG6 = 0xAF;
30static constexpr uint8_t AS7341_SMUX_CMD_WRITE = 0x10; // copy the SMUX image from RAM to the chain
31static constexpr uint8_t AS7341_SMUX_RAM = 0x00;
32static constexpr uint8_t AS7343_CHAIN_CMD = 0xE4;
33static constexpr uint8_t AS7343_CHAIN_SMUX = 0xE7;
34static constexpr uint8_t AS7343_CHAINS = 3;
35
36// Read one field of a ChipInfo kept in flash
37template<typename T> static T pgm(const T &field) {
38 T value;
39 progmem_memcpy(&value, &field, sizeof(T));
40 return value;
41}
42
43static constexpr uint8_t NO_SLOT = 0xFF;
44static constexpr uint8_t CLEAR_BAND = NUM_BANDS - 1;
45static constexpr uint8_t MAX_SMUX_LEN = 20;
46static constexpr uint8_t MAX_ADC_SLOTS = 18;
47static constexpr uint32_t MIN_COLLECTION_TIMEOUT_MS = 30 * 1000;
48static constexpr uint32_t MAX_ADC_COUNT = 65535;
49
50PROGMEM_STRING_TABLE(BandNames, "F1", "F2", "FZ", "F3", "F4", "FY", "F5", "FXL", "F6", "F7", "F8", "NIR", "Clear");
51
52#ifdef USE_AS7341
53static const char AS7341_NAME[] PROGMEM = "AS7341";
54static constexpr uint8_t AS7341_ADC_SLOTS = 6;
55static constexpr uint8_t AS7341_SMUX_LEN = 20;
56static constexpr uint8_t AS7341_SMUX_STEPS = 2;
57static constexpr i2c::I2CRegValue AS7341_INIT[] PROGMEM = {
58 {0x70, 0x00}}; // CONFIG: SPM mode, INT_SEL and LED_SEL cleared
59static const uint8_t AS7341_SMUX[] PROGMEM = {
60 0x30, 0x01, 0x00, 0x00, 0x00, 0x42, 0x00, 0x00, 0x50, 0x00, // step 0: F1 to F4, NIR, Clear
61 0x00, 0x00, 0x20, 0x04, 0x00, 0x30, 0x01, 0x50, 0x00, 0x06, // step 0, continued
62 0x00, 0x00, 0x00, 0x40, 0x02, 0x00, 0x10, 0x03, 0x50, 0x10, // step 1: F5 to F8, NIR, Clear
63 0x03, 0x00, 0x00, 0x00, 0x24, 0x00, 0x00, 0x50, 0x00, 0x06, // step 1, continued
64};
65static_assert(sizeof(AS7341_SMUX) == AS7341_SMUX_STEPS * AS7341_SMUX_LEN && AS7341_SMUX_LEN <= MAX_SMUX_LEN);
66static constexpr uint8_t N = NO_SLOT;
67static const uint8_t AS7341_READOUT[] PROGMEM = {
68 0, 1, N, 2, 3, N, N, N, N, N, N, N, N, // step 0
69 N, N, N, N, N, N, 0, N, 1, 2, 3, 5, 4, // step 1: SMUX routes clear to ADC4 and NIR to ADC5
70};
71static_assert(sizeof(AS7341_READOUT) == AS7341_SMUX_STEPS * NUM_BANDS && AS7341_ADC_SLOTS <= MAX_ADC_SLOTS);
72// This chip has no FZ, FY or FXL band, so those slots are marked absent.
73// clang-format off
74static const uint16_t AS7341_WAVELENGTHS[] PROGMEM = {
75 415, 445, ABSENT_NM, 480, 515, ABSENT_NM, 555, ABSENT_NM, 590, 630, 680, 910, WIDEBAND_NM,
76};
77// clang-format on
78static_assert(sizeof(AS7341_WAVELENGTHS) == NUM_BANDS * sizeof(uint16_t));
79// Datasheet values for the golden device: gain correction per gain step, the same for every band.
80// The last two entries stay at zero because this chip has no 1024x or 2048x gain.
81static const float AS7341_GAIN_CORRECTION[] PROGMEM = {1.0577f, 1.0491f, 1.0479f, 1.0491f, 1.0207f, 1.0158f, 1.0109f,
82 1.0000f, 1.0003f, 0.9873f, 0.9593f, 0.0f, 0.0f};
83static_assert(sizeof(AS7341_GAIN_CORRECTION) == GAIN_COUNT * sizeof(float));
84// clang-format off
85// The three bands this chip does not have contribute nothing to the weighted sums.
86static const ChannelContribution AS7341_CONTRIBUTIONS[] PROGMEM = {
87 {0.005261294f, 5.936230324f, 0.020518273f}, // F1
88 {0.242615252f, 3.572528495f, 0.013525490f}, // F2
89 {0.0f, 0.0f, 0.0f}, // FZ, absent
90 {0.174482552f, 2.914113437f, 0.011585145f}, // F3
91 {1.479499075f, 2.452851227f, 0.010604986f}, // F4
92 {0.0f, 0.0f, 0.0f}, // FY, absent
93 {1.906818555f, 1.940656433f, 0.008890531f}, // F5
94 {0.0f, 0.0f, 0.0f}, // FXL, absent
95 {1.162058142f, 1.533976606f, 0.007441544f}, // F6
96 {0.462374845f, 1.819838250f, 0.009393590f}, // F7
97 {-0.017794572f, 1.232942274f, 0.006890812f}, // F8
98 {-0.260730901f, -1.102368000f, -0.004647911f}, // NIR
99 {-0.022604075f, -0.033304813f, -0.000129106f}, // Clear
100};
101static const ChannelTristimulus AS7341_TRISTIMULUS[] PROGMEM = {
102 {0.39814f, 0.01396f, 1.95010f}, // F1
103 {1.29540f, 0.16748f, 6.45490f}, // F2
104 {0.0f, 0.0f, 0.0f}, // FZ, absent
105 {0.36956f, 0.23538f, 2.78010f}, // F3
106 {0.10902f, 1.42750f, 0.18501f}, // F4
107 {0.0f, 0.0f, 0.0f}, // FY, absent
108 {0.71942f, 1.88670f, 0.15325f}, // F5
109 {0.0f, 0.0f, 0.0f}, // FXL, absent
110 {1.78180f, 1.14200f, 0.09539f}, // F6
111 {1.10110f, 0.46497f, 0.10563f}, // F7
112 {-0.03991f, -0.02702f, 0.08866f}, // F8
113 {-0.27597f, -0.24468f, -0.61140f}, // NIR
114 {-0.02347f, -0.01993f, -0.00938f}, // Clear
115};
116// clang-format on
117static_assert(sizeof(AS7341_CONTRIBUTIONS) == NUM_BANDS * sizeof(ChannelContribution));
118static_assert(sizeof(AS7341_TRISTIMULUS) == NUM_BANDS * sizeof(ChannelTristimulus));
119const ChipInfo AS7341_CHIP PROGMEM = {
120 .name = AS7341_NAME,
121 .init = AS7341_INIT,
122 .smux = AS7341_SMUX,
123 .readout = AS7341_READOUT,
124 .wavelengths = AS7341_WAVELENGTHS,
125 .gain_correction = AS7341_GAIN_CORRECTION,
126 .contributions = AS7341_CONTRIBUTIONS,
127 .tristimulus = AS7341_TRISTIMULUS,
128 .init_count = 1,
129 .astep_reg = 0xCA,
130 .cfg0_reg = 0xA9,
131 .cfg1_reg = 0xAA,
132 .status2_reg = 0xA3,
133 .id_reg = 0x92,
134 .id_mask = 0xFC,
135 .id_value = 0x09 << 2,
136 .led_reg = 0x74,
137 .led_sel_reg = 0x70, // CONFIG, whose LED_SEL bit connects the pin to the driver
138 .adc_slots = AS7341_ADC_SLOTS,
139 .smux_steps = AS7341_SMUX_STEPS,
140 .integration_cycles = 1,
141 .smux_len = AS7341_SMUX_LEN,
142 .auto_smux = false,
143 .gain_correction_per_band = false,
144 .extra_clear_slot = NO_SLOT,
145};
146#endif
147
148#ifdef USE_AS7343
149static const char AS7343_NAME[] PROGMEM = "AS7343";
150static constexpr uint8_t AS7343_ADC_SLOTS = 18;
151static constexpr uint8_t AS7343_SMUX_LEN = 10;
152static const char TCS3448_NAME[] PROGMEM = "TCS3448";
153// CFG6, FD_CFG0, CFG10, CFG8, CFG20 (auto_smux, 18 channels in 3 cycles), AGC_GAIN_MAX, FD_TIME_1, FD_TIME_2
154static constexpr i2c::I2CRegValue AS7343_INIT[] PROGMEM = {{0xF5, 0x00}, {0xDF, 0xA1}, {0x65, 0xF2}, {0xC9, 0xC8},
155 {0xD6, 0x62}, {0xD7, 0x99}, {0xE0, 0x64}, {0xE2, 0x21}};
156static const uint8_t AS7343_SMUX[] PROGMEM = {0x00, 0x04, 0x65, 0x02, 0x00, 0x05, 0x00, 0x01, 0x00, 0x30,
157 0x00, 0x00, 0x60, 0x20, 0x04, 0x50, 0x03, 0x00, 0x01, 0x05,
158 0x05, 0x00, 0x60, 0x00, 0x30, 0x00, 0x40, 0x10, 0x20, 0x00};
159// Clear is the average of the cycle 1 (slot 4) and cycle 2 (slot 10) readings; cycle 3 always reads 0.
160static const uint8_t AS7343_READOUT[] PROGMEM = {12, 6, 0, 7, 8, 1, 15, 2, 9, 13, 14, 3, 10};
161static_assert(sizeof(AS7343_SMUX) == AS7343_CHAINS * AS7343_SMUX_LEN && AS7343_SMUX_LEN <= MAX_SMUX_LEN);
162static_assert(sizeof(AS7343_READOUT) == NUM_BANDS && AS7343_ADC_SLOTS <= MAX_ADC_SLOTS);
163// clang-format off
164static const uint16_t AS7343_WAVELENGTHS[] PROGMEM = {
165 405, 425, 450, 475, 515, 555, 550, 600, 640, 690, 745, 855, WIDEBAND_NM,
166};
167// clang-format on
168static_assert(sizeof(AS7343_WAVELENGTHS) == NUM_BANDS * sizeof(uint16_t));
169// Datasheet values for the golden device: gain correction per gain step, per band.
170// clang-format off
171static const float AS7343_GAIN_CORRECTION[] PROGMEM = {
172 1.149f, 1.100f, 1.060f, 1.070f, 1.063f, 1.051f, 1.062f, 1.056f, 1.049f, 1.040f, 1.080f, 1.038f, 1.065f, // 0.5x
173 1.090f, 1.128f, 1.064f, 1.071f, 1.063f, 1.050f, 1.068f, 1.055f, 1.047f, 1.039f, 1.075f, 1.038f, 1.085f, // 1x
174 1.083f, 1.086f, 1.062f, 1.070f, 1.062f, 1.049f, 1.057f, 1.053f, 1.045f, 1.038f, 1.063f, 1.037f, 1.069f, // 2x
175 1.059f, 1.068f, 1.056f, 1.066f, 1.058f, 1.046f, 1.051f, 1.051f, 1.044f, 1.036f, 1.059f, 1.035f, 1.053f, // 4x
176 1.100f, 1.109f, 1.096f, 1.108f, 1.099f, 1.089f, 1.091f, 1.092f, 1.082f, 1.078f, 1.100f, 1.076f, 1.088f, // 8x
177 1.099f, 1.109f, 1.096f, 1.108f, 1.099f, 1.089f, 1.091f, 1.092f, 1.082f, 1.078f, 1.100f, 1.075f, 1.087f, // 16x
178 1.088f, 1.096f, 1.085f, 1.097f, 1.087f, 1.078f, 1.079f, 1.080f, 1.071f, 1.067f, 1.087f, 1.064f, 1.076f, // 32x
179 1.083f, 1.091f, 1.078f, 1.090f, 1.079f, 1.072f, 1.072f, 1.073f, 1.064f, 1.062f, 1.080f, 1.057f, 1.069f, // 64x
180 1.076f, 1.084f, 1.072f, 1.085f, 1.074f, 1.066f, 1.062f, 1.067f, 1.055f, 1.056f, 1.074f, 1.051f, 1.061f, // 128x
181 1.067f, 1.074f, 1.063f, 1.075f, 1.064f, 1.059f, 1.055f, 1.058f, 1.049f, 1.051f, 1.064f, 1.044f, 1.053f, // 256x
182 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, 1.000f, // 512x
183 1.033303857f, 1.034763813f, 1.029855013f, 1.036911249f, 0.988150537f, 1.029003501f, 1.021363258f,
184 0.98762089f, 1.021713376f, 1.040108204f, 0.987417698f, 1.019481421f, 0.987270057f, // 1024x
185 0.986859143f, 0.980877221f, 0.9469769f, 0.985535324f, 0.926243961f, 0.959814787f, 1.007963896f,
186 0.942685187f, 1.007630587f, 1.025460005f, 0.928696275f, 1.001296639f, 1.041275263f, // 2048x
187};
188// clang-format on
189static_assert(sizeof(AS7343_GAIN_CORRECTION) == GAIN_COUNT * NUM_BANDS * sizeof(float));
190// clang-format off
191static const ChannelContribution AS7343_CONTRIBUTIONS[] PROGMEM = {
192 {-0.028559089f, 0.450293995f, 0.001266925f}, // F1
193 {-0.042150948f, 3.566379984f, 0.012515925f}, // F2
194 {0.000661721f, 2.877424672f, 0.010243005f}, // FZ
195 {-0.108791278f, 2.273837581f, 0.009376157f}, // F3
196 {-0.167172180f, 1.519298503f, 0.006017556f}, // F4
197 {5.726660294f, 4.199345859f, 0.019357905f}, // FY
198 {0.0f, 0.0f, 0.0f}, // F5
199 {-0.241492014f, 1.185259160f, 0.006516325f}, // FXL
200 {-0.047665296f, 1.759469826f, 0.009780714f}, // F6
201 {-0.012516990f, 1.702006611f, 0.009950228f}, // F7
202 {-0.026424974f, -1.059196137f, -0.005425656f}, // F8
203 {-0.007565221f, -0.064827881f, -0.000232267f}, // NIR
204 {0.0f, 0.0f, 0.0f}, // Clear
205};
206static const ChannelTristimulus AS7343_TRISTIMULUS[] PROGMEM = {
207 {-0.07879f, -0.03269f, -0.31295f}, // F1
208 {-0.12235f, -0.01297f, -0.57885f}, // F2
209 {1.99879f, -0.04011f, 10.00197f}, // FZ
210 {-0.33364f, -0.06889f, -0.31281f}, // F3
211 {-0.06795f, -0.17453f, -0.19657f}, // F4
212 {-0.45419f, 5.69083f, -0.11077f}, // FY
213 {0.0f, 0.0f, 0.0f}, // F5
214 {5.27242f, -0.22956f, -0.06132f}, // FXL
215 {-0.05072f, -0.04762f, -0.03536f}, // F6
216 {-0.04666f, -0.01295f, -0.06025f}, // F7
217 {-0.03931f, -0.02797f, -0.12174f}, // F8
218 {0.0f, 0.0f, 0.0f}, // NIR
219 {0.0f, 0.0f, 0.0f}, // Clear
220};
221// clang-format on
222static_assert(sizeof(AS7343_CONTRIBUTIONS) == NUM_BANDS * sizeof(ChannelContribution));
223static_assert(sizeof(AS7343_TRISTIMULUS) == NUM_BANDS * sizeof(ChannelTristimulus));
224static constexpr ChipInfo as7343_chip(const char *name) {
225 return {
226 .name = name,
227 .init = AS7343_INIT,
228 .smux = AS7343_SMUX,
229 .readout = AS7343_READOUT,
230 .wavelengths = AS7343_WAVELENGTHS,
231 .gain_correction = AS7343_GAIN_CORRECTION,
232 .contributions = AS7343_CONTRIBUTIONS,
233 .tristimulus = AS7343_TRISTIMULUS,
234 .init_count = sizeof(AS7343_INIT) / sizeof(i2c::I2CRegValue),
235 .astep_reg = 0xD4,
236 .cfg0_reg = 0xBF,
237 .cfg1_reg = 0xC6,
238 .status2_reg = 0x90,
239 .id_reg = 0x5A,
240 .id_mask = 0xFF,
241 .id_value = 0x81,
242 .led_reg = 0xCD,
243 .led_sel_reg = 0, // the LED register drives the pin on its own
244 .adc_slots = AS7343_ADC_SLOTS,
245 .smux_steps = 1,
246 .integration_cycles = 3,
247 .smux_len = AS7343_SMUX_LEN,
248 .auto_smux = true,
249 .gain_correction_per_band = true,
250 .extra_clear_slot = 4,
251 };
252}
253const ChipInfo AS7343_CHIP PROGMEM = as7343_chip(AS7343_NAME);
254const ChipInfo TCS3448_CHIP PROGMEM = as7343_chip(TCS3448_NAME); // AS7343 register map, address 0x59
255#endif
256
257// Registers below 0x80 are only reachable with the REG_BANK bit of CFG0 set; CFG0 itself always answers.
258bool AS734XComponent::select_bank_(uint8_t reg) {
259 const bool low = reg < BANK_SPLIT;
260 if (low == this->bank_low_) {
261 return true;
262 }
263 this->bank_low_ = low;
264 return this->write_byte(pgm(this->chip_->cfg0_reg), low ? CFG0_REG_BANK : 0);
265}
266
267bool AS734XComponent::update_bits_(uint8_t reg, uint8_t mask, bool value) {
268 return this->select_bank_(reg) && this->update_register(reg, mask, value ? mask : 0);
269}
270
271// The exposure is applied before every measurement, so a gain, ATIME or ASTEP changed at runtime
272// takes effect on the next reading rather than only after a restart.
273bool AS734XComponent::write_exposure_() {
274 const ChipInfo *chip = this->chip_;
275 if (!this->select_bank_(REG_ATIME) || !this->write_byte(REG_ATIME, this->atime_) ||
276 !this->write_byte_16_le(pgm(chip->astep_reg), this->astep_) ||
277 !this->write_byte(pgm(chip->cfg1_reg), this->gain_)) {
278 return false;
279 }
280 this->reading_gain_ = this->gain_;
281 this->reading_atime_ = this->atime_;
282 this->reading_astep_ = this->astep_;
283 // One integration cycle lasts (ATIME + 1) * (ASTEP + 1) * 2.78 us.
284 const uint32_t cycle_ms = (this->atime_ + 1UL) * (this->astep_ + 1UL) * 139 / 50000;
285 this->integration_ms_ = cycle_ms * pgm(chip->integration_cycles);
286 this->timeout_ms_ = std::max(MIN_COLLECTION_TIMEOUT_MS, 2 * this->integration_ms_);
287 return true;
288}
289
290void AS734XComponent::setup() {
291 const ChipInfo *chip = this->chip_;
292 const uint8_t id_reg = pgm(chip->id_reg);
293 uint8_t id = 0;
294 // The sensor keeps its bank across an MCU reset, so the first access always writes CFG0
295 bool ok = this->select_bank_(REG_ENABLE) && this->write_byte(REG_ENABLE, ENABLE_PON);
296 delayMicroseconds(200); // oscillator start-up
297 ok = ok && this->select_bank_(id_reg) && this->read_byte(id_reg, &id);
298 if (ok && (id & pgm(chip->id_mask)) != pgm(chip->id_value)) {
299 this->mark_failed(LOG_STR("Wrong chip ID"));
300 return;
301 }
302 const i2c::I2CRegValue *init = pgm(chip->init);
303 for (uint8_t i = 0, n = pgm(chip->init_count); ok && i < n; i++) {
304 i2c::I2CRegValue rv;
305 progmem_memcpy(&rv, &init[i], sizeof(rv));
306 ok = this->select_bank_(rv.reg) && this->write_byte(rv.reg, rv.value);
307 }
308 // Everything from here on, including the measurement registers, is in the high bank.
309 ok = ok && this->write_exposure_();
310 if (pgm(chip->auto_smux)) {
311 const uint8_t *smux = pgm(chip->smux);
312 const uint8_t len = pgm(chip->smux_len);
313 for (uint8_t i = 0; ok && i < AS7343_CHAINS * len; i++) {
314 ok = this->write_byte(AS7343_CHAIN_SMUX, progmem_read_byte(&smux[i])) &&
315 this->write_byte(AS7343_CHAIN_CMD, 0x46 + (i / len) * 0x10);
316 }
317 }
318 if (!ok) {
319 this->mark_failed(LOG_STR(ESP_LOG_MSG_COMM_FAIL));
320 return;
321 }
322 this->disable_loop();
323}
324
325void AS734XComponent::dump_config() {
326 const float gain = this->gain_ == GAIN_0_5X ? 0.5f : static_cast<float>(1 << (this->gain_ - 1));
327 ESP_LOGCONFIG(TAG,
328 "AS734x:\n"
329 " Chip: %s\n"
330 " Gain: %gx\n"
331 " ATIME: %u\n"
332 " ASTEP: %u\n"
333 " Glass attenuation factor: %.3f",
334 LOG_STR_ARG(pgm(this->chip_->name)), gain, this->atime_, this->astep_, this->glass_attenuation_factor_);
335 LOG_I2C_DEVICE(this);
336 LOG_UPDATE_INTERVAL(this);
337 for (uint8_t band = 0; band < NUM_BANDS; band++) {
338 char label[24];
339 const char *name = LOG_STR_ARG(BandNames::get_log_str(band, BandNames::LAST_INDEX));
340 snprintf(label, sizeof(label), "Counts %s", name);
341 sensor::log_sensor(TAG, " ", label, this->sensors_[band]);
342 snprintf(label, sizeof(label), "Basic counts %s", name);
343 sensor::log_sensor(TAG, " ", label, this->basic_counts_sensors_[band]);
344 }
345 LOG_SENSOR(" ", "Saturation level", this->saturation_level_sensor_);
346 LOG_SENSOR(" ", "Illuminance", this->illuminance_sensor_);
347 LOG_SENSOR(" ", "Irradiance photopic", this->irradiance_photopic_sensor_);
348 LOG_SENSOR(" ", "Irradiance PAR", this->irradiance_par_sensor_);
349 LOG_SENSOR(" ", "PPFD", this->ppfd_sensor_);
350 LOG_SENSOR(" ", "Color temperature", this->color_temperature_sensor_);
351#ifdef USE_AS734X_RGB
352 LOG_TEXT_SENSOR(" ", "RGB hex", this->rgb_hex_text_sensor_);
353#endif
354}
355
356void AS734XComponent::enable_led(bool enable) {
357 const uint8_t led_reg = pgm(this->chip_->led_reg);
358 if (led_reg == 0) {
359 return;
360 }
361 // The LED register only drives the LED while LED_SEL is set, so the pin is handed over before
362 // switching on and released only after switching off. The other order would leave the LED lit
363 // with nothing able to turn it off.
364 const uint8_t led_sel_reg = pgm(this->chip_->led_sel_reg);
365 bool ok = true;
366 if (enable && led_sel_reg != 0) {
367 ok = this->update_bits_(led_sel_reg, CONFIG_LED_SEL, true);
368 }
369 ok = this->update_bits_(led_reg, LED_ACT, enable) && ok;
370 if (!enable && led_sel_reg != 0) {
371 ok = this->update_bits_(led_sel_reg, CONFIG_LED_SEL, false) && ok;
372 }
373 // The measurement path assumes the high bank, so leave the chip there for a reading in flight
374 ok = this->select_bank_(REG_ENABLE) && ok;
375 if (!ok) {
376 ESP_LOGW(TAG, "Failed to switch the LED");
377 }
378}
379
380void AS734XComponent::update() {
381 if (this->state_ != State::STATE_IDLE) {
382 ESP_LOGW(TAG, "Skipping update, previous measurement still running");
383 return;
384 }
385 if (!this->write_exposure_()) {
386 this->abort_measurement_(LOG_STR("Failed to apply measurement settings"));
387 return;
388 }
389 this->step_ = 0;
390 this->peak_raw_count_ = 0;
391 this->raw_counts_.fill(0);
392 this->enable_loop();
393 if (!this->start_step_()) {
394 this->abort_measurement_(LOG_STR("Failed to start measurement"));
395 }
396}
397
398bool AS734XComponent::start_step_() {
399 this->start_ms_ = App.get_loop_component_start_time();
400 if (pgm(this->chip_->auto_smux)) {
401 this->state_ = State::STATE_READ_DATA;
402 return this->write_byte(REG_ENABLE, ENABLE_PON | ENABLE_SP_EN);
403 }
404 // Load this step's image into SMUX RAM; SMUX_EN copies it to the chain and clears itself when done.
405 std::array<uint8_t, MAX_SMUX_LEN> image{};
406 const uint8_t len = pgm(this->chip_->smux_len);
407 progmem_memcpy(image.data(), pgm(this->chip_->smux) + this->step_ * len, len);
408 this->state_ = State::STATE_WAIT_SMUX;
409 return this->write_byte(AS7341_CFG6, AS7341_SMUX_CMD_WRITE) &&
410 this->write_bytes(AS7341_SMUX_RAM, image.data(), len) &&
411 this->write_byte(REG_ENABLE, ENABLE_PON | ENABLE_SMUX_EN);
412}
413
414void AS734XComponent::loop() {
416 uint8_t value = 0;
417 switch (this->state_) {
418 case State::STATE_WAIT_SMUX:
419 // A failed read counts as busy, so the timeout below catches a chip that stops answering.
420 if (this->read_byte(REG_ENABLE, &value) && !(value & ENABLE_SMUX_EN)) {
421 this->start_ms_ = now;
422 this->state_ = State::STATE_READ_DATA;
423 if (!this->write_byte(REG_ENABLE, ENABLE_PON | ENABLE_SP_EN)) {
424 this->abort_measurement_(LOG_STR("Failed to start integration"));
425 }
426 return;
427 }
428 break;
429 case State::STATE_READ_DATA:
430 if (now - this->start_ms_ < this->integration_ms_) {
431 return;
432 }
433 if (this->read_byte(pgm(this->chip_->status2_reg), &value) && (value & STATUS2_AVALID)) {
434 this->read_step_();
435 return;
436 }
437 break;
438 case State::STATE_IDLE:
439 this->disable_loop();
440 return;
441 }
442 if (now - this->start_ms_ > this->timeout_ms_) {
443 this->abort_measurement_(LOG_STR("Measurement timeout"));
444 }
445}
446
447void AS734XComponent::read_step_() {
448 // Reading ASTATUS latches the data, which is only consistent within one burst starting there.
449 std::array<uint8_t, 1 + 2 * MAX_ADC_SLOTS> frame{};
450 if (!this->read_bytes(REG_ASTATUS, frame.data(), 1 + 2 * pgm(this->chip_->adc_slots)) ||
451 !this->write_byte(REG_ENABLE, ENABLE_PON)) {
452 this->abort_measurement_(LOG_STR("Failed to read channel data"));
453 return;
454 }
455 if (frame[0] & ASTATUS_ASAT) {
456 ESP_LOGV(TAG, "Step %u saturated", this->step_);
457 }
458 auto slot_value = [&frame](uint8_t slot) { return encode_value_le<uint16_t>(&frame[1 + 2 * slot]); };
459 const uint8_t *readout = pgm(this->chip_->readout) + this->step_ * NUM_BANDS;
460 const uint8_t extra_clear = pgm(this->chip_->extra_clear_slot);
461 for (uint8_t band = 0; band < NUM_BANDS; band++) {
462 const uint8_t slot = progmem_read_byte(&readout[band]);
463 if (slot == NO_SLOT) {
464 continue;
465 }
466 const uint16_t raw = slot_value(slot);
467 this->peak_raw_count_ = std::max(this->peak_raw_count_, raw);
468 uint16_t counts = raw;
469 if (band == CLEAR_BAND && extra_clear != NO_SLOT) {
470 const uint16_t extra = slot_value(extra_clear);
471 this->peak_raw_count_ = std::max(this->peak_raw_count_, extra);
472 counts = (static_cast<uint32_t>(raw) + extra) / 2;
473 }
474 this->raw_counts_[band] = counts;
475 }
476 if (++this->step_ < pgm(this->chip_->smux_steps)) {
477 if (!this->start_step_()) {
478 this->abort_measurement_(LOG_STR("Failed to configure SMUX"));
479 }
480 return;
481 }
482 this->publish_measurement_();
483 this->status_clear_warning();
484 this->state_ = State::STATE_IDLE;
485 this->disable_loop();
486}
487
488// A basic count is the raw count scaled to one unit of gain and one millisecond of integration
489// time, which makes readings taken with different settings comparable. The manufacturer's
490// conversion factors are calibrated against that definition.
491void AS734XComponent::calculate_basic_counts_() {
492 this->basic_counts_.fill(0.0f);
493 this->max_basic_count_ = 0.0f;
494 this->max_band_basic_count_ = 0.0f;
495 this->clear_basic_count_ = 0.0f;
496
497 // The gain enum counts in powers of two starting at 0.5x, so the multiplier is 2^gain / 2.
498 const float gain_x = static_cast<float>(1 << this->reading_gain_) / 2.0f;
499 const float integration_ms = (1.0f + this->reading_atime_) * (1.0f + this->reading_astep_) * 2.78e-3f;
500 if (gain_x <= 0.0f || integration_ms <= 0.0f) {
501 return;
502 }
503 const float inv_exposure = 1.0f / (gain_x * integration_ms);
504 const ChipInfo *chip = this->chip_;
505 const uint16_t *wavelengths = pgm(chip->wavelengths);
506 const float *gain_correction = pgm(chip->gain_correction);
507 const bool per_band = pgm(chip->gain_correction_per_band);
508 const uint8_t correction_base = per_band ? this->reading_gain_ * NUM_BANDS : this->reading_gain_;
509
510 for (uint8_t band = 0; band < NUM_BANDS; band++) {
511 const uint16_t wavelength = pgm(wavelengths[band]);
512 if (wavelength == ABSENT_NM) {
513 continue;
514 }
515 float basic_count = this->raw_counts_[band] * inv_exposure;
516 basic_count -= this->dark_current_[band];
517 basic_count = std::max(basic_count, 0.0f);
518 basic_count *= pgm(gain_correction[per_band ? correction_base + band : correction_base]);
519 basic_count *= this->channel_correction_[band];
520 basic_count *= this->glass_attenuation_factor_;
521
522 this->basic_counts_[band] = basic_count;
523 this->max_basic_count_ = std::max(this->max_basic_count_, basic_count);
524 if (wavelength == WIDEBAND_NM) {
525 this->clear_basic_count_ = basic_count;
526 } else if (wavelength >= VISIBLE_MIN_NM && wavelength <= VISIBLE_MAX_NM) {
527 this->max_band_basic_count_ = std::max(this->max_band_basic_count_, basic_count);
528 }
529 }
530}
531
532float AS734XComponent::normalization_divisor_() const {
533 float divisor = 1.0f;
534 switch (this->normalization_) {
536 divisor = this->max_basic_count_;
537 break;
539 divisor = this->max_band_basic_count_;
540 break;
542 divisor = this->clear_basic_count_;
543 break;
545 return 1.0f;
546 }
547 // In the dark the reference can be zero, and dividing by that would publish infinities.
548 return divisor > 0.0f ? divisor : 1.0f;
549}
550
551void AS734XComponent::publish_basic_counts_() {
552 // Normalization describes the shape of the spectrum rather than its absolute level. Channels
553 // outside the chosen reference can exceed 1.0 and are left that way rather than clipped: with
554 // BANDS the near infrared channel legitimately sits well above the visible bands.
555 const float scale = 1.0f / this->normalization_divisor_();
556 for (uint8_t band = 0; band < NUM_BANDS; band++) {
557 PUBLISH_STATE(this->basic_counts_sensors_[band], this->basic_counts_[band] * scale);
558 }
559}
560
561// Each band contributes a fixed amount per basic count to every integrated quantity, so the
562// totals are a weighted sum over the bands.
563// The weighted sums can go negative under light the tables were not fitted for, such as pure blue or
564// far red, so the published values are floored at zero.
565void AS734XComponent::publish_light_metrics_() {
566 float irradiance_photopic = 0.0f;
567 float irradiance_par = 0.0f;
568 float ppfd = 0.0f;
569
570 const ChannelContribution *contributions = pgm(this->chip_->contributions);
571 for (uint8_t band = 0; band < NUM_BANDS; band++) {
572 const float basic_count = this->basic_counts_[band];
573 const ChannelContribution contribution = pgm(contributions[band]);
574
575 irradiance_photopic += contribution.irradiance_photopic * basic_count;
576 irradiance_par += contribution.irradiance_par * basic_count;
577 ppfd += contribution.ppfd * basic_count;
578 }
579 irradiance_photopic = std::max(irradiance_photopic, 0.0f);
580 irradiance_par = std::max(irradiance_par, 0.0f);
581 ppfd = std::max(ppfd, 0.0f) * 1e3f;
582 const float illuminance = irradiance_photopic * LUMENS_PER_WATT;
583
584 ESP_LOGV(TAG, "Photopic irradiance %.4f, PAR %.4f, PPFD %.4f, illuminance %.2f lx", irradiance_photopic,
585 irradiance_par, ppfd, illuminance);
586 PUBLISH_STATE(this->illuminance_sensor_, illuminance);
587 PUBLISH_STATE(this->irradiance_photopic_sensor_, irradiance_photopic);
588 PUBLISH_STATE(this->irradiance_par_sensor_, irradiance_par);
589 PUBLISH_STATE(this->ppfd_sensor_, ppfd);
590}
591
592void AS734XComponent::publish_color_() {
593 float tri_x = 0.0f;
594 float tri_y = 0.0f;
595 float tri_z = 0.0f;
596
597 const ChannelTristimulus *table = pgm(this->chip_->tristimulus);
598 for (uint8_t band = 0; band < NUM_BANDS; band++) {
599 const float basic_count = this->basic_counts_[band];
600 const ChannelTristimulus tristimulus = pgm(table[band]);
601
602 tri_x += tristimulus.x * basic_count;
603 tri_y += tristimulus.y * basic_count;
604 tri_z += tristimulus.z * basic_count;
605 }
606
607 const float color_temperature = tristimulus_to_cct(tri_x, tri_y, tri_z);
608 ESP_LOGV(TAG, "XYZ %.4f, %.4f, %.4f -> CCT %.0f K", tri_x, tri_y, tri_z, color_temperature);
609 PUBLISH_STATE(this->color_temperature_sensor_, color_temperature);
610
611#ifdef USE_AS734X_RGB
612 if (this->rgb_hex_text_sensor_ == nullptr) {
613 return;
614 }
615 // Convert to chromaticity first, so the colour describes the hue rather than the brightness.
616 // Absolute tristimulus values clamp to white under anything but dim light.
617 char rgb_hex[7] = "000000"; // no usable chromaticity reads as black rather than an empty string
618 const float sum = tri_x + tri_y + tri_z;
619 if (sum > MIN_TRISTIMULUS_SUM) {
620 uint8_t rgb[3];
621 tristimulus_to_rgb(tri_x / sum, tri_y / sum, tri_z / sum, rgb[0], rgb[1], rgb[2]);
622 format_hex_to(rgb_hex, rgb, sizeof(rgb));
623 }
624 this->rgb_hex_text_sensor_->publish_state(rgb_hex);
625#endif
626}
627
628void AS734XComponent::publish_measurement_() {
629 this->calculate_basic_counts_();
630 for (uint8_t band = 0; band < NUM_BANDS; band++) {
631 PUBLISH_STATE(this->sensors_[band], this->raw_counts_[band]);
632 }
633 this->publish_basic_counts_();
634 this->publish_light_metrics_();
635 this->publish_color_();
636 if (this->saturation_level_sensor_ != nullptr) {
637 const uint32_t max_adc =
638 std::min<uint32_t>((this->reading_atime_ + 1UL) * (this->reading_astep_ + 1UL), MAX_ADC_COUNT);
639 const float level = max_adc == 0 ? 0.0f : 100.0f * this->peak_raw_count_ / max_adc;
640 ESP_LOGV(TAG, "Highest ADC count %u of %u (%.1f%%)", this->peak_raw_count_, static_cast<unsigned>(max_adc), level);
641 this->saturation_level_sensor_->publish_state(level);
642 }
643}
644
645void AS734XComponent::abort_measurement_(const LogString *reason) {
646 ESP_LOGW(TAG, "%s", LOG_STR_ARG(reason));
647 this->write_byte(REG_ENABLE, ENABLE_PON);
648 this->status_set_warning(reason);
649 this->state_ = State::STATE_IDLE;
650 this->disable_loop();
651}
652
653} // namespace esphome::as734x
uint8_t raw[35]
Definition bl0939.h:0
uint32_t IRAM_ATTR HOT get_loop_component_start_time() const
Get the cached time in milliseconds from when the current component started its loop execution.
void mark_failed()
Mark this component as failed.
void enable_loop()
Enable this component's loop.
Definition component.h:261
void disable_loop()
Disable this component's loop.
void status_clear_warning()
Definition component.h:309
bool write_byte_16_le(uint8_t a_register, uint16_t data) const
Write a 16-bit value least significant byte first.
Definition i2c.cpp:123
bool write_byte(uint8_t a_register, uint8_t data) const
Definition i2c.h:312
bool read_byte(uint8_t a_register, uint8_t *data)
Definition i2c.h:272
I2CRegister reg(uint8_t a_register)
calls the I2CRegister constructor
Definition i2c.h:164
bool write_bytes(uint8_t a_register, const uint8_t *data, uint8_t len) const
Definition i2c.h:298
bool update_register(uint8_t a_register, uint8_t mask, uint8_t value)
Read a register, replace the bits in mask with those of value and write it back.
Definition i2c.cpp:95
bool read_bytes(uint8_t a_register, uint8_t *data, uint8_t len)
Compat APIs All methods below have been added for compatibility reasons.
Definition i2c.h:249
AlsGain501 gain
ESPHOME_LOG_TAG(TAG, "as734x")
const ChipInfo TCS3448_CHIP
void tristimulus_to_rgb(float x, float y, float z, uint8_t &r, uint8_t &g, uint8_t &b)
PROGMEM_STRING_TABLE(BandNames, "F1", "F2", "FZ", "F3", "F4", "FY", "F5", "FXL", "F6", "F7", "F8", "NIR", "Clear")
const ChipInfo AS7341_CHIP
float tristimulus_to_cct(float x, float y, float z)
constexpr float MIN_TRISTIMULUS_SUM
const ChipInfo AS7343_CHIP
FLAG_HAS_TRANSITION float
void log_sensor(const char *tag, const char *prefix, const char *type, Sensor *obj)
Definition sensor.cpp:12
static uint64_t const uint8_t * table
Definition vnc_des.cpp:92
void progmem_memcpy(void *dst, const void *src, size_t len)
Definition hal.h:56
uint32_t value
Definition hal.cpp:41
const void size_t len
Definition hal.h:68
void IRAM_ATTR HOT delayMicroseconds(uint32_t us)
Definition hal.cpp:48
constexpr T encode_value_le(const uint8_t *bytes)
Encode a value from its constituent bytes (from least to most significant) in an array with length si...
Definition helpers.h:1084
char * format_hex_to(char *buffer, size_t buffer_size, const uint8_t *data, size_t length)
Format byte array as lowercase hex to buffer (base implementation).
Definition helpers.cpp:428
Application App
Global storage of Application pointer - only one Application can exist.
uint8_t progmem_read_byte(const uint8_t *addr)
Definition hal.h:51
static void uint32_t
const uint8_t * smux
Definition as734x.h:75
const ChannelTristimulus * tristimulus
Definition as734x.h:80
const char * name
Definition as734x.h:73
const uint8_t * readout
Definition as734x.h:76
const ChannelContribution * contributions
Definition as734x.h:79
One register write for I2CDevice::write_registers(); tables of these may live in PROGMEM.
Definition i2c.h:18