Device Control¶

This tutorial shows how to control a Senxor device by reading and writing configuration fields.

1. Connect to the device¶

See the Connect Device tutorial for how to connect to the device.

from senxor import connect, list_senxor

devices = list_senxor("serial")
if not devices:
    raise ValueError("No devices found")

dev = connect(devices[0])

2. Read a field¶

Use dev.fields to access configuration fields. .get() returns the raw integer value; .display gives a human-readable string when available.

dev.fields.EMISSIVITY.get()

Output: 56

dev.fields.EMISSIVITY.display

Output: '56%'

dev.fields.MCU_TYPE.get(), dev.fields.MCU_TYPE.display

Output: (3, 'MI48G')

You can also use subscript: dev.fields["EMISSIVITY"].get().

3. Configure a field¶

Use .set(value) to write a field. Values are validated by the library.

dev.fields.FRAME_RATE_DIVIDER.set(1)
dev.fields.FRAME_RATE_DIVIDER.get()

Output: 1

dev.fields.EMISSIVITY.set(98)
dev.fields.EMISSIVITY.display

Output: '98%'

4. Discover and understand fields¶

Each field has .description (short) and .help (detailed). You can iterate over all fields or look up by name.

print(dev.fields.EMISSIVITY.description)
print(dev.fields.FRAME_RATE_DIVIDER.help)

for field in dev.fields:
    print(field.name, field.address)

To inspect field definitions without a device, use the static class:

from senxor.regmap import Fields
print(Fields.EMISSIVITY.description)
print(Fields.FRAME_RATE_DIVIDER.help)

5. Cache and refresh¶

.get() uses a cached value when possible; for fields that change on the device (e.g. status bits), the value is read from the device when needed. To refresh all register and field caches in one go, call dev.refresh_all().

To read the current cache without triggering I/O:

dev.regs.cache
dev.fields.cache
dev.fields.cache_display

cache holds raw integer values; cache_display holds the same values as shown by .display.

6. Registers (low-level)¶

Registers are 8-bit values at fixed addresses; fields are bits or bit-ranges inside those registers. You access registers via dev.regs. Reading or writing registers directly requires understanding the hardware (register map, bit layout). Prefer fields (sections 2–4) for configuration when possible.

Access by name¶

Like fields, each register has .description, .get(), .read(), and .set(value). You can use the register name or subscript: dev.regs["FRAME_MODE"] or dev.regs.FRAME_MODE.

print(dev.regs.FRAME_MODE.description)
dev.regs.FRAME_MODE.get()
dev.regs.FRAME_MODE.read()
dev.regs.FRAME_MODE.set(0x02)

Read/write by address¶

When you know the register address (0x00–0xFF), use:

dev.regs.read_reg(0xB1)
dev.regs.write_reg(0xB1, 0x02)

To read multiple registers in one round-trip:

dev.regs.read_regs([0xB1, 0xB2, 0xCA])

Returns a dict mapping address to value. Writes still go one register at a time via write_reg(addr, value).

7. Helper functions¶

The library provides helper methods on the device for the most common settings. They wrap the underlying fields and return or accept convenient types (e.g. float for emissivity, bool for filter enable). All of the following are called on dev (e.g. dev.get_emissivity()).

Device info (read-only)¶

Method	Description
`get_shape()`	Returns the frame shape `(height, width)`.
`get_fw_version()`	Returns the firmware version string (e.g. `"4.5.12"`).
`get_senxor_type()`	Returns the Senxor type as a string.
`get_module_type()`	Returns the module type as a string.
`get_mcu_type()`	Returns the MCU type as a string.
`get_module_name()`	Returns the module name: `"Cougar"`, `"Panther"`, or `"Cheetah"`.
`get_production_year()`	Returns the production year (e.g. 2024).
`get_production_week()`	Returns the production week (1–52).
`get_manuf_location()`	Returns the manufacturing location code.
`get_serial_number()`	Returns the serial number as an integer.
`get_sn()`	Returns the full SN code as a hex string (format `YYWWLLSSSSSS`).

Frame rate¶

Method	Description
`get_frame_rate_divider()`	Returns the current frame rate divider.
`set_frame_rate_divider(divider)`	Sets the frame rate divider.

Gain¶

Method	Description
`get_module_gain()`	Returns the module gain as a string (e.g. `"1.0"`, `"auto"`, `"0.25"`, `"0.5"`).
`set_module_gain(gain)`	Sets the module gain (0–3).

Temperature correction¶

Method	Description
`get_sensitivity()`	Returns the sensitivity correction factor (float).
`set_sensitivity(value)`	Sets the sensitivity correction factor.
`get_emissivity()`	Returns the emissivity as a float (e.g. 0.56 for 56%).
`set_emissivity(value)`	Sets the emissivity.
`get_offset()`	Returns the temperature offset correction (K or °C).
`set_offset(value)`	Sets the temperature offset correction.
`get_otf()`	Returns the OTF (optical transfer) correction factor.
`set_otf(value)`	Sets the OTF correction factor.

Filters¶

Method	Description
`disable_all_filters()`	Disables all onboard filters (STARK, MMS KXMS, MMS RA, Median, Temporal).
`get_filters_status()`	Returns a dict of whether each filter is available and enabled.
`get_stark_enable()`	Returns whether the STARK filter is available and enabled.
`set_stark_enable(enabled)`	Enables or disables the STARK filter.
`get_mms_kxms_enable()`	Returns whether the MMS KXMS filter is available and enabled.
`set_mms_kxms_enable(enabled)`	Enables or disables the MMS KXMS filter.
`get_mms_ra_enable()`	Returns whether the MMS RA filter is available and enabled.
`set_mms_ra_enable(enabled)`	Enables or disables the MMS RA filter.
`get_median_enable()`	Returns whether the median filter is available and enabled.
`set_median_enable(enabled)`	Enables or disables the median filter.
`get_temporal_enable()`	Returns whether the temporal filter is available and enabled.
`set_temporal_enable(enabled)`	Enables or disables the temporal filter.

Data output¶

Method	Description
`get_adc_enabled()`	Returns whether raw ADC data output is enabled.
`set_adc_enabled(enabled)`	Enables or disables raw ADC data output.

For full register and field definitions, see the API Reference.

8. Thread safety¶

pysenxor-lite is designed to be thread-safe, you can read and set fields from multiple threads concurrently. Note that the actual communication with the device is still synchronous, which means each operation will wait for the device to complete the latest operation before proceeding.