From f60ffc5760c1bbc018d750e36a718bd199dc4b4f Mon Sep 17 00:00:00 2001 From: Song Guo Date: Tue, 15 Dec 2020 14:20:31 +0800 Subject: [PATCH] [doc] Add document for chip device controller python cli (#4169) * [doc] Add document for chip device controller python cli * Add note about building bluez * Update doc --- docs/BUILDING.md | 2 + src/controller/python/README.md | 162 ++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 src/controller/python/README.md diff --git a/docs/BUILDING.md b/docs/BUILDING.md index 2ab5baa3bd631d..f00489f308bd4a 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -83,6 +83,8 @@ Finally, install some Raspberry Pi specific dependencies: sudo apt-get install pi-bluetooth ``` +You need to reboot your RPi after install `pi-bluetooth`. + ### Build Preparation Before running any other build command, the `scripts/activate.sh` environment diff --git a/src/controller/python/README.md b/src/controller/python/README.md new file mode 100644 index 00000000000000..a42b62e17f9896 --- /dev/null +++ b/src/controller/python/README.md @@ -0,0 +1,162 @@ +# CHIP Device Controller - Python Binding & Command line interface + +## Overview + +Chip Device Controller is a general library to control devices and manage +commissioner functionality, it has Python, Java (for Android) and ObjC (for iOS) +bindings for building tests and CHIP mobile applications. This document will +focus on its python binding interface on Linux and mac os. + +## Checkout / Build / Install + +> Note: The CHIP can be built on Linux (amd64 / aarch64) and macOS + +1. Clone Project CHIP repo. + +``` +git clone https://github.com/project-chip/connectedhomeip.git +``` + +2. Build CHIP + +Follow [BUILDING.md](/docs/BUILDING.md) to build CHIP on your platform. + +3. Install Chip Device Controller + +**For Linux** + +``` +cd out/debug/linux_arm64_clang/controller/python +sudo pip3 install chip-0.0-cp38-cp38-linux_aarch64.whl +``` + +> Note: for linux, sudo is necessary since it need to interact with bluetoothd +> via dbus with sudo permission + +**For macOS** + +``` +cd out/debug/mac_x64_clang/controller/python +pip3 install chip-0.0-cp38-cp38-mac_aarch64.whl +``` + +## BLE Virtualization on Linux (Optional) + +If we would like to setup virtual BLE central and peripheral in the same +machine, then Bluez setup + +``` +cd third_party/bluez/repo +./bootstrap +third_party/bluez/repo/configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc --localstatedir=/var --enable-experimental --with-systemdsystemunitdir=/lib/systemd/system --with-systemduserunitdir=/usr/lib/systemd --enable-deprecated --enable-testing --enable-tools +make +``` + +Note: You also need to install several packages on RPi if you want to build +bluez + +``` +sudo apt-get install libtool m4 automake autotools-dev libudev-dev libical-dev libreadline-dev +``` + +Run bluetoothd: + +``` +sudo third_party/bluez/repo/src/bluetoothd --experimental --debug & +``` + +Bring up two virtual ble interface: + +``` +sudo third_party/bluez/repo/emulator/btvirt -L -l2 +``` + +## Usage + +1. Run CHIP Device Controller + +``` +sudo chip-device-ctrl +``` + +2. [Required when there are multiple BLE adapters] Select BLE adapter (Linux + only) + +``` +chip-device-ctrl > ble-adapter-print +2020-11-23 17:41:53,116 ChipBLEMgr INFO adapter 0 = DE:AD:BE:EF:00:00 +2020-11-23 17:41:53,116 ChipBLEMgr INFO adapter 1 = DE:AD:BE:EF:01:01 +2020-11-23 17:41:53,116 ChipBLEMgr INFO adapter 2 = DE:AD:BE:EF:02:02 + +chip-device-ctrl > ble-adapter-select DE:AD:BE:EF:00:00 +``` + +3. Scan BLE devices + +``` +chip-device-ctrl > ble-scan +2020-11-23 17:36:18,012 ChipBLEMgr INFO use default adapter +2020-11-23 17:36:18,102 ChipBLEMgr INFO scanning started +2020-11-23 17:36:18,837 ChipBLEMgr INFO Name = CHIP-0000 +2020-11-23 17:36:18,837 ChipBLEMgr INFO ID = f8cc7d32-c110-398b-984b-e43732c9afa1 +2020-11-23 17:36:18,839 ChipBLEMgr INFO RSSI = -56 +2020-11-23 17:36:18,840 ChipBLEMgr INFO address = C3:A7:6C:A5:E3:ED +2020-11-23 17:36:18,843 ChipBLEMgr INFO ADV data: 0000feaf-0000-1000-8000-00805f9b34fb +Connect to BLE device +``` + +**Using device name** + +``` +chip-device-ctrl > ble-connect CHIP-0000 +2020-11-23 17:36:41,894 ChipBLEMgr INFO trying to connect to CHIP-0000 +2020-11-23 17:36:44,571 ChipBLEMgr INFO BLE connecting +2020-11-23 17:36:44,572 ChipBLEMgr INFO Discovering services +2020-11-23 17:36:45,939 ChipBLEMgr INFO Service discovering success +2020-11-23 17:36:45,971 ChipBLEMgr INFO connect success +``` + +**Using device address (on Linux)** + +``` +chip-device-ctrl > ble-connect C3:A7:6C:A5:E3:ED +2020-11-23 17:36:41,894 ChipBLEMgr INFO trying to connect to C3:A7:6C:A5:E3:ED +2020-11-23 17:36:44,571 ChipBLEMgr INFO BLE connecting +2020-11-23 17:36:44,572 ChipBLEMgr INFO Discovering services +2020-11-23 17:36:45,939 ChipBLEMgr INFO Service discovering success +2020-11-23 17:36:45,971 ChipBLEMgr INFO connect success +``` + +**Using uuid (on macOS)** + +``` +chip-device-ctrl > ble-connect f8cc7d32-c110-398b-984b-e43732c9afa1 +2020-11-23 17:36:41,894 ChipBLEMgr INFO trying to connect to f8cc7d32-c110-398b-984b-e43732c9afa1 +2020-11-23 17:36:44,571 ChipBLEMgr INFO BLE connecting +2020-11-23 17:36:44,572 ChipBLEMgr INFO Discovering services +2020-11-23 17:36:45,939 ChipBLEMgr INFO Service discovering success +2020-11-23 17:36:45,971 ChipBLEMgr INFO connect success +``` + +> Note, they will be replaced by using discriminator. + +5. Set wifi credential + +> Note: This command will be deprerated after the network provisioning cluster +> is ready. + +``` +chip-device-ctrl > set-pairing-wifi-credential TestAP TestPassword +``` + +6. Connect to device using setup pin code + +``` +chip-device-ctrl > connect 12345678 +``` + +## Commands + +// TODO: For now, the CHIP device controller does not have any interaction model +(cluster) or service provisioning commands, they will be added to the device +controller as soon as they are implemented.