.. _module-pw_sys_io_stm32cube:

-------------------
pw_sys_io_stm32cube
-------------------

``pw_sys_io_stm32cube`` implements the ``pw_sys_io`` facade over UART using
the STM32Cube HAL to support an assortment of boards from STMicroelectronics.

The UART baud rate is fixed at 115200 (8N1).

Setup
=====
This module requires relatively minimal setup:

  1. Write code against the ``pw_sys_io`` facade.
  2. Specify the ``dir_pw_sys_io_backend`` GN global variable to point to this
     backend.
  3. Call ``pw_sys_io_Init()`` during init so the UART is properly initialized
     and configured.

For devices other than the STM32F429I-DISC1, this module will need to be
configured to use the appropriate GPIO pins and USART peripheral.

Module Configuration Options
============================
The following configurations can be adjusted via compile-time configuration of
this module, see the
:ref:`module documentation <module-structure-compile-time-configuration>` for
more details.

.. c:macro:: PW_SYS_IO_STM32CUBE_USART_NUM

  The USART peripheral number to use. (1 for USART1, 2 for USART2, etc.)

.. c:macro:: PW_SYS_IO_STM32CUBE_GPIO_PORT

  The port that the USART peripheral TX/RX pins are on. (e.g. to use A9/A10
  pins for TX and RX, respectively, set this to A)

  This defaults to 64 Bytes.

.. c:macro:: PW_SYS_IO_STM32CUBE_GPIO_TX_PIN

  The pin index to use for USART transmission within the port set by
  ``PW_SYS_IO_STM32CUBE_GPIO_PORT``.

.. c:macro:: PW_SYS_IO_STM32CUBE_GPIO_RX_PIN

  The pin index to use for USART reception within the port set by
  ``PW_SYS_IO_STM32CUBE_GPIO_PORT``.

.. c:macro:: PW_SYS_IO_STM32CUBE_GPIO_AF

  The alternate function index to use for USART reception within the port set by
  ``PW_SYS_IO_STM32CUBE_GPIO_PORT``.

Module usage
============
After building an executable that utilizes this backend, flash the
produced .elf binary to the development board. Then, using a serial
communication terminal like minicom/screen (Linux/Mac) or TeraTerm (Windows),
connect to the device at a baud rate of 115200 (8N1). If you're not using a
STM32F429I-DISC1 development board, manually connect a USB-to-serial TTL adapter
to pins ``PA9`` (MCU TX) and ``PA10`` (MCU RX), making sure to match logic
levels (e.g. 3.3V versus 1.8V).

Sample connection diagram
-------------------------

.. code-block:: text

  --USB Serial--+    +-----STM32F429 MCU-----
                |    |
             TX o--->o PA10/USART1_RX
                |    |
             RX o<---o PA9/USART1_TX
                |    |
  --------------+    +-----------------------