examples/lock-app/cc13x2x7_26x2x7/README.md

   1 # CHIP CC1352 CC2652 Lock Example Application
   2
   3 An example application showing the use [CHIP][chip] on the Texas Instruments
   4 CC13X2_26X2 family of Wireless MCUs.
   5
   6 ---
   7
   8 -   [CHIP CC1352 CC2652 Lock Example Application](#chip-cc1352-cc2652-lock-example-application)
   9     -   [Introduction](#introduction)
  10         -   [Device UI](#device-ui)
  11     -   [Building](#building)
  12         -   [Preparation](#preparation)
  13         -   [Compilation](#compilation)
  14     -   [Programming](#programming)
  15         -   [UniFlash](#uniflash)
  16         -   [Code Composer Studio](#code-composer-studio)
  17     -   [Viewing Logging Output](#viewing-logging-output)
  18     -   [Running the Example](#running-the-example)
  19         -   [Provisioning](#provisioning)
  20             -   [Bluetooth LE Advertising](#bluetooth-le-advertising)
  21             -   [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous)
  22         -   [CHIP Remote Commands](#chip-remote-commands)
  23     -   [TI Support](#ti-support)
  24
  25 ---
  26
  27 ## Introduction
  28
  29 ![CC1352R1_LAUNCHXL](doc/images/cc1352r1_launchxl.jpg)
  30
  31 The CC13X2_26X2 lock example application provides a working demonstration of a
  32 connected door lock device. This uses the open-source CHIP implementation and
  33 the Texas Instruments SimpleLink™ CC13x2 and CC26x2 software development kit.
  34
  35 This example is enabled to build for CC2652R7 devices. This upcoming devices are
  36 currently not yet in full production. For more information on device
  37 availability or early access to an engineering build of our CHIP-enabled SDK,
  38 please reach out [here][ti_cc13x2_26x2_r7_chip_request].
  39
  40 The lock example is intended to serve both as a means to explore the workings of
  41 CHIP, as well as a template for creating real products based on the Texas
  42 Instruments devices.
  43
  44 ## Device UI
  45
  46 This example application has a simple User Interface to depict the state of the
  47 door lock and to control the state. The user LEDs on the LaunchPad are set on
  48 when the lock is locked, and are set off when unlocked. The LEDs will flash when
  49 in the transition state between locked and unlocked.
  50
  51 Short presses (less than 1000ms) of the user buttons are used for requesting
  52 lock and unlock of the door lock. The left button (`BTN-1`) is used to request
  53 locking. The right button (`BTN-2`) is used to request unlocking.
  54
  55 Long presses (greater than 1000ms) of the user buttons are used for controlling
  56 BLE advertisements. The left button (`BTN-1`) is used to disable advertisements
  57 if they are enabled. The Right button (`BTN-2`) is used to enable
  58 advertisements.
  59
  60 ## Building
  61
  62 ### Preparation
  63
  64 Some initial setup is necessary for preparing the build environment. This
  65 section will need to be done when migrating to new versions of the SDK.
  66
  67 -   An engineering SDK from TI is required. Please request access for it
  68     [here][ti_cc13x2_26x2_r7_chip_request].
  69
  70     -   Follow the default installation instructions when executing the
  71         installer.
  72
  73     -   The version of OpenThread used in this repository is newer than the one
  74         packaged with the TI SDK. Check the following section for a list of
  75         changes needed.
  76
  77 -   Download and install [SysConfig][sysconfig]
  78     ([sysconfig-1.5.0_1397][sysconfig-1.5.0_1397])
  79
  80     -   This may have already been installed with your SimpleLink SDK install.
  81
  82 -   If you have installed different versions, the build defaults will need to be
  83     changed to reflect this in
  84     `${chip_root}/examples/build_overrides/ti_simplelink_sdk.gni`.
  85
  86 -   Install Python 3.8 for the GN build system:
  87
  88     ```
  89     # Linux
  90     $ sudo apt-get install python3.8 python3.8-distutils python3.8-dev python3.8-venv
  91     # Distutils listed due to a package manager error on Ubuntu 18.04
  92
  93     ```
  94
  95     -   You will have to ensure that the default version of Python 3 is Python
  96         3.8.
  97
  98 -   Run the bootstrap script to setup the build environment.
  99
 100     ```
 101     $ cd ~/connectedhomeip
 102     $ source ./script/bootstrap.sh
 103
 104     ```
 105
 106 ### Compilation
 107
 108 It is necessary to activate the environment in every new shell. Then run GN and
 109 Ninja to build the executable.
 110
 111 -   Activate the build environment with the repository activate script.
 112
 113     ```
 114     $ cd ~/connectedhomeip
 115     $ source ./script/activate.sh
 116
 117     ```
 118
 119 -   Run the build to produce a default executable. By default on Linux both the
 120     TI SimpleLink SDK and Sysconfig are located in a `ti` folder in the user's
 121     home directory, and you must provide the absolute path to them. For example
 122     `/home/username/ti/simplelink_cc13x2_26x2_sdk_4_40_05_02_eng` and
 123     `/home/username/ti/sysconfig_1.6.0`. On Windows the default directory is
 124     `C:\ti`
 125
 126     ```
 127     $ cd ~/connectedhomeip/examples/lock-app/cc13x2_26x2
 128     $ export TI_SIMPLELINK_SDK_ROOT=<path-to-simplelink-sdk>
 129     $ export TI_SYSCONFIG_ROOT=<path-to-sysconfig-sdk>
 130     $ gn gen out/debug --args="ti_simplelink_sdk_root=\"${TI_SIMPLELINK_SDK_ROOT}\" ti_sysconfig_root=\"${TI_SYSCONFIG_ROOT}\""
 131     $ ninja -C out/debug
 132
 133     ```
 134
 135 ## Programming
 136
 137 Loading the built image onto a LaunchPad is supported through two methods;
 138 Uniflash and Code Composer Studio (CCS). UniFlash can be used to load the image.
 139 Code Composer Studio can be used to load the image and debug the source code.
 140
 141 ### UniFlash
 142
 143 [Programming UniFlash](doc/programming-uniflash.md)
 144
 145 ### Code Composer Studio
 146
 147 [Programming and Debugging with CCS](doc/programming-ccs.md)
 148
 149 ## Viewing Logging Output
 150
 151 By default the log output will be sent to the Application/User UART. Open a
 152 terminal emulator to that port to see the output with the following options:
 153
 154 | Parameter    | Value    |
 155 | ------------ | -------- |
 156 | Speed (baud) | `115200` |
 157 | Data bits    | `8`      |
 158 | Stop bits    | `1`      |
 159 | Parity       | `None`   |
 160 | Flow control | `None`   |
 161
 162 ## Running the Example
 163
 164 Once a device has been flashed with this example, it can now join and operate in
 165 an existing Thread network. The following sections assume that a Thread network
 166 is already active, and has at least one [OpenThread Border
 167 Router][ot_border_router_setup].
 168
 169 ### Provisioning
 170
 171 The first step to bring the CHIP device onto the network is to provision it. Our
 172 example accomplishes this with Bluetooth Low Energy (BLE) and the
 173 [CHIPTool](../../../src/android/CHIPTool/README.md) mobile app.
 174
 175 #### Bluetooth LE Advertising
 176
 177 To provision this example onto a Thread network, the device must be discoverable
 178 over Bluetooth LE. BLE advertising is started by long pressing the right button
 179 (greater than 1000ms), labeled `BTN-2` on the silkscreen. Once the device is
 180 fully provisioned, BLE advertising will stop.
 181
 182 #### Bluetooth LE Rendezvous
 183
 184 In this example, the provisioning procedure (called Rendezvous) is done over
 185 Bluetooth LE between a CHIP device (lock-app) and the CHIP controller
 186 (CHIPTool), where the controller has the commissioner role.
 187
 188 To start the rendezvous, the controller must get the commissioning information
 189 from the CHIP device.
 190
 191 This is done by scanning a QR code. A URL will be displayed on the lock-app's
 192 log ([UART terminal](#viewing-logging-output)). It will look like the following:
 193
 194 ```
 195 SetupQRCode:  [CH:.81TM -00 0C9SS0]
 196 Copy/paste the below URL in a browser to see the QR Code:
 197 https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3A.81TM%20-00%200C9SS0
 198 ```
 199
 200 You can directly navigate to the webpage URL displayed (which has QR payload
 201 pre-loaded). Alternatively, you can navigate to [the QR code
 202 generator][qr_code_generator] and enter in the payload shown in `SetupQRCode`
 203 (in this case `CH:.81TM -00 0C9SS0`).
 204
 205 ### CHIP Remote Commands
 206
 207 Once the CHIP device is provisioned and operating on the network, CHIPTool can
 208 be used to control the device. During the provisioning process, the CHIP device
 209 would have sent one of its newly assigned IPv6 addresses to the CHIPTool.
 210
 211 In the app, you should see an On/Off cluster; this corresponds to the lock-app.
 212 You can now control the lock-app CHIP device from the smartphone!
 213
 214 ## TI Support
 215
 216 For technical support, please consider creating a post on TI's [E2E forum][e2e].
 217 Additionally, we welcome any feedback.
 218
 219 [chip]: https://github.com/project-chip/connectedhomeip
 220 [cc1352r1_launchxl]: https://www.ti.com/tool/LAUNCHXL-CC1352R1
 221 [e2e]: https://e2e.ti.com/support/wireless-connectivity/zigbee-and-thread
 222 [simplelink_sdk]: https://www.ti.com/tool/SIMPLELINK-CC13X2-26X2-SDK
 223 [simplelink_sdk_4.30.00.54]:
 224     https://www.ti.com/tool/download/SIMPLELINK-CC13X2-26X2-SDK/4.30.00.54
 225 [sysconfig]: https://www.ti.com/tool/SYSCONFIG
 226 [sysconfig-1.5.0_1397]:
 227     http://software-dl.ti.com/ccs/esd/sysconfig/sysconfig-1.5.0_1397-setup.run
 228 [ti_thread_dnd]:
 229     https://www.ti.com/wireless-connectivity/thread/design-development.html
 230 [ti_cc13x2_26x2_r7_chip_request]: https://ti.com/chip_sdk
 231 [ot_border_router_setup]:
 232     https://openthread.io/guides/border-router/beaglebone-black
 233 [qr_code_generator]: https://dhrishi.github.io/connectedhomeip/qrcode.html