An example application showing the use CHIP on the Nordic nRF52840.
The nRF52840 lighting example application provides a working demonstration of a connected lighting device, built using CHIP, and the Nordic nRF5 SDK. The example supports remote access and control of a lighting 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 lighting 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 application builds upon the CHIP. A top-level Makefile orchestrates the entire build process, including building CHIP, and select files from the nRF5 SDK. The resultant image file can be flashed directly onto the Nordic dev kit hardware.
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.
The remaining two LEDs and buttons (#3 and #4) are unused.
devcontainerTools and SDK are preinstalled in CHIP's VSCode devcontainer. You can build this example on a clean tree by running make. Run the following commands in a devcontainer shell.
$ cd /workspaces/connectedhomeip
# CAUTION: the following step will delete any unstaged files
$ git clean -Xdf
$ cd examples/lock-app/nrf5
$ make clean
$ make
Other alternatives:
Run Build nRF5 Lock App VSCode task.
Run the GN build VSCode task. This does not require a clean tree.
Build manually with GN:
$ source scripts/activate.sh
$ cd examples/lock-app/nrf5
$ gn gen out/debug
$ ninja -C out/debug
Download and install the Nordic nRF5x Command Line Tools (Direct download link: Linux Mac OS X)
Download and install a suitable ARM gcc tool chain: GNU Arm Embedded Toolchain 7-2018-q2-update (Direct download link: Linux Mac OS X)
Install some additional tools:
# Linux $ sudo apt-get install git make automake libtool ccache # Mac OS X $ brew install automake libtool ccache
Set the following environment variables based on the locations/versions of the packages installed above:
export NRF5_SDK_ROOT=${HOME}/tools/nRF5_SDK_for_Thread_and_Zigbee_v4.0.0
export NRF5_TOOLS_ROOT=${HOME}/tools/nRF-Command-Line-Tools
export ARM_GCC_INSTALL_ROOT=${HOME}/tools/gcc-arm-none-eabi-9-2019-q4-major/bin
export PATH=${PATH}:${NRF5_TOOLS_ROOT}/nrfjprog
Clone the CHIP repo into a local directory
$ cd ~ $ git clone https://github.com/project-chip/connectedhomeip.git
Run make to build the application
$ cd ~/connectedhomeip/examples/lock-app/nrf5 $ make clean $ make
Or, run GN to build the application
$ cd ~/connectedhomeip $ git submodule update --init $ source scripts/activate.sh $ cd examples/lock-app/nrf5 $ gn gen out/debug $ ninja -C out/debug
The example application is designed to run on the Nordic nRF52840 DK development kit. Prior to installing the application, the device's flash memory should be erased and the Nordic SoftDevice image installed.
Use the Makefile to erase the flash and program the Nordic SoftDevice image.
$ cd ~/connectedhomeip/examples/lock-app/nrf5 $ make erase $ make flash-softdevice
Once the above is complete, it shouldn't need be done again unless the SoftDevice image or the Nordic configuration storage (fds) area becomes corrupt. To correct either of these problems erase the device and reflash the SoftDevice and application again.
To flash the example app, run the following commands:
$ cd ~/connectedhomeip/examples/lock-app/nrf5
$ make flash-app
The VSCode devcontainer cannot communicate with the nRF device. So, the above command must be run from a native shell. This also means that the
nRF command line toolsmust be installed on your development machine.
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.
An alternate method for viewing log output is to use the J-Link GDB server described in the following section.