diff --git a/boards/shields/openthread_rcp_arduino/Kconfig.defconfig b/boards/shields/openthread_rcp_arduino/Kconfig.defconfig new file mode 100644 index 00000000000..8d31821441e --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/Kconfig.defconfig @@ -0,0 +1,19 @@ +# Copyright 2025 Basalte bv +# SPDX-License-Identifier: Apache-2.0 + +if SHIELD_OPENTHREAD_RCP_ARDUINO_SERIAL || SHIELD_OPENTHREAD_RCP_ARDUINO_SPI + +if OPENTHREAD + +config SERIAL + default y if SHIELD_OPENTHREAD_RCP_ARDUINO_SERIAL + +config SPI + default y if SHIELD_OPENTHREAD_RCP_ARDUINO_SPI + +config HDLC_RCP_IF + default y + +endif # OPENTHREAD + +endif diff --git a/boards/shields/openthread_rcp_arduino/Kconfig.shield b/boards/shields/openthread_rcp_arduino/Kconfig.shield new file mode 100644 index 00000000000..7916cc83cd9 --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/Kconfig.shield @@ -0,0 +1,8 @@ +# Copyright 2025 Basalte bv +# SPDX-License-Identifier: Apache-2.0 + +config SHIELD_OPENTHREAD_RCP_ARDUINO_SERIAL + def_bool $(shields_list_contains,openthread_rcp_arduino_serial) + +config SHIELD_OPENTHREAD_RCP_ARDUINO_SPI + def_bool $(shields_list_contains,openthread_rcp_arduino_spi) diff --git a/boards/shields/openthread_rcp_arduino/doc/index.rst b/boards/shields/openthread_rcp_arduino/doc/index.rst new file mode 100644 index 00000000000..245abe140cd --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/doc/index.rst @@ -0,0 +1,136 @@ +.. _openthread_rcp_arduino_shield: + +OpenThread RCP over Arduino header +################################## + +Overview +******** + +This (virtual) shield can be used to connect a board with an Arduino R3 compatible header to an +external `OpenThread RCP`_ device. The RCP device would function as the Thread radio, while another +board can function as the OpenThread host. + +Requirements +************ + +An RCP radio device is needed for this shield to work. As an example, the reference from +OpenThread using the :zephyr:board:`nrf52840dk` is chosen as a demonstration. Refer to the +`OpenThread on nRF52840 Example website`_. + +Both UART and SPI can be used as the transport, depending on the board connections. + +The following was executed on Ubuntu 24.04 to build and flash the RCP firmware: + +Preparation +=========== + +.. code-block:: bash + + git clone https://github.com/openthread/ot-nrf528xx.git --recurse-submodules + cd ot-nrf528xx + python3 -m venv .venv + source .venv/bin/activate + ./script/bootstrap + +Building +======== + +.. tabs:: + + .. group-tab:: UART + + .. code-block:: bash + + # Set -DOT_PLATFORM_DEFINES="UART_HWFC_ENABLED=1" to enable flow control + ./script/build nrf52840 UART_trans -DOT_PLATFORM_DEFINES="UART_HWFC_ENABLED=0" + + .. group-tab:: SPI + + .. code-block:: bash + + ./script/build nrf52840 SPI_trans_NCP + +Flashing +======== + +.. code-block:: bash + + arm-none-eabi-objcopy -O ihex build/bin/ot-rcp build/bin/ot-rcp.hex + nrfjprog -f nrf52 --chiperase --program build/bin/ot-rcp.hex --reset + +Pins Assignments +================ + +The RCP firmware comes with default pins assigned, the following table lists both the Arduino header +pins and the nRF52840DK pins. + +.. tabs:: + + .. group-tab:: UART + + +-----------------------+-----------------------+-----------------------+ + | Arduino Header Pin | Function (host) | nRF52840 DK Pin | + +=======================+=======================+=======================+ + | D0 | UART RX | P0.06 | + +-----------------------+-----------------------+-----------------------+ + | D1 | UART TX | P0.08 | + +-----------------------+-----------------------+-----------------------+ + | Host specific | UART CTS | P0.05 (flow control) | + +-----------------------+-----------------------+-----------------------+ + | Host specific | UART RTS | P0.07 (flow control) | + +-----------------------+-----------------------+-----------------------+ + + .. group-tab:: SPI + + +-----------------------+-----------------------+-----------------------+ + | Arduino Header Pin | Function | nRF52840 DK Pin | + +=======================+=======================+=======================+ + | D8 | RSTn | P0.18/RESET | + +-----------------------+-----------------------+-----------------------+ + | D9 | INTn | P0.30 | + +-----------------------+-----------------------+-----------------------+ + | D10 | SPI CSn | P0.29 | + +-----------------------+-----------------------+-----------------------+ + | D11 | SPI MOSI | P0.04 | + +-----------------------+-----------------------+-----------------------+ + | D12 | SPI MISO | P0.28 | + +-----------------------+-----------------------+-----------------------+ + | D13 | SPI SCK | P0.03 | + +-----------------------+-----------------------+-----------------------+ + +Programming +*********** + +Include ``--shield openthread_rcp_arduino_serial`` or ``--shield openthread_rcp_arduino_spi`` +when you invoke ``west build`` for projects utilizing this shield. For example: + +.. tabs:: + + .. group-tab:: UART + + .. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/echo_client + :board: stm32h573i_dk/stm32h573xx + :shield: openthread_rcp_arduino_serial + :conf: "prj.conf overlay-ot-rcp-host-uart.conf" + :goals: build + + .. group-tab:: SPI + + .. zephyr-app-commands:: + :zephyr-app: samples/net/sockets/echo_client + :board: stm32h573i_dk/stm32h573xx + :shield: openthread_rcp_aduino_spi + :conf: "prj.conf overlay-ot-rcp-host-uart.conf" + :goals: build + +References +********** + +.. target-notes:: + +.. _OpenThread RCP: + https://openthread.io/platforms/co-processor + +.. _OpenThread on nRF52840 Example website: + https://github.com/openthread/ot-nrf528xx/blob/main/src/nrf52840/README.md diff --git a/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_serial.overlay b/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_serial.overlay new file mode 100644 index 00000000000..42b61cfb2cb --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_serial.overlay @@ -0,0 +1,25 @@ +/* + * Copyright 2025 Basalte bv + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * Overlay to enable support for OpenThread's RCP over UART communication + */ + +/ { + chosen { + zephyr,hdlc-rcp-if = &hdlc_rcp_if; + zephyr,ot-uart = &arduino_serial; + }; + + hdlc_rcp_if: hdlc_rcp_if { + compatible = "uart,hdlc-rcp-if"; + }; +}; + +&arduino_serial { + status = "okay"; + current-speed = <115200>; +}; diff --git a/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_spi.overlay b/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_spi.overlay new file mode 100644 index 00000000000..1d8dc34dede --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/openthread_rcp_arduino_spi.overlay @@ -0,0 +1,29 @@ +/* + * Copyright 2025 Basalte bv + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/** + * Overlay to enable support for OpenThread's RCP over SPI communication + */ + +/ { + chosen { + zephyr,hdlc-rcp-if = &hdlc_rcp_if; + }; +}; + +&arduino_spi { + status = "okay"; + + hdlc_rcp_if: hdlc_rcp_if@0 { + compatible = "spi,hdlc-rcp-if"; + status = "okay"; + reg = <0>; + + spi-max-frequency = <1000000>; /* 1 MHz to support most devices */ + int-gpios = <&arduino_header 15 GPIO_ACTIVE_LOW>; /* D9 */ + reset-gpios = <&arduino_header 14 GPIO_ACTIVE_LOW>; /* D8 */ + }; +}; diff --git a/boards/shields/openthread_rcp_arduino/shield.yml b/boards/shields/openthread_rcp_arduino/shield.yml new file mode 100644 index 00000000000..2270454ac0b --- /dev/null +++ b/boards/shields/openthread_rcp_arduino/shield.yml @@ -0,0 +1,12 @@ +shields: + - name: openthread_rcp_arduino_serial + full_name: OpenThread RCP over Arduino UART + vendor: others + supported_features: + - hdlc_rcp_if + + - name: openthread_rcp_arduino_spi + full_name: OpenThread RCP over Arduino SPI + vendor: others + supported_features: + - hdlc_rcp_if