modules: hal_silabs: Add Proprietary TRX example

Add Proprietary TRX example to show SiliconLabs radio board capabilities.

Signed-off-by: Zoltan Havas <[email protected]>

examples/License.txt

@@ -0,0 +1,26 @@
+# Example Licensing terms
+
+Source code in this example folder is covered by one of several different
+licenses. The default license is the Zlib which applies unless otherwise noted.
+
+Some files may use different licensing terms. If so, they will be clearly
+marked in the beginning of the file.
+
+## Zlib license
+The licensor of this software is Silicon Laboratories Inc.
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.

examples/proprietary_trx/CMakeLists.txt

@@ -0,0 +1,22 @@
+# Copyright (c) 2023 Silicon Laboratories Inc.
+# SPDX-License-Identifier: Zlib
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(propriatery_trx)
+
+target_include_directories(app PRIVATE
+    src/
+    src/autogen/
+    src/config/
+    src/config/rail
+    src/config/rail/${CONFIG_BOARD}
+)
+
+target_sources(app PRIVATE src/main.c)
+target_sources(app PRIVATE src/app_gpio.c)
+target_sources(app PRIVATE src/app_cli.c)
+target_sources(app PRIVATE src/app_rail.c)
+target_sources(app PRIVATE src/autogen/sl_rail_util_callbacks.c)
+target_sources(app PRIVATE src/autogen/sl_rail_util_init.c)
+target_sources(app PRIVATE src/config/rail/${CONFIG_BOARD}/rail_config.c)

examples/proprietary_trx/README.rst

@@ -0,0 +1,114 @@
+Proprietary TRX
+###############
+
+Overview
+********
+
+The Proprietary TRX example demonstrates the simplest exchange of transmit and
+receive operation between two nodes implemented in RAIL.
+
+This application can be used for setting up a simple link test, where the nodes
+are listening except for the short periods where packet transmission takes
+place. Also, this application can be used as a learning material.
+
+Requirements
+************
+
+This application requires part or board that support RAIL, has radio antenna 
+connection and has at least one LED and one button.
+
+Building and Running
+********************
+
+This sample can be built for multiple boards, in this example we will build it
+for the efr32bg22_brd4184a board:
+
+.. code-block:: bash
+
+    west build -p always -b efr32bg22_brd4184a
+
+
+This example implements both the receiver (RX) and the transmitter (TX) nodes.
+The implementation is therefore symmetric, as both nodes are capable of sending
+and receiving messages. In this document the use of `RX node` and `TX node` are
+implicit and these terms refer the devices temporary, while the denoted
+operations are performed.
+
+Compile the project and download the application to two radio boards.
+
+On startup the Zephyr boot will be displayed, with additional information
+about the RAIL library version. 
+
+The devices start in the receiving state.
+
+Issue the `send` command on the TX node to request packet transmission:
+
+.. code-block:: bash
+
+    send
+    > Send packet request
+
+Additional logs can be viewed by the logger, which can be turned off.
+
+On the receiver side the following response will be printed out on packet
+reception:
+
+.. code-block:: bash
+
+    > Packet has been received: 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77,
+                                0x88, 0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 
+
+Additional logs can be viewed by the logger, which can be turned off.
+
+If the reception is enabled the device will automatically switch back to RX mode
+either after a successful or faulty reception or a transmission.
+
+
+The reception can be disabled by the `receive` command.
+
+.. code-block:: bash
+
+    receive 0
+    > Continues packet receiving is OFF
+
+Receive mode can be enabled again by the same command:
+
+.. code-block:: bash
+
+    receive 1
+    > Continues packet receiving is ON
+
+
+Peripherals
+***********
+
+Same working can be achieved by pushing button or buttons and waiting for the 
+led or LEDs to toggle.
+
+Radio settings
+**************
+
+For changing any settings for the used radio or radio phy please re-generate 
+the rail_config.c and rail_config.h files use 
+Simplicity Studio's `EFR32 Radio Configurator`_.
+
+.. _EFR32 Radio Configurator: https://www.silabs.com/documents/public/application-notes/an1253-efr32-radio-configurator-guide-for-ssv5.pdf
+
+Advance settings
+****************
+
+For advance user settings please use Simplicity Studio's slc generator, where
+more settings can be generated for rail components. If new settings are ready,
+they should be copied from Simplicity Studio config folder to `hal/silabs/gecko`
+folder and overwrite their original file. For example after editing with slc
+the RAIL Utility component user should copy `sl_rail_util_init_inst0_config.h``
+to `gecko/platform/radio/rail_lib/plugin/rail_util_init/config/proprietary/``
+
+Extra Resources
+***************
+
+- `RAIL Tutorial Series`_:
+  it is advised to read through the `Studio v5 series` first to familiarize the
+  basics of packet transmission and reception
+
+.. _RAIL Tutorial Series: https://community.silabs.com/s/article/rail-tutorial-series?language=en_US

examples/proprietary_trx/boards/efr32bg22_brd4184a.overlay

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2023 Silicon Laboratories Inc.
+ * SPDX-License-Identifier: Zlib
+ */
+
+&cpu0 {
+	cpu-power-states = <&pstate_em1>;
+};

examples/proprietary_trx/boards/efr32bg22_brd4184b.overlay

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2023 Silicon Laboratories Inc.
+ * SPDX-License-Identifier: Zlib
+ */
+
+&cpu0 {
+	cpu-power-states = <&pstate_em1>;
+};

examples/proprietary_trx/boards/efr32mg22_brd4182a.overlay

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2023 Silicon Laboratories Inc.
+ * SPDX-License-Identifier: Zlib
+ */
+
+&cpu0 {
+	cpu-power-states = <&pstate_em1>;
+};

examples/proprietary_trx/boards/efr32xg24_dk2601b.overlay

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2023 Silicon Laboratories Inc.
+ * SPDX-License-Identifier: Zlib
+ */
+
+&cpu0 {
+	cpu-power-states = <&pstate_em0>;
+};

examples/proprietary_trx/prj.conf

@@ -0,0 +1,15 @@
+# Copyright (c) 2024 Silicon Laboratories Inc.
+# SPDX-License-Identifier: Zlib
+CONFIG_GPIO=y
+CONFIG_SOC_GECKO_CUSTOM_RADIO_PHY=y
+CONFIG_FPU=y
+CONFIG_PM=y
+CONFIG_PRINTK=y
+CONFIG_LOG=y
+CONFIG_SHELL=y
+CONFIG_EVENTS=y
+CONFIG_ASSERT=y
+CONFIG_BOOT_BANNER=y
+CONFIG_POSIX_CLOCK=y
+CONFIG_INIT_STACKS=y
+CONFIG_SMF=y

examples/proprietary_trx/prj_efr32xg24_dk2601b.conf

@@ -0,0 +1,14 @@
+# Copyright (c) 2023 Silicon Laboratories Inc.
+# SPDX-License-Identifier: Zlib
+CONFIG_GPIO=y
+CONFIG_SOC_GECKO_CUSTOM_RADIO_PHY=y
+CONFIG_FPU=y
+CONFIG_PRINTK=y
+CONFIG_LOG=y
+CONFIG_SHELL=y
+CONFIG_EVENTS=y
+CONFIG_ASSERT=y
+CONFIG_BOOT_BANNER=y
+CONFIG_POSIX_CLOCK=y
+CONFIG_INIT_STACKS=y
+CONFIG_SMF=y

examples/proprietary_trx/src/app_cli.c

@@ -0,0 +1,84 @@
+/***************************************************************************//**
+ * @file app_cli.c
+ * @brief CLI commands for the proprietary_trx example.
+ *******************************************************************************
+ * # License
+ * <b>Copyright 2024 Silicon Laboratories Inc. www.silabs.com</b>
+ *******************************************************************************
+ *
+ * SPDX-License-Identifier: Zlib
+ *
+ * The licensor of this software is Silicon Laboratories Inc.
+ *
+ * This software is provided 'as-is', without any express or implied
+ * warranty. In no event will the authors be held liable for any damages
+ * arising from the use of this software.
+ *
+ * Permission is granted to anyone to use this software for any purpose,
+ * including commercial applications, and to alter it and redistribute it
+ * freely, subject to the following restrictions:
+ *
+ * 1. The origin of this software must not be misrepresented; you must not
+ *    claim that you wrote the original software. If you use this software
+ *    in a product, an acknowledgment in the product documentation would be
+ *    appreciated but is not required.
+ * 2. Altered source versions must be plainly marked as such, and must not be
+ *    misrepresented as being the original software.
+ * 3. This notice may not be removed or altered from any source distribution.
+ *
+ ******************************************************************************/
+
+// -----------------------------------------------------------------------------
+// Includes
+
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/sys/util.h>
+#include <zephyr/sys/printk.h>
+#include <inttypes.h>
+#include <zephyr/shell/shell.h>
+#include <zephyr/logging/log.h>
+#include <stdlib.h>
+#include "em_chip.h"
+#include "main.h"
+
+// -----------------------------------------------------------------------------
+// Public Function Definitions
+
+/******************************************************************************
+ * CLI - send: Sets a flag indicating that a packet has to be sent
+ *****************************************************************************/
+void cli_send_packet(const struct shell *sh, size_t argc, char **argv)
+{
+	shell_fprintf(sh, SHELL_NORMAL, "Send packet request\n");
+	k_event_post(&s_sl_machine.smf_event, EVENT_REQUEST_SEND);
+}
+
+/******************************************************************************
+ * CLI - info message: Unique ID of the board
+ *****************************************************************************/
+void cli_info(const struct shell *sh, size_t argc, char **argv)
+{
+	shell_fprintf(sh, SHELL_NORMAL, "Info:\n");
+	shell_fprintf(sh, SHELL_NORMAL, "  MCU Id:       0x%llx\n", SYSTEM_GetUnique());
+}
+
+/******************************************************************************
+ * CLI - receive: Turn on/off continues packet receiving
+ *****************************************************************************/
+void cli_receive_packet(const struct shell *sh, size_t argc, char **argv)
+{
+	unsigned long continues_receive = strtoul(argv[1], NULL, 0);
+	s_sl_machine.allow_rx = continues_receive;
+	shell_fprintf(sh, SHELL_NORMAL, "Continues packet receiving is %s\n",
+		      (continues_receive == 0) ? "OFF" : "ON");
+	k_event_post(&s_sl_machine.smf_event, EVENT_CLI_RECEIVE_SETTING);
+}
+
+SHELL_CMD_ARG_REGISTER(info, NULL, "Display unique ID of the MCU", cli_info, 1, 0);
+
+SHELL_CMD_ARG_REGISTER(send, NULL, "Send a packet", cli_send_packet, 1, 0);
+
+SHELL_CMD_ARG_REGISTER(receive, NULL, "Turn ON/OFF continues packet receiving", cli_receive_packet,
+		       2, 0);