1 # CHIP nRF Connect Pigweed Example Application
3 The nRF Connect Pigweed Example demonstrates the usage of Pigweed module
4 functionalities in an application.
7 <img src="../../platform/nrfconnect/doc/images/Logo_RGB_H-small.png" alt="Nordic Semiconductor logo"/>
8 <img src="../../platform/nrfconnect/doc/images/nRF52840-DK-small.png" alt="nRF52840 DK">
11 The example is based on [CHIP](https://github.com/project-chip/connectedhomeip),
12 the [Pigweed](https://pigweed.googlesource.com/pigweed/pigweed) module, which is
13 a collection of libraries that provide different functionalities for embedded
14 systems, and Nordic Semiconductor's nRF Connect SDK.
16 You can use this example as a training ground for making experiments, testing
17 Pigweed module features and checking what actions are necessary to fully
18 integrate Pigweed in a CHIP project.
20 Pigweed functionalities are being gradually integrated into CHIP. Currently, the
21 following features are available:
23 - **Echo RPC** - Creates a Remote Procedure Call server and allows sending
24 commands through the serial port to the device, which makes echo and sends
25 the received commands back.
29 - [Overview](#overview)
30 - [Requirements](#requirements)
31 - [Supported devices](#supported_devices)
32 - [Device UI](#device-ui)
33 - [Setting up the environment](#setting-up-the-environment)
34 - [Using Docker container for setup](#using-docker-container-for-setup)
35 - [Using native shell for setup](#using-native-shell-for-setup)
36 - [Building](#building)
37 - [Configuring the example](#configuring-the-example)
38 - [Flashing and debugging](#flashing-and-debugging)
39 - [Flashing on the nRF52840 DK](#nrf52840dk_flashing)
40 - [Flashing on the nRF52840 Dongle](#nrf52840dongle_flashing)
41 - [Testing the example](#testing-the-example)
45 <a name="overview"></a>
49 This example is running on the nRF Connect platform, which is based on the
50 [nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html)
51 and [Zephyr RTOS](https://zephyrproject.org/). Visit CHIP's
52 [nRF Connect platform overview](../../../docs/guides/nrfconnect_platform_overview.md)
53 to read more about the platform structure and dependencies.
55 Pigweed libraries are built and organized in a way that enables faster and more
56 reliable development. In the CHIP project, the Pigweed module is planned to be
57 used to create system infrastructures, for example for performing on-device
58 tests, but considering its general functionalities, it can be useful also in
63 <a name="requirements"></a>
67 The application requires a specific revision of the nRF Connect SDK to work
68 correctly. See [Setting up the environment](#setting-up-the-environment) for
71 <a name="supported_devices"></a>
75 The example supports building and running on the following devices:
77 | Hardware platform | Build target | Platform image |
78 | ------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
79 | [nRF52840 Dongle](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-Dongle) | `nrf52840dongle_nrf52840` | <details><summary>nRF52840 Dongle</summary><img src="../../platform/nrfconnect/doc/images/nRF52840-Dongle-small.jpg" alt="nRF52840 Dongle"/></details> |
80 | [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` | <details><summary>nRF52840 DK</summary><img src="../../platform/nrfconnect/doc/images/nRF52840-DK_top-view-small.jpg" alt="nRF52840 DK"/></details> |
84 <a name="device-ui"></a>
88 This section lists the User Interface elements that you can use to control and
89 monitor the state of the device. These correspond to PCB components on the
92 **LED 1** shows the overall state of the device. The following states are
95 - _Solid On_ — The application was flashed and ran successfully.
97 **Serial port** can be used to communicate with the device by sending commands
98 and receiving responses.
102 > Please note that supported hardware platforms are using different transport
103 > interfaces to perform serial communication, which leads to differences in
104 > configuration. By default, these interfaces are used:
106 > - `nrf52840dk_nrf52840` - UART interface routed to the SEGGER J-Link USB
108 > - `nrf52840dongle_nrf52840` - USB interface routed to the USB port.
112 ## Setting up the environment
114 Before building the example, check out the CHIP repository and sync submodules
115 using the following command:
117 $ git submodule update --init
119 The example requires a specific revision of the nRF Connect SDK. You can either
120 install it along with the related tools directly on your system or use a Docker
121 image that has the tools pre-installed.
123 If you are a macOS user, you won't be able to use the Docker container to flash
124 the application onto a Nordic development kit due to
125 [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container).
126 Use the [native shell](#using-native-shell) for building instead.
128 ### Using Docker container for setup
130 To use the Docker container for setup, complete the following steps:
132 1. If you do not have the nRF Connect SDK installed yet, create a directory for
133 it by running the following command:
137 2. Download the latest version of the nRF Connect SDK Docker image by running
138 the following command:
140 $ docker pull nordicsemi/nrfconnect-chip
142 3. Start Docker with the downloaded image by running the following command,
143 customized to your needs as described below:
145 $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \
146 -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip
150 - _~/nrfconnect_ can be replaced with an absolute path to the nRF Connect
151 SDK source directory.
152 - _~/connectedhomeip_ must be replaced with an absolute path to the CHIP
154 - _-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:_ rmw"\*
155 parameters can be omitted if you are not planning to flash the example
156 onto hardware. These parameters give the container access to USB devices
157 connected to your computer such as the nRF52840 DK.
158 - _--rm_ can be omitted if you do not want the container to be
159 auto-removed when you exit the container shell session.
160 - _-e RUNAS=\$(id -u)_ is needed to start the container session as the
161 current user instead of root.
163 4. Update the nRF Connect SDK to the most recent supported revision, by running
164 the following command:
167 $ python3 scripts/setup/nrfconnect/update_ncs.py --update
169 Now you can proceed with the [Building](#building) instruction.
171 ### Using native shell for setup
173 To use the native shell for setup, complete the following steps:
175 1. Download and install the following additional software:
177 - [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools)
178 - [GN meta-build system](https://gn.googlesource.com/gn/)
180 2. If you do not have the nRF Connect SDK installed, follow the
181 [guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_assistant.html#)
182 in the nRF Connect SDK documentation to install the latest stable nRF
183 Connect SDK version. Since command-line tools will be used for building the
184 example, installing SEGGER Embedded Studio is not required.
186 If you have the SDK already installed, continue to the next step and update
187 the nRF Connect SDK after initializing environment variables.
189 3. Initialize environment variables referred to by the CHIP and the nRF Connect
190 SDK build scripts. Replace _nrfconnect-dir_ with the path to your nRF
191 Connect SDK installation directory, and _toolchain-dir_ with the path to GNU
192 Arm Embedded Toolchain.
194 $ source nrfconnect-dir/zephyr/zephyr-env.sh
195 $ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
196 $ export GNUARMEMB_TOOLCHAIN_PATH=toolchain-dir
198 4. Update the nRF Connect SDK to the most recent supported revision by running
199 the following command (replace _chip-dir_ with the path to CHIP repository
203 $ python3 scripts/setup/nrfconnect/update_ncs.py --update
205 Now you can proceed with the [Building](#building) instruction.
209 <a name="building"></a>
213 Complete the following steps, regardless of the method used for setting up the
216 1. Run the `activate.sh` script, regardless of the building strategy. The
217 script is required for building the Pigweed library. Use the following
220 $ source scripts/activate.sh
222 2. Navigate to the example's directory:
224 $ cd examples/pigweed-app/nrfconnect
226 3. Run the following command to build the example, with _build-target_ replaced
227 with the build target name of the Nordic Semiconductor's kit you own, for
228 example `nrf52840dk_nrf52840`:
230 $ west build -b build-target
232 You only need to specify the build target on the first build. See
233 [Requirements](#requirements) for the build target names of compatible kits.
235 The output `zephyr.hex` file will be available in the `build/zephyr/` directory.
237 ### Removing build artifacts
239 If you're planning to build the example for a different kit or make changes to
240 the configuration, remove all build artifacts before building. To do so, use the
247 <a name="configuring"></a>
249 ## Configuring the example
251 The Zephyr ecosystem is highly configurable and allows you to modify many
252 aspects of the application. The configuration system is based on Kconfig files
253 and the settings can be modified using the menuconfig utility.
255 To open the menuconfig utility, complete the following steps:
257 1. Go to the example directory by running the following command, with the
258 _example-dir_ directory name updated for your configuration:
262 2. Choose one of the following options:
264 - If you are running the build for the first time, run the following
267 $ west build -b nrf52840dk_nrf52840 -t menuconfig
269 - If you are running a subsequent build, run the following command:
271 $ west build -t menuconfig
273 - If you are running menuconfig with ninja, run the following commands:
275 $ cd example-dir/build
278 Changes done with menuconfig will be lost if the `build` directory is deleted.
279 To make them persistent, save the configuration options in the `prj.conf` file.
281 For more information, see the
282 [Configuring nRF Connect SDK examples](../../../docs/guides/nrfconnect_examples_configuration.md)
287 <a name="flashing"></a>
289 ## Flashing and debugging
291 The flashing and debugging procedure is different for the nRF52840 DK and the
294 <a name="nrf52840dk_flashing"></a>
296 ### Flashing on the nRF52840 DK
298 To flash the application to the device, use the west tool and run the following
299 commands, with the _example-dir_ directory name updated for your configuration:
304 If you have multiple nRF52840 development kits connected, west will prompt you
305 to pick the correct one.
307 To debug the application on target, run the following commands:
312 <a name="nrf52840dongle_flashing"></a>
314 ### Flashing on the nRF52840 Dongle
317 [Programming and Flashing nRF52840 Dongle](https://docs.zephyrproject.org/latest/boards/arm/nrf52840dongle_nrf52840/doc/index.html#programming-and-debugging)
318 to read more about flashing on the nRF52840 Dongle.
322 <a name="currently-implemented-features"></a>
324 ## Testing the example
326 Run the following command to start an interactive Python shell, where the Echo
327 RPC commands can be invoked:
329 python -m pw_hdlc.rpc_console --device /dev/ttyACM0 -b 115200 $CHIP_ROOT/third_party/pigweed/repo/pw_rpc/pw_rpc_protos/echo.proto -o /tmp/pw_rpc.out
331 To send an Echo RPC message, type the following command, where the actual
332 message is the text in quotation marks after the `msg=` phrase:
334 rpcs.pw.rpc.EchoService.Echo(msg="hi")