Matter Telink Lighting Example Application

The Telink Lighting Example demonstrates how to remotely control a white dimmable light bulb. It uses buttons to test changing the lighting and device states and LEDs to show the state of these changes. You can use this example as a reference for creating your own application.

Build and flash

1. Run the Docker container:

   $ docker run -it --rm -v $PWD:/host -w /host ghcr.io/project-chip/chip-build-telink:$(wget -q -O - https://raw.githubusercontent.com/project-chip/connectedhomeip/master/.github/workflows/examples-telink.yaml 2> /dev/null | grep chip-build-telink | awk -F: '{print $NF}')
   

   Compatible docker image version can be found in next file:

   $ .github/workflows/examples-telink.yaml
   

2. Activate the build environment:

   $ source ./scripts/activate.sh -p all,telink
   

3. In the example dir run (replace <build_target> with your board name, for example, tlsr9518adk80d, tlsr9528a or tlsr9258a):

   $ west build -b <build_target>
   

   Also use key -DFLASH_SIZE, if your board has memory size different from 2 MB, for example, -DFLASH_SIZE=1m or -DFLASH_SIZE=4m:

   $ west build -b tlsr9518adk80d -- -DFLASH_SIZE=4m
   

4. Flash binary:

   $ west flash --erase
   

Usage

UART

To get output from device, connect UART to following pins:

Buttons

The following buttons are available on tlsr9518adk80d board:

LEDs

Indicate current state of Thread network

Red LED indicates current state of Thread network. It is able to be in following states:

Indicate identify of device

Green LED used to identify the device. The LED starts blinking when the Identify command of the Identify cluster is received. The command's argument can be used to specify the the effect. It is able to be in following effects:

Indicate current state of lightbulb

By default, only Blue LED is used to show current state of lightbulb (only for lightning-app).

To enable RGB functionality in Your application set this config:

In Matter examples/lighting-app/telink/include/AppConfig.h, set the define USE_RGB_PWM:

    define USE_RGB_PWM 1

To get current state of lightbulb in RGB mode, connect 3-color LED module to following pins:

CHIP tool commands

1. Build chip-tool cli

2. Pair with device

   ${CHIP_TOOL_DIR}/chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}
   

   Example:

   ./chip-tool pairing ble-thread 1234 hex:0e080000000000010000000300000f35060004001fffe0020811111111222222220708fd61f77bd3df233e051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f010212340410445f2b5ca6f2a93a55ce570a70efeecb0c0402a0fff8 20202021 3840
   

3. Switch on the light:

   ${CHIP_TOOL_DIR}/chip-tool onoff on 1
   

   here:

   • onoff is name of cluster
   • on command to the cluster
   • 1 ID of endpoint

4. Switch off the light:

   ${CHIP_TOOL_DIR}/chip-tool onoff off 1
   

   here:

   • onoff is name of cluster
   • off command to the cluster
   • 1 ID of endpoint

5. Read the light state:

   ${CHIP_TOOL_DIR}/chip-tool onoff read on-off 1
   

   here:

   • onoff is name of cluster
   • read command to the cluster
   • on-off attribute to read
   • 1 ID of endpoint

6. Change brightness of light:

   ${CHIP_TOOL_DIR}/chip-tool levelcontrol move-to-level 32 0 0 0 1
   

   here:

   • levelcontrol is name of cluster
   • move-to-level command to the cluster
   • 32 brightness value
   • 0 transition time
   • 0 option mask
   • 0 option override
   • 1 ID of endpoint

7. Read brightness level:

   ./chip-tool levelcontrol read current-level 1
   

   here:

   • levelcontrol is name of cluster
   • read command to the cluster
   • current-level attribute to read
   • 1 ID of endpoint

OTA with Linux OTA Provider

OTA feature enabled by default only for ota-requestor-app example. To enable OTA feature for another Telink example:

• set CONFIG_CHIP_OTA_REQUESTOR=y in corresponding “prj.conf” configuration file.

After build application with enabled OTA feature, use next binary files:

• zephyr.bin - main binary to flash PCB (Use at least 2MB PCB).
• zephyr-ota.bin - binary for OTA Provider

All binaries has the same SW version. To test OTA “zephyr-ota.bin” should have higher SW version than base SW. Set CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=2 in corresponding “prj.conf” configuration file.

Usage of OTA:

• Build the Linux OTA Provider

  ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_ble=false
  

• Run the Linux OTA Provider with OTA image.

  ./chip-ota-provider-app -f zephyr-ota.bin
  

• Provision the Linux OTA Provider using chip-tool

  ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021
  

  here:

  • ${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider

• Configure the ACL of the ota-provider-app to allow access

  ./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}]' ${OTA_PROVIDER_NODE_ID} 0
  

  here:

  • ${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider

• Use the chip-tool to announce the ota-provider-app to start the OTA process

  ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0
  

  here:

  • ${OTA_PROVIDER_NODE_ID} is the node id of Linux OTA Provider
  • ${DEVICE_NODE_ID} is the node id of paired device

Once the transfer is complete, OTA requestor sends ApplyUpdateRequest command to OTA provider for applying the image. Device will restart on successful application of OTA image.

Building with Pigweed RPCs

The RPCs in lighting-common/lighting_service/lighting_service.proto can be used to control various functionalities of the lighting app from a USB-connected host computer. To build the example with the RPC server, run the following command with build-target replaced with the build target name of the Telink Semiconductor's kit you own:

```
$ west build -b tlsr9518adk80d -- -DOVERLAY_CONFIG=rpc.overlay
```