This directory contains example platform drivers for Nordic Semiconductor nRF52833 SoC.
To facilitate Thread products development with the nRF52833 platform, Nordic Semiconductor provides nRF5 SDK for Thread and Zigbee. See Nordic Semiconductor's nRF5 SDK for Thread and Zigbee section for more details.
Before you start building the examples, you must download and install the toolchain and the tools required for flashing and debugging.
Download and install the GNU toolchain for ARM Cortex-M.
To install the GNU toolchain and its dependencies, run the following commands in Bash:
$ cd <path-to-openthread> $ ./script/bootstrap
Install the nRF5 Command Line Tools to flash, debug, and make use of logging features on the nRF52833 DK with SEGGER J-Link.
To build the examples, run the following command in Bash:
$ cd <path-to-openthread> $ ./bootstrap $ make -f examples/Makefile-nrf52833
After a successful build, the elf files can be found in <path-to-openthread>/output/nrf52833/bin. You can convert them to hex using arm-none-eabi-objcopy:
$ arm-none-eabi-objcopy -O ihex ot-cli-ftd ot-cli-ftd.hex
You can build the libraries with support for the native USB CDC ACM as a serial transport. To do so, build the firmware with the following parameter:
$ make -f examples/Makefile-nrf52833 USB=1
Note that the USB CDC ACM serial transport is not supported with Engineering sample A of the nRF52833 chip.
If you are using Windows 7 or earlier, you must load an additional USB CDC driver. The driver can be found in third_party/NordicSemiconductor/libraries/usb/nordic_cdc_acm_example.inf.
The examples support the following bootloaders for performing a Device Firmware Upgrade (DFU):
The support for a particular bootloader can be enabled with the following switches:
BOOTLOADER=USBBOOTLOADER=UARTBOOTLOADER=BLEYou can build the libraries with support for native SPI Slave. To build the libraries, run make with the following parameter:
$ make -f examples/Makefile-nrf52833 NCP_SPI=1
With this option enabled, SPI communication between the NCP example and wpantund is possible (provided that the wpantund host supports SPI Master). To achieve that, an appropriate SPI device should be chosen in wpantund configuration file, /etc/wpantund.conf. You can find an example below.
Config:NCP:SocketPath "system:/usr/bin/spi-hdlc-adapter --gpio-int /sys/class/gpio/gpio25 /dev/spidev0.0"
In this example, spi-hdlc-adapter is a tool that you can use to communicate between NCP and wpantund over SPI. For this example, spi-hdlc-adapter is installed in /usr/bin.
The default SPI Slave pin configuration for nRF52833 is defined in examples/platforms/nrf52833/platform-config.h.
Note that the native SPI Slave support is not intended to be used with Engineering sample A of the nRF52833 chip due to single transfer size limitation.
You can prefix the compiler command using the CCPREFIX parameter. This speeds up the compilation when you use tools like ccache. Example usage:
$ make -f examples/Makefile-nrf52833 USB=1 CCPREFIX=ccache
By default, mbedTLS library is built without support for multiple threads. You can enable this built-in support by building OpenThread with the following parameter:
$ make -f examples/Makefile-nrf52833 MBEDTLS_THREADING=1
The simple mutex definition is used as shown below:
typedef void * mbedtls_threading_mutex_t;
However, you can modify it, by providing a path to a header file with proper definition. To do that, build OpenThread with the following parameter:
$ make -f examples/Makefile-nrf52833 MBEDTLS_THREADING=1 MBEDTLS_THREADING_MUTEX_DEF="path_to_a_header_file_with_mutex_definition.h"
See mbedTls Thread Safety and Multi Threading for more details.
When the Thread device is configured to obtain the Thread Network security credentials with either Thread Commissioning or an out-of-band method, the extended MAC address should be constructed out of the globally unique IEEE EUI-64.
The IEEE EUI-64 address consists of two parts:
By default, the device uses Nordic Semiconductor's MA-L (f4-ce-36). You can modify it by overwriting the OPENTHREAD_CONFIG_STACK_VENDOR_OUI define, located in the openthread-core-nrf52833-config.h file. This value must be publicly registered by the IEEE Registration Authority.
You can also provide the full IEEE EUI-64 address by providing a custom otPlatRadioGetIeeeEui64 function. To do this, define the flag OPENTHREAD_CONFIG_ENABLE_PLATFORM_EUI64_CUSTOM_SOURCE.
After the Thread Network security credentials have been successfully obtained, the device uses randomly generated extended MAC address.
Flash the compiled binaries onto nRF52833 using nrfjprog which is part of the nRF5 Command Line Tools.
$ nrfjprog -f nrf52 --chiperase --program output/nrf52833/bin/ot-cli-ftd.hex --reset
To test the example:
Prepare two boards with the flashed CLI Example (as shown above). The CLI FTD example uses the direct UART connection.
Open a terminal connection on two boards:
a. Start a terminal emulator like screen.
b. Connect to the used COM port with the following direct UART settings:
Baud rate: 115200
8 data bits
1 stop bit
No parity
HW flow control: RTS/CTS This allows you to view the raw UART output.
On Linux system a port name should be called e.g. /dev/ttyACM0 or /dev/ttyACM1.
c. Run the following command to connect to a board.
screen /dev/ttyACM0 115200
Now you are connected with the CLI.
Use the following commands to form a network on the first board.
> dataset init new Done > dataset Active Timestamp: 1 Channel: 13 Channel Mask: 07fff800 Ext PAN ID: d63e8e3e495ebbc3 Mesh Local Prefix: fd3d:b50b:f96d:722d/64 Master Key: dfd34f0f05cad978ec4e32b0413038ff Network Name: OpenThread-8f28 PAN ID: 0x8f28 PSKc: c23a76e98f1a6483639b1ac1271e2e27 Security Policy: 0, onrcb Done > dataset commit active Done > ifconfig up Done > thread start Done
After a couple of seconds the node will become a Leader of the network.
> state leader
Use the following commands to attach to the network on the second board.
> dataset masterkey dfd34f0f05cad978ec4e32b0413038ff Done > dataset commit active Done > ifconfig up Done > thread start Done
After a couple of seconds the second node will attach and become a Child.
> state child
List all IPv6 addresses of the first board.
> ipaddr fd3d:b50b:f96d:722d:0:ff:fe00:fc00 fd3d:b50b:f96d:722d:0:ff:fe00:c00 fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 fe80:0:0:0:6c41:9001:f3d6:4148 Done
Choose one of them and send an ICMPv6 ping from the second board.
> ping fd3d:b50b:f96d:722d:7a73:bff6:9093:9117 16 bytes from fd3d:b50b:f96d:722d:558:f56b:d688:799: icmp_seq=1 hlim=64 time=24ms
For a list of all available commands, visit OpenThread CLI Reference README.md.
SEGGER J-Link tools allow to debug and flash generated firmware using on-board debugger or external one.
By default, the OpenThread‘s logging module provides functions to output logging information over SEGGER’s Real Time Transfer (RTT).
You can set the desired log level by using the OPENTHREAD_CONFIG_LOG_LEVEL define.
To enable the highest verbosity level, append FULL_LOGS flag to the make command:
$ make -f examples/Makefile-nrf52833 FULL_LOGS=1
J-Link RTT Viewer. The configuration window appears.NRF52833_XXAA.SWD.JLinkExe to connect to the target. For example:JLinkExe -device NRF52833_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN <SEGGER_ID> -RTTTelnetPort 19021
JLinkRTTTelnet to obtain the RTT logs from the connected device in a separate console. For example:JLinkRTTClient -RTTTelnetPort 19021
Depending on your version, due to a known issue in SEGGER's J-Link firmware, you might experience data corruption or data drops if you use the serial port. You can avoid this issue by disabling the Mass Storage Device.
J-Link Commander. The configuration window appears.NRF52833_XXAA.SWD.MSDDisable
JLinkExe to connect to the target. For example:JLinkExe -device NRF52833_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN <SEGGER_ID>
MSDDisable
By default, SEGGER J-Link automatically detects at runtime whether the target is using Hardware Flow Control (HWFC).
The automatic HWFC detection is done by driving P0.07 (Clear to Send - CTS) from the interface MCU and evaluating the state of P0.05 (Request to Send - RTS) when the first data is sent or received. If the state of P0.05 (RTS) is high, it is assumed that HWFC is not used.
To avoid potential race conditions, you can force HWFC and bypass the runtime auto-detection.
J-Link Commander. The configuration window appears.NRF52833_XXAA.SWD.SetHWFC Force
JLinkExe to connect to the target. For example:JLinkExe -device NRF52833_XXAA -if SWD -speed 4000 -autoconnect 1 -SelectEmuBySN <SEGGER_ID>
SetHWFC Force
You can find more details here.
nRF52833 port extends OpenThread Diagnostics Module.
You can read about all the features here.
The radio driver comes with documentation that describes the operation of state machines in this module. To open the *.uml sequence diagrams, use PlantUML.
Use nRF5 Software Development Kit (SDK) for Thread and Zigbee when developing Thread products with Nordic Semiconductor's advanced nRF52840, nRF52833 or nRF52811 SoCs.
The nRF5 SDK for Thread and Zigbee includes: