examples/lighting-app/linux/README.md

   1 # CHIP Linux Lighting Example
   2
   3 An example showing the use of CHIP on the Linux. The document will describe how
   4 to build and run CHIP Linux Lighting Example on Raspberry Pi. This doc is tested
   5 on **Ubuntu for Raspberry Pi Server 20.04 LTS (aarch64)** and **Ubuntu for
   6 Raspberry Pi Desktop 20.10 (aarch64)**
   7
   8 <hr>
   9
  10 -   [CHIP Linux Lighting Example](#chip-linux-lighting-example)
  11     -   [Building](#building)
  12     -   [Running the Complete Example on Raspberry Pi 4](#running-complete-example)
  13
  14 <hr>
  15
  16 <a name="building"></a>
  17
  18 ## Building
  19
  20 -   Install tool chain
  21
  22           $ sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev ninja-build python3-venv python3-dev unzip
  23
  24 -   Build the example application:
  25
  26           $ cd ~/connectedhomeip/examples/lighting-app/linux
  27           $ git submodule update --init
  28           $ source third_party/connectedhomeip/scripts/activate.sh
  29           $ gn gen out/debug
  30           $ ninja -C out/debug
  31
  32 -   To delete generated executable, libraries and object files use:
  33
  34           $ cd ~/connectedhomeip/examples/lighting-app/linux
  35           $ rm -rf out/
  36
  37 <a name="running-complete-example"></a>
  38
  39 ## Running the Complete Example on Raspberry Pi 4
  40
  41 > If you want to test ZCL, please disable Rendezvous
  42 >
  43 >     gn gen out/debug --args='chip_bypass_rendezvous=true'
  44 >     ninja -C out/debug
  45 >
  46 > Note that GN will set chip_bypass_rendezvous for future builds, to enable
  47 > rendezvous, re-generate using
  48 >
  49 >     gn gen out/debug --args='chip_bypass_rendezvous=false'
  50
  51 > If you want to test Echo protocol, please disable Rendezvous and enable Echo
  52 > handler
  53 >
  54 >     gn gen out/debug --args='chip_bypass_rendezvous=true chip_app_use_echo=true'
  55 >     ninja -C out/debug
  56
  57 -   Prerequisites
  58
  59     1. A Raspberry Pi 4 board
  60     2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement,
  61        which will block CHIP from connecting via BLE. On Ubuntu server, you need
  62        to install `pi-bluetooth` via APT.
  63     3. Ubuntu 20.04 or newer image for ARM64 platform.
  64
  65 -   Building
  66
  67     Follow [Building](#building) section of this document.
  68
  69 -   Running
  70
  71     -   [Optional] Plug USB Bluetooth dongle
  72
  73         -   Plug USB Bluetooth dongle and find its bluetooth device number. The
  74             number after `hci` is the bluetooth device number, `1` in this
  75             example.
  76
  77                   $ hciconfig
  78                   hci1: Type: Primary  Bus: USB
  79                       BD Address: 00:1A:7D:AA:BB:CC  ACL MTU: 310:10  SCO MTU: 64:8
  80                       UP RUNNING PSCAN ISCAN
  81                       RX bytes:20942 acl:1023 sco:0 events:1140 errors:0
  82                       TX bytes:16559 acl:1011 sco:0 commands:121 errors:0
  83
  84                   hci0: Type: Primary  Bus: UART
  85                       BD Address: B8:27:EB:AA:BB:CC  ACL MTU: 1021:8  SCO MTU: 64:1
  86                       UP RUNNING PSCAN ISCAN
  87                       RX bytes:8609495 acl:14 sco:0 events:217484 errors:0
  88                       TX bytes:92185 acl:20 sco:0 commands:5259 errors:0
  89
  90         -   Run Linux Lighting Example App
  91
  92                   $ cd ~/connectedhomeip/examples/lighting-app/linux
  93                   $ sudo out/debug/chip-lighting-app --ble-device [bluetooth device number]
  94                   # In this example, the device we want to use is hci1
  95                   $ sudo out/debug/chip-lighting-app --ble-device 1
  96
  97         -   Test the device using ChipDeviceController on your laptop /
  98             workstation etc.