As of the June 2017 release of the Silicon Labs Gecko SDK Suite, the mesh stacks (EmberZNet 5.10, Silicon Labs Thread 2.3) have moved over to a new board definition style for HAL peripheral configuration on EFR32 platforms.  This KBA will explain some of the differences from the old format and how to craft a proper HAL config file for your custom hardware.


HAL Config

The HAL Config framework is a set of standardized configuration options which can be used to initialize and customize hardware peripherals and drivers. These options, spanning from antenna diversity GPIO to enabling the watchdog, are constructed with three components:


Prefix - There are two prefixes for HAL config defines: BSP and HAL. As the name suggests, BSP (board support package) type options relate to the board design, for example GPIO route locations, clock/crystal options, and DCDC usage.


Module - There are 19 HAL config modules:

  • CLK
  • DCDC
  • LED
  • PA
  • PTA
  • PTI
  • RHO
  • VCOM
  • WDOG

Each module pertains to a set of hardware features based on an underlying peripheral and/or software enhancements.


Option - Each module can be customized by defining configuration options. These might include enabling/disabling the module, specifying a peripheral signal route location, or mode to initialize the module. A full list of HAL Config options can be found in the attached pdf, along with values and descriptions. Links to the options in html format are also provided here:

HAL Configuration Options Table Part 1

HAL Configuration Options Table Part 2


What's Changed?

Board Headers:

  • All Gecko SDK Suite 1.1 EFR and EZR board headers have been migrated to use HAL Config options.
  • The new board headers are standalone, meaning no BSP dependencies. All options are defined within the board header and can be freely customized.
  • Removed preprocessor function definitions. Board headers now only contain definitions of options and values.

HAL Configuration Plugin:

  • New plugin provides an interface to easily modify common configuration options:
  • Enable antenna diversity, PTA, RHO, RX wakeup, VCOM, VUART, WDOG, and any LEUART/USART
  • Set UART flow control modes and UART NCP port
  • Sample apps are pre-configured to use correct HAL Config options.

HAL Configuration Plugin


HAL Configuration in Gecko SDK Suite 1.1

HAL Config  currently only applies to EFR32/EZR32 devices in Zigbee, Thread, and Flex.

  1. SDK 1.1 based projects
    • All sample apps will generate and compile out-of-box with a board header which follows the HAL Config framework and appropriate HAL Config plugin options. To customize, select options in the HAL Config plugin and/or modify the board header according to the HAL Config framework options found in the attached pdf.
  2. Migrating from previous SDK
    • A project created with a previous SDK will require some manual migration before it can compile/run properly. To migrate a project:
      1. Select appropriate HAL Configuration plugin options. The plugin is automatically enabled with some default options which may not be required.
      2. Generate and overwrite the project board header (making sure to preserve the backup). The previously generated board header will no longer work in Gecko SDK Suite 1.1.
      3. Compare newly generated board header with backed up header; modify as necessary.


How do I change which pins my UART uses?

  1. Make sure VCOM is not enabled in the HAL Configuration plugin.
  2. Check which UART is being used for your application. For SoC applications, this is the application serial port (found in the HAL Tab). For NCP apps, this can be found in the HAL Configuration plugin.
  3. Modify the selected UART options in your board header or add them if not already present. Here is an example:
// -----------------------------------------------------------------------------
/* USART0 */
#define BSP_USART0_CTS_PIN 2
#define BSP_USART0_CTS_PORT gpioPortA
#define BSP_USART0_RTS_PIN 3
#define BSP_USART0_RTS_PORT gpioPortA
#define BSP_USART0_RX_PIN 1
#define BSP_USART0_RX_PORT gpioPortA
#define BSP_USART0_TX_PIN 0
#define BSP_USART0_TX_PORT gpioPortA

How do I disable/enable buttons or LEDs?

It is no longer necessary to define HalBoardLedPins nor a BUTTON_ISR in the board header. Instead, LEDs and buttons are now defined in a two part interface. GPIO locations are all defined under the BSP prefix like so:

// -----------------------------------------------------------------------------
/* BUTTON */
// Enable two buttons, 0 and 1
#define HAL_BUTTON_ENABLE { 0, 1 }
// Board has two buttons
{ \
// Initialize button GPIO DOUT to 0
// Initialize button GPIO mode as input
// Define individual button GPIO port/pin
#define BSP_BUTTON0_PORT gpioPortF
#define BSP_BUTTON0_PIN 6
#define BSP_BUTTON1_PORT gpioPortF
#define BSP_BUTTON1_PIN 7

In addition, there are two HAL options: COUNT and ENABLE. Set HAL_BUTTON/LED_COUNT to 0 to disable buttons/leds or any non-zero number (less than BSP_BUTTON/LED_COUNT) to enable. Then enter the indices of the buttons(according to BSP_BUTTON/LED_INIT) which should be enabled in the HAL_BUTTON_ENABLE array.


How do I specify a LFXO (or not)?

The LFCLK source can now be defined by setting HAL_CLK_LFCLK_SOURCE as HAL_CLK_LFCLK_SOURCE_LFRCO. This will automatically propogate to other drivers, so it is not necessary to define RTCDRV_USE_LFRCO anymore.


How do I disable VCOM/What is VCOM?

VCOM is the virtual communications port which serves passes UART communication to the USB/ethernet connection on the WSTK. When enabled, VCOM settings will override whichever UART it is configured to (note the underlying UART must also be enabled). VCOM is enabled by default on most EFR32 and EZR32 projects. However, if you wish to disable it, either for use on a WSTK or custom hardware, simply disable it via the HAL Configuration plugin. Note, ENABLE_EXP_UART is now deprecated. Also note


Known Issues

  • When selecting the HAL Configuration using the search function, the plugin options may fail to display.
  • VUART must be enabled for Thread NCPs to run.
  • BSP_VCOM_PRESENT not currently active; use the plugin to set VCOM to 0 or 1.

  • ZigBee and Thread
  • Knowledge Base Articles
  • Does this mean the board header file which needs to modify manually? Are there any template files to refer?



  • Hi Ray25,


    The material here is related to a combination of Plugin settings and some board header changes to supplement the interface picks.


    When you generate your project, the board header will already contain a lot of defines you can use for examples.