Module sensors_driver

Expand description

The C ABI for the sensor drivers that run over an I2C bus.

A driver runs the datasheet’s whole conversation with a part over a PamojaI2cBus: reset, identify, read the calibration, configure, measure. It holds a share of the bus, so the caller may free its own bus handle straight after building the driver, or keep it to look at the bus between reads. A driver waits as its datasheet asks through the bus’s delay, which sleeps only when real parts are on the other end.

Every part has a simulated twin that answers a driver with nothing plugged in: a _sim_part that reads the datasheet’s typical values and a _sim_reporting that reads whatever it is asked to. Either goes on a simulated bus with pamoja_i2c_bus_attach.

A driver’s failure is PamojaStatus::Io when the bus failed or the part never finished, and PamojaStatus::Codec when a part answered but is not the one the driver expected or its checksum failed, with the reason in the last error message either way.

The DS18B20 is the exception: on a Linux board it is not driven over a bus but read through the files the kernel’s 1-Wire driver serves, which pamoja_ds18b20_thermometer_read does.

Structs§

PamojaAds1115: An ADS1115 driven over an I2C bus. Opaque; release it with pamoja_ads1115_free.
PamojaAds1115Sample: One ADS1115 conversion.
PamojaAds1115Settings: How an ADS1115 driver converts: which input, at which range, how fast.
PamojaBme280: A BME280 driven over an I2C bus. Opaque; release it with pamoja_bme280_free.
PamojaBme280Settings: How a BME280 driver measures: the oversampling of each measurement and the IIR filter.
PamojaBmp280: A BMP280 driven over an I2C bus. Opaque; release it with pamoja_bmp280_free.
PamojaBmp280Settings: How a BMP280 driver measures: the oversampling of each measurement and the IIR filter.
PamojaDs18b20Thermometer: A DS18B20 the Linux kernel serves as a w1_slave file. Opaque; release it with pamoja_ds18b20_thermometer_free.
PamojaDs18b20Thermometers: The DS18B20s the kernel has found, in order of their directory names. Opaque; release it with pamoja_ds18b20_thermometers_free.
PamojaHdc1080: An HDC1080 driven over an I2C bus. Opaque; release it with pamoja_hdc1080_free.
PamojaHdc1080Settings: How an HDC1080 driver measures: the resolution of each channel.
PamojaIna219: An INA219 driven over an I2C bus. Opaque; release it with pamoja_ina219_free.
PamojaIna226: An INA226 driven over an I2C bus. Opaque; release it with pamoja_ina226_free.
PamojaIna219Reading: One INA219 conversion: the four result registers as read, and what they mean.
PamojaIna219Settings: How an INA219 driver measures: the shunt, the current it is sized for, and the register settings.
PamojaIna226Reading: One INA226 conversion: the four result registers as read, and what they mean.
PamojaIna226Settings: How an INA226 driver measures: the shunt, the current it is sized for, and the register settings.
PamojaOpt3001: An OPT3001 driven over an I2C bus. Opaque; release it with pamoja_opt3001_free.
PamojaOpt3001Reading: An OPT3001 illuminance result.
PamojaOpt3001Settings: How an OPT3001 driver measures.
PamojaScd4x: An SCD40 or SCD41 driven over an I2C bus. Opaque; release it with pamoja_scd4x_free.
PamojaSht3x: An SHT3x driven over an I2C bus. Opaque; release it with pamoja_sht3x_free.
PamojaTmp117: A TMP117 driven over an I2C bus. Opaque; release it with pamoja_tmp117_free.
PamojaTmp117Alerts: The TMP117’s alert flags: whether a result since they were last read crossed a limit.
PamojaTmp117Reading: A TMP117 temperature result.

Constants§

PAMOJA_ADS1115_SIM_VOLTS: The voltage a simulated ADS1115 reports unless it is asked for another: half a 3.3 V supply.
PAMOJA_BME280_SIM_STATUS_IDLE: The status a simulated BME280 reports when it is neither measuring nor loading its calibration.
PAMOJA_BMP280_SIM_STATUS_IDLE: The status a simulated BMP280 reports when it is neither measuring nor loading its calibration.
PAMOJA_HDC1080_SIM_CELSIUS: The temperature a simulated HDC1080 reports unless it is asked for another.
PAMOJA_HDC1080_SIM_RELATIVE_HUMIDITY: The relative humidity a simulated HDC1080 reports unless it is asked for another.
PAMOJA_INA219_SIM_BUS_MILLIVOLTS: The bus voltage a simulated INA219 reports unless it is asked for another, in millivolts.
PAMOJA_INA219_SIM_MAX_MICROAMPS: The largest current a simulated INA219 is sized for, in microamps.
PAMOJA_INA219_SIM_MICROAMPS: The current a simulated INA219 reports unless it is asked for another, in microamps.
PAMOJA_INA219_SIM_SHUNT_MILLIOHMS: The shunt a simulated INA219 sits across, in milliohms: the common breakout’s.
PAMOJA_INA226_SIM_BUS_MICROVOLTS: The bus voltage a simulated INA226 reports unless it is asked for another, in microvolts.
PAMOJA_INA226_SIM_MAX_MICROAMPS: The largest current a simulated INA226 is sized for, in microamps.
PAMOJA_INA226_SIM_MICROAMPS: The current a simulated INA226 reports unless it is asked for another, in microamps.
PAMOJA_INA226_SIM_SHUNT_MILLIOHMS: The shunt a simulated INA226 sits across, in milliohms.
PAMOJA_OPT3001_SIM_LUX: The illuminance a simulated OPT3001 reports unless it is asked for another.
PAMOJA_SCD4X_SIM_CELSIUS: The temperature a simulated SCD4x reports unless it is asked for another.
PAMOJA_SCD4X_SIM_CO2_PPM: The carbon dioxide a simulated SCD4x reports unless it is asked for another, in parts per million.
PAMOJA_SCD4X_SIM_RELATIVE_HUMIDITY: The relative humidity a simulated SCD4x reports unless it is asked for another.
PAMOJA_SCD4X_SIM_SERIAL: The serial number every simulated SCD4x reports.
PAMOJA_SHT3X_SIM_CELSIUS: The temperature a simulated SHT3x reports unless it is asked for another.
PAMOJA_SHT3X_SIM_RELATIVE_HUMIDITY: The relative humidity a simulated SHT3x reports unless it is asked for another.
PAMOJA_TMP117_SIM_CELSIUS: The temperature a simulated TMP117 reports unless it is asked for another.

Functions§

pamoja_ads1115_config^⚠: Copies the configuration an ADS1115 driver writes.
pamoja_ads1115_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_ads1115_init^⚠: Writes the input, range, and data rate, and reads the configuration back, which is the identity check a part with no id register allows.
pamoja_ads1115_new^⚠: Creates an ADS1115 driver on a bus. Nothing is sent until pamoja_ads1115_init or the first pamoja_ads1115_sample.
pamoja_ads1115_sample^⚠: Runs one conversion of the configured input, initializing the part first if pamoja_ads1115_init has not run.
pamoja_ads1115_sample_input^⚠: Converts another input once, leaving the configured input as it was.
pamoja_ads1115_settings_default: Returns the settings an ADS1115 driver starts with, the part’s own reset settings: AIN0 against AIN1, the 2.048 V range, and 128 samples per second.
pamoja_ads1115_sim_part: Creates a simulated ADS1115 reading PAMOJA_ADS1115_SIM_VOLTS at the range a driver starts with.
pamoja_ads1115_sim_reporting: Creates a simulated ADS1115 that reads what it is asked to at the range a driver converts at.
pamoja_bme280_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_bme280_init^⚠: Resets the part, checks it is a BME280, reads its calibration, and writes the settings, in the order the datasheet requires, leaving the part asleep.
pamoja_bme280_measure^⚠: Runs one forced measurement and compensates it, initializing the part first if pamoja_bme280_init has not run.
pamoja_bme280_new^⚠: Creates a BME280 driver on a bus. Nothing is sent until pamoja_bme280_init or the first pamoja_bme280_measure.
pamoja_bme280_settings_default: Returns the settings a BME280 driver starts with: every measurement at oversampling x1 and the filter off.
pamoja_bme280_sim_burst^⚠: Copies the one measurement a simulated BME280 holds: the eight data registers a real part read, which compensate to 20.44 C, 848.05 hPa, and 44.65 % against its calibration.
pamoja_bme280_sim_burst_for^⚠: Builds the eight data registers a simulated BME280 holds when it reports a reading.
pamoja_bme280_sim_calibration^⚠: Copies the calibration a simulated BME280 holds: the two blocks a driver reads at start-up.
pamoja_bme280_sim_part: Creates a simulated BME280 holding a real part’s calibration and one measurement it took, which compensate to 20.44 C, 848.05 hPa, and 44.65 %.
pamoja_bme280_sim_reporting: Creates a simulated BME280 that reads what it is asked to.
pamoja_bmp280_coefficients^⚠: Copies the trimming coefficients a BMP280 driver read at initialization.
pamoja_bmp280_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_bmp280_init^⚠: Resets the part, checks it is a BMP280, reads its trimming coefficients, and writes the settings, leaving the part asleep.
pamoja_bmp280_measure^⚠: Runs one forced measurement and compensates it, initializing the part first if pamoja_bmp280_init has not run.
pamoja_bmp280_new^⚠: Creates a BMP280 driver on a bus. Nothing is sent until pamoja_bmp280_init or the first pamoja_bmp280_measure.
pamoja_bmp280_settings_default: Returns the settings a BMP280 driver starts with: both measurements at oversampling x1 and the filter off.
pamoja_bmp280_sim_burst^⚠: Copies the six data registers a simulated BMP280 holds: one measurement a real part took.
pamoja_bmp280_sim_burst_for^⚠: Builds the six data registers a simulated BMP280 holds when it reports a reading.
pamoja_bmp280_sim_calibration^⚠: Copies the 24 trimming bytes a simulated BMP280 holds.
pamoja_bmp280_sim_part: Creates a simulated BMP280 holding a real part’s trimming and one measurement it took, which compensate to 20.44 C and 848.05 hPa.
pamoja_bmp280_sim_reporting: Creates a simulated BMP280 that reads what it is asked to.
pamoja_ds18b20_discover^⚠: Lists every DS18B20 the kernel has found: one per 28- directory.
pamoja_ds18b20_thermometer_at^⚠: Names a DS18B20 by the path of its w1_slave file, for a system that mounts sysfs elsewhere or a test that writes the file itself.
pamoja_ds18b20_thermometer_free^⚠: Releases a thermometer. A null pointer is ignored.
pamoja_ds18b20_thermometer_new^⚠: Names a DS18B20 the kernel serves by the serial in its directory name, reading /sys/bus/w1/devices/28-<serial>/w1_slave.
pamoja_ds18b20_thermometer_path^⚠: Returns the path of the file a thermometer reads.
pamoja_ds18b20_thermometer_read^⚠: Reads a thermometer’s file, which makes the kernel run a conversion, and decodes it.
pamoja_ds18b20_thermometer_serial^⚠: Returns the serial the kernel named a thermometer’s directory after.
pamoja_ds18b20_thermometers_free^⚠: Releases a list of thermometers. A null pointer is ignored.
pamoja_ds18b20_thermometers_get^⚠: Copies one thermometer out of a list.
pamoja_ds18b20_thermometers_len^⚠: Returns how many thermometers a list holds.
pamoja_hdc1080_configuration^⚠: Copies the configuration an HDC1080 driver writes.
pamoja_hdc1080_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_hdc1080_heater^⚠: Switches the on-die heater, which runs only during acquisitions, on or off.
pamoja_hdc1080_init^⚠: Checks the part is an HDC1080 and writes the configuration.
pamoja_hdc1080_measure^⚠: Triggers one acquisition of both channels and reads them, initializing the part first if pamoja_hdc1080_init has not run.
pamoja_hdc1080_new^⚠: Creates an HDC1080 driver on a bus; the part has one address. Nothing is sent until pamoja_hdc1080_init or the first pamoja_hdc1080_measure.
pamoja_hdc1080_settings_default: Returns the settings an HDC1080 driver starts with: both channels at 14 bits.
pamoja_hdc1080_sim_part: Creates a simulated HDC1080 reading PAMOJA_HDC1080_SIM_CELSIUS and PAMOJA_HDC1080_SIM_RELATIVE_HUMIDITY.
pamoja_hdc1080_sim_reporting: Creates a simulated HDC1080 that reads what it is asked to.
pamoja_ina219_calibration_word^⚠: Returns the calibration word an INA219 driver programs.
pamoja_ina219_current_lsb^⚠: Returns the current step an INA219 driver programs.
pamoja_ina219_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_ina219_init^⚠: Resets the part, writes the configuration and the calibration, and reads the calibration back, which is the identity check a part with no id register allows.
pamoja_ina219_measure^⚠: Triggers one shunt and bus conversion and reads every result, initializing the part first if pamoja_ina219_init has not run.
pamoja_ina219_new^⚠: Creates an INA219 driver on a bus. Nothing is sent until pamoja_ina219_init or the first pamoja_ina219_measure.
pamoja_ina219_settings_default: Returns the settings an INA219 driver starts with: a 100 milliohm shunt sized for 3.2 A, the common breakout, the finest current step for it, and the power-on register settings.
pamoja_ina219_sim_part: Creates a simulated INA219 carrying PAMOJA_INA219_SIM_MICROAMPS at PAMOJA_INA219_SIM_BUS_MILLIVOLTS through the shunt a driver starts with.
pamoja_ina219_sim_reporting: Creates a simulated INA219 that reads what it is asked to, calibrated for the same shunt and largest current a driver is given.
pamoja_ina226_calibration_word^⚠: Returns the calibration word an INA226 driver programs.
pamoja_ina226_current_lsb^⚠: Returns the current step an INA226 driver programs.
pamoja_ina226_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_ina226_identity^⚠: Reports the die id an INA226 driver read at initialization.
pamoja_ina226_init^⚠: Resets the part, checks it is an INA226, writes the configuration and the calibration, and reads the calibration back.
pamoja_ina226_measure^⚠: Triggers one shunt and bus conversion and reads every result, initializing the part first if pamoja_ina226_init has not run.
pamoja_ina226_new^⚠: Creates an INA226 driver on a bus. Nothing is sent until pamoja_ina226_init or the first pamoja_ina226_measure.
pamoja_ina226_set_alert^⚠: Programs the alert pin: which limit it watches, and the limit.
pamoja_ina226_settings_default: Returns the settings an INA226 driver starts with: a 100 milliohm shunt sized for 3.2 A, the finest current step for it, and the power-on register settings.
pamoja_ina226_sim_part: Creates a simulated INA226 carrying PAMOJA_INA226_SIM_MICROAMPS at PAMOJA_INA226_SIM_BUS_MICROVOLTS through the shunt a driver starts with.
pamoja_ina226_sim_reporting: Creates a simulated INA226 that reads what it is asked to, calibrated for the same shunt and largest current a driver is given.
pamoja_opt3001_configuration^⚠: Copies the configuration an OPT3001 driver writes, with the part in shutdown.
pamoja_opt3001_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_opt3001_init^⚠: Checks the part is an OPT3001 and writes the settings with the part in shutdown.
pamoja_opt3001_measure^⚠: Runs one conversion and reads the illuminance, initializing the part first if pamoja_opt3001_init has not run.
pamoja_opt3001_new^⚠: Creates an OPT3001 driver on a bus. Nothing is sent until pamoja_opt3001_init or the first pamoja_opt3001_measure.
pamoja_opt3001_set_limits^⚠: Writes the low and high limits the part’s interrupt pin compares each result against.
pamoja_opt3001_settings_default: Returns the settings an OPT3001 driver starts with, the part’s own reset settings: the 800 ms integration time and the range chosen automatically.
pamoja_opt3001_sim_part: Creates a simulated OPT3001 reading PAMOJA_OPT3001_SIM_LUX.
pamoja_opt3001_sim_reporting: Creates a simulated OPT3001 that reads what it is asked to. Its configuration register keeps the flags the part sets for itself, with the conversion-ready flag set.
pamoja_scd4x_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_scd4x_init^⚠: Stops any running measurement, reads the serial number, and starts periodic measurement, after which the part has a new result every five seconds.
pamoja_scd4x_measure^⚠: Waits for the next periodic result and reads it, initializing the part first if pamoja_scd4x_init has not run.
pamoja_scd4x_measure_single_shot^⚠: Runs one on-demand measurement on an SCD41, which takes five seconds. The part must not be measuring periodically: call pamoja_scd4x_stop first, or use this in place of pamoja_scd4x_init.
pamoja_scd4x_new^⚠: Creates an SCD40 or SCD41 driver on a bus; the part has one address. Nothing is sent until pamoja_scd4x_init or the first pamoja_scd4x_measure.
pamoja_scd4x_poll_ready^⚠: Asks the part whether a periodic result is waiting.
pamoja_scd4x_serial^⚠: Reports the serial number an SCD4x driver read at initialization.
pamoja_scd4x_set_sensor_altitude^⚠: Sets the altitude the part corrects its carbon dioxide reading for, stopping periodic measurement to write it and starting it again.
pamoja_scd4x_set_temperature_offset^⚠: Sets the temperature offset that compensates the part’s own warmth, stopping periodic measurement to write it and starting it again. The setting lasts until power is lost.
pamoja_scd4x_sim_part: Creates a simulated SCD4x reading PAMOJA_SCD4X_SIM_CO2_PPM, PAMOJA_SCD4X_SIM_CELSIUS, and PAMOJA_SCD4X_SIM_RELATIVE_HUMIDITY.
pamoja_scd4x_sim_reporting: Creates a simulated SCD4x that reads what it is asked to. It answers the serial number, data-ready, and measurement commands, and always has a result waiting.
pamoja_scd4x_start^⚠: Starts periodic measurement.
pamoja_scd4x_stop^⚠: Stops periodic measurement, after which the part takes its settings commands.
pamoja_sht3x_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_sht3x_heater_off^⚠: Switches the heater off, which is its state after any reset.
pamoja_sht3x_heater_on^⚠: Switches the plausibility-check heater on, initializing the part first if needed, since the reset in initialization switches it off.
pamoja_sht3x_init^⚠: Soft-resets the part and reads its status; a status word whose CRC checks is what confirms an SHT3x answers, as the part has no id register.
pamoja_sht3x_last_status^⚠: Reports the status an SHT3x driver last read, without reading it again.
pamoja_sht3x_measure^⚠: Runs one single-shot measurement, initializing the part first if pamoja_sht3x_init has not run.
pamoja_sht3x_new^⚠: Creates an SHT3x driver on a bus. Nothing is sent until pamoja_sht3x_init or the first pamoja_sht3x_measure.
pamoja_sht3x_read_status^⚠: Reads the status register.
pamoja_sht3x_sim_part: Creates a simulated SHT3x reading PAMOJA_SHT3X_SIM_CELSIUS and PAMOJA_SHT3X_SIM_RELATIVE_HUMIDITY.
pamoja_sht3x_sim_reporting: Creates a simulated SHT3x that reads what it is asked to. It answers every single-shot command, a periodic fetch, and the status command with the replies a real part gives.
pamoja_tmp117_alerts^⚠: Reads the alert flags: whether a result since the last call was above the high limit or below the low limit, including results the driver’s own reads saw.
pamoja_tmp117_free^⚠: Releases a driver and its share of the bus. A null pointer is ignored.
pamoja_tmp117_init^⚠: Checks the part is a TMP117, waits for its EEPROM to finish loading, and writes the settings with the part in shutdown.
pamoja_tmp117_measure^⚠: Runs one conversion and reads the temperature, initializing the part first if pamoja_tmp117_init has not run.
pamoja_tmp117_new^⚠: Creates a TMP117 driver on a bus. Nothing is sent until pamoja_tmp117_init or the first pamoja_tmp117_measure.
pamoja_tmp117_set_alert_limits^⚠: Writes the high and low limits the part compares each result against.
pamoja_tmp117_silicon_revision^⚠: Reports the silicon revision a TMP117 driver read at initialization.
pamoja_tmp117_sim_part: Creates a simulated TMP117 reading PAMOJA_TMP117_SIM_CELSIUS.
pamoja_tmp117_sim_reporting: Creates a simulated TMP117 that reads what it is asked to. Its configuration register keeps the flags the part sets for itself, with the data-ready flag set.