pamoja-radios 0.2.0__tar.gz

pamoja_radios-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_radios-0.2.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pamoja_radios-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: pamoja-radios
+Version: 0.2.0
+Summary: The Semtech SX126x and SX127x LoRa radios and the SX1302 and SX1303 gateway concentrators: their commands, registers, and decoders, the amplifier setting a regional EIRP ceiling allows, a duty-cycle guard, and simulated chips that stand in for a module.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/radios.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: iot,pamoja,radios,robotics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.2.0
+Description-Content-Type: text/markdown
+
+# pamoja-radios
+
+The Semtech SX126x and SX127x LoRa radios and the SX1302 and SX1303 gateway concentrators: their commands, registers, and decoders, the amplifier setting a regional EIRP ceiling allows, a duty-cycle guard, and simulated chips that stand in for a module. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/radios.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html)
+
+## Install
+
+```sh
+pip install pamoja-radios
+```
+
+```python
+from pamoja import radios
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/radios.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/radios.py):
+
+```python
+from pamoja.lora import LinkBudget, plan_for
+from pamoja.radios import DutyCycle, SimulatedLoraChip, sx126x
+
+# An SX1262 node sends a ten-byte reading on 868.1 MHz at DR3, SF9 at 125 kHz, through a
+# 2.15 dBi whip on half a decibel of pigtail. The plan caps the EIRP there, and the antenna
+# and pigtail decide how hard the amplifier may drive under that cap.
+eu868 = plan_for("EU868")
+frequency = 868_100_000
+link = eu868.link_settings(3)
+whip = LinkBudget(transmit_antenna_gain_dbi=2.15, transmit_cable_loss_db=0.5)
+ceiling = eu868.max_eirp_dbm(frequency)
+power = sx126x.tx_power_under_ceiling(sx126x.Amplifier.HIGH_POWER, whip, ceiling)
+print(f"power     {power.setting_dbm} dBm under a {ceiling} dBm EIRP ceiling")
+
+# A simulated SX1262 stands in for the chip on the node's board, driven by the same code that
+# drives a real one, and it reports what that code told it.
+chip = SimulatedLoraChip.sx126x(sx126x.Amplifier.HIGH_POWER)
+bench = chip.radio()
+bench.configure(frequency, link, power.setting_dbm)
+tuned = chip.tuning()
+print(
+    f"tuned     {tuned.frequency_hz / 1e6:.1f} MHz, SF{tuned.link.spreading_factor} "
+    f"at {tuned.link.bandwidth_hz // 1000} kHz, {tuned.output_dbm} dBm"
+)
+
+# The reading goes out, and the airtime comes back for the duty-cycle guard. The sub-band that
+# holds 868.1 MHz allows 1% of the time, so the frame buys ninety-nine times as long in silence
+# before the next.
+reading = b"level=0.42"
+airtime = bench.transmit(reading)
+print(f"sent      {len(chip.sent()[0].payload)} bytes, {airtime} us on air")
+guard = DutyCycle(eu868.duty_cycle_permille(frequency))
+guard.transmitted(0, link, len(reading))
+print(f"silence   the next frame starts {guard.wait_us(0)} us after this one did")
+
+# A gateway's answer arrives from the edge of range, 2.5 dB under the noise.
+chip.hear(b"ack", -109, -2.5)
+heard = bench.receive(1_000_000)
+if heard.outcome == "Frame":
+    print(
+        f"received  {heard.payload.decode()} at {heard.rssi_dbm:.2f} dBm, "
+        f"SNR {heard.snr_db:.2f} dB"
+    )
+
+# With nothing on the air the reception times out, and a frame whose CRC fails is dropped
+# rather than handed over.
+quiet = bench.receive(1_000_000).outcome
+chip.hear_corrupt(-121, -12)
+broken = bench.receive(1_000_000).outcome
+print(f"then      {quiet}, then {broken}")
+bench.close()
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-radios`](https://crates.io/crates/pamoja-radios) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_radios/index.html), [docs.rs](https://docs.rs/pamoja-radios), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-radios) |
+| TypeScript | [`@pamoja/radios`](https://www.npmjs.com/package/@pamoja/radios) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_radios.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-radios) |
+| Python | [`pamoja-radios`](https://pypi.org/project/pamoja-radios/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-radios) |
+| C# | [`Pamoja.Radios`](https://www.nuget.org/packages/Pamoja.Radios) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Radios.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-radios) |
+
+## Documentation
+
+- [`pamoja.radios` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html), every class and function in this module.
+- [The LoRa radios guide](https://pamoja.molex.cloud/docs/guides/radios.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_radios-0.2.0/README.md

@@ -0,0 +1,98 @@
+# pamoja-radios
+
+The Semtech SX126x and SX127x LoRa radios and the SX1302 and SX1303 gateway concentrators: their commands, registers, and decoders, the amplifier setting a regional EIRP ceiling allows, a duty-cycle guard, and simulated chips that stand in for a module. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/radios.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html)
+
+## Install
+
+```sh
+pip install pamoja-radios
+```
+
+```python
+from pamoja import radios
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/radios.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/radios.py):
+
+```python
+from pamoja.lora import LinkBudget, plan_for
+from pamoja.radios import DutyCycle, SimulatedLoraChip, sx126x
+
+# An SX1262 node sends a ten-byte reading on 868.1 MHz at DR3, SF9 at 125 kHz, through a
+# 2.15 dBi whip on half a decibel of pigtail. The plan caps the EIRP there, and the antenna
+# and pigtail decide how hard the amplifier may drive under that cap.
+eu868 = plan_for("EU868")
+frequency = 868_100_000
+link = eu868.link_settings(3)
+whip = LinkBudget(transmit_antenna_gain_dbi=2.15, transmit_cable_loss_db=0.5)
+ceiling = eu868.max_eirp_dbm(frequency)
+power = sx126x.tx_power_under_ceiling(sx126x.Amplifier.HIGH_POWER, whip, ceiling)
+print(f"power     {power.setting_dbm} dBm under a {ceiling} dBm EIRP ceiling")
+
+# A simulated SX1262 stands in for the chip on the node's board, driven by the same code that
+# drives a real one, and it reports what that code told it.
+chip = SimulatedLoraChip.sx126x(sx126x.Amplifier.HIGH_POWER)
+bench = chip.radio()
+bench.configure(frequency, link, power.setting_dbm)
+tuned = chip.tuning()
+print(
+    f"tuned     {tuned.frequency_hz / 1e6:.1f} MHz, SF{tuned.link.spreading_factor} "
+    f"at {tuned.link.bandwidth_hz // 1000} kHz, {tuned.output_dbm} dBm"
+)
+
+# The reading goes out, and the airtime comes back for the duty-cycle guard. The sub-band that
+# holds 868.1 MHz allows 1% of the time, so the frame buys ninety-nine times as long in silence
+# before the next.
+reading = b"level=0.42"
+airtime = bench.transmit(reading)
+print(f"sent      {len(chip.sent()[0].payload)} bytes, {airtime} us on air")
+guard = DutyCycle(eu868.duty_cycle_permille(frequency))
+guard.transmitted(0, link, len(reading))
+print(f"silence   the next frame starts {guard.wait_us(0)} us after this one did")
+
+# A gateway's answer arrives from the edge of range, 2.5 dB under the noise.
+chip.hear(b"ack", -109, -2.5)
+heard = bench.receive(1_000_000)
+if heard.outcome == "Frame":
+    print(
+        f"received  {heard.payload.decode()} at {heard.rssi_dbm:.2f} dBm, "
+        f"SNR {heard.snr_db:.2f} dB"
+    )
+
+# With nothing on the air the reception times out, and a frame whose CRC fails is dropped
+# rather than handed over.
+quiet = bench.receive(1_000_000).outcome
+chip.hear_corrupt(-121, -12)
+broken = bench.receive(1_000_000).outcome
+print(f"then      {quiet}, then {broken}")
+bench.close()
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-radios`](https://crates.io/crates/pamoja-radios) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_radios/index.html), [docs.rs](https://docs.rs/pamoja-radios), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-radios) |
+| TypeScript | [`@pamoja/radios`](https://www.npmjs.com/package/@pamoja/radios) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_radios.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-radios) |
+| Python | [`pamoja-radios`](https://pypi.org/project/pamoja-radios/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-radios) |
+| C# | [`Pamoja.Radios`](https://www.nuget.org/packages/Pamoja.Radios) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Radios.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-radios) |
+
+## Documentation
+
+- [`pamoja.radios` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/radios.html), every class and function in this module.
+- [The LoRa radios guide](https://pamoja.molex.cloud/docs/guides/radios.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_radios-0.2.0/pamoja/radios/__init__.py

@@ -0,0 +1,38 @@
+"""Idiomatic LoRa radio facade.
+
+``pamoja.lora`` works out what a link costs and how far it reaches; this puts a radio chip
+on the air to match. For the Semtech SX1261, SX1262, and LLCC68, :mod:`pamoja.radios.sx126x`
+builds the bytes of every command and decodes every answer, and chooses the amplifier
+setting a regional EIRP ceiling allows behind an antenna. For the SX1276 family,
+:mod:`pamoja.radios.sx127x` gives the register values and decodes the readings.
+:class:`DutyCycle` holds the radio
+silent for the off time a duty-cycle limit owes after each frame. On a Linux board,
+:class:`LoraRadio` opens a module of either family through the kernel's spidev and GPIO
+character devices and drives it with the same calls. On any platform,
+:class:`SimulatedLoraChip` stands in for a module: the radio it gives is the same class,
+and the chip says what it was tuned to and what it sent.
+"""
+
+from __future__ import annotations
+
+from pamoja._native import (
+    LoraRadio,
+    LoraReception,
+    LoraSentFrame,
+    LoraTuning,
+    SimulatedLoraChip,
+)
+from pamoja._native import RadioDutyCycle as DutyCycle
+
+from . import sx126x, sx127x
+
+__all__ = [
+    "DutyCycle",
+    "LoraRadio",
+    "LoraReception",
+    "LoraSentFrame",
+    "LoraTuning",
+    "SimulatedLoraChip",
+    "sx126x",
+    "sx127x",
+]

pamoja_radios-0.2.0/pamoja/radios/sx126x.py

@@ -0,0 +1,523 @@
+"""The Semtech SX1261, SX1262, and LLCC68, as the bytes they take and the answers they give.
+
+Every command goes out in one SPI transaction framed by NSS, sent once the chip's BUSY line
+is low, and a query's answer is read in the same transaction after its bytes. These
+functions build the bytes and decode the answers from the SX1261/2 datasheet (Rev 2.2), so a
+program with its own SPI access can drive the chip with nothing else.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, IntFlag
+
+from pamoja._native import (
+    LinkBudget,
+    LoraLink,
+    Sx126xPacketStatus as PacketStatus,
+    Sx126xQuery as Query,
+    Sx126xRxBufferStatus as RxBufferStatus,
+    Sx126xStatus as Status,
+    Sx126xTxPower as TxPower,
+)
+from pamoja._native import sx126x_calibrate_image as _calibrate_image
+from pamoja._native import sx126x_clear_irq_status as _clear_irq_status
+from pamoja._native import sx126x_constants as _constants
+from pamoja._native import sx126x_device_errors as _device_errors
+from pamoja._native import sx126x_frequency_word as _frequency_word
+from pamoja._native import sx126x_get_device_errors as _get_device_errors
+from pamoja._native import sx126x_get_irq_status as _get_irq_status
+from pamoja._native import sx126x_get_packet_status as _get_packet_status
+from pamoja._native import sx126x_get_rssi_inst as _get_rssi_inst
+from pamoja._native import sx126x_get_rx_buffer_status as _get_rx_buffer_status
+from pamoja._native import sx126x_get_status as _get_status
+from pamoja._native import sx126x_image_calibration as _image_calibration
+from pamoja._native import sx126x_irq as _irq
+from pamoja._native import sx126x_llcc68_supports as _llcc68_supports
+from pamoja._native import sx126x_packet_status as _packet_status
+from pamoja._native import sx126x_ramp_time_us as _ramp_time_us
+from pamoja._native import sx126x_read_buffer as _read_buffer
+from pamoja._native import sx126x_read_register as _read_register
+from pamoja._native import sx126x_rssi_inst_dbm as _rssi_inst_dbm
+from pamoja._native import sx126x_rx_buffer_status as _rx_buffer_status
+from pamoja._native import sx126x_set_dio_irq_params as _set_dio_irq_params
+from pamoja._native import sx126x_set_lora_modulation_params as _set_lora_modulation_params
+from pamoja._native import sx126x_set_lora_packet_params as _set_lora_packet_params
+from pamoja._native import sx126x_set_pa_config as _set_pa_config
+from pamoja._native import sx126x_set_packet_type_lora as _set_packet_type_lora
+from pamoja._native import sx126x_set_rf_frequency as _set_rf_frequency
+from pamoja._native import sx126x_set_rx as _set_rx
+from pamoja._native import sx126x_set_rx_continuous as _set_rx_continuous
+from pamoja._native import sx126x_set_sleep as _set_sleep
+from pamoja._native import sx126x_set_standby as _set_standby
+from pamoja._native import sx126x_set_tx as _set_tx
+from pamoja._native import sx126x_set_tx_params as _set_tx_params
+from pamoja._native import sx126x_status as _status
+from pamoja._native import sx126x_timeout_steps as _timeout_steps
+from pamoja._native import sx126x_tx_power as _tx_power
+from pamoja._native import sx126x_tx_power_under_ceiling as _tx_power_under_ceiling
+from pamoja._native import sx126x_write_buffer as _write_buffer
+from pamoja._native import sx126x_write_register as _write_register
+
+__all__ = [
+    "REGISTER_LORA_SYNC_WORD",
+    "RX_CONTINUOUS",
+    "SYNC_WORD_PRIVATE",
+    "SYNC_WORD_PUBLIC",
+    "Amplifier",
+    "DeviceError",
+    "Irq",
+    "PacketStatus",
+    "Query",
+    "RxBufferStatus",
+    "Status",
+    "TxPower",
+    "calibrate_image",
+    "clear_irq_status",
+    "device_errors",
+    "frequency_word",
+    "get_device_errors",
+    "get_irq_status",
+    "get_packet_status",
+    "get_rssi_inst",
+    "get_rx_buffer_status",
+    "get_status",
+    "image_calibration",
+    "irq",
+    "llcc68_supports",
+    "packet_status",
+    "ramp_time_us",
+    "read_buffer",
+    "read_register",
+    "rssi_inst_dbm",
+    "rx_buffer_status",
+    "set_dio_irq_params",
+    "set_lora_modulation_params",
+    "set_lora_packet_params",
+    "set_pa_config",
+    "set_packet_type_lora",
+    "set_rf_frequency",
+    "set_rx",
+    "set_rx_continuous",
+    "set_sleep",
+    "set_standby",
+    "set_tx",
+    "set_tx_params",
+    "status",
+    "timeout_steps",
+    "tx_power",
+    "tx_power_under_ceiling",
+    "write_buffer",
+    "write_register",
+]
+
+_CONSTANTS = _constants()
+
+#: The receive timeout word that keeps the chip listening until another command stops it.
+RX_CONTINUOUS = _CONSTANTS["RX_CONTINUOUS"]
+#: The LoRa sync word of a public network such as LoRaWAN.
+SYNC_WORD_PUBLIC = _CONSTANTS["SYNC_WORD_PUBLIC"]
+#: The LoRa sync word of a private network, and the chip's reset value.
+SYNC_WORD_PRIVATE = _CONSTANTS["SYNC_WORD_PRIVATE"]
+#: The register that holds the most significant byte of the LoRa sync word.
+REGISTER_LORA_SYNC_WORD = _CONSTANTS["REGISTER_LORA_SYNC_WORD"]
+
+
+class Amplifier(str, Enum):
+    """Which power amplifier a chip has.
+
+    The SPI interface cannot tell the chips apart, so the caller names the amplifier.
+    """
+
+    #: The low power amplifier of the SX1261, up to +15 dBm.
+    LOW_POWER = "LowPower"
+    #: The high power amplifier of the SX1262 and the LLCC68, up to +22 dBm.
+    HIGH_POWER = "HighPower"
+
+
+class Irq(IntFlag):
+    """The interrupt bits of the IRQ register, from Table 13-29 of the datasheet."""
+
+    #: A packet has been sent.
+    TX_DONE = _CONSTANTS["IRQ_TX_DONE"]
+    #: A packet has been received.
+    RX_DONE = _CONSTANTS["IRQ_RX_DONE"]
+    #: A preamble has been detected.
+    PREAMBLE_DETECTED = _CONSTANTS["IRQ_PREAMBLE_DETECTED"]
+    #: A valid (G)FSK sync word has been detected.
+    SYNC_WORD_VALID = _CONSTANTS["IRQ_SYNC_WORD_VALID"]
+    #: A valid LoRa header has been received.
+    HEADER_VALID = _CONSTANTS["IRQ_HEADER_VALID"]
+    #: A LoRa header failed its CRC.
+    HEADER_ERROR = _CONSTANTS["IRQ_HEADER_ERROR"]
+    #: A packet failed its CRC.
+    CRC_ERROR = _CONSTANTS["IRQ_CRC_ERROR"]
+    #: Channel activity detection has finished.
+    CAD_DONE = _CONSTANTS["IRQ_CAD_DONE"]
+    #: Channel activity detection heard LoRa.
+    CAD_DETECTED = _CONSTANTS["IRQ_CAD_DETECTED"]
+    #: A transmission or a reception timed out.
+    TIMEOUT = _CONSTANTS["IRQ_TIMEOUT"]
+    #: A long-range FHSS hop is due.
+    LR_FHSS_HOP = _CONSTANTS["IRQ_LR_FHSS_HOP"]
+
+
+class DeviceError(IntFlag):
+    """The device error bits GetDeviceErrors answers with."""
+
+    #: The RC64k oscillator failed to calibrate.
+    RC64K_CALIBRATION = _CONSTANTS["ERROR_RC64K_CALIBRATION"]
+    #: The RC13M oscillator failed to calibrate.
+    RC13M_CALIBRATION = _CONSTANTS["ERROR_RC13M_CALIBRATION"]
+    #: The PLL failed to calibrate.
+    PLL_CALIBRATION = _CONSTANTS["ERROR_PLL_CALIBRATION"]
+    #: The ADC failed to calibrate.
+    ADC_CALIBRATION = _CONSTANTS["ERROR_ADC_CALIBRATION"]
+    #: Image rejection failed to calibrate.
+    IMAGE_CALIBRATION = _CONSTANTS["ERROR_IMAGE_CALIBRATION"]
+    #: The crystal oscillator failed to start, which a TCXO raises until it is powered.
+    XOSC_START = _CONSTANTS["ERROR_XOSC_START"]
+    #: The PLL failed to lock.
+    PLL_LOCK = _CONSTANTS["ERROR_PLL_LOCK"]
+    #: The power amplifier failed to ramp.
+    PA_RAMP = _CONSTANTS["ERROR_PA_RAMP"]
+
+
+def frequency_word(frequency_hz: int) -> int:
+    """Return the word SetRfFrequency takes for a frequency.
+
+    :param frequency_hz: The carrier frequency in hertz.
+    :returns: The frequency times 2^25 over the 32 MHz crystal, rounded to the nearest step.
+
+    >>> hex(frequency_word(868_100_000))
+    '0x3641999a'
+    """
+    return _frequency_word(frequency_hz)
+
+
+def timeout_steps(timeout_us: int) -> int:
+    """Return the 24-bit timeout word SetTx and SetRx take for a duration.
+
+    :param timeout_us: The duration in microseconds.
+    :returns: The number of 15.625 us steps; a nonzero duration never becomes the zero word
+        that disables the timeout.
+
+    >>> timeout_steps(1_000_000)
+    64000
+    """
+    return _timeout_steps(timeout_us)
+
+
+def image_calibration(low_hz: int, high_hz: int) -> bytes:
+    """Return the two CalibrateImage codes that cover a band.
+
+    :param low_hz: The lower edge of the band in hertz.
+    :param high_hz: The upper edge of the band in hertz.
+    :returns: ``freq1`` and ``freq2``, 4 MHz steps that always cover the band.
+
+    >>> image_calibration(863_000_000, 870_000_000).hex()
+    'd7da'
+    """
+    return _image_calibration(low_hz, high_hz)
+
+
+def ramp_time_us(at_least_us: int) -> int:
+    """Return the shortest amplifier ramp time the chip offers that lasts at least a duration.
+
+    :param at_least_us: The least ramp time wanted, in microseconds.
+    :returns: One of the eight ramp times of Table 13-41, in microseconds.
+    """
+    return _ramp_time_us(at_least_us)
+
+
+def tx_power(amplifier: Amplifier | str, output_dbm: int) -> TxPower:
+    """Choose the amplifier settings for an output power.
+
+    :param amplifier: The chip's amplifier.
+    :param output_dbm: The output power wanted at the antenna port, in dBm.
+    :returns: The configuration and the setting, clamped to what the amplifier allows.
+    :raises ValueError: If no amplifier goes by that name.
+    """
+    return _tx_power(Amplifier(amplifier).value, output_dbm)
+
+
+def tx_power_under_ceiling(
+    amplifier: Amplifier | str, budget: LinkBudget, eirp_ceiling_dbm: float
+) -> TxPower:
+    """Choose the amplifier settings that keep a link's EIRP at or under a ceiling.
+
+    :param amplifier: The chip's amplifier.
+    :param budget: The link budget, whose transmitting antenna and cable apply.
+    :param eirp_ceiling_dbm: The EIRP limit, such as a channel plan's ceiling for the
+        frequency.
+    :returns: The configuration and the setting, rounded down to whole decibels so the EIRP
+        stays under the ceiling.
+    :raises ValueError: If no amplifier goes by that name.
+    """
+    return _tx_power_under_ceiling(Amplifier(amplifier).value, budget, eirp_ceiling_dbm)
+
+
+def set_standby() -> bytes:
+    """Return SetStandby into STDBY_RC, which stops a transmission or a reception."""
+    return _set_standby()
+
+
+def set_packet_type_lora() -> bytes:
+    """Return SetPacketType for LoRa, the first radio setting a configuration sends."""
+    return _set_packet_type_lora()
+
+
+def set_rf_frequency(frequency_hz: int) -> bytes:
+    """Return SetRfFrequency for a carrier frequency.
+
+    :param frequency_hz: The carrier frequency in hertz.
+    :returns: The command bytes.
+    """
+    return _set_rf_frequency(frequency_hz)
+
+
+def calibrate_image(low_hz: int, high_hz: int) -> bytes:
+    """Return CalibrateImage over a band.
+
+    :param low_hz: The lower edge of the band in hertz.
+    :param high_hz: The upper edge of the band in hertz.
+    :returns: The command bytes.
+    """
+    return _calibrate_image(low_hz, high_hz)
+
+
+def set_pa_config(power: TxPower) -> bytes:
+    """Return SetPaConfig for a power setting.
+
+    :param power: The settings from :func:`tx_power` or :func:`tx_power_under_ceiling`.
+    :returns: The command bytes.
+    """
+    return _set_pa_config(power)
+
+
+def set_tx_params(power: TxPower, ramp_us: int) -> bytes:
+    """Return SetTxParams for a power setting and a ramp time.
+
+    :param power: The power settings.
+    :param ramp_us: The least amplifier ramp time wanted, in microseconds.
+    :returns: The command bytes.
+    """
+    return _set_tx_params(power, ramp_us)
+
+
+def set_lora_modulation_params(link: LoraLink) -> bytes:
+    """Return SetModulationParams for a LoRa link.
+
+    :param link: The link settings, from :mod:`pamoja.lora`.
+    :returns: The command bytes.
+    :raises PamojaError: If the link's bandwidth is not one the SX126x offers.
+    """
+    return _set_lora_modulation_params(link)
+
+
+def set_lora_packet_params(link: LoraLink, payload_len: int, invert_iq: bool) -> bytes:
+    """Return SetPacketParams for a LoRa link and a payload.
+
+    :param link: The link settings, whose preamble, header, and CRC the frame uses.
+    :param payload_len: The payload length to send, or the most a receiver accepts.
+    :param invert_iq: Whether the IQ polarity is inverted, as LoRaWAN downlinks use.
+    :returns: The command bytes.
+    """
+    return _set_lora_packet_params(link, payload_len, invert_iq)
+
+
+def set_dio_irq_params(irq: int, dio1: int, dio2: int = 0, dio3: int = 0) -> bytes:
+    """Return SetDioIrqParams: which interrupts are enabled, and which DIO lines raise them.
+
+    :param irq: The interrupts to enable, as :class:`Irq` bits.
+    :param dio1: The interrupts routed to DIO1.
+    :param dio2: The interrupts routed to DIO2.
+    :param dio3: The interrupts routed to DIO3.
+    :returns: The command bytes.
+    """
+    return _set_dio_irq_params(int(irq), int(dio1), int(dio2), int(dio3))
+
+
+def clear_irq_status(irq: int) -> bytes:
+    """Return ClearIrqStatus for a set of interrupts.
+
+    :param irq: The interrupts to clear, as :class:`Irq` bits.
+    :returns: The command bytes.
+    """
+    return _clear_irq_status(int(irq))
+
+
+def set_tx(timeout_us: int) -> bytes:
+    """Return SetTx with a timeout.
+
+    :param timeout_us: How long the chip may transmit before it raises TIMEOUT, in
+        microseconds; ``0`` disables the timeout.
+    :returns: The command bytes.
+    """
+    return _set_tx(timeout_us)
+
+
+def set_rx(timeout_us: int) -> bytes:
+    """Return SetRx with a timeout.
+
+    :param timeout_us: How long the chip listens for a packet to start, in microseconds;
+        ``0`` listens for one packet with no timeout.
+    :returns: The command bytes.
+    """
+    return _set_rx(timeout_us)
+
+
+def set_rx_continuous() -> bytes:
+    """Return SetRx in continuous mode, receiving packet after packet until another command."""
+    return _set_rx_continuous()
+
+
+def set_sleep(warm_start: bool) -> bytes:
+    """Return SetSleep, without an RTC wake-up.
+
+    :param warm_start: Whether to keep the configuration in retention while asleep.
+    :returns: The command bytes.
+    """
+    return _set_sleep(warm_start)
+
+
+def write_register(address: int, values: bytes) -> bytes:
+    """Return a whole WriteRegister transaction.
+
+    :param address: The first register's address, such as :data:`REGISTER_LORA_SYNC_WORD`.
+    :param values: The register values, one byte each.
+    :returns: The opcode, the address, and the values.
+    """
+    return _write_register(address, bytes(values))
+
+
+def write_buffer(offset: int, payload: bytes) -> bytes:
+    """Return a whole WriteBuffer transaction.
+
+    :param offset: Where in the data buffer the first byte goes.
+    :param payload: The bytes to write.
+    :returns: The opcode, the offset, and the payload.
+    """
+    return _write_buffer(offset, bytes(payload))
+
+
+def get_status() -> Query:
+    """Return GetStatus, answered by the status byte; decode it with :func:`status`."""
+    return _get_status()
+
+
+def get_irq_status() -> Query:
+    """Return GetIrqStatus, answered by two IRQ bytes; decode them with :func:`irq`."""
+    return _get_irq_status()
+
+
+def get_rx_buffer_status() -> Query:
+    """Return GetRxBufferStatus, answered by two bytes; decode them with :func:`rx_buffer_status`."""
+    return _get_rx_buffer_status()
+
+
+def get_packet_status() -> Query:
+    """Return GetPacketStatus, answered by three bytes; decode them with :func:`packet_status`."""
+    return _get_packet_status()
+
+
+def get_rssi_inst() -> Query:
+    """Return GetRssiInst, answered by one byte; decode it with :func:`rssi_inst_dbm`."""
+    return _get_rssi_inst()
+
+
+def get_device_errors() -> Query:
+    """Return GetDeviceErrors, answered by two bytes; decode them with :func:`device_errors`."""
+    return _get_device_errors()
+
+
+def read_register(address: int, length: int) -> Query:
+    """Return ReadRegister for a run of consecutive registers.
+
+    :param address: The first register's address.
+    :param length: How many registers to read.
+    :returns: The query.
+    """
+    return _read_register(address, length)
+
+
+def read_buffer(offset: int, length: int) -> Query:
+    """Return ReadBuffer for a run of the data buffer.
+
+    :param offset: Where in the buffer the first byte is.
+    :param length: How many bytes to read.
+    :returns: The query.
+    """
+    return _read_buffer(offset, length)
+
+
+def status(byte: int) -> Status:
+    """Decode a status byte.
+
+    :param byte: The status byte.
+    :returns: The chip's mode, how its last command went, and whether that was an error.
+
+    >>> status(0x2C).chip_mode
+    'StandbyRc'
+    """
+    return _status(byte)
+
+
+def irq(answer: bytes) -> Irq:
+    """Decode a GetIrqStatus answer.
+
+    :param answer: The two answer bytes.
+    :returns: The pending interrupts.
+    :raises ValueError: If the answer is not two bytes.
+    """
+    return Irq(_irq(bytes(answer)))
+
+
+def device_errors(answer: bytes) -> DeviceError:
+    """Decode a GetDeviceErrors answer.
+
+    :param answer: The two answer bytes.
+    :returns: The flagged errors.
+    :raises ValueError: If the answer is not two bytes.
+    """
+    return DeviceError(_device_errors(bytes(answer)))
+
+
+def packet_status(answer: bytes) -> PacketStatus:
+    """Decode a LoRa GetPacketStatus answer.
+
+    :param answer: RssiPkt, SnrPkt, and SignalRssiPkt.
+    :returns: The three signal levels, exact to a hundredth of a decibel.
+    :raises ValueError: If the answer is not three bytes.
+    """
+    return _packet_status(bytes(answer))
+
+
+def rx_buffer_status(answer: bytes) -> RxBufferStatus:
+    """Decode a GetRxBufferStatus answer.
+
+    :param answer: PayloadLengthRx and RxStartBufferPointer.
+    :returns: The payload length and where it starts in the data buffer.
+    :raises ValueError: If the answer is not two bytes.
+    """
+    return _rx_buffer_status(bytes(answer))
+
+
+def rssi_inst_dbm(byte: int) -> float:
+    """Decode a GetRssiInst answer.
+
+    :param byte: RssiInst.
+    :returns: The signal power the receiver hears right now, in dBm.
+    """
+    return _rssi_inst_dbm(byte)
+
+
+def llcc68_supports(link: LoraLink) -> bool:
+    """Report whether an LLCC68 supports a link's spreading factor at its bandwidth.
+
+    The LLCC68 takes the SX1262's commands but not all its settings: up to SF9 at 125 kHz,
+    SF10 at 250 kHz, and SF11 at 500 kHz, and no bandwidth below 125 kHz.
+
+    :param link: The link settings.
+    :returns: ``True`` when an LLCC68 can use the link.
+    """
+    return _llcc68_supports(link)

pamoja_radios-0.2.0/pamoja/radios/sx127x.py

@@ -0,0 +1,493 @@
+"""The Semtech SX1276, SX1277, SX1278, and SX1279, as the register values they take.
+
+These radios, and modules built on them such as the RFM95W, are driven through registers.
+Each SPI transaction starts with an address byte whose top bit is set for a write, followed
+by the data, and the address advances with each byte except at the FIFO. These functions
+give the addresses, the values a LoRa link and an output power put in them, and the
+readings decoded, from the SX1276/77/78/79 datasheet (Rev 7), so a program with its own SPI
+access can drive the chip.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, IntEnum, IntFlag
+
+from pamoja._native import (
+    LinkBudget,
+    LoraLink,
+    Sx127xHighBwOptimize as HighBwOptimize,
+    Sx127xModem as Modem,
+    Sx127xModemStatus as ModemStatus,
+    Sx127xPacketStatus as PacketStatus,
+    Sx127xSpuriousReception as SpuriousReception,
+    Sx127xTxPower as TxPower,
+)
+from pamoja._native import sx127x_automatic_if as _automatic_if
+from pamoja._native import sx127x_constants as _constants
+from pamoja._native import sx127x_frequency_from_word as _frequency_from_word
+from pamoja._native import sx127x_frequency_word as _frequency_word
+from pamoja._native import sx127x_fsk_op_mode as _fsk_op_mode
+from pamoja._native import sx127x_high_bw_optimize as _high_bw_optimize
+from pamoja._native import sx127x_image_cal_start as _image_cal_start
+from pamoja._native import sx127x_invert_iq as _invert_iq
+from pamoja._native import sx127x_invert_iq_2 as _invert_iq_2
+from pamoja._native import sx127x_irq_flags as _irq_flags
+from pamoja._native import sx127x_lora_op_mode as _lora_op_mode
+from pamoja._native import sx127x_mode_from_op_mode as _mode_from_op_mode
+from pamoja._native import sx127x_modem as _modem
+from pamoja._native import sx127x_modem_status as _modem_status
+from pamoja._native import sx127x_ocp_register as _ocp_register
+from pamoja._native import sx127x_packet_status as _packet_status
+from pamoja._native import sx127x_read_address as _read_address
+from pamoja._native import sx127x_registers as _registers
+from pamoja._native import sx127x_rssi_dbm as _rssi_dbm
+from pamoja._native import sx127x_spurious_reception as _spurious_reception
+from pamoja._native import sx127x_symbol_timeout as _symbol_timeout
+from pamoja._native import sx127x_tx_power as _tx_power
+from pamoja._native import sx127x_tx_power_under_ceiling as _tx_power_under_ceiling
+from pamoja._native import sx127x_write_address as _write_address
+
+__all__ = [
+    "IMAGE_CAL_RUNNING",
+    "IMAGE_CAL_START",
+    "LNA_BOOSTED",
+    "PA_DAC_DEFAULT",
+    "PA_DAC_HIGH_POWER",
+    "SYNC_WORD_PRIVATE",
+    "SYNC_WORD_PUBLIC",
+    "TCXO_INPUT_ON",
+    "VERSION",
+    "WRITE",
+    "Dio0",
+    "HighBwOptimize",
+    "Irq",
+    "Mode",
+    "Modem",
+    "ModemStatus",
+    "PaOutput",
+    "PacketStatus",
+    "Register",
+    "SpuriousReception",
+    "TxPower",
+    "automatic_if",
+    "frequency_from_word",
+    "frequency_word",
+    "fsk_op_mode",
+    "high_bw_optimize",
+    "image_cal_start",
+    "invert_iq",
+    "invert_iq_2",
+    "lora_op_mode",
+    "mode_from_op_mode",
+    "modem",
+    "modem_status",
+    "ocp_register",
+    "packet_status",
+    "read_address",
+    "rssi_dbm",
+    "spurious_reception",
+    "symbol_timeout",
+    "tx_power",
+    "tx_power_under_ceiling",
+    "write_address",
+]
+
+_REGISTERS = _registers()
+_CONSTANTS = _constants()
+_IRQ_FLAGS = _irq_flags()
+
+#: The RegVersion value of an SX1276, SX1277, SX1278, or SX1279.
+VERSION = _CONSTANTS["version"]
+#: The bit of an address byte that makes an access a write.
+WRITE = _CONSTANTS["write"]
+#: The sync word the datasheet reserves for LoRaWAN networks.
+SYNC_WORD_PUBLIC = _CONSTANTS["syncWordPublic"]
+#: The private sync word, and the chip's reset value.
+SYNC_WORD_PRIVATE = _CONSTANTS["syncWordPrivate"]
+#: RegPaDac at its reset value.
+PA_DAC_DEFAULT = _CONSTANTS["paDacDefault"]
+#: RegPaDac with the +20 dBm setting on PA_BOOST.
+PA_DAC_HIGH_POWER = _CONSTANTS["paDacHighPower"]
+#: The RegImageCal bit that starts a calibration.
+IMAGE_CAL_START = _CONSTANTS["imageCalStart"]
+#: The RegImageCal bit set while a calibration runs.
+IMAGE_CAL_RUNNING = _CONSTANTS["imageCalRunning"]
+#: RegLna with maximum gain and the high frequency LNA boost.
+LNA_BOOSTED = _CONSTANTS["lnaBoosted"]
+#: RegTcxo for a module clocked by a TCXO.
+TCXO_INPUT_ON = _CONSTANTS["tcxoInputOn"]
+
+
+class Register(IntEnum):
+    """The register addresses, from Table 41 of the datasheet with the LoRa page selected."""
+
+    #: RegFifo, the LoRa data buffer, read or written at RegFifoAddrPtr.
+    FIFO = _REGISTERS["fifo"]
+    #: RegOpMode: LoRa or FSK, the register page, and the operating mode.
+    OP_MODE = _REGISTERS["opMode"]
+    #: RegFrfMsb, the top byte of the carrier word.
+    FRF_MSB = _REGISTERS["frfMsb"]
+    #: RegFrfMid, the middle byte of the carrier word.
+    FRF_MID = _REGISTERS["frfMid"]
+    #: RegFrfLsb, the low byte of the carrier word.
+    FRF_LSB = _REGISTERS["frfLsb"]
+    #: RegPaConfig: the amplifier output, its maximum, and the power.
+    PA_CONFIG = _REGISTERS["paConfig"]
+    #: RegPaRamp, the amplifier ramp time.
+    PA_RAMP = _REGISTERS["paRamp"]
+    #: RegOcp, the amplifier current limit.
+    OCP = _REGISTERS["ocp"]
+    #: RegLna, the LNA gain and current.
+    LNA = _REGISTERS["lna"]
+    #: RegFifoAddrPtr, where the next RegFifo access lands.
+    FIFO_ADDR_PTR = _REGISTERS["fifoAddrPtr"]
+    #: RegFifoTxBaseAddr, where a transmitted payload starts.
+    FIFO_TX_BASE_ADDR = _REGISTERS["fifoTxBaseAddr"]
+    #: RegFifoRxBaseAddr, where received payloads start.
+    FIFO_RX_BASE_ADDR = _REGISTERS["fifoRxBaseAddr"]
+    #: RegFifoRxCurrentAddr, where the last received packet starts.
+    FIFO_RX_CURRENT_ADDR = _REGISTERS["fifoRxCurrentAddr"]
+    #: RegIrqFlagsMask, the interrupts masked off.
+    IRQ_FLAGS_MASK = _REGISTERS["irqFlagsMask"]
+    #: RegIrqFlags, the interrupts raised, each cleared by writing it back as a 1.
+    IRQ_FLAGS = _REGISTERS["irqFlags"]
+    #: RegRxNbBytes, the payload length of the last packet received.
+    RX_NB_BYTES = _REGISTERS["rxNbBytes"]
+    #: RegModemStat, the live state of the modem.
+    MODEM_STAT = _REGISTERS["modemStat"]
+    #: RegPktSnrValue, the SNR of the last packet in quarters of a decibel.
+    PKT_SNR_VALUE = _REGISTERS["pktSnrValue"]
+    #: RegPktRssiValue, the RSSI of the last packet.
+    PKT_RSSI_VALUE = _REGISTERS["pktRssiValue"]
+    #: RegRssiValue, the RSSI the receiver hears right now.
+    RSSI_VALUE = _REGISTERS["rssiValue"]
+    #: RegHopChannel, the PLL lock and the CRC the last header announced.
+    HOP_CHANNEL = _REGISTERS["hopChannel"]
+    #: RegModemConfig1: bandwidth, coding rate, and header mode.
+    MODEM_CONFIG_1 = _REGISTERS["modemConfig1"]
+    #: RegModemConfig2: spreading factor, CRC, and the top bits of the symbol timeout.
+    MODEM_CONFIG_2 = _REGISTERS["modemConfig2"]
+    #: RegSymbTimeoutLsb, the low byte of the symbol timeout.
+    SYMB_TIMEOUT_LSB = _REGISTERS["symbTimeoutLsb"]
+    #: RegPreambleMsb, the high byte of the preamble length.
+    PREAMBLE_MSB = _REGISTERS["preambleMsb"]
+    #: RegPreambleLsb, the low byte of the preamble length.
+    PREAMBLE_LSB = _REGISTERS["preambleLsb"]
+    #: RegPayloadLength, the payload length to send.
+    PAYLOAD_LENGTH = _REGISTERS["payloadLength"]
+    #: RegMaxPayloadLength, the longest payload a received header may announce.
+    MAX_PAYLOAD_LENGTH = _REGISTERS["maxPayloadLength"]
+    #: RegModemConfig3: low data rate optimization and the automatic gain control.
+    MODEM_CONFIG_3 = _REGISTERS["modemConfig3"]
+    #: RegRssiWideband, a wideband RSSI sample.
+    RSSI_WIDEBAND = _REGISTERS["rssiWideband"]
+    #: RegIfFreq2, which the spurious reception erratum sets.
+    IF_FREQ_2 = _REGISTERS["ifFreq2"]
+    #: RegIfFreq1, which the spurious reception erratum clears.
+    IF_FREQ_1 = _REGISTERS["ifFreq1"]
+    #: RegDetectOptimize: the automatic IF and the detection optimization.
+    DETECT_OPTIMIZE = _REGISTERS["detectOptimize"]
+    #: RegInvertIQ, the IQ polarity of each path.
+    INVERT_IQ = _REGISTERS["invertIq"]
+    #: RegHighBwOptimize1, which the 500 kHz erratum sets.
+    HIGH_BW_OPTIMIZE_1 = _REGISTERS["highBwOptimize1"]
+    #: RegDetectionThreshold, the LoRa detection threshold.
+    DETECTION_THRESHOLD = _REGISTERS["detectionThreshold"]
+    #: RegSyncWord, the LoRa sync word.
+    SYNC_WORD = _REGISTERS["syncWord"]
+    #: RegHighBwOptimize2, which the 500 kHz erratum sets.
+    HIGH_BW_OPTIMIZE_2 = _REGISTERS["highBwOptimize2"]
+    #: RegInvertIQ2, which completes an IQ inversion.
+    INVERT_IQ_2 = _REGISTERS["invertIq2"]
+    #: RegImageCal, at the address of RegInvertIQ2 on the FSK page.
+    IMAGE_CAL = _REGISTERS["imageCal"]
+    #: RegDioMapping1, the events DIO0 to DIO3 signal.
+    DIO_MAPPING_1 = _REGISTERS["dioMapping1"]
+    #: RegDioMapping2, the events DIO4 and DIO5 signal.
+    DIO_MAPPING_2 = _REGISTERS["dioMapping2"]
+    #: RegVersion, the silicon revision.
+    VERSION = _REGISTERS["version"]
+    #: RegTcxo, a crystal or a TCXO on XTA.
+    TCXO = _REGISTERS["tcxo"]
+    #: RegPaDac, the +20 dBm setting of PA_BOOST.
+    PA_DAC = _REGISTERS["paDac"]
+
+
+class Dio0(IntEnum):
+    """The RegDioMapping1 values that route an event to DIO0, from Table 18 of the datasheet."""
+
+    #: DIO0 signals RxDone.
+    RX_DONE = _CONSTANTS["dio0RxDone"]
+    #: DIO0 signals TxDone.
+    TX_DONE = _CONSTANTS["dio0TxDone"]
+    #: DIO0 signals CadDone.
+    CAD_DONE = _CONSTANTS["dio0CadDone"]
+
+
+class Irq(IntFlag):
+    """The LoRa interrupt flags of RegIrqFlags."""
+
+    #: A single reception timed out before a preamble arrived.
+    RX_TIMEOUT = _IRQ_FLAGS["rxTimeout"]
+    #: A packet has been received.
+    RX_DONE = _IRQ_FLAGS["rxDone"]
+    #: The payload failed its CRC.
+    PAYLOAD_CRC_ERROR = _IRQ_FLAGS["payloadCrcError"]
+    #: A valid header was received.
+    VALID_HEADER = _IRQ_FLAGS["validHeader"]
+    #: The payload has been transmitted.
+    TX_DONE = _IRQ_FLAGS["txDone"]
+    #: Channel activity detection finished.
+    CAD_DONE = _IRQ_FLAGS["cadDone"]
+    #: Frequency hopping moved to the next channel.
+    FHSS_CHANGE_CHANNEL = _IRQ_FLAGS["fhssChangeChannel"]
+    #: Channel activity detection heard a LoRa signal.
+    CAD_DETECTED = _IRQ_FLAGS["cadDetected"]
+
+
+class PaOutput(str, Enum):
+    """The amplifier output a module wires to its antenna.
+
+    The SPI interface cannot see which output a module uses, so the caller names it.
+    """
+
+    #: The high efficiency amplifier on RFO_LF or RFO_HF, -4 to +15 dBm.
+    RFO = "Rfo"
+    #: The regulated amplifier on PA_BOOST, +2 to +20 dBm, as on the RFM95W.
+    PA_BOOST = "PaBoost"
+
+
+class Mode(str, Enum):
+    """The operating modes of RegOpMode."""
+
+    #: Only the SPI interface and the registers are powered; the only mode that may switch modems.
+    SLEEP = "Sleep"
+    #: The oscillator and the baseband are on.
+    STANDBY = "Standby"
+    #: The PLL is locked for transmit.
+    FS_TX = "FsTx"
+    #: One packet goes out, then the chip returns to standby.
+    TX = "Tx"
+    #: The PLL is locked for receive.
+    FS_RX = "FsRx"
+    #: The receiver takes packet after packet.
+    RX_CONTINUOUS = "RxContinuous"
+    #: The receiver waits for one packet or the symbol timeout.
+    RX_SINGLE = "RxSingle"
+    #: Channel activity detection looks for a LoRa preamble.
+    CAD = "Cad"
+
+
+def frequency_word(frequency_hz: int) -> int:
+    """Return the 24-bit RegFrf word for a frequency.
+
+    :param frequency_hz: The carrier frequency in hertz.
+    :returns: The frequency times 2^19 over the 32 MHz crystal, rounded to the nearest step.
+
+    >>> hex(frequency_word(868_100_000))
+    '0xd90666'
+    """
+    return _frequency_word(frequency_hz)
+
+
+def frequency_from_word(word: int) -> int:
+    """Return the frequency a RegFrf word selects.
+
+    :param word: The 24-bit frequency word.
+    :returns: The carrier frequency in hertz.
+    """
+    return _frequency_from_word(word)
+
+
+def read_address(address: int) -> int:
+    """Return the address byte that reads a register.
+
+    :param address: The register address.
+    :returns: The address with the write bit clear.
+    """
+    return _read_address(address)
+
+
+def write_address(address: int) -> int:
+    """Return the address byte that writes a register.
+
+    :param address: The register address.
+    :returns: The address with the write bit set.
+    """
+    return _write_address(address)
+
+
+def lora_op_mode(mode: Mode | str) -> int:
+    """Return the RegOpMode value for a LoRa operating mode.
+
+    :param mode: The operating mode.
+    :returns: The register value, with the LoRa register page selected.
+    :raises ValueError: If no mode goes by that name.
+    """
+    return _lora_op_mode(Mode(mode).value)
+
+
+def fsk_op_mode(mode: Mode | str) -> int:
+    """Return the RegOpMode value for an FSK operating mode, which image calibration needs.
+
+    :param mode: The operating mode.
+    :returns: The register value.
+    :raises ValueError: If no mode goes by that name.
+    """
+    return _fsk_op_mode(Mode(mode).value)
+
+
+def mode_from_op_mode(op_mode: int) -> Mode:
+    """Return the operating mode a RegOpMode value holds.
+
+    :param op_mode: The register value.
+    :returns: The mode.
+    """
+    return Mode(_mode_from_op_mode(op_mode))
+
+
+def modem(link: LoraLink, frequency_hz: int, symbol_timeout: int = 0) -> Modem:
+    """Return the LoRa modem registers for a link at a carrier.
+
+    :param link: The link settings.
+    :param frequency_hz: The carrier frequency, which rules out 250 and 500 kHz below 175 MHz.
+    :param symbol_timeout: A single reception timeout in symbols, whose top bits go in
+        RegModemConfig2.
+    :returns: RegModemConfig1 to 3 and the SF6 detection settings.
+    :raises PamojaError: If the SX127x cannot use the link at the carrier.
+    """
+    return _modem(link, frequency_hz, symbol_timeout)
+
+
+def symbol_timeout(link: LoraLink, timeout_us: int) -> int:
+    """Return a single reception timeout in the link's symbols.
+
+    :param link: The link settings, whose symbol time counts the timeout.
+    :param timeout_us: How long to listen for a preamble, in microseconds.
+    :returns: The timeout rounded up to whole symbols, from 4 to 1023.
+    """
+    return _symbol_timeout(link, timeout_us)
+
+
+def tx_power(output: PaOutput | str, output_dbm: int) -> TxPower:
+    """Choose the amplifier settings for an output power.
+
+    :param output: The amplifier output the module uses.
+    :param output_dbm: The output power wanted, in dBm.
+    :returns: The settings, clamped to what the output delivers.
+    :raises ValueError: If no output goes by that name.
+    """
+    return _tx_power(PaOutput(output).value, output_dbm)
+
+
+def tx_power_under_ceiling(
+    output: PaOutput | str, budget: LinkBudget, eirp_ceiling_dbm: float
+) -> TxPower:
+    """Choose the amplifier settings that keep a link's EIRP at or under a ceiling.
+
+    :param output: The amplifier output the module uses.
+    :param budget: The link budget, whose transmitting antenna and cable apply.
+    :param eirp_ceiling_dbm: The EIRP limit in dBm.
+    :returns: The settings, rounded down to whole decibels.
+    :raises ValueError: If no output goes by that name.
+    """
+    return _tx_power_under_ceiling(PaOutput(output).value, budget, eirp_ceiling_dbm)
+
+
+def ocp_register(milliamps: int) -> int:
+    """Return RegOcp for a current limit.
+
+    :param milliamps: The most current the amplifier may draw.
+    :returns: The register value with the protection on.
+    """
+    return _ocp_register(milliamps)
+
+
+def invert_iq(receive: bool, transmit: bool) -> int:
+    """Return RegInvertIQ for the IQ polarity of each path.
+
+    :param receive: Whether to invert the receive path, as a LoRaWAN device does for downlinks.
+    :param transmit: Whether to invert the transmit path, as a gateway does.
+    :returns: The register value, with the transmit bit set for normal IQ as the reference
+        drivers have it.
+    """
+    return _invert_iq(receive, transmit)
+
+
+def invert_iq_2(inverted: bool) -> int:
+    """Return RegInvertIQ2 for the path in use.
+
+    :param inverted: Whether that path is inverted.
+    :returns: 0x19 when inverted, else 0x1D.
+    """
+    return _invert_iq_2(inverted)
+
+
+def high_bw_optimize(link: LoraLink, frequency_hz: int) -> HighBwOptimize:
+    """Return the writes of the 500 kHz sensitivity erratum.
+
+    :param link: The link settings, whose bandwidth decides.
+    :param frequency_hz: The carrier frequency in hertz.
+    :returns: RegHighBwOptimize1 and, where it is written, RegHighBwOptimize2.
+    :raises PamojaError: If the SX127x has no such bandwidth.
+    """
+    return _high_bw_optimize(link, frequency_hz)
+
+
+def spurious_reception(link: LoraLink) -> SpuriousReception:
+    """Return the receive settings of the spurious reception erratum.
+
+    :param link: The link settings, whose bandwidth decides.
+    :returns: The automatic IF, the hand-set IF, and the carrier offset.
+    :raises PamojaError: If the SX127x has no such bandwidth.
+    """
+    return _spurious_reception(link)
+
+
+def image_cal_start(current: int) -> int:
+    """Return RegImageCal to start a calibration.
+
+    :param current: The register's current value.
+    :returns: The value with ImageCalStart set and AutoImageCalOn clear.
+    """
+    return _image_cal_start(current)
+
+
+def automatic_if(current: int, on: bool) -> int:
+    """Return RegDetectOptimize with AutomaticIFOn set or clear.
+
+    :param current: The register's current value.
+    :param on: Whether the automatic IF stays on.
+    :returns: The register value.
+    """
+    return _automatic_if(current, on)
+
+
+def packet_status(answer: bytes, frequency_hz: int) -> PacketStatus:
+    """Decode RegPktSnrValue and RegPktRssiValue, read together.
+
+    :param answer: The two register values, SNR first.
+    :param frequency_hz: The carrier the packet was heard at, which picks the RF port's offset.
+    :returns: The three signal levels, exact to a hundredth of a decibel.
+    :raises ValueError: If the answer is not two bytes.
+    """
+    return _packet_status(bytes(answer), frequency_hz)
+
+
+def rssi_dbm(byte: int, frequency_hz: int) -> float:
+    """Decode RegRssiValue.
+
+    :param byte: The register value.
+    :param frequency_hz: The carrier the receiver is tuned to.
+    :returns: The signal power the receiver hears right now, in dBm.
+    """
+    return _rssi_dbm(byte, frequency_hz)
+
+
+def modem_status(byte: int) -> ModemStatus:
+    """Decode RegModemStat.
+
+    :param byte: The register value.
+    :returns: The modem's live state.
+    """
+    return _modem_status(byte)

pamoja_radios-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-radios"
+version = "0.2.0"
+description = "The Semtech SX126x and SX127x LoRa radios and the SX1302 and SX1303 gateway concentrators: their commands, registers, and decoders, the amplifier setting a regional EIRP ceiling allows, a duty-cycle guard, and simulated chips that stand in for a module."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "radios"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/radios.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]