stm32/subghz: Add STM32WL55 subghz radio interface to stm module.

This is the minimum C interface to allow a modem driver to be built in
Python.  Interface is simple, with the intention that the micropython-lib
driver is the main (only) consumer of it.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

1 files changed, 36 insertions, 0 deletions

diff --git a/docs/library/stm.rst b/docs/library/stm.rst
index a181d6044..970ab1883 100644
--- a/docs/library/stm.rst
+++ b/docs/library/stm.rst
@@ -102,3 +102,39 @@ the second CPU, the RF core.
     Execute a HCI command on the SYS channel.  The execution is synchronous.
 
     Returns a bytes object with the result of the SYS command.
+
+Functions specific to STM32WLxx MCUs
+------------------------------------
+
+These functions are available on STM32WLxx microcontrollers, and interact with
+the integrated "SUBGHZ" radio modem peripheral.
+
+.. function:: subghz_cs(level)
+
+   Sets the internal SPI CS pin attached to the radio peripheral. The ``level``
+   argument is active-low: a truthy value means "CS pin high" and de-asserts the
+   signal, a falsey value means "CS pin low" and asserts the signal.
+
+   The internal-only SPI bus corresponding to this CS signal can be instantiated
+   using :ref:`machine.SPI()<machine.SPI>` ``id`` value ``"SUBGHZ"``.
+
+.. function:: subghz_irq(handler)
+
+   Sets the internal SUBGHZ radio interrupt handler to the provided
+   function. The handler function is called as a "hard" interrupt in response to
+   radio peripheral interrupts. See :ref:`isr_rules` for more information about
+   interrupt handlers in MicroPython.
+
+   Calling this function with the handler argument set to None disables the IRQ.
+
+   Due to a hardware limitation, each time this IRQ fires MicroPython disables
+   it before calling the handler. In order to receive another interrupt, Python
+   code should call ``subghz_irq()`` to set the handler again. This has the side
+   effect of re-enabling the IRQ.
+
+.. function:: subghz_is_busy()
+
+   Return a ``bool`` corresponding to the internal "RFBUSYS" signal from the
+   radio peripheral. Before sending a new command to the radio over SPI then
+   this function should be polled until it returns ``False``, to confirm the
+   busy signal is de-asserted.