Skip to main content

Custom configuration

What this example shows​

The electrochemical-customConfig.py example builds its own sensor configuration, SENSOR_CUSTOM, instead of using a preset, and prints readings in PPB every 2.5 seconds. As shipped, its values are the same as the SENSOR_O3 ozone preset; this is the place to put your cell's own settings. The sensor is created with no address, so the constructor uses its default, adc_addr=0x49.

The example opens I2C bus 0 with SCL on pin 22 and SDA on pin 21. Change them to the pins your controller's Qwiic connector or your wiring uses.

You do not need to wire LMPEN on this board, whatever the example's comments say: the board holds it low itself.

The example code​

# FILE: electrochemical-customConfig.py
# AUTHOR: Fran Fodor @ Soldered
# BRIEF: Custom LMP91000 configuration example for any electrochemical sensor.
# LAST UPDATED: 2026-05-21

# Connecting diagram:
#
# Qwiic------------------------>Qwiic
# LMPEN------------------------>GPIO pin (see config_pin parameter below)

from machine import I2C, Pin
import time
from ElectrochemicalGasSensor import (
ElectrochemicalGasSensor, SensorConfig,
TIA_GAIN_35_KOHM, RLOAD_10_OHM, REF_EXTERNAL,
INTERNAL_ZERO_67_PERCENT, BIAS_SIGN_NEGATIVE, BIAS_0_PERCENT,
FET_SHORT_DISABLED, OP_MODE_3LEAD_AMP_CELL,
)
from ads1115 import ADS_GAIN_2_048V

# Custom sensor configuration — edit these values to match your sensor's datasheet.
#
# nanoAmperesPerPPM: Sensitivity from the sensor datasheet (nA/PPM)
# internalZeroCalibration: Voltage offset added to zero the reading in clean air
# adsGain: ADS1115 full-scale range (ADS_GAIN_6_144V .. ADS_GAIN_0_256V)
# tia_gain: TIA feedback resistor (TIA_GAIN_2_75_KOHM .. TIA_GAIN_350_KOHM)
# rload: Load resistor (RLOAD_10_OHM .. RLOAD_100_OHM)
# ref_source: Reference voltage source (REF_INTERNAL / REF_EXTERNAL)
# internal_zero: Internal zero percentage (INTERNAL_ZERO_20/50/67_PERCENT or _BYPASSED)
# bias_sign: Bias polarity (BIAS_SIGN_NEGATIVE / BIAS_SIGN_POSITIVE)
# bias: Bias percentage of Vref (BIAS_0_PERCENT .. BIAS_24_PERCENT)
# fet_short: FET short (FET_SHORT_DISABLED / FET_SHORT_ENABLED)
# op_mode: Operating mode (OP_MODE_3LEAD_AMP_CELL for normal operation)
SENSOR_CUSTOM = SensorConfig(
nano_amperes_per_ppm=-1000.0,
internal_zero_calibration=-0.0012,
ads_gain=ADS_GAIN_2_048V,
tia_gain=TIA_GAIN_35_KOHM,
rload=RLOAD_10_OHM,
ref_source=REF_EXTERNAL,
internal_zero=INTERNAL_ZERO_67_PERCENT,
bias_sign=BIAS_SIGN_NEGATIVE,
bias=BIAS_0_PERCENT,
fet_short=FET_SHORT_DISABLED,
op_mode=OP_MODE_3LEAD_AMP_CELL,
)

# Initialize I2C
i2c = I2C(0, scl=Pin(22), sda=Pin(21))

sensor = ElectrochemicalGasSensor(SENSOR_CUSTOM, i2c)

# -------------------------------------------------------------------------
# Setup
# -------------------------------------------------------------------------
print("Electrochemical Gas Sensor - Custom Config Example")

if not sensor.begin():
print("ERROR: Can't init the sensor! Check connections!")
while True:
time.sleep_ms(100)

print("Sensor initialized successfully!")

# -------------------------------------------------------------------------
# Main loop
# -------------------------------------------------------------------------
while True:
reading = sensor.getPPB()

print("Sensor reading: {:.5f} PPB".format(reading))

time.sleep_ms(2500)

🔗Open the complete example

Examples/electrochemical-customConfig.py at commit 623e1e6

→

What this board prints with the example as written has not been measured yet. When this board was tested over Qwiic, an I2C scan found only one address, 0x30, and begin() failed for a sensor created at 0x49, the default this example uses. If begin() fails, the example prints ERROR: Can't init the sensor! Check connections! after its title line and stops there.

When begin() succeeds, the shell shows:

ShellMicroPython
Electrochemical Gas Sensor - Custom Config Example
Sensor initialized successfully!

After that, a line Sensor reading: followed by a value with five decimals and PPB arrives every 2.5 seconds.

Functions used​

SensorConfig(nano_amperes_per_ppm, internal_zero_calibration, ads_gain, tia_gain, rload, ref_source, internal_zero, bias_sign, bias, fet_short, op_mode)returns SensorConfig

Holds the settings for one electrochemical cell: how getPPM() converts the voltage, and what begin() sends to the ADC and the LMP91000. Import it and its constants from ElectrochemicalGasSensor; the ADC gain constants come from ads1115.

ReturnsThe configuration object to pass to the constructor.

Parameters

TypeNameDescription
floatnano_amperes_per_ppmThe cell's sensitivity in nA per PPM.
floatinternal_zero_calibrationA voltage offset added to every reading.
intads_gainThe ADS1115 full-scale range, such as ADS_GAIN_2_048V.
inttia_gainThe LMP91000 TIA gain, TIA_GAIN_2_75_KOHM to TIA_GAIN_350_KOHM, or TIA_GAIN_EXTERNAL.
intrloadThe load resistor, RLOAD_10_OHM to RLOAD_100_OHM.
intref_sourceREF_INTERNAL or REF_EXTERNAL.
intinternal_zeroINTERNAL_ZERO_20_PERCENT, _50_PERCENT, _67_PERCENT or INTERNAL_ZERO_BYPASSED.
intbias_signBIAS_SIGN_NEGATIVE or BIAS_SIGN_POSITIVE.
intbiasThe bias as a share of the reference, BIAS_0_PERCENT to BIAS_24_PERCENT.
intfet_shortFET_SHORT_DISABLED or FET_SHORT_ENABLED.
intop_modeThe operating mode, such as OP_MODE_3LEAD_AMP_CELL.
I2C(id, scl, sda)returns I2C

Creates the I2C bus object from MicroPython's machine module, which the sensor object uses. The example uses bus 0 with SCL on Pin(22) and SDA on Pin(21). I2C and Pin come with MicroPython and are not part of this library.

ReturnsThe I2C bus object.

Parameters

TypeNameDescription
intidThe hardware I2C bus, 0 in the example.
PinsclThe clock pin, Pin(22) in the example.
PinsdaThe data pin, Pin(21) in the example.
ElectrochemicalGasSensor(sensor_type, i2c=None, adc_addr=0x49, config_pin=None)returns ElectrochemicalGasSensor

Creates the sensor object. Nothing is sent to the board until you call begin(). The example passes SENSOR_CUSTOM and the bus, and leaves adc_addr and config_pin at their defaults.

ReturnsThe sensor object.

Parameters

TypeNameDescription
SensorConfigsensor_typeThe configuration to use, SENSOR_CUSTOM in the example.
I2Ci2cThe bus to use. When left out, the module picks pins only on boards it recognises (ESP32: bus 0, SCL 22, SDA 21; ESP8266: SCL 5, SDA 4) and raises an exception otherwise.
intadc_addrThe address the module talks to, 0x49 by default, as in this example. An address from 0x30 to 0x37 makes begin() use the bridge commands; any other address is taken as the ADS1115's own address.
intconfig_pinA GPIO pin the module holds high and pulls low while it writes the LMP91000 settings. None by default; not used for an address from 0x30 to 0x37.
sensor.begin()returns bool

Configures the ADC and the LMP91000 from the sensor configuration. For an adc_addr from 0x30 to 0x37 it checks that the board's bridge answers and sends it the ADC gain, the slowest ADC data rate and the LMP91000 settings, retrying each command for up to 500 ms. For any other address it sets up the ADS1115 at that address with the same gain and data rate and writes the LMP91000 settings directly, pulling config_pin low while it does when one is given.

ReturnsTrue when every step succeeded, False otherwise.

sensor.getPPB()returns float

Takes one reading and returns it in parts per billion: the getPPM() value multiplied by 1000. getPPM() subtracts the internal zero (a share of the board's 2.5 V reference), adds internal_zero_calibration, divides by the TIA gain and by nano_amperes_per_ppm, and returns 0.0 for a negative result.

ReturnsThe concentration in PPB.

Putting it together​

The values in the listing's SENSOR_CUSTOM are the example's own placeholders, not settings for this board's SGX-4OX-ROHS oxygen cell. Its bias=BIAS_0_PERCENT applies no bias, and the cell needs one, so change the configuration before you use it with this board:

  • The cell needs a −600 mV bias. With the board's 2.5 V reference, that is bias_sign=BIAS_SIGN_NEGATIVE with bias=BIAS_24_PERCENT (24% of 2.5 V is 0.6 V). Import BIAS_24_PERCENT in place of BIAS_0_PERCENT.
  • Keep ref_source=REF_EXTERNAL: the board has a 2.5 V external reference.
  • The cell's output in air is 0.1 ± 0.03 mA, and its output is logarithmic, S = K ln(1/(1-C)), so the module's linear PPM calculation does not convert it to % vol directly.

After power-up the cell can take up to 15 minutes to settle, so let it run before you trust a reading.