Merge pull request #12344 from chrysn-pull-requests/particle-antenna-switch

particle-*: Configure antenna switch

boards/common/particle-mesh/Makefile.include

@@ -1,3 +1,7 @@
+# See doc.txt on nRF antenna selection
+BOARD_NRFANTENNA_DEFAULT ?= BUILTIN
+CFLAGS += -DBOARD_NRFANTENNA_DEFAULT=BOARD_NRFANTENNA_$(BOARD_NRFANTENNA_DEFAULT)
+
 # set default port depending on operating system
 PORT_LINUX ?= /dev/ttyUSB0
 PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.SLAB_USBtoUART*)))

boards/common/particle-mesh/board.c

@@ -23,6 +23,26 @@
 
 #include "periph/gpio.h"
 
+void board_nrfantenna_select(enum board_nrfantenna_selection choice)
+{
+    switch (choice) {
+        case BOARD_NRFANTENNA_BUILTIN:
+            /* Suppress output to the UFL connector */
+            gpio_set(VCTL1_PIN);
+#ifdef VCTL2_PIN
+            /* Enable output to the built-in antenna */
+            gpio_clear(VCTL2_PIN);
+#endif
+            break;
+        case BOARD_NRFANTENNA_EXTERNAL:
+            gpio_clear(VCTL1_PIN);
+#ifdef VCTL2_PIN
+            gpio_set(VCTL2_PIN);
+#endif
+            break;
+    }
+}
+
 void board_init(void)
 {
     /* initialize the boards LEDs */
@@ -33,6 +53,14 @@ void board_init(void)
     gpio_init(LED2_PIN, GPIO_OUT);
     gpio_set(LED2_PIN);
 
+    gpio_init(VCTL1_PIN, GPIO_OUT);
+#ifdef VCTL2_PIN
+    /* On boards without VCLT2_PIN (Boron), the VCTL2 net is driven by NOT(VCTL1) */
+    gpio_init(VCTL2_PIN, GPIO_OUT);
+#endif
+
+    board_nrfantenna_select(BOARD_NRFANTENNA_DEFAULT);
+
     /* initialize the CPU */
     cpu_init();
 }

boards/common/particle-mesh/doc.txt

@@ -50,4 +50,18 @@ The STDIO is not accessible via the USB port.
 To access the STDIO of RIOT, a FTDI to USB converter needs to be plugged to
 the RX/TX pins on the board.
 
+### nRF antenna selection
+
+The Particle Mesh boards all have two antenna choices for their nRF (Bluetooth
+/ 802.15.4) radios, a on-board antenna and a U.FL connector for an external
+antenna.
+
+By default, the on-board antenna is selected at startup. That choice can be
+overridden by setting ``BOARD_NRFANTENNA_DEFAULT = EXTERNAL`` (as opposed to
+the default ``BUILTIN``) in a project's `Makefile`, or at runtime using @ref
+board_nrfantenna_select function.
+
+The external antenna connection should only be enabled if a suitable antenna is
+connected.
+
  */

boards/common/particle-mesh/include/board.h

@@ -61,6 +61,61 @@ extern "C" {
 #define BTN0_MODE           GPIO_IN_PU
 /** @} */
 
+/**
+ * @name    Antenna selection configuration
+ * @{
+ */
+
+/** Choices in antenna outputs for the board's nRF radio
+ *
+ * @see board_nrfantenna_select */
+enum board_nrfantenna_selection {
+    /** The board's built-in antenna */
+    BOARD_NRFANTENNA_BUILTIN,
+    /** The board's uFL connector */
+    BOARD_NRFANTENNA_EXTERNAL,
+};
+
+/** @brief Antenna output selection
+ *
+ * Drive the on-board antenna switch to connect the nRF radio to a given @p
+ * choice of antenna output.
+ *
+ * This can be called to change the antenna selection at runtime; for the
+ * default configuration that gets set during board initialization, see @ref
+ * boards_common_particle-mesh.
+ * */
+void board_nrfantenna_select(enum board_nrfantenna_selection choice);
+
+#if defined(BOARD_PARTICLE_XENON) || defined(DOXYGEN)
+/** The GPIO pin used to drive the VCTL1 pin of antenna switch
+ *
+ * Rather than actuating this directly, consider using the @ref
+ * board_nrfantenna_select function.
+ */
+#define VCTL1_PIN           GPIO_PIN(0, 24)
+/** The GPIO pin used to drive the VCTL2 pin of antenna switch
+ *
+ * This definition is left out for boards whose VCTL2 is driven by an inverter
+ * from VCTL1.
+ *
+ * Rather than actuating this directly, consider using the @ref
+ * board_nrfantenna_select function.
+ */
+#define VCTL2_PIN           GPIO_PIN(0, 25)
+#endif
+
+#ifdef BOARD_PARTICLE_ARGON
+#define VCTL1_PIN           GPIO_PIN(0, 25)
+#define VCTL2_PIN           GPIO_PIN(0, 2)
+#endif
+
+#ifdef BOARD_PARTICLE_BORON
+#define VCTL1_PIN           GPIO_PIN(0, 7)
+#endif
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif