# Matter `Bouffalo Lab` Lighting Example This example functions as a light bulb device type, with on/off and level capabilities and uses a test Vendor ID (VID) and a Product ID (PID) of **0x8005**. Current supported boards: - `BL602DK` - `BL706DK` - `BL704LDK` Legacy supported boards: - `BL602-IoT-Matter-V1`, [here](https://www.amazon.com/dp/B0B9ZVGXD8) to purchase. - `BL602-NIGHT-LIGHT` - `XT-ZB6-DevKit` - `BL706-NIGHT-LIGHT` > Warning: Changing the VID/PID may cause compilation problems, we recommend > leaving it as the default while using this example. ## BL602 BL602/BL604 is combo chip-set for Wi-Fi 802.11b/g/n and BLE 5.0 base-band/MAC. ## BL70x BL70x is combo chip-set for BLE and IEEE 802.15.4/ZigBee/Thread. - BL702/BL706 has 14dbm tx power and is recommended for routing devices. SDK uses BL702 as a general name. - BL702L/BL704L is designed for low power application. SDK uses BL702L as a general name. BL70x has fully certified with all Thread 1.3 features, included Thread `SSED` and Thread Border Router. ## Solutions introduction `Bouffalo Lab` has full connectives support for Matter Applications. - Wi-Fi 4/6 application, we have - BL602, Wi-Fi 4 application. - BL706 + BL602, Wi-Fi 4 application. BL602 runs as a normal WLAN transceiver; TCP/IP stack runs as BL706 side. We recommend this solution is for Openthread Border Router application and Matter ZigBee bridge. - Openthread Border Router application, please refer to Openthread Border Router application - Matter ZigBee Bridge application, please contact `Bouffalo Lab` for support. - Thread application, we have - B70X - Ethernet application, we have - BL706. It supports single Matter application, and also Openthread Border Router application and Matter ZigBee bridge - Openthread Border Router application, please refer to Openthread Border Router application - Matter ZigBee application, please contact `Bouffalo Lab` for support. ## Initial setup The following steps in this document were validated on Ubuntu 20.04. - Install dependencies as specified in the **connectedhomeip** repository: [Building Matter](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/BUILDING.md). - Clone and initialize the **connectedhomeip** repo ``` git clone https://github.com/project-chip/connectedhomeip.git cd connectedhomeip git submodule update --init --recursive source ./scripts/activate.sh -p bouffalolab ``` - Setup build environment for `Bouffalo Lab` SoC ``` ./integrations/docker/images/stage-2/chip-build-bouffalolab/setup.sh ``` Script `setpu.sh` requires to select install path, and please execute following command to export `BOUFFALOLAB_SDK_ROOT` before building. ``` export BOUFFALOLAB_SDK_ROOT="Your install path" ``` ## Build CHIP Lighting App example The following steps take examples for `BL602DK`, `BL704LDK` and `BL706DK`. - Build lighting app with UART baudrate 2000000 ``` ./scripts/build/build_examples.py --target bouffalolab-bl602dk-light build ./scripts/build/build_examples.py --target bouffalolab-bl616dk-light-wifi build ./scripts/build/build_examples.py --target bouffalolab-bl704ldk-light build ./scripts/build/build_examples.py --target bouffalolab-bl706dk-light build ``` - Build lighting app with RPC enabled and UART baudrate 115200. ``` ./scripts/build/build_examples.py --target bouffalolab-bl602dk-light-light-rpc-115200 build ./scripts/build/build_examples.py --target bouffalolab-bl704ldk-light-light-rpc-115200 build ./scripts/build/build_examples.py --target bouffalolab-bl706dk-light-light-rpc-115200 build ``` ### Build options with build_examples.py - `-wifi`, specifies to use Wi-Fi for Matter application. - BL602 uses Wi-Fi by default. `-wifi` could be elided. - BL702 needs it to specify to use BL706 + BL602 for Wi-Fi. - `-thread`, specifies to use Thread for Matter application. - BL70X uses Thread by default. `-thread` could be elided. - `-ethernet`, specifies to use Ethernet for Matter application. - BL706 needs it to specify to use Ethernet. - `-littlefs`, specifies to use `littlefs` for flash access. - `-easyflash`, specifies to use `easyflash` for flash access. - for platform BL602/BL70X, it is necessary to specify one of `-easyflash` and `-littlefs`. - `-mfd`, enable Matter factory data feature, which load factory data from `MFD` partition - Please refer to [Bouffalo Lab Matter factory data guide](../../../docs/platforms/bouffalolab/matter_factory_data.md) or contact to `Bouffalo Lab` for support. - `-shell`, enable command line - `-rpc`, enable Pigweed RPC feature - `-115200`, set UART baudrate to 115200 for log and command line - `-cdc`, enable USB CDC feature, only support for BL706, and can't work with Ethernet Board - `-resetCnt`, enable feature to do factory reset when continues power cycle is greater than 3 - `-mot`, to specify to use openthread stack under `third_party/openthread/repo` - Without `-mot` specified, Matter Thread will use openthread stack under `Bouffalo Lab` SDK - `-fp`, to specify to enable frame pointer feature to print call stack when hit an exception for debug purpose. ## Download image - Using script `*.flash.py`. After building gets done, python script `*.flash.py` will generate under build output folder, such as - `chip-bl602-lighting-example.flash.py` for BL602 - `chip-bl702-lighting-example.flash.py` for BL702 - `chip-bl702l-lighting-example.flash.py` for BL702L Download operation steps as below, please check `help` option of script for more detail. - Connect the board to your build machine - Put the board to the download mode: - Press and hold the **BOOT** button. - Click the **RESET** or **EN** button. - Release the **BOOT** button. - Type following command for image download. Please set serial port accordingly, here we use /dev/ttyACM0 as a serial port example. - `BL602DK`, `BL704LDK` and `BL706DK`. ```shell ./out/bouffalolab-bl602dk-light-littlefs/chip-bl602-lighting-example.flash.py --port /dev/ttyACM0 ./out/bouffalolab-bl616dk-light-wifi/chip-bl616dk-lighting-example.flash.py --port /dev/ttyACM0 ./out/bouffalolab-bl704ldk-light-littlefs/chip-bl702l-lighting-example.flash.py --port /dev/ttyACM0 ./out/bouffalolab-bl706dk-light-littlefs/chip-bl702-lighting-example.flash.py --port /dev/ttyACM0 ``` - To wipe out flash and download image, please append `--erase` option. Take BL602DK as example. ```shell ./out/bouffalolab-bl602dk-light/chip-bl602-lighting-example.flash.py --port /dev/ttyACM0 --erase ``` > Note, better to append --erase option to download image for BL602 > develop board at first time. ## Run the example - You can open the serial console. For example, if the device is at `/dev/ttyACM0` with UART baudrate 2000000 built: ```shell picocom -b 2000000 /dev/ttyACM0 ``` - To reset the board, Click the **RESET** or **EN** button. - To toggle the light bulb’s on/off state by clicking BOOT button, which also toggles the LED. - To do factory reset, press BOOT button over 4 seconds, release BOOT button after led blink stopped. ## Test Commission and Control with chip-tool Please follow [chip_tool_guide](../../../docs/development_controllers/chip-tool/chip_tool_guide.md) and [guide](../../chip-tool/README.md) to build and use chip-tool for test. ### Prerequisite for Thread Protocol Thread wireless protocol runs on BL706, which needs a Thread border router to connect Thread network to Wi-Fi/Ethernet network. Please follow this [guide](../../../docs/platforms/openthread/openthread_border_router_pi.md) to setup a raspberry Pi border router. After Thread border router setup, please type following command on Thread border router to get Thread network credential. ```shell sudo ot-ctl dataset active -x ``` ### Commissioning over BLE - Reset the board or factory reset the board - Enter build out folder of chip-tool and running the following command to do BLE commission - Wi-Fi ```shell ./chip-tool pairing ble-wifi 20202021 3840 ``` - Thread ```shell ./chip-tool pairing ble-thread hex: 20202021 3840 ``` > ``, which is node ID assigned to device within chip-tool > fabric
``, Wi-Fi network SSID
``, Wi-FI > network password
``, Thread network > credential which running `sudo ot-ctl dataset active -x` command on border > router to get. ### Cluster control After successful commissioning, cluster commands available to control the board. - OnOff cluster The following command shows to toggle the LED on the board ``` $ ./chip-tool onoff toggle 1 ``` - Level cluster The following command shows to move level to 128. ``` $ ./chip-tool levelcontrol move-to-level 128 10 0 0 1 ``` - Color cluster The following command shows to change hue and saturation to 240 and 100 ``` $ ./chip-tool colorcontrol move-to-hue-and-saturation 240 100 0 0 0 1 ``` - Identify Light The following command shows to identify the board 10 seconds ```shell ./chip-tool identify identify 10 1 ``` ## Test OTA software upgrade with ota-provider-app Please take [guide](../../ota-provider-app/linux/README.md) for more detail on ota-provider-app build and usage. ### Create the Matter OTA image `Bouffalo Lab` Matter OTA image contains two parts: - `Bouffalo Lab` OTA bootable image: - Add boot parameters, signature/encryption if specified - And specify whether image has be compressed. - Add Matter recognition header by [ota_image_tool.py](../../../docs/platforms/openthread/openthread_border_router_pi.md). Script `*.flash.py` builds `Bouffalo Lab` bootable image and call [ota_image_tool.py](../../../docs/platforms/openthread/openthread_border_router_pi.md) to add Matter recognition header. Take `BL602DK` as example. ```shell ./out/bouffalolab-bl602dk-light/chip-bl602-lighting-example.flash.py --build-ota --vendor-id --product-id --version --version-str --digest-algorithm ``` > lighting-app.ota should have greater software version which is defined by > macro `CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION` in CHIPProjectConfig.h ### Start ota-provider-app - Start ota-provider-app for lighting-app.ota ```shell $ rm -r /tmp/chip_* $ ./chip-ota-provider-app -f /lighting-app.ota ``` where `` is the folder for lighting-app.ota. - Provision ota-provider-app with assigned node id to 1 ```shell $ ./chip-tool pairing onnetwork 1 20202021 $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0 ``` ### Start ota software upgrade - BLE commission BL602/BL702 lighting if not commissioned. - Start OTA software upgrade process ```shell ./chip-tool otasoftwareupdaterequestor announce-otaprovider 1 0 0 0 0 ``` where `` is node id of BL602/BL702 lighting app. - After OTA software upgrade gets done, BL602/BL702 will get reboot automatically. ## Run RPC Console - Build chip-console following this [guide](../../common/pigweed/rpc_console/README.md) - Start the console ``` $ chip-console --device /dev/ttyUSB0 -b 2000000 ``` - Get or Set the light state `rpcs.chip.rpc.Lighting.Get()` `rpcs.chip.rpc.Lighting.Set(on=True, level=128)`