sensecap-lorawan 0.1.0__tar.gz

sensecap_lorawan-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: sensecap-lorawan
+Version: 0.1.0
+Summary: SenseCAP LoRaWAN device models and command-line reader
+Author: Paulus Schoutsen
+Author-email: Paulus Schoutsen <balloob@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Dist: lorawan-connection>=0.14.0,<0.15
+Requires-Dist: lorawan-connection[chirpstack]>=0.14.0,<0.15 ; extra == 'chirpstack'
+Requires-Dist: lorawan-connection[tts]>=0.14.0,<0.15 ; extra == 'tts'
+Requires-Python: >=3.12
+Project-URL: Issues, https://github.com/balloob/sensecap-lorawan/issues
+Project-URL: Repository, https://github.com/balloob/sensecap-lorawan
+Provides-Extra: chirpstack
+Provides-Extra: tts
+Description-Content-Type: text/markdown
+
+# SenseCAP LoRaWAN
+
+Read SenseCAP sensors through ChirpStack or The Things Stack using
+[`lorawan-connection`](https://github.com/home-assistant-libs/lorawan-connection).
+
+| Model | Readings | Automatic discovery |
+| --- | --- | --- |
+| S2100 | Data logger input channels | ChirpStack, TTS |
+| S2101 | Air temperature, humidity | ChirpStack, TTS |
+| S2102 | Light intensity | ChirpStack, TTS |
+| S2103 | Air temperature, humidity, CO₂ | ChirpStack, TTS |
+| S2104 | Soil temperature, moisture | ChirpStack, TTS |
+| S2105 | Soil temperature, moisture, conductivity | ChirpStack, TTS |
+| S2106 | Temperature, pH | ChirpStack |
+| S2107 | Three temperature probes, including buffered readings | ChirpStack |
+| S2120 | Temperature, humidity, light, UV, wind, pressure, rainfall | ChirpStack, TTS |
+| A1101 | Vision AI measurements | ChirpStack |
+| A1102 | Vision detections and digital meter readings | Explicit Python use |
+| T1000 A/B | Position, temperature, light, motion, Wi-Fi/BLE scans | ChirpStack, TTS |
+| T1000-E | Position, temperature, light, acceleration, Wi-Fi/BLE scans | Explicit Python use |
+| T2000 A/B/C | Position, acceleration, motion, Wi-Fi/BLE scans | ChirpStack, TTS |
+| WM1110 | GNSS fragments, Wi-Fi/BLE scans, environmental and custom readings | Explicit Python use |
+| Gen1 sensors | Air temperature/humidity, CO₂, light, pressure, soil temperature/moisture | TTS |
+
+Coverage follows every device family in Seeed's
+[SenseCAP-Decoder](https://github.com/Seeed-Solution/SenseCAP-Decoder/tree/d0a234205fb9574dd03abd49561b60c243c0d1e3).
+The A1102, T1000-E, and WM1110 classes have no automatic discovery identifiers:
+they are absent from the SenseCAP catalogs checked for this release. Use their
+`decode()` methods directly, or subclass them with your deployment's model identity.
+
+Tracker support requires SenseCAP LoRaWAN firmware. Meshtastic firmware and
+T1000 Mapper payloads are outside this decoder set. Wi-Fi/BLE scans and GNSS
+fragments remain scan data; the library does not resolve them through a location
+service or assemble fragmented GNSS messages. This library decodes uplinks and
+does not implement device configuration commands.
+
+Raw payloads are decoded locally; a server-side payload formatter is not required.
+
+## Command-line reader
+
+The `sensecap-lorawan` command lists devices or prints readings as they arrive.
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) to run it with
+`uvx`, or use `pip install "sensecap-lorawan[chirpstack]"` for ChirpStack and
+`pip install "sensecap-lorawan[tts]"` for The Things Stack.
+
+### ChirpStack
+
+Use a ChirpStack v4 gRPC endpoint, an API key, and the tenant UUID. The endpoint must
+expose the gRPC API; forwarding only the web interface is not sufficient.
+
+```sh
+export CHIRPSTACK_API_KEY="your-api-key"
+uvx --from "sensecap-lorawan[chirpstack]" sensecap-lorawan \
+  --backend chirpstack \
+  --server https://chirpstack.example.com:8080 \
+  --tenant YOUR_TENANT_UUID \
+  --application YOUR_APPLICATION_UUID
+```
+
+Repeat `--application` to select more applications. If omitted, all accessible
+applications in the selected tenant are used. A global key can omit `--tenant`
+to discover its accessible tenants.
+
+### The Things Stack
+
+Use the Application Server gRPC endpoint and an application API key with device
+read and application traffic read rights. Specify each application explicitly.
+
+```sh
+export TTS_API_KEY="your-api-key"
+uvx --from "sensecap-lorawan[tts]" sensecap-lorawan \
+  --backend tts \
+  --server https://eu1.cloud.thethings.network:8884 \
+  --identity-server https://eu1.cloud.thethings.network:8884 \
+  --application YOUR_APPLICATION_ID
+```
+
+Set `--identity-server` to your deployment's Identity Server if it differs from
+the Application Server. Repeat `--application` for multiple applications.
+
+Add `--list` to print the current devices and exit, or `--json` for newline-delimited
+JSON output. Use `--api-key-file /path/to/key` instead of an environment variable
+if preferred. Stop watching with Ctrl+C. Run `sensecap-lorawan --help` for all options.
+
+With a pip installation, use `sensecap-lorawan` directly in place of the
+`uvx --from ... sensecap-lorawan` prefix. `python -m sensecap_lorawan` also works.
+
+## Python
+
+```python
+from lorawan_connection.backend.chirpstack import ChirpStackConnection
+from sensecap_lorawan import SenseCapDeviceCollection
+
+
+async def list_sensors(
+    endpoint: str, api_key: str, tenant: str, application: str
+) -> None:
+    connection = ChirpStackConnection(
+        endpoint,
+        api_key,
+        tenant_id=tenant,
+        application_ids=[application],
+        network_id=endpoint,
+    )
+    devices = SenseCapDeviceCollection(connection)
+    try:
+        await connection.async_connect()
+        await devices.async_setup()
+        for device in devices.devices.values():
+            print(device.descriptor.name, type(device).__name__)
+    finally:
+        devices.close()
+        await connection.close()
+```
+
+The collection also accepts a `TTSConnection`. Subscribe with
+`devices.subscribe_device_added(listener)` and `device.add_update_listener(listener)`
+to receive live readings. Values remain `None` until the sensor reports them.
+
+### Reading measurements
+
+Existing properties such as `S2101.temperature`, `S2101.humidity`, and
+`S2102.illuminance` remain available. All models also expose
+`measurements[channel][measurement_id]`, whose `Measurement` contains `value`,
+`timestamp`, and protocol-specific `attributes`. Timestamps are timezone-aware
+UTC values when transmitted by the device; otherwise they are `None`.
+
+```python
+from sensecap_lorawan import S2107
+
+payload = S2107.decode(bytes.fromhex("470000ff9c8000"))
+for measurement in payload.measurements:
+    print(measurement.channel, measurement.value)
+# 1 0.0
+# 2 -1.0
+# 3 None
+```
+
+For a live device, use `device.measurement_value(4203, channel=2)` or
+`device.temperature(channel=2)` on an S2107. The S2100 uses input channel numbers as measurement
+IDs within channel 1, matching Seeed's decoder. Unknown seven-byte measurement
+IDs are retained. See Seeed's [measurement ID list](https://wiki.seeedstudio.com/sensecraft-data-platform/api/appendix/list_of_measurement_ids/)
+for their meanings and units.
+
+`metadata` contains reported versions, intervals, model information, and errors.
+`battery_percentage` reads the battery value from the vendor payload;
+`battery_level` remains the standardized LoRaWAN status value. Tracker event
+measurements contain numeric event IDs, positioning status is a numeric code,
+and Wi-Fi/BLE scan values are lists of `{mac, rssi}` dictionaries.
+
+Direct decoding raises `ValueError` for malformed or unknown frame layouts. Live
+models discard those payloads atomically. Partial updates retain other readings;
+older readings cannot replace newer values on the same channel and measurement ID.
+Device timestamps take precedence over receipt time for buffered readings.
+Fault/absent values become `None`; zero remains a valid reading. The seven-byte
+protocol's two-byte trailer is not CRC-validated, matching Seeed's decoder.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check .
+uv run mypy
+uv build
+```
+
+Tests include captured S2101/S2102 uplinks, reference outputs for every decoder
+family, and malformed, partial, and out-of-order messages.
+See [fixture provenance and regeneration](tests/fixtures/README.md).
+
+## Releases
+
+The source version stays `0.0.0`. Publishing a GitHub release named `0.1.0`, for
+example, builds that version and publishes it to PyPI through Trusted Publishing.
+See [RELEASING.md](RELEASING.md) for the one-time publisher setup.
+
+## License
+
+Apache-2.0. Extracted from the SenseCAP examples in
+[`lorawan-connection`](https://github.com/home-assistant-libs/lorawan-connection).

sensecap_lorawan-0.1.0/README.md

@@ -0,0 +1,181 @@
+# SenseCAP LoRaWAN
+
+Read SenseCAP sensors through ChirpStack or The Things Stack using
+[`lorawan-connection`](https://github.com/home-assistant-libs/lorawan-connection).
+
+| Model | Readings | Automatic discovery |
+| --- | --- | --- |
+| S2100 | Data logger input channels | ChirpStack, TTS |
+| S2101 | Air temperature, humidity | ChirpStack, TTS |
+| S2102 | Light intensity | ChirpStack, TTS |
+| S2103 | Air temperature, humidity, CO₂ | ChirpStack, TTS |
+| S2104 | Soil temperature, moisture | ChirpStack, TTS |
+| S2105 | Soil temperature, moisture, conductivity | ChirpStack, TTS |
+| S2106 | Temperature, pH | ChirpStack |
+| S2107 | Three temperature probes, including buffered readings | ChirpStack |
+| S2120 | Temperature, humidity, light, UV, wind, pressure, rainfall | ChirpStack, TTS |
+| A1101 | Vision AI measurements | ChirpStack |
+| A1102 | Vision detections and digital meter readings | Explicit Python use |
+| T1000 A/B | Position, temperature, light, motion, Wi-Fi/BLE scans | ChirpStack, TTS |
+| T1000-E | Position, temperature, light, acceleration, Wi-Fi/BLE scans | Explicit Python use |
+| T2000 A/B/C | Position, acceleration, motion, Wi-Fi/BLE scans | ChirpStack, TTS |
+| WM1110 | GNSS fragments, Wi-Fi/BLE scans, environmental and custom readings | Explicit Python use |
+| Gen1 sensors | Air temperature/humidity, CO₂, light, pressure, soil temperature/moisture | TTS |
+
+Coverage follows every device family in Seeed's
+[SenseCAP-Decoder](https://github.com/Seeed-Solution/SenseCAP-Decoder/tree/d0a234205fb9574dd03abd49561b60c243c0d1e3).
+The A1102, T1000-E, and WM1110 classes have no automatic discovery identifiers:
+they are absent from the SenseCAP catalogs checked for this release. Use their
+`decode()` methods directly, or subclass them with your deployment's model identity.
+
+Tracker support requires SenseCAP LoRaWAN firmware. Meshtastic firmware and
+T1000 Mapper payloads are outside this decoder set. Wi-Fi/BLE scans and GNSS
+fragments remain scan data; the library does not resolve them through a location
+service or assemble fragmented GNSS messages. This library decodes uplinks and
+does not implement device configuration commands.
+
+Raw payloads are decoded locally; a server-side payload formatter is not required.
+
+## Command-line reader
+
+The `sensecap-lorawan` command lists devices or prints readings as they arrive.
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) to run it with
+`uvx`, or use `pip install "sensecap-lorawan[chirpstack]"` for ChirpStack and
+`pip install "sensecap-lorawan[tts]"` for The Things Stack.
+
+### ChirpStack
+
+Use a ChirpStack v4 gRPC endpoint, an API key, and the tenant UUID. The endpoint must
+expose the gRPC API; forwarding only the web interface is not sufficient.
+
+```sh
+export CHIRPSTACK_API_KEY="your-api-key"
+uvx --from "sensecap-lorawan[chirpstack]" sensecap-lorawan \
+  --backend chirpstack \
+  --server https://chirpstack.example.com:8080 \
+  --tenant YOUR_TENANT_UUID \
+  --application YOUR_APPLICATION_UUID
+```
+
+Repeat `--application` to select more applications. If omitted, all accessible
+applications in the selected tenant are used. A global key can omit `--tenant`
+to discover its accessible tenants.
+
+### The Things Stack
+
+Use the Application Server gRPC endpoint and an application API key with device
+read and application traffic read rights. Specify each application explicitly.
+
+```sh
+export TTS_API_KEY="your-api-key"
+uvx --from "sensecap-lorawan[tts]" sensecap-lorawan \
+  --backend tts \
+  --server https://eu1.cloud.thethings.network:8884 \
+  --identity-server https://eu1.cloud.thethings.network:8884 \
+  --application YOUR_APPLICATION_ID
+```
+
+Set `--identity-server` to your deployment's Identity Server if it differs from
+the Application Server. Repeat `--application` for multiple applications.
+
+Add `--list` to print the current devices and exit, or `--json` for newline-delimited
+JSON output. Use `--api-key-file /path/to/key` instead of an environment variable
+if preferred. Stop watching with Ctrl+C. Run `sensecap-lorawan --help` for all options.
+
+With a pip installation, use `sensecap-lorawan` directly in place of the
+`uvx --from ... sensecap-lorawan` prefix. `python -m sensecap_lorawan` also works.
+
+## Python
+
+```python
+from lorawan_connection.backend.chirpstack import ChirpStackConnection
+from sensecap_lorawan import SenseCapDeviceCollection
+
+
+async def list_sensors(
+    endpoint: str, api_key: str, tenant: str, application: str
+) -> None:
+    connection = ChirpStackConnection(
+        endpoint,
+        api_key,
+        tenant_id=tenant,
+        application_ids=[application],
+        network_id=endpoint,
+    )
+    devices = SenseCapDeviceCollection(connection)
+    try:
+        await connection.async_connect()
+        await devices.async_setup()
+        for device in devices.devices.values():
+            print(device.descriptor.name, type(device).__name__)
+    finally:
+        devices.close()
+        await connection.close()
+```
+
+The collection also accepts a `TTSConnection`. Subscribe with
+`devices.subscribe_device_added(listener)` and `device.add_update_listener(listener)`
+to receive live readings. Values remain `None` until the sensor reports them.
+
+### Reading measurements
+
+Existing properties such as `S2101.temperature`, `S2101.humidity`, and
+`S2102.illuminance` remain available. All models also expose
+`measurements[channel][measurement_id]`, whose `Measurement` contains `value`,
+`timestamp`, and protocol-specific `attributes`. Timestamps are timezone-aware
+UTC values when transmitted by the device; otherwise they are `None`.
+
+```python
+from sensecap_lorawan import S2107
+
+payload = S2107.decode(bytes.fromhex("470000ff9c8000"))
+for measurement in payload.measurements:
+    print(measurement.channel, measurement.value)
+# 1 0.0
+# 2 -1.0
+# 3 None
+```
+
+For a live device, use `device.measurement_value(4203, channel=2)` or
+`device.temperature(channel=2)` on an S2107. The S2100 uses input channel numbers as measurement
+IDs within channel 1, matching Seeed's decoder. Unknown seven-byte measurement
+IDs are retained. See Seeed's [measurement ID list](https://wiki.seeedstudio.com/sensecraft-data-platform/api/appendix/list_of_measurement_ids/)
+for their meanings and units.
+
+`metadata` contains reported versions, intervals, model information, and errors.
+`battery_percentage` reads the battery value from the vendor payload;
+`battery_level` remains the standardized LoRaWAN status value. Tracker event
+measurements contain numeric event IDs, positioning status is a numeric code,
+and Wi-Fi/BLE scan values are lists of `{mac, rssi}` dictionaries.
+
+Direct decoding raises `ValueError` for malformed or unknown frame layouts. Live
+models discard those payloads atomically. Partial updates retain other readings;
+older readings cannot replace newer values on the same channel and measurement ID.
+Device timestamps take precedence over receipt time for buffered readings.
+Fault/absent values become `None`; zero remains a valid reading. The seven-byte
+protocol's two-byte trailer is not CRC-validated, matching Seeed's decoder.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check .
+uv run mypy
+uv build
+```
+
+Tests include captured S2101/S2102 uplinks, reference outputs for every decoder
+family, and malformed, partial, and out-of-order messages.
+See [fixture provenance and regeneration](tests/fixtures/README.md).
+
+## Releases
+
+The source version stays `0.0.0`. Publishing a GitHub release named `0.1.0`, for
+example, builds that version and publishes it to PyPI through Trusted Publishing.
+See [RELEASING.md](RELEASING.md) for the one-time publisher setup.
+
+## License
+
+Apache-2.0. Extracted from the SenseCAP examples in
+[`lorawan-connection`](https://github.com/home-assistant-libs/lorawan-connection).

sensecap_lorawan-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "sensecap-lorawan"
+version = "0.1.0"
+description = "SenseCAP LoRaWAN device models and command-line reader"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Paulus Schoutsen", email = "balloob@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = ["lorawan-connection>=0.14.0,<0.15"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+chirpstack = ["lorawan-connection[chirpstack]>=0.14.0,<0.15"]
+tts = ["lorawan-connection[tts]>=0.14.0,<0.15"]
+
+[project.scripts]
+sensecap-lorawan = "sensecap_lorawan.__main__:main"
+
+[project.urls]
+Repository = "https://github.com/balloob/sensecap-lorawan"
+Issues = "https://github.com/balloob/sensecap-lorawan/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9", "pytest-asyncio>=1", "pytest-cov>=6", "ruff>=0.11", "mypy>=1.19"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]

sensecap_lorawan-0.1.0/src/sensecap_lorawan/__init__.py

@@ -0,0 +1,108 @@
+"""SenseCAP device models for ChirpStack and The Things Stack."""
+
+from lorawan_connection import DeviceCollection
+
+from .device import SenseCapDevice
+from .models import (
+    A1101,
+    A1102,
+    S2100,
+    S2101,
+    S2102,
+    S2103,
+    S2104,
+    S2105,
+    S2106,
+    S2107,
+    S2120,
+    T1000,
+    T1000A,
+    T1000B,
+    T1000E,
+    T2000,
+    VENDOR_ID,
+    WM1110,
+    Gen1AirTemperatureHumidity,
+    Gen1CO2,
+    Gen1Light,
+    Gen1Pressure,
+    Gen1SoilTemperatureMoisture,
+)
+from .payload import DecodedPayload, Measurement
+from .records import decode_records
+
+
+def decode_s2101(data: bytes) -> dict[str, float | None]:
+    """Decode S2101 channel-one temperature and humidity records."""
+    result: dict[str, float | None] = {}
+    for item in decode_records(data).measurements:
+        key = {4097: "temperature", 4098: "humidity"}.get(item.id)
+        if item.channel != 1 or key is None:
+            continue
+        value = item.value
+        if value is not None:
+            assert isinstance(value, (float, int))
+            if key == "temperature" and not -40 <= value <= 85:
+                raise ValueError("Temperature outside S2101 measurement range")
+            if key == "humidity" and not 0 <= value <= 100:
+                raise ValueError("Humidity outside valid range")
+        result[key] = value
+    return result
+
+
+class SenseCapDeviceCollection(DeviceCollection[SenseCapDevice]):
+    """Discover SenseCAP devices using official catalog identities."""
+
+    DEVICES = (
+        S2100,
+        S2101,
+        S2102,
+        S2103,
+        S2104,
+        S2105,
+        S2106,
+        S2107,
+        S2120,
+        A1101,
+        T1000,
+        T1000A,
+        T1000B,
+        T2000,
+        Gen1AirTemperatureHumidity,
+        Gen1CO2,
+        Gen1Light,
+        Gen1Pressure,
+        Gen1SoilTemperatureMoisture,
+    )
+
+
+__all__ = [
+    "S2100",
+    "S2101",
+    "S2102",
+    "S2103",
+    "S2104",
+    "S2105",
+    "S2106",
+    "S2107",
+    "S2120",
+    "A1101",
+    "A1102",
+    "T1000",
+    "T1000A",
+    "T1000B",
+    "T1000E",
+    "T2000",
+    "WM1110",
+    "Gen1AirTemperatureHumidity",
+    "Gen1CO2",
+    "Gen1Light",
+    "Gen1Pressure",
+    "Gen1SoilTemperatureMoisture",
+    "VENDOR_ID",
+    "DecodedPayload",
+    "Measurement",
+    "SenseCapDevice",
+    "SenseCapDeviceCollection",
+    "decode_s2101",
+]

sensecap_lorawan-0.1.0/src/sensecap_lorawan/__main__.py

@@ -0,0 +1,14 @@
+"""Discover SenseCAP devices and print their readings."""
+
+from lorawan_connection.cli_helper import run
+
+from . import SenseCapDeviceCollection
+
+
+def main() -> None:
+    """Run the SenseCAP command-line interface."""
+    run(SenseCapDeviceCollection.DEVICES)
+
+
+if __name__ == "__main__":
+    main()