examples/lighting-app/efr32/README.md

   1 #CHIP EFR32 Lighting Example
   2
   3 An example showing the use of CHIP on the Silicon Labs EFR32 MG12.
   4
   5 <hr>
   6
   7 -   [CHIP EFR32 Lighting Example](#chip-efr32-lighting-example)
   8     -   [Introduction](#introduction)
   9     -   [Building](#building)
  10         -   [Note](#note)
  11     -   [Flashing the Application](#flashing-the-application)
  12     -   [Viewing Logging Output](#viewing-logging-output)
  13     -   [Running the Complete Example](#running-the-complete-example)
  14         -   [Notes](#notes)
  15     -   [Running Pigweed RPC console](#running-pigweed-rpc-console)
  16
  17 <hr>
  18
  19 <a name="intro"></a>
  20
  21 ## Introduction
  22
  23 The EFR32 lighting example provides a baseline demonstration of a Light control
  24 device, built using CHIP and the Silicon Labs gecko SDK. It can be controlled by
  25 a Chip controller over Openthread network..
  26
  27 The EFR32 device can be commissioned over Bluetooth Low Energy where the device
  28 and the Chip controller will exchange security information with the Rendez-vous
  29 procedure. Thread Network credentials are then provided to the EFR32 device
  30 which will then join the network.
  31
  32 The LCD on the Silabs WSTK shows a QR Code containing the needed commissioning
  33 information for the BLE connection and starting the Rendez-vous procedure.
  34
  35 The lighting example is intended to serve both as a means to explore the
  36 workings of CHIP as well as a template for creating real products based on the
  37 Silicon Labs platform.
  38
  39 <a name="building"></a>
  40
  41 ## Building
  42
  43 -   Download the
  44     [Simplicity Commander](https://www.silabs.com/mcu/programming-options)
  45     command line tool, and ensure that `commander` is your shell search path.
  46     (For Mac OS X, `commander` is located inside
  47     `Commander.app/Contents/MacOS/`.)
  48
  49 -   Download and install a suitable ARM gcc tool chain:
  50     [GNU Arm Embedded Toolchain 9-2019-q4-major](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads)
  51
  52 -   Install some additional tools(likely already present for CHIP developers):
  53
  54 #Linux \$ sudo apt-get install git libwebkitgtk-1.0-0 ninja-build
  55
  56 #Mac OS X \$ brew install ninja
  57
  58 -   Supported hardware:
  59
  60     MG12 boards:
  61
  62     -   BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm
  63     -   BRD4164A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm
  64     -   BRD4166A / SLTB004A / Thunderboard Sense 2 / 2.4GHz@10dBm
  65     -   BRD4170A / SLWSTK6000B / Multiband Wireless Starter Kit / 2.4GHz@19dBm,
  66         915MHz@19dBm
  67     -   BRD4304A / SLWSTK6000B / MGM12P Module / 2.4GHz@19dBm
  68
  69     MG21 boards:
  70
  71     -   BRD4180A / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm
  72
  73 *   Build the example application:
  74
  75           cd ~/connectedhomeip
  76           ./scripts/examples/gn_efr32_example.sh ./examples/lighting-app/efr32/ ./out/lighting-app BRD4161A
  77
  78 -   To delete generated executable, libraries and object files use:
  79
  80           $ cd ~/connectedhomeip
  81           $ rm -rf ./out/
  82
  83 OR use GN/Ninja directly
  84
  85           $ cd ~/connectedhomeip/examples/lighting-app/efr32
  86           $ git submodule update --init
  87           $ source third_party/connectedhomeip/scripts/activate.sh
  88           $ export EFR32_BOARD=BRD4161A
  89           $ gn gen out/debug
  90           $ ninja -C out/debug
  91
  92 -   To delete generated executable, libraries and object files use:
  93
  94           $ cd ~/connectedhomeip/examples/lighting-app/efr32
  95           $ rm -rf out/
  96
  97 *   Build the example with pigweed RCP use GN/Ninja Directly
  98
  99           $ cd ~/connectedhomeip/examples/lighting-app/efr32
 100           $ git submodule update --init
 101           $ source third_party/connectedhomeip/scripts/activate.sh
 102           $ export EFR32_BOARD=BRD4161A
 103           $ gn gen out/debug --args='import("//with_pw_rpc.gni")'
 104           $ ninja -C out/debug
 105
 106     [Running Pigweed RPC console](#running-pigweed-rpc-console)
 107
 108 <a name="flashing"></a>
 109
 110 ## Flashing the Application
 111
 112 -   On the command line:
 113
 114           $ cd ~/connectedhomeip/examples/lighting-app/efr32
 115           $ python3 out/debug/chip-efr32-lighting-example.flash.py
 116
 117 -   Or with the Ozone debugger, just load the .out file.
 118
 119 <a name="view-logging"></a>
 120
 121 ## Viewing Logging Output
 122
 123 The example application is built to use the SEGGER Real Time Transfer (RTT)
 124 facility for log output. RTT is a feature built-in to the J-Link Interface MCU
 125 on the WSTK development board. It allows bi-directional communication with an
 126 embedded application without the need for a dedicated UART.
 127
 128 Using the RTT facility requires downloading and installing the _SEGGER J-Link
 129 Software and Documentation Pack_
 130 ([web site](https://www.segger.com/downloads/jlink#J-LinkSoftwareAndDocumentationPack)).
 131
 132 Alternatively, SEGGER Ozone J-Link debugger can be used to view RTT logs too
 133 after flashing the .out file.
 134
 135 -   Download the J-Link installer by navigating to the appropriate URL and
 136     agreeing to the license agreement.
 137
 138 -   [JLink_Linux_x86_64.deb](https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb)
 139 -   [JLink_MacOSX.pkg](https://www.segger.com/downloads/jlink/JLink_MacOSX.pkg)
 140
 141 *   Install the J-Link software
 142
 143           $ cd ~/Downloads
 144           $ sudo dpkg -i JLink_Linux_V*_x86_64.deb
 145
 146 *   In Linux, grant the logged in user the ability to talk to the development
 147     hardware via the linux tty device (/dev/ttyACMx) by adding them to the
 148     dialout group.
 149
 150           $ sudo usermod -a -G dialout ${USER}
 151
 152 Once the above is complete, log output can be viewed using the JLinkExe tool in
 153 combination with JLinkRTTClient as follows:
 154
 155 -   Run the JLinkExe tool with arguments to autoconnect to the WSTK board:
 156
 157     For MG12 use:
 158
 159           $ JLinkExe -device EFR32MG12PXXXF1024 -if JTAG -speed 4000 -autoconnect 1
 160
 161     For MG21 use:
 162
 163           $ JLinkExe -device EFR32MG21AXXXF1024 -if SWD -speed 4000 -autoconnect 1
 164
 165 -   In a second terminal, run the JLinkRTTClient to view logs:
 166
 167           $ JLinkRTTClient
 168
 169 <a name="running-complete-example"></a>
 170
 171 ## Running the Complete Example
 172
 173 -   It is assumed here that you already have an OpenThread border router
 174     configured and running. If not, see the following guide
 175     [OpenThread Border Router](https://openthread.io/guides/border-router) for
 176     more information on how to setup a border router. Take note that the RCP
 177     code is available directly through
 178     [Simplicity Studio 5](https://www.silabs.com/products/development-tools/software/simplicity-studio/simplicity-studio-5)
 179     under File->New->Project Wizard->Examples->Thread : ot-rcp
 180
 181 -   User interface : **LCD** The LCD on Silabs WSTK shows a QR Code. This QR
 182     Code is be scanned by the CHIP Tool app For the Rendez-vous procedure over
 183     BLE
 184
 185         * On devices that do not have or support the LCD Display like the BRD4166A Thunderboard Sense 2,
 186           a URL can be found in the RTT logs.
 187
 188           <info  > [SVR] Copy/paste the below URL in a browser to see the QR Code:
 189           <info  > [SVR] https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3AI34NM%20-00%200C9SS0
 190
 191     **LED 0** shows the overall state of the device and its connectivity. The
 192     following states are possible:
 193
 194         -   _Short Flash On (50 ms on/950 ms off)_ ; The device is in the
 195             unprovisioned (unpaired) state and is waiting for a commissioning
 196             application to connect.
 197
 198         -   _Rapid Even Flashing_ ; (100 ms on/100 ms off)_ &mdash; The device is in the
 199             unprovisioned state and a commissioning application is connected through
 200             Bluetooth LE.
 201
 202         -   _Short Flash Off_ ; (950ms on/50ms off)_ &mdash; The device is fully
 203             provisioned, but does not yet have full Thread network or service
 204             connectivity.
 205
 206         -   _Solid On_ ; The device is fully provisioned and has full Thread
 207             network and service connectivity.
 208
 209     **LED 1** Simulates the Light The following states are possible:
 210
 211         -   _Solid On_ ; Light is on
 212         -   _Off_ ; Light is off
 213
 214     **Push Button 0**
 215
 216         -   _Press and Release_ : Start, or restart, BLE advertisement in fast mode. It will advertise in this mode
 217             for 30 seconds. The device will then switch to a slower interval advertisement.
 218             After 15 minutes, the adverstiment stops.
 219
 220         -   _Pressed and hold for 6 s_ : Initiates the factory reset of the device.
 221             Releasing the button within the 6-second window cancels the factory reset
 222             procedure. **LEDs** blink in unison when the factory reset procedure is
 223             initiated.
 224
 225     **Push Button 1** Toggles the light state On/Off
 226
 227 -   Once the device is provisioned, it will join the Thread network is
 228     established, look for the RTT log
 229
 230     ```
 231         [DL] Device Role: CHILD
 232         [DL] Partition Id:0x6A7491B7
 233         [DL] \_OnPlatformEvent default: event->Type = 32778
 234         [DL] OpenThread State Changed (Flags: 0x00000001)
 235         [DL] Thread Unicast Addresses:
 236         [DL]    2001:DB8::E1A2:87F1:7D5D:FECA/64 valid preferred
 237         [DL]    FDDE:AD00:BEEF::FF:FE00:2402/64 valid preferred rloc
 238         [DL]    FDDE:AD00:BEEF:0:383F:5E81:A05A:B168/64 valid preferred
 239         [DL]    FE80::D8F2:592E:C109:CF00/64 valid preferred
 240         [DL] LwIP Thread interface addresses updated
 241         [DL] FE80::D8F2:592E:C109:CF00 IPv6 link-local address, preferred)
 242         [DL] FDDE:AD00:BEEF:0:383F:5E81:A05A:B168 Thread mesh-local address, preferred)
 243         [DL] 2001:DB8::E1A2:87F1:7D5D:FECA IPv6 global unicast address, preferred)
 244     ```
 245
 246     Keep The global unicast address; It is to be used to reach the Device with
 247     the chip-tool. The device will be promoted to Router shortly after [DL]
 248     Device Role: ROUTER
 249
 250     (you can verify that the device is on the thread network with the command
 251     `router table` using a serial terminal (screen / minicom etc.) on the board
 252     running the lighting-app example. You can also get the address list with the
 253     command ipaddr again in the serial terminal )
 254
 255 -   Using chip-tool you can now control the light status with on/off command
 256     such as `chip-tool onoff on 1`
 257
 258     \*\* Currently, chip-tool for Mac or Linux do not yet have the Thread
 259     provisioning feature
 260     `chip-tool bypass <Global ipv6 address of the node> 11097`
 261
 262     You can provision the Chip device using Chip tool Android or iOS app or
 263     through CLI commands on your OT BR
 264
 265 ### Notes
 266
 267 -   Depending on your network settings your router might not provide native ipv6
 268     addresses to your devices (Border router / PC). If this is the case, you
 269     need to add a static ipv6 addresses on both device and then an ipv6 route to
 270     the border router on your PC
 271
 272 #On Border Router: \$ sudo ip addr add dev <Network interface> 2002::2/64
 273
 274 #On PC(Linux): \$ sudo ip addr add dev <Network interface> 2002::1/64
 275
 276 #Add Ipv6 route on PC(Linux) \$ sudo ip route add <Thread global ipv6 prefix>/64
 277 via 2002::2
 278
 279 <a name="running-pigweed-rpc-console"></a>
 280
 281 ## Running Pigweed RPC console
 282
 283 -   If you build the example with pigweed RPC option you can can interact with
 284     the example by UART using the RPC LightingService. Call the following
 285     command in your terminal
 286
 287     `python -m pw_hdlc.rpc_console --device /dev/tty.<SERIALDEVICE> -b 115200 /<CHIP_ROOT>/examples/lighting-app/lighting-common/lighting_service/pigweed_lighting.proto -o /<YourFolder>/pw_log.out`
 288
 289 -   Then you can simulate a button press or realease using the following command
 290     where : idx = 0 or 1 for Button PB0 or PB1 action = 0 for PRESSED, 1 for
 291     RELEASE Test toggling the LED with
 292     `rpcs.chip.rpc.LightingService.ButtonEvent(idx=1,action=0)`
 293
 294 ## Memory settings
 295
 296 While most of the RAM usage in CHIP is static, allowing easier debugging and
 297 optimization with symbols analysis, we still need some HEAP for the crypto and
 298 OpenThread. Size of the HEAP can be modified by changing the value of the
 299 `SL_STACK_SIZE` define inside of the BUILD.gn file of this example. Please take
 300 note that a HEAP size smaller than 5k can and will cause a Mbedtls failure
 301 during the BLE rendez-vous.
 302
 303 To track memory usage you can set `enable_heap_monitoring = true` either in the
 304 BUILD.gn file or pass it as a build argument to gn. This will print on the RTT
 305 console the RAM usage of each individual task and the number of Memory
 306 allocation and Free. While this is not extensive monitoring you're welcome to
 307 modify `examples/platform/efr32/MemMonitoring.cpp` to add your own memory
 308 tracking code inside the `trackAlloc` and `trackFree` function