Reference

sensortap documentation

Every CLI command and flag, the whole Python API, every schema field and enum value, the sensor‑id grammar, the consent and streaming models, the complete error table, and the adapter interface. Every value here is taken from the shipped source, not from an example.

Overview#

sensortap discovers every sensor a computer can reach and exposes raw readings through one API. One registry loads many independent adapters; no adapter knows about any other. Every sensor, whatever its backend, reports the same shape: a stable id, a kind from a closed vocabulary, a unit, a sampling rate, and whether it is currently reachable.

Nothing in the core branches on the operating system. All platform variance lives inside adapters, so the public surface is identical everywhere.

Install#

$ pip install sensortap

Covers camera, microphone, motion, orientation, light, battery, radio, and touchpad sensors, with no extra downloads.

Hardware-monitor sensors (per-core CPU load, temperatures, voltages, power, clock speeds) need the optional extra, which pulls in a bundled self-contained .NET helper of a few dozen megabytes:

$ pip install "sensortap[hwmon]"

Development install#

$ pip install -e ".[dev]"
$ pytest

Concepts#

Sensor ids#

Exactly three dot-separated segments:

<kind>.<source-qualifier>.<instance-qualifier>

temp.hwmon.2aed4545974396bc
accel.winrt.0
radio-signal.win-radio.0

• kind is a member of the closed kind vocabulary.
• source-qualifier identifies the reporting backend, for example hwmon, winrt, win-radio, reference. It is not required to equal the adapter's own adapter_id.
• instance-qualifier is a stable per-device value. Adapters derive it by hashing a persistent hardware identifier (BLAKE2b, 8-byte digest, 16 lowercase hex characters, unsalted so ids reproduce across runs and machines for the same hardware), or use a run-invariant fallback index when no persistent identifier exists. It is never a bus-probe-order index.

CLI#

sensortap [global-options] <command> [command-arguments] [global-options]

Global options are accepted both before and after the subcommand: sensortap --json list and sensortap list --json are equivalent.

list#

Enumerate every discovered sensor, followed by per-adapter status lines and a summary line. Takes no positional arguments.

$ sensortap list
$ sensortap list --json
$ sensortap list --include-elevated --include-motherboard

read#

Read one sensor once.

$ sensortap read temp.hwmon.2aed4545974396bc
$ sensortap read microphone.winrt.0 --consent microphone.winrt.0

Rejected with exit code 4 for a buffer-dtype sensor; use stream instead. The command is bounded at 10 seconds regardless of adapter behaviour, after which it exits with code 6.

stream#

Stream one sensor continuously, one line per block, flushed as it arrives.

$ sensortap stream microphone.reference.0 \
    --consent microphone.reference.0 --duration 10

Runs until the duration elapses, the stream ends, or the process is interrupted. Requires the owning adapter to implement streaming; otherwise exits with code 4.

inspect#

Print the full SensorInfo record for one sensor, every field included.

$ sensortap inspect accel.reference.0
$ sensortap inspect accel.reference.0 --json

Exits with code 3 if the id is not in the current enumeration.

doctor#

Run the shipped conformance check against every adapter that loaded on this machine, and report the result. Takes no positional arguments.

$ sensortap doctor
$ sensortap doctor --include-elevated
$ sensortap doctor --json

The test suite can only prove the adapter contract holds for hardware the maintainer owns. doctor moves that same check to your machine, where the hardware actually is. Several shipped defects were structurally present on every machine but only observable on one carrying the relevant sensor, so this is the intended first step for any bug report.

Each adapter is run through the five checks in the conformance check: schema compliance of discovered records, Sensor_Id stability across consecutive discover() calls, reachability of every discovered sensor through read() or open_stream(), adapter-level error behaviour, and the declared read-only obligation.

environment
  sensortap: 0.1.0
  python: 3.12.10
  platform: Windows-10-10.0.19045-SP0
  machine: AMD64
  elevated: True

adapters
  [ok  ] winrt_motion
  [ok  ] winrt_audio
  [FAIL] winrt_light
           adapter-level error behaviour: read() returned a Reading for a
           sensor_id this adapter does not own

9/10 adapters passed  failed: 1

On failure the plain-text output appends a GitHub issue URL with title and body already filled in from the run. The environment block reports version, Python version, platform string, machine architecture and elevation state, and deliberately carries no hostname, no username and no sensor ids, because it is built to be pasted in public.

--json emits:

Exits 0 when every adapter passes and 7 when any adapter fails. Code 7 is deliberately distinct from the generic 1: "sensortap itself broke" and "sensortap works and found a real contract violation on your hardware" are different outcomes, and CI needs to tell them apart.

Global options#

Invoking sensortap with no command, or an unrecognised one, prints usage naming all four commands and exits with code 2.

Admin rights change what the hardware monitor sees#

sensortap list surfaces this: when hwmon_bridge loaded and the current process is not elevated, the plain-text output prints a note after the summary line, and --json's summary.elevated field reports the same fact structurally. sensortap never requests elevation itself and never triggers a UAC prompt; re-running from an elevated terminal is the user's call.

The motherboard opt-in#

--include-motherboard enables motherboard, Super-IO and embedded-controller monitoring in the bundled hardware-monitor helper. It typically adds board temperatures, fan tachometers, and extra voltage rails.

Sensors that appear only under this flag carry hwmon-mb as their source qualifier instead of hwmon, so an id records which capability set produced it.

On a machine with no Ring 0 driver present and no recognised Super-IO chip, the flag is safe and finds nothing extra. Desktop boards with a standard Nuvoton or ITE chip usually have more to report than laptops.

Environment variables#

Python API#

A single lazily-created Registry backs the module-level functions. Importing sensortap has no side effects: no adapters load, no setup() runs, and no helper process spawns until one of these is first called. Teardown is registered with atexit and runs exactly once per adapter.

import sensortap

# enumerate, opens nothing, prompts nothing
sensors = sensortap.list_sensors()

# read a sensor that needs no consent
reading = sensortap.read("temp.hwmon.2aed4545974396bc")
print(reading.values, reading.status)

# a privacy-sensitive sensor needs an explicit grant
with sensortap.consent(["microphone.winrt.0"]):
    for block in sensortap.stream("microphone.winrt.0"):
        ...

list_sensors()#

list_sensors(*, kind=None, source=None, id=None) -> list[SensorInfo]

Run discovery across every loaded adapter concurrently and return the de-duplicated, validated, ordered records.

Filters are conjunctive and exact; nothing matching returns an empty list. Never opens a device and never triggers an operating-system permission prompt, including for camera and microphone sensors. Ordering is deterministic: by adapter load order, then ascending id within an adapter.

read()#

read(sensor_id: str) -> Reading

Read one sensor once. Order of checks, each of which happens before any adapter is invoked: grammar validation, existence against the most recent enumeration, consent, then dtype. Adapter errors are not swallowed; they propagate unchanged.

Enumerate before you read. "The most recent enumeration" means there has to be one. read() never discovers implicitly — that would hide a concurrent sweep of every adapter, under a multi-second timeout, inside what looks like a single-sensor call. So on a fresh process call list_sensors() first; a bare read() raises UnknownSensorError for an id that genuinely exists. The CLI enumerates for you, which is why sensortap read <id> works as a one-liner and the Python equivalent needs two.

Raises MalformedSensorIdError, UnknownSensorError, ConsentError, or BlockPathRequiredError. A rejected read never consumes a seq value.

stream()#

stream(sensor_id, *, block_size=None, rate_hz=None, buffer_blocks=64) -> Stream

These are the only two acquisition parameters anywhere in the interface. There is no **kwargs, so no additional configuration key can be smuggled through. Raises UnsupportedOperationError if the owning adapter does not implement streaming; that adapter's other sensors remain readable through read().

consent()#

consent(sensor_ids) -> ConsentGrant

Create a grant covering exactly the named sensor ids. See Consent.

backend_status()#

backend_status() -> list[BackendStatus]

Return the current per-adapter status records. Performs no I/O and no adapter interaction, so it answers immediately even before any enumeration has run.

Registry#

Construct one directly for isolation from the module-level singleton. Separate instances never share consent state.

from sensortap import Registry

registry = Registry(
    discovery_timeout_ms=5000,
    include_elevated=False,
    audit_hook=None,
)

Methods: list_sensors, read, stream, consent, backend_status, and shutdown.

shutdown() calls teardown() on every loaded adapter exactly once, catching and recording rather than re-raising any exception so one failing teardown cannot stop the rest. It is idempotent and also registered with atexit. An adapter whose discover() times out contributes no records for that round; it is not an error and does not raise.

Schema types#

SensorInfo#

Frozen and slotted. Records are shared across threads during concurrent enumeration, so immutability removes any question of a consumer mutating a record the registry still holds.

Reading#

Concurrent readers of one sensor always receive distinct seq values, and t_mono is clamped forward if an adapter ever reports a non-increasing clock.

RateSpec#

A requested rate outside min..max raises RateOutOfRangeError. When supported is non-empty and the request is not a member, the nearest supported rate by absolute distance is used, with exact ties resolving to the lower rate.

Enums#

All four are StrEnum, so they compare and serialize as plain strings, and the value sets are identical across platforms by construction.

Dtype

Delivery

Availability

Status

Vocabularies#

Kind vocabulary#

Closed, 24 members. Adding a kind is a MINOR schema bump; removing or re-meaning one is MAJOR. An adapter needing a kind outside this set must land a one-line vocabulary change alongside its adapter file. The friction is deliberate: an open vocabulary would make cross-platform kind filtering meaningless.

accel              gyro               magn               incline
orientation        hinge-angle        light              proximity
temp               fan                voltage            current
power              clock              load               battery
camera             microphone         touchpad           touchscreen
keystroke-timing   radio-signal       humidity           pressure

Unit vocabulary#

unit is validated as a well-formed token of at most 32 characters, not as a semantic UCUM expression. Adapters shipped with sensortap emit only:

degC   V   A   W   Hz   m/s2   deg/s   uT   lx   deg   %   mW.h   rpm

Fan speed is pinned to rpm once in the schema so no adapter picks its own spelling.

Consent#

Camera, microphone, and touchpad capacitive-image sensors are privacy-sensitive: their SensorInfo.requires_consent is True.

import sensortap

with sensortap.consent(["microphone.winrt.0"]) as grant:
    for block in sensortap.stream("microphone.winrt.0"):
        ...
# grant ended, every device opened under it closed

ConsentGrant exposes sensor_ids, revoke(), register_open_device(), and the context-manager protocol.

Audit events#

Every grant creation, use, denial, and end emits an AuditEvent to the audit_hook passed to Registry.

The type carries no values field, so a reading cannot leak into the audit trail. An exception raised by the hook is swallowed rather than propagated.

Streaming#

Stream is both an iterator and a context manager. A fixed-capacity ring buffer sits between a background producer thread and the consumer.

import sensortap

with sensortap.stream("microphone.winrt.0", buffer_blocks=128) as s:
    for block in s:
        print(block.seq, block.status, len(block.values))
        if s.discarded_blocks:
            break

While the buffer is empty and the stream is open, iteration blocks until a block arrives. Once the producer stops and the buffer drains, iteration raises StopIteration. Iterating an explicitly closed stream raises ClosedStreamError.

Resources are released by close(), by garbage collection through weakref.finalize if the stream is dropped without closing, or by an atexit backstop. Some backends permit only one concurrent stream per sensor; a second request raises StreamBusyError and leaves the existing stream open and unaffected.

Backend status#

backend_status() returns one BackendStatus per adapter, maintained continuously rather than computed on demand.

NotLoadedReason is a closed set: unsupported_platform, missing_dependency, load_error, elevation_required, not_opted_in.

Loaded-with-zero-sensors is state="loaded" with discovered_count=0, which never collapses into a not_loaded record: reason is meaningful only when state is not_loaded.

Errors and exit codes#

All exceptions derive from SensortapError, so one except clause catches everything. Each carries structured fields, so no caller needs to parse a message string.

from sensortap.registry.errors import SensortapError, UnknownSensorError

Exit codes#

Frozen; part of the CLI's contract.

Exception reference#

Shipped adapters#

Nine Windows adapters, all run against real hardware.

Helper process security#

hwmon_bridge spawns a child process and speaks newline-delimited JSON over a named pipe. Python is the pipe server; the helper is the client.

• The pipe carries a per-user security descriptor and rejects remote clients.
• A single-use launch token is delivered over the child's stdin, never on the command line.
• The helper's first message must be exactly HELLO <token>, compared in constant time.
• The connecting process id is verified against the spawned child's.
• Any authentication failure closes the pipe and terminates the child immediately, with no retry.
• Total readiness budget is 10 seconds. Failure marks the adapter unavailable rather than raising, so every other adapter still enumerates.

sensortap never installs, registers, or starts a kernel driver.

Writing an adapter#

One sensor family is one file, registered through a standard Python entry point. No edit to sensortap's own source is needed.

[project.entry-points."sensortap.adapters"]
my_widget = "my_package.adapter:MyWidgetAdapter"

The interface is a typing.Protocol, so structural typing applies and your class needs no import-time dependency on a sensortap base class.

AdapterMeta#

Declared as a class variable. The registry reads it without instantiating your class, so the platform and version gates cost no side effects.

Required methods#

Optional methods#

A missing optional method is not a load-time error. The registry raises UnsupportedOperationError only when a caller actually invokes that operation, and the adapter's other sensors stay readable through read().

StreamSource#

Buffering, discard-on-backpressure, and the iterator surface belong to the registry's Stream, not to your adapter.

Conformance check#

A reusable check ships inside the package, so you can validate your adapter against the same rules the nine Windows adapters were checked against, with no access to sensortap's repository:

$ python -m sensortap.adapters.conformance my_package.adapter:MyWidgetAdapter

Exits 0 when the report passes, 1 when it fails, 2 on a usage or construction error.

It runs five checks: schema compliance of discovered records, Sensor_Id stability across consecutive discover() calls, reachability of every discovered sensor through read() or open_stream(), adapter-level error behaviour, and the declared read-only obligation. sensortap doctor runs the same check against every adapter loaded on the current machine.

Load sequence#

1. Entry points are discovered and sorted by (distribution_name, entry_point_name) for a deterministic load order.
2. AdapterMeta is read off the class without instantiating it.
3. A platform or interface-MAJOR mismatch is a skip, not a failure.
4. An adapter requiring elevation opt-in is skipped unless the caller opted in.
5. Import, instantiation, and setup() are bounded at 5000 ms in total. An overrun or raise is recorded as a load failure, retained for the process lifetime, and iteration continues with the remaining adapters.
6. An adapter whose read_only_declared is not True is refused.

One bad adapter never aborts loading the rest.

Post-collection pipeline#

Records returned by discover() pass through six ordered steps:

1. Validate every record. An invalid record is dropped individually; that adapter's other records survive.
2. De-duplicate on byte-for-byte id equality only. No fuzzy matching.
3. Resolve conflicts between different adapters reporting the same id, by declared priority, ties going to the first loaded. The winner's source lists every reporting adapter.
4. Disambiguate collisions where one adapter reports the same id for genuinely distinct sensors, by appending a suffix. Every sensor is kept.
5. Order by adapter load order, then ascending id.
6. Filter on kind, source, and id.

Guarantees and limits#

Guaranteed#

• Importing sensortap loads no adapters and spawns no processes.
• Enumeration never opens a device or triggers a permission prompt.
• Reading a camera, microphone, or touchpad capacitive image requires an explicit per-id consent grant. Grants live in memory only.
• No kernel driver is ever installed, registered, or started.
• The interface defines no actuation path: no method transmits a setpoint, control value, or firmware payload. Acquisition configuration is limited to sampling rate and block size.
• Sensor ids are stable across runs on unchanged hardware.
• t_mono never decreases for a sensor, and concurrent readers get distinct seq values.
• One adapter's failure, timeout, or exception never prevents other adapters from loading or enumerating.
• The public API is identical on every platform. Nothing in the core branches on the operating system.
• Every enum value set is identical across platforms.

Not guaranteed, or not built#

• Linux. The registry and adapter interface are already platform-neutral and nothing in the core imports anything Windows-specific, but no Linux backend exists yet. This is the clearest open contribution: sysfs hwmon, IIO, V4L2, ALSA, evdev, one file per family.
• A sensor's existence. A WinRT class the operating system does not expose reports absent rather than guessing whether the physical chip is there, since a wrong reading is harder to debug than a missing one.
• read_only_declared enforcement. It is a declaration the registry requires, not a property it can verify inside an adapter's internals.
• Unit semantics. unit is validated as a token, not as a UCUM expression.
• Motherboard and EC sensors. Available only under an explicit opt-in, and absent entirely where no Ring 0 driver is already present or no Super-IO chip is recognised.
• Adoption figures. None exist to quote, and none are invented.
• A touchpad's maximum contact count. Touchpad presence is detected from the HID usage tables — usage page 0x0D (Digitizer), usage 0x05 (Touch Pad) — which is vendor-neutral and separates a touchpad from a touchscreen (0x04) or a pen (0x02). A maximum-contacts figure lives in the HID report descriptor, and parsing it requires opening the device, which discover() never does. Where WinRT's PointerDevice does not also surface the touchpad, touchpad.win-ptp.0 is present while touchpad.win-contacts.0 is absent: the touchpad exists and its contact count is not obtainable without acquisition.
• Correct behaviour on hardware the maintainer does not own. Adapters are written against the schema contract and the test suite proves it holds for the hardware available. It cannot prove anything about hardware it has never seen. sensortap doctor exists so the check runs where the hardware is.