| # Matter TV Example |
| |
| An example showing the use of CHIP on the Linux. The document will describe how |
| to build and run Matter TV Example on Raspberry Pi. This doc is tested on |
| **Ubuntu for Raspberry Pi Server 20.04 LTS (aarch64)** and **Ubuntu for |
| Raspberry Pi Desktop 20.10 (aarch64)** |
| |
| <hr> |
| |
| - [Matter TV Example](#matter-tv-example) |
| - [Building](#building) |
| - [Exercising Commissioning](#exercising-commissioning) |
| - [App Platform commands](#app-platform-commands) |
| - [Casting](#casting) |
| - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) |
| |
| <hr> |
| |
| ## Building |
| |
| - Install tool chain |
| |
| $ 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 |
| |
| - Build the example application: |
| |
| $ cd ~/connectedhomeip/examples/tv-app/linux |
| $ git submodule update --init |
| $ source third_party/connectedhomeip/scripts/activate.sh |
| $ gn gen out/debug |
| $ ninja -C out/debug |
| |
| - To delete generated executable, libraries and object files use: |
| |
| $ cd ~/connectedhomeip/examples/tv-app/linux |
| $ rm -rf out/ |
| |
| ## Exercising Commissioning |
| |
| - Regular Commissioning |
| |
| Start the tv-app. Set ports to not conflict with other Matter apps you might run |
| on the same machine (chip-tool, tv-casting-app, etc) |
| |
| $ ./out/debug/chip-tv-app --secured-device-port 5640 --secured-commissioner-port 5552 |
| |
| Using the tv-app shell, invoke the controller commands: |
| |
| Print out all controller commands (discovery, commissioning, etc.) |
| |
| $ controller help |
| |
| Try the "commission-onnetwork <pincode> <disc> <IP> <port>" command |
| |
| $ controller commission-onnetwork 34567890 2976 192.168.65.3 5540 -or- |
| $ controller commission-onnetwork 34567890 2976 fe80::50:ff:fe00:1 5540 |
| |
| When the tv-app receives a UDC request from a commissionable node (like a |
| tv-casting-app), it will print out |
| |
| ``` |
| CHIP:SVR: UserDirectedCommissioningServer::OnMessageReceived |
| CHIP:SVR: UDC instance=F879911BF17129AA |
| CHIP:SVR: OnCommissionableNodeFound instance: name=F879911BF17129AA old_state=1 new_state=3 |
| CHIP:CTL: ------PROMPT USER: Test TV casting app is requesting permission to cast to this TV, approve? [0x0000_FFF1,0x0000_8001,F879911BF17129AA,01005DD9BB0990AF18F19C35C30C670532BC] |
| CHIP:CTL: ------Via Shell Enter: controller ux ok|cancel |
| ``` |
| |
| Begin commissioning it by running |
| |
| $ controller ux ok |
| |
| - User Directed Commissioning (UDC) |
| |
| Print out the cached list of UDC sessions |
| |
| $ udc-print |
| |
| Commission an entry from this UDC session cache. This will allow you to skip |
| entering discriminator, IP and port because these will be taken from the UDC |
| session cache: |
| |
| $ udc-commission <pincode> <udc-entry> |
| $ udc-commission 34567890 0 |
| |
| ## App Platform commands |
| |
| As an app platform, Content Apps can be launched and assigned to endpoints |
| following (see Video Player Architecture in the Device Library spec). |
| |
| There is a dummy app platform included in the linux tv-app which includes a |
| small number of hardcoded apps. See `examples/tv-app/tv-common/src/AppTv.h` and |
| `examples/tv-app/tv-common/src/AppTv.cpp` for this dummy implementation. These |
| apps have hardcoded values for many operations - on a real device, these apps |
| would usually be developed by streaming video content providers and the native |
| platform may or may not provide Matter interfaces to these apps. In some cases, |
| the video player platform will bridge its existing internal interfaces to |
| Matter, allowing apps to continue to not be Matter-aware, while other platforms |
| may provide Matter interfaces to Content Apps so that they can directly respond |
| to each Matter cluster. |
| |
| On Linux, there are shell commands to start and stop the dummy apps (by vendor |
| id): |
| |
| $ app add 1 (vendor id 1) |
| $ app add 2 (vendor id 2) |
| $ app add 9050 (vendor id 9050) |
| $ app remove 1 |
| |
| As an app platform, local apps can be used to facilitate commissioning using |
| their AccountLogin clusters. The dummy apps have hardcoded setup codes - on a |
| real device, these apps would communicate with a cloud service to obtain the |
| setup code given a rotating id from a tv-casting-app (eg. a phone app). You can |
| change the setup code for a given Content App using "setpin <vid> <pincode>": |
| |
| $ setpin 9050 20202021 |
| $ setpin 9050 34567890 |
| |
| When a UDC message comes from a vendor id that maps to a ContentApp in the |
| ContentAppPlatform, the AccountLogin cluster of the ContentApp endpoint will be |
| given the chance to obtain a setup code. You can trigger this process using "app |
| commission <udc-entry>". <udc-entry> will usually be 0 (when there is only one |
| entry in the UDC cache): |
| |
| $ app commission 0 |
| |
| - App Launching from chip-tool |
| |
| You can use chip-tool to launch apps by invoking the Application Launcher |
| cluster on endpoint 1 using chiptool: |
| |
| $ ./out/debug/chip-tool applicationlauncher launch-app Data CatalogVendorId ApplicationId node-id endpoint-id |
| $ ./out/debug/chip-tool applicationlauncher launch-app foo1 1 App2 1234 1 |
| |
| - Target Navigation from chip-tool |
| |
| You can use chip-tool to navigate among targets on endpoint 1 (main video |
| player) and on Content App endpoints: |
| |
| Read targets for a given endpoint: |
| |
| $ ./out/debug/chip-tool targetnavigator read attr-name node-id endpoint-id |
| $ ./out/debug/chip-tool targetnavigator read target-navigator-list 1234 1 (video player endpoint 1) |
| $ ./out/debug/chip-tool targetnavigator read target-navigator-list 1234 6 (content app endpoint 6 - requires app to be launched) |
| |
| Navigate to a new target: |
| |
| $ ./out/debug/chip-tool targetnavigator navigate-target Target Data node-id endpoint-id |
| $ ./out/debug/chip-tool targetnavigator navigate-target 2 foo1 1234 6 (target id 2 on endpoint 6) |
| |
| ## Casting |
| |
| The tv-casting-app can be used to discover casting video players, selecting one, |
| sending a UDC message, get commissioned, and then send commands to the video |
| player and/or a Content App on it. |
| |
| - Start the Apps |
| |
| Start the tv-app: |
| |
| $ ./out/debug/chip-tv-app --secured-device-port 5640 --secured-commissioner-port 5552 |
| |
| Start the tv-casting-app: |
| |
| $ ./out/debug/chip-tv-casting-app |
| |
| TV casting app should discover video players on the network. Into the shell, |
| enter "1" to select the first one in the list: |
| |
| $ 1 |
| |
| TV casting app will send a UDC command to the selected video player. The tv-app |
| should print out receipt of the UDC message. |
| |
| - Commission the Casting App |
| |
| If the VID for the tv-casting-app matches the vid for a Content App, then you |
| can initiate commissioning using the Account Login cluster of the Content App: |
| |
| $ app commission <udc cache index> |
| $ app commission 0 |
| |
| If the VID does not match a ContentApp or the Account Login cluster of the |
| ContentApp endpoint does not provide the correct setup code, initiate |
| commissioning by entering the setup code into the shell: |
| |
| $ udc-commission <pincode> <udc-entry> |
| $ udc-commission 34567890 0 |
| |
| - Send commands from the Casting App |
| |
| TODO |
| |
| ## Running the Complete Example on Raspberry Pi 4 |
| |
| - Prerequisites |
| |
| 1. A Raspberry Pi 4 board |
| 2. A USB Bluetooth Dongle, Ubuntu desktop will send Bluetooth advertisement, |
| which will block Matter from connecting via BLE. On Ubuntu server, you |
| need to install `pi-bluetooth` via APT. |
| 3. Ubuntu 20.04 or newer image for ARM64 platform. |
| |
| - Building |
| |
| Follow [Building](#building) section of this document. |
| |
| - Running |
| |
| - [Optional] Plug USB Bluetooth dongle |
| |
| - Plug USB Bluetooth dongle and find its bluetooth device number. The |
| number after `hci` is the bluetooth device number, `1` in this |
| example. |
| |
| $ hciconfig |
| hci1: Type: Primary Bus: USB |
| BD Address: 00:1A:7D:AA:BB:CC ACL MTU: 310:10 SCO MTU: 64:8 |
| UP RUNNING PSCAN ISCAN |
| RX bytes:20942 acl:1023 sco:0 events:1140 errors:0 |
| TX bytes:16559 acl:1011 sco:0 commands:121 errors:0 |
| |
| hci0: Type: Primary Bus: UART |
| BD Address: B8:27:EB:AA:BB:CC ACL MTU: 1021:8 SCO MTU: 64:1 |
| UP RUNNING PSCAN ISCAN |
| RX bytes:8609495 acl:14 sco:0 events:217484 errors:0 |
| TX bytes:92185 acl:20 sco:0 commands:5259 errors:0 |
| |
| - Run TV Example App |
| |
| $ cd ~/connectedhomeip/examples/tv-app/linux |
| $ sudo out/debug/chip-tv-app --ble-device [bluetooth device number] |
| # In this example, the device we want to use is hci1 |
| $ sudo out/debug/chip-tv-app --ble-device 1 |
| |
| - Test the device using ChipDeviceController on your laptop / |
| workstation etc. |
