examples/lock-app/efr32/README.md

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