An example application showing the use CHIP on the Nordic nRF52840.
The nRF52840 lock example application provides a working demonstration of a connected door lock device, built using CHIP, and the Nordic nRF Connect. The example supports remote access and control of a simulated door lock over a low-power, 802.15.4 Thread network. It is capable of being paired into an existing CHIP network along with other CHIP-enabled devices. The example targets the Nordic nRF52840 DK development kit, but is readily adaptable to other nRF52840-based hardware.
The lock example is intended to serve both as a means to explore the workings of CHIP, as well as a template for creating real products based on the Nordic platform.
The example makes use of the CMake build system to generate the ninja build script. The build system takes care of invoking the CHIP library build with all necessary flags exported from the Zephyr environment.
The example application provides a simple UI that depicts the state of the device and offers basic user control. This UI is implemented via the general-purpose LEDs and buttons built in to the nRF52840 DK dev board.
LED #1 shows the overall state of the device and its connectivity. Four states are depicted:
Button #1 can be used to initiate a OTA software update as well as to reset the device to a default state.
Pressing and holding Button #1 for 6 seconds initiates a factory reset. After an initial period of 3 seconds, all four LED will flash in unison to signal the pending reset. Holding the button past 6 seconds will cause the device to reset its persistent configuration and initiate a reboot. The reset action can be cancelled by releasing the button at any point before the 6 second limit.
LED #2 shows the state of the simulated lock bolt. When the LED is lit the bolt is extended (i.e. door locked); when not lit, the bolt is retracted (door unlocked). The LED will flash whenever the simulated bolt is in motion from one position to another.
Button #2 can be used to change the state of the simulated bolt. This can be used to mimick a user manually operating the lock. The button behaves as a toggle, swapping the state every time it is pressed.
Button #3 can be used to start Thread networking using default configuration which was selected to match OpenThread Border Router default settings and network credentials.
The remaining two LEDs (#3 and #4) and button #4 are unused.
Important:
Due to certain limitations of Docker for MacOS it is impossible to use the Docker container to communicate with a USB device such as nRF 52840 DK. Therefore, MacOS users are advised to follow the Using Native shell instruction.
The easiest way to get started with the example is to use nRF Connect SDK Docker image for CHIP applications. Run the following commands to start a Docker container:
$ mkdir ~/nrfconnect
$ mkdir ~/connectedhomeip
$ docker run --rm -it --privileged -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip nordicsemi/nrfconnect-chip
Note:
~/nrfconnectcan be replaced with an absolute path to nRF Connect SDK source directory in case you have it already installed.- Likewise,
~/connectedhomeipcan be replaced with an absolute path to CHIP source directory.--privilegedflag can be omitted if you're not planning to flash the example onto hardware. The parameter gives the container access to devices connected to your computer when the container is started.--rmflag can be omitted if you don't want the container to be auto-removed when you exit the container shell session.
If you use the container for the first time and you don't have nRF Connect SDK and CHIP sources downloaded yet, run setup command in the container to pull the sources into directories mounted as /var/ncs and /var/chip, respectively:
$ setup --ncs 83764f
/var/ncs repository is empty. Do you wish to check out nRF Connect SDK sources [83764f]? [Y/N] y
...
/var/chip repository is empty. Do you wish to check out Project CHIP sources [master]? [Y/N] y
...
Now you may build the example by running the commands below in the Docker container:
$ cd /var/chip/examples/lock-app/nrfconnect
$ west build -b nrf52840dk_nrf52840
If the build succeeds, the binary will be available under /var/chip/examples/lock-app/nrfconnect/build/zephyr/zephyr.hex. Note that other operations described in this document like flashing or debugging can also be done in the container.
Before building the example, download the nRF Connect SDK and install all requirements. Please read the Supported nRF Connect SDK versions section to learn which version to use to avoid unexpected compatibility issues.
If you don't want to use SEGGER Embedded Studio, you may skip the part about installing and configuring it.
Download and install the nRF Command Line Tools.
Download and install GN meta-build system.
Make sure that you source the following file:
$ source <ncs-dir>/zephyr/zephyr-env.sh
Note:
Ensure that
$ZEPHYR_BASE,$GNUARMEMB_TOOLCHAIN_PATH, and$ZEPHYR_TOOLCHAIN_VARIANTenvironment variables are set in your current terminal before building.$GNUARMEMB_TOOLCHAIN_PATHand$ZEPHYR_TOOLCHAIN_VARIANTmust be set manually.
After your environment is set up, you are ready to build the example. The recommended tool for building and flashing the device is west.
The following commands will build the lock-app example:
$ cd ~/connectedhomeip/examples/lock-app/nrfconnect
# If this is a first time build or if `build` directory was deleted
$ west build -b nrf52840dk_nrf52840
# Any subsequent build
$ west build
After a successful build, the binary will be available under <example-dir>/build/zephyr/zephyr.hex
It is recommended to use the nRF Connect version which is being verified as a part of CHIP Continuous Integration testing, which happens to be 83764f at the moment. You may verify that the revision is used in chip-build-nrf-platform Docker image in case of doubt.
Please refer to this section in the user guide to learn how to update nRF Connect SDK repository.
The Zephyr ecosystem is higly configurable and allows the user to modify many aspects of the application. The configuration system is based on Kconfig and the settings can be modified using the menuconfig utility.
To open the configuration menu, do the following:
$ cd <example-dir>
# First time build
$ west build -b nrf52840dk_nrf52840 -t menuconfig
# Any subsequent build
$ west build -t menuconfig
# Running menuconfig with ninja
$ cd <example-dir>/build
$ ninja menuconfig
Changes done with menuconfig will be lost, if the build directory is deleted. To make them persistent, save the configuration options in prj.conf file.
The example application is designed to run on the Nordic nRF52840 DK development kit.
To flash the application to the device, use the west tool:
$ cd <example-dir>
$ west flash
If you have multiple nRF52840 DK boards connected, west will prompt you to pick the correct one.
To debug the application on target:
$ cd <example-dir>
$ west debug
The application includes a command line interface with support for logs and the OpenThread commands.
To access it, use any serial terminal program you like, for example minicom or GNU screen.
The UART interface is configured for 115200 baud rate.
All OpenThread commands must be prefixed with ot, for example ot thread start.
The example application is built to use the SEGGER Real Time Transfer (RTT) facility for log output. RTT is a feature built-in to the J-Link Interface MCU on the development kit board. It allows bi-directional communication with an embedded application without the need for a dedicated UART.
Using the RTT facility requires downloading and installing the SEGGER J-Link Software and Documentation Pack (web site).
Install the J-Link software
$ cd ~/Downloads $ sudo dpkg -i JLink_Linux_V*_x86_64.deb
In Linux, grant the logged in user the ability to talk to the development hardware via the linux tty device (/dev/ttyACMx) by adding them to the dialout group.
$ sudo usermod -a -G dialout ${USER}
Once the above is complete, log output can be viewed using the JLinkExe tool in combination with JLinkRTTClient as follows:
Run the JLinkExe tool with arguments to autoconnect to the nRF82480 DK board:
$ JLinkExe -device NRF52840_XXAA -if SWD -speed 4000 -autoconnect 1
In a second terminal, run the JLinkRTTClient:
$ JLinkRTTClient
Logging output will appear in the second terminal.