diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 167e857b58ecfc..12d0c32dffcb7b 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -169,7 +169,7 @@ { "label": "Connect to device (Tizen)", "type": "shell", - "command": "sdb", + "command": "${env:TIZEN_SDK_ROOT}/tools/sdb", "args": ["connect", "${input:tizenTargetDeviceAddress}"], "problemMatcher": [], "runOptions": { @@ -179,12 +179,12 @@ { "label": "Install LightingApp (Tizen)", "type": "shell", - "command": "sdb", + "command": "${env:TIZEN_SDK_ROOT}/tools/sdb", "args": [ "-s", "${input:tizenTargetDeviceAddressSdb}", "install", - "${workspaceFolder}/out/tizen-arm-light/package/out/org.tizen.matter.example.lighting-1.0.0.tpk" + "${workspaceFolder}/out/tizen-arm-light/org.tizen.matter.example.lighting/out/org.tizen.matter.example.lighting-1.0.0.tpk" ], "problemMatcher": [], "runOptions": { @@ -354,7 +354,7 @@ "type": "command", "command": "shellCommand.execute", "args": { - "command": "sdb devices | grep -v 'List of devices attached' |awk '{print $1 \"|\" $1, $3, \"(\" $2 \")\"}'", + "command": "${env:TIZEN_SDK_ROOT}/tools/sdb devices | grep -v 'List of devices attached' |awk '{print $1 \"|\" $1, $3, \"(\" $2 \")\"}'", "fieldSeparator": "|", "description": "Select target device" } diff --git a/docs/platforms/index.md b/docs/platforms/index.md index bc345d2ff8d52d..f22cf21c60527b 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -17,6 +17,7 @@ openthread/index silabs/index stm32/index ti/index +tizen/index ``` - [Android](./android/) @@ -31,3 +32,4 @@ ti/index - [Silabs](./silabs/) - [STM32](./stm32/) - [TI](./ti/) +- [Tizen](./tizen/) diff --git a/docs/platforms/tizen/building.md b/docs/platforms/tizen/building.md new file mode 100644 index 00000000000000..650c6eae532cc1 --- /dev/null +++ b/docs/platforms/tizen/building.md @@ -0,0 +1,152 @@ +# Building for Tizen + +## Prerequisites + +### Docker Compose Environment + +We use a combined Docker Compose configuration with four services for different +Tizen development tasks: + +```yaml +version: "3.8" +name: matter +services: + tizen: + image: ghcr.io/project-chip/chip-build-tizen:latest + network_mode: "host" + privileged: true + user: ubuntu + working_dir: /workspace + volumes: + - .:/workspace + - /var/run/docker.sock:/var/run/docker.sock + environment: + PW_ENVIRONMENT_ROOT: /workspace/.environment-tizen + tty: true + stdin_open: true + tizen-qemu: + image: ghcr.io/project-chip/chip-build-tizen-qemu:latest + network_mode: "host" + privileged: true + user: ubuntu + working_dir: /workspace + volumes: + - .:/workspace + - /var/run/docker.sock:/var/run/docker.sock + environment: + PW_ENVIRONMENT_ROOT: /workspace/.environment-tizen-qemu + tty: true + stdin_open: true + crosscompile: + image: ghcr.io/project-chip/chip-build-crosscompile:latest + network_mode: "host" + privileged: true + user: ubuntu + working_dir: /workspace + volumes: + - .:/workspace + - /var/run/docker.sock:/var/run/docker.sock + environment: + PW_ENVIRONMENT_ROOT: /workspace/.environment-crosscompile + tty: true + stdin_open: true + linux: + image: ghcr.io/project-chip/chip-build:latest + network_mode: "host" + privileged: true + user: ubuntu + working_dir: /workspace + volumes: + - .:/workspace + - /var/run/docker.sock:/var/run/docker.sock + environment: + PW_ENVIRONMENT_ROOT: /workspace/.environment-linux + tty: true + stdin_open: true +``` + +| Service | Purpose | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `tizen` | Build Tizen TPK packages with the Tizen SDK toolchain; includes `sdb` | +| `tizen-qemu` | Extends the `tizen` image with QEMU support; used for running tests in the QEMU emulator; includes `sdb` | +| `crosscompile` | Build native Linux ARM64 binaries that can run on Tizen (e.g., on Raspberry Pi) | +| `linux` | Build Linux x64 host tools (e.g., `chip-tool`); useful for integration testing where part of the system runs on Tizen and part on Linux | + +All services share the same workspace volume. Artifacts built in one container +(e.g., `out/...`) are accessible from all other containers. + +The `tizen` and `tizen-qemu` containers include the `sdb` tool. You can use +`sdb` directly from inside the container, or install the +[Tizen VS Code Extension](./vscode_setup.md#tizen-extension-installation) to use +`sdb` from your host machine. + +## Building with build_examples.py + +### Building the Tizen TPK Package + +Start and enter the Tizen compilation environment: + +```bash +docker compose run --rm tizen bash +source scripts/activate.sh +``` + +Compile the application using the `build_examples.py` script. Supply the +`--enable-flashbundle` flag to pack the compiled binary, assets, and manifest +files into a deployable native Tizen package (`.tpk` bundle): + +```bash +./scripts/build/build_examples.py --target tizen-arm64-light-no-thread --enable-flashbundle build +``` + +The target artifacts and the generated installation bundle will be placed inside +the `out/tizen-arm64-light-no-thread/` directory. + +### Available Tizen Targets + +The following Tizen target patterns are available: + +```text +tizen-{arm,arm64}-{all-clusters,chip-tool,light,tests}[-asan][-coverage][-no-ble][-no-thread][-no-wifi][-ubsan][-with-ui] +``` + +For example: + +- `tizen-arm64-light-no-thread` – Lighting app for ARM64 without Thread (BLE + enabled) +- `tizen-arm64-light-no-thread-no-ble` – Lighting app without Thread and BLE +- `tizen-arm64-all-clusters-no-thread` – All-clusters app +- `tizen-arm64-tests` – Unit tests + +### Building the Linux-ARM64 Variant (Native Binary) + +To cross-compile a native Linux ARM64 binary that can run on Tizen (e.g., on +Raspberry Pi 4), use the `crosscompile` Docker service: + +```bash +docker compose run --rm crosscompile bash +source scripts/activate.sh +./scripts/build/build_examples.py --target linux-arm64-light-no-thread-no-ble-clang build +``` + +The output binary will be in `out/linux-arm64-light-no-thread-no-ble-clang/`. + +### Alternative: Building with GN and Ninja + +For advanced use cases that require direct control over build arguments, you can +build manually using `gn gen` and `ninja`. See the +[lighting-app Tizen README](../../../examples/lighting-app/tizen/README.md) for +detailed instructions. + +### Building chip-tool for the Host PC + +To build `chip-tool` for your Linux x64 host (needed for commissioning and +controlling Tizen devices), use the `linux` Docker service: + +```bash +docker compose run --rm linux bash +source scripts/activate.sh +./scripts/build/build_examples.py --target linux-x64-chip-tool-clang build +``` + +The output will be in `out/linux-x64-chip-tool-clang/`. diff --git a/docs/platforms/tizen/debugging_gdb.md b/docs/platforms/tizen/debugging_gdb.md new file mode 100644 index 00000000000000..2756abd8d6c4e3 --- /dev/null +++ b/docs/platforms/tizen/debugging_gdb.md @@ -0,0 +1,197 @@ +# Debugging with GDB + +This section covers how to debug Matter applications running on Tizen from the +command line using GDB. + +## Prerequisites + +- `sdb` tool available in your `PATH` (inside the Tizen Docker container or + installed via the + [VS Code Tizen Extension](./vscode_setup.md#tizen-extension-installation)) +- Application built with debug symbols (do not strip symbols) + +## Deploying GDBServer to the Target + +To debug applications on the target device, `gdbserver` must be available on the +Raspberry Pi. The `tizen_gdbserver_run.sh` helper script handles this +automatically, but you can also deploy it manually: + +```bash +# Push the aarch64 gdbserver from the Tizen SDK to the Raspberry Pi +sdb push $TIZEN_SDK_ROOT/tools/aarch64-linux-gnu-gdb-15.1/bin/gdbserver /opt/bin/aarch64-linux-gnu-gdbserver + +# Grant execution permissions +sdb shell chmod +x /opt/bin/aarch64-linux-gnu-gdbserver +``` + +## Debugging the Native Linux-ARM64 App via GDB CLI + +This approach debugs the standalone `linux-arm64` binary running directly on the +Tizen device. The binary is built using the crosscompile Docker service (see +[Building the Linux-ARM64 Variant](./building.md#building-the-linux-arm64-variant-native-binary)). + +### 1. Launch the Application via GDBServer on Target + +Run the application binary directly through `gdbserver`, which freezes the +application at the very first instruction entry point. Run this on the target +device: + +```bash +sdb shell /opt/bin/aarch64-linux-gnu-gdbserver :9999 /opt/matter/chip-lighting-app --wifi true --discriminator 1234 --passcode 11223344 +``` + +The console will print: +`Process /opt/matter/chip-lighting-app created; pid = ; Listening on port 9999` + +### 2. Start the Remote GDB CLI Session on Host PC + +Navigate to the build output directory to preserve relative path alignment: + +```bash +cd out/linux-arm64-light-no-thread-no-ble-clang +``` + +Execute the cross-compiled GDB binary with connection and breakpoint parameters: + +```bash +$TIZEN_SDK_ROOT/tools/aarch64-linux-gnu-gdb-15.1/bin/aarch64-linux-gnu-gdb \ + -ex "set auto-solib-add off" \ + -ex "target remote RASPBERRY_PI_IP:9999" \ + -ex "break LightingManager::InitiateAction" \ + -ex "continue" \ + chip-lighting-app +``` + +Replace `RASPBERRY_PI_IP` with your Raspberry Pi's IP address. + +### 3. Verify the Breakpoint + +Trigger a cluster state change from another terminal: + +```bash +./out/linux-x64-chip-tool/chip-tool onoff toggle 1 1 +``` + +The GDB console will stop at the breakpoint: + +```text +Thread 8 "chip-lighting-a" hit Breakpoint 1, LightingManager::InitiateAction (this=0xaaaad1ed2d30 , aAction=LightingManager::OFF_ACTION) + at ../../examples/lighting-app/lighting-common/src/LightingManager.cpp:46 +46 bool action_initiated = false; +``` + +You can now use standard GDB commands: `print aAction`, `backtrace`, `continue`, +etc. + +## Debugging the Tizen TPK App via GDB CLI + +Because Tizen apps are managed by the platform runtime lifecycle, we cannot use +direct execution via `gdbserver`. Instead, we use `app_launcher --debug` to +spawn the process in a suspended state, then attach `gdbserver`. + +The TPK app is built using the Tizen Docker service (see +[Building the Tizen TPK Package](./building.md#building-the-tizen-tpk-package)). + +### 1. Launch the App in Suspended Debug Mode + +Run this on the target device: + +```bash +sdb shell app_launcher --debug --start org.tizen.matter.example.lighting -- wifi true discriminator 1234 passcode 11223344 +``` + +The output will include the assigned PID: +`successfully launched pid = 473505 with debug 1` + +### 2. Attach GDBServer to the Suspended Process + +Attach `gdbserver` to the frozen PID on port `9999` (replace `473505` with your +active PID): + +```bash +sdb shell /opt/bin/aarch64-linux-gnu-gdbserver :9999 --attach 473505 +``` + +The console will report: `Listening on port 9999; Attached; pid = 473505` + +### 3. Start the Remote GDB CLI Session on Host PC + +Navigate to the Tizen build output directory: + +```bash +cd out/tizen-arm64-light-no-thread +``` + +Run the cross-compiled GDB with sysroot and connection parameters: + +```bash +$TIZEN_SDK_ROOT/tools/aarch64-linux-gnu-gdb-15.1/bin/aarch64-linux-gnu-gdb \ + -ex "set sysroot $TIZEN_SDK_SYSROOT_ARM64" \ + -ex "set solib-absolute-prefix $TIZEN_SDK_SYSROOT_ARM64" \ + -ex "target remote RASPBERRY_PI_IP:9999" \ + -ex "break LightingManager::InitiateAction" \ + -ex "continue" \ + chip-lighting-app +``` + +Replace `RASPBERRY_PI_IP` with your Raspberry Pi's IP address. + +### 4. Verify + +Trigger a toggle from another terminal: + +```bash +./out/linux-x64-chip-tool/chip-tool onoff toggle 1 1 +``` + +GDB will trap the execution: + +```text +Thread 1 "chip-lighting-a" hit Breakpoint 1, LightingManager::InitiateAction (this=0xaaaad1ed2d30, aAction=LightingManager::OFF_ACTION) + at ../../examples/lighting-app/tizen/src/LightingManager.cpp:46 +46 bool action_initiated = false; +``` + +## Using the tizen_gdbserver_run.sh Helper Script + +The SDK provides a helper script that automates the gdbserver deployment, +application launch in debug mode, and gdbserver attachment: + +```bash +./scripts/helpers/tizen_gdbserver_run.sh \ + --target RASPBERRY_PI_IP:26101 \ + --gdbserver-port 9999 \ + --app-name "org.tizen.matter.example.lighting" \ + -- \ + wifi true discriminator 1234 passcode 11223344 +``` + +Options: + +| Option | Description | +| ----------------------- | ----------------------------------------------------------------- | +| `--app-name APP_NAME` | Name of app to debug (required) | +| `--gdbserver-port PORT` | GDB server port (default: 9999) | +| `--target SDB_ID` | SDB identifier (if not specified, first connected device is used) | +| `-- APP_ARGUMENTS` | Arguments to pass to the debugged app | + +The script will: + +1. Detect or deploy `gdbserver` on the target device +2. Launch the application in suspended debug mode +3. Attach `gdbserver` to the process +4. Set up SDB port forwarding + +You can then connect from your host GDB or VS Code. + +## Analyzing Crash Dumps + +The `tizen-crashlog.sh` helper script processes core dumps from Tizen builds: + +```bash +./scripts/helpers/tizen-crashlog.sh +``` + +It will scan `out/tizen-*/dump/` directories for `.zip` files, extract core +dumps, and generate full thread backtraces using `gdb-multiarch` with the +correct Tizen sysroot. diff --git a/docs/platforms/tizen/index.md b/docs/platforms/tizen/index.md new file mode 100644 index 00000000000000..d982aa6c444b49 --- /dev/null +++ b/docs/platforms/tizen/index.md @@ -0,0 +1,20 @@ +# Tizen + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* +``` + +This guide covers building, deploying, testing, and debugging Matter +applications on the Tizen platform. + +- [Building for Tizen](./building.md) +- [Testing on QEMU Emulator](./qemu_testing.md) +- [Installing Tizen on Raspberry Pi](./raspberry_pi_install.md) +- [Testing Native Apps on Raspberry Pi](./raspberry_pi_native_apps.md) +- [Testing TPK Apps on Raspberry Pi](./raspberry_pi_tpk.md) +- [Debugging with GDB](./debugging_gdb.md) +- [VS Code Setup for Tizen Development](./vscode_setup.md) diff --git a/docs/platforms/tizen/qemu_testing.md b/docs/platforms/tizen/qemu_testing.md new file mode 100644 index 00000000000000..e30959f03bc3b7 --- /dev/null +++ b/docs/platforms/tizen/qemu_testing.md @@ -0,0 +1,53 @@ +# Testing on QEMU Emulator + +Matter provides a QEMU-based testing environment for Tizen that allows running +unit tests and integration tests without physical hardware. + +The QEMU environment uses a 32-bit ARM image. Tests are built and executed +automatically by `build_examples.py`. + +For more details on the QEMU test infrastructure, see the +[test driver README](../../../src/test_driver/tizen/README.md). + +## Prerequisites + +Enter the Tizen QEMU environment using the `tizen-qemu` Docker service (see +[Docker Compose Environment](./building.md#docker-compose-environment)): + +```bash +docker compose run --rm tizen-qemu bash +source scripts/activate.sh +``` + +## Running Tests + +Build and run the Tizen tests using `build_examples.py`. The `build` command for +the `tizen-arm-tests` target automatically compiles and runs both unit tests and +integration tests in QEMU: + +```bash +./scripts/build/build_examples.py --target tizen-arm-tests-no-thread-no-ble build +``` + +The test runner will: + +1. Boot Tizen in QEMU +2. Mount the build output directory with test binaries +3. Discover and run all unit test executables +4. Install the lighting TPK and run integration tests (pairing, on/off control) +5. Report pass/fail status for each test + +:::{note} The QEMU image is 32-bit ARM, so the `tizen-arm-tests` target must be +used (not `tizen-arm64-tests`). ::: + +## Coverage Reports + +To generate code coverage reports, build with the `--enable-coverage` flag: + +```bash +./scripts/build/build_examples.py --target tizen-arm-tests-no-thread-no-ble-coverage build +``` + +Coverage data (`.gcda` files) will be collected during the test run. The build +system will generate an HTML coverage report in +`out/tizen-arm-tests-no-thread-no-ble-coverage/coverage/html/`. diff --git a/docs/platforms/tizen/raspberry_pi_install.md b/docs/platforms/tizen/raspberry_pi_install.md new file mode 100644 index 00000000000000..1bb0ef44a57c60 --- /dev/null +++ b/docs/platforms/tizen/raspberry_pi_install.md @@ -0,0 +1,204 @@ +# Installing Tizen on Raspberry Pi 4 + +This guide covers how to install Tizen OS on a Raspberry Pi 4 and configure +Wi-Fi connectivity. + +## Prerequisites + +- Linux host, or Windows with WSL Ubuntu +- MicroSD card reader +- Docker Compose environment configured (see + [Building for Tizen](./building.md#docker-compose-environment)) + +## Download Tizen Images + +Download images from the Tizen release page: + + + +Select the latest version, then navigate to `images/standard/` and download: + +- `tizen-10.0-boot-image.tar.gz` – Bootloader image +- `tizen-10.0-headed-image.tar.gz` – Headed (GUI) OS image + +:::{note} Always check for the latest version. The URLs above are examples and +may not reflect the most recent release. ::: + +## Flashing the MicroSD Card + +The flashing process uses the `sd_fusing.py` script. Clone it from +: + +```bash +git clone https://git.tizen.org/cgit/platform/kernel/tizen-fusing-scripts +cd tizen-fusing-scripts +# Script is at: scripts/sd_fusing.py +``` + +For reference, see the official Tizen documentation at +. + +### On Ubuntu / Linux + +1. Insert the MicroSD card into your card reader. +2. Find the device with `lsblk` (look for the one matching your card size): + + ```bash + lsblk + ``` + +3. Wipe existing partitions (replace `/dev/sdYourCard` with your actual device, + e.g., `/dev/sde`): + + ```bash + sudo wipefs -a /dev/sdYourCard + ``` + +4. Flash the card: + + ```bash + # Format the card layout for Raspberry Pi 4 + sudo ./sd_fusing.py -d /dev/sdYourCard -t rpi4 --format + + # Flash the bootloader and OS images + sudo ./sd_fusing.py -d /dev/sdYourCard -b tizen-10.0-boot-image.tar.gz tizen-10.0-headed-image.tar.gz -t rpi4 + ``` + +5. Safe eject: + + ```bash + sync + ``` + + You can now insert the card into your Raspberry Pi 4 and boot it up. + +### On Windows + WSL 2 (Optional) + +Since Windows often locks raw storage drives, we use `usbipd` to pass the USB +card reader directly into the Linux kernel inside WSL. + +#### 1. Identify and Attach the USB Device (Windows PowerShell) + +Open **PowerShell as Administrator** to find and bind your USB card reader. + +**List all USB devices:** + +```powershell +usbipd list +``` + +**Force Windows to release the card reader** (using your device's specific +BUSID, for example, `3-21`): + +```powershell +usbipd bind --busid 3-21 --force +``` + +**Attach the device to WSL:** + +```powershell +usbipd attach --busid 3-21 --wsl +``` + +#### 2. Flash the Card (WSL Ubuntu Terminal) + +Switch to your **WSL (Ubuntu)** terminal and follow the same flashing steps as +in the Ubuntu section above. After flashing, run `sync` in WSL, then go back to +PowerShell and run `usbipd detach --busid 3-21`. + +## Configuring Wi-Fi + +The standard Tizen image lacks the Broadcom Wi-Fi firmware for the Raspberry +Pi 4. To install the missing firmware, you need access to the device console via +**SDB (Smart Development Bridge)**. + +### Connect via SDB + +The `sdb` tool is available inside the Tizen Docker container, or you can +install the +[Tizen VS Code Extension](./vscode_setup.md#tizen-extension-installation) to use +`sdb` from your host machine. + +To use `sdb` from Docker: + +```bash +docker compose run --rm tizen bash +``` + +Find your Raspberry Pi's IP address from your home router, then connect and +switch to root: + +```bash +sdb connect RASPBERRY_PI_IP +sdb root on +sdb shell +``` + +### Upload and Install the Wi-Fi Firmware + +The Wi-Fi firmware files are available from the +[RPi-Distro/firmware-nonfree](https://github.com/RPi-Distro/firmware-nonfree.git) +repository: + +```bash +git clone https://github.com/RPi-Distro/firmware-nonfree.git +``` + +The Tizen root file system is mounted as **Read-Only** by default. We must +temporarily change it to **Read-Write** to add the missing driver files. + +**On the Raspberry Pi console (`sdb shell`):** + +Unlock the file system and create the firmware directory: + +```bash +mount -o remount,rw / +mkdir -p /lib/firmware/brcm +``` + +**On your local terminal (second window):** + +Copy the physical firmware files from the cloned `firmware-nonfree` repository +into the temporary RAM directory (`/tmp`) of the Raspberry Pi: + +```bash +cd firmware-nonfree/debian/config/brcm80211/brcm/ + +# Push the physical binary, clm_blob, and txt configuration files +sdb push ../cypress/cyfmac43455-sdio-standard.bin /tmp/cyfmac43455-sdio.bin +sdb push ../cypress/cyfmac43455-sdio.clm_blob /tmp/cyfmac43455-sdio.clm_blob +sdb push brcmfmac43455-sdio.txt /tmp/brcmfmac43455-sdio.txt +``` + +**Back on the Raspberry Pi console (`sdb shell`):** + +Move the files from `/tmp` into the correct system paths, renaming them to match +what the Linux kernel expects for the Raspberry Pi 4 model: + +```bash +cd /lib/firmware/brcm/ + +cp /tmp/cyfmac43455-sdio.bin brcmfmac43455-sdio.bin +cp /tmp/cyfmac43455-sdio.bin brcmfmac43455-sdio.raspberrypi,4-model-b.bin + +cp /tmp/cyfmac43455-sdio.clm_blob brcmfmac43455-sdio.clm_blob +cp /tmp/cyfmac43455-sdio.clm_blob brcmfmac43455-sdio.raspberrypi,4-model-b.clm_blob + +cp /tmp/brcmfmac43455-sdio.txt brcmfmac43455-sdio.txt +cp /tmp/brcmfmac43455-sdio.txt brcmfmac43455-sdio.raspberrypi,4-model-b.txt + +# Lock the system back to Read-Only and restart +mount -o remount,ro / +reboot +``` + +After the reboot, the Raspberry Pi kernel successfully detects the wireless +chip, creating the `wlan0` interface. You can now scan and connect to your local +network directly inside the Tizen graphical user interface (GUI). + +## Additional Resources + +- [Tizen flashing documentation](https://docs.stg.tizen.org/platform/developing/flashing-rpi/) +- [sd_fusing.py script source](https://git.tizen.org/cgit/platform/kernel/tizen-fusing-scripts) +- [Wi-Fi firmware source](https://github.com/RPi-Distro/firmware-nonfree) +- [Samsung Tizen OS device configuration guide](https://samsungtizenos.com/docs/application/flutter/guides/flutter-tizen/doc/configure-device) diff --git a/docs/platforms/tizen/raspberry_pi_native_apps.md b/docs/platforms/tizen/raspberry_pi_native_apps.md new file mode 100644 index 00000000000000..c99e0137a3daab --- /dev/null +++ b/docs/platforms/tizen/raspberry_pi_native_apps.md @@ -0,0 +1,111 @@ +# Testing Native Apps on Raspberry Pi + +This section documents how to cross-compile the Matter lighting application as a +native Linux ARM64 binary, deploy it to a Raspberry Pi 4 running Tizen OS, and +test it using `chip-tool`. + +Unlike the TPK approach, this method runs the application as a standalone +executable without the Tizen package manager. This is useful for rapid +development iteration. + +## Prerequisites + +- Raspberry Pi 4 running Tizen OS with Wi-Fi configured (see + [Installing Tizen on Raspberry Pi](./raspberry_pi_install.md)) +- `sdb` tool — available inside the Tizen Docker container (see + [Building for Tizen](./building.md#docker-compose-environment)) +- `chip-tool` built for your host PC (see + [Building chip-tool](./building.md#building-chip-tool-for-the-host-pc)) + +## Building + +Use the `crosscompile` Docker service to build the Linux ARM64 variant: + +```bash +docker compose run --rm crosscompile bash +source scripts/activate.sh +./scripts/build/build_examples.py --target linux-arm64-light-no-thread-no-ble-clang build +exit +``` + +The output binary will be in `out/linux-arm64-light-no-thread-no-ble-clang/`. + +:::{note} All Docker services share the same workspace volume. Artifacts built +in the `crosscompile` container (e.g., +`out/linux-arm64-light-no-thread-no-ble-clang/`) are also accessible from the +`tizen` container, and vice versa. ::: + +## Installing the Binary via SDB + +Use `sdb` from the Tizen Docker container. The build output from `crosscompile` +is available in the shared workspace: + +```bash +docker compose run --rm tizen bash +sdb connect RASPBERRY_PI_IP +sdb root on + +# Ensure the target directory exists on the Raspberry Pi +sdb shell mkdir -p /opt/matter/ + +# Push the native executable binary to the target deployment path +sdb push out/linux-arm64-light-no-thread-no-ble-clang/chip-lighting-app /opt/matter/ + +# Mark the binary as an executable on the device +sdb shell chmod +x /opt/matter/chip-lighting-app +``` + +## Running the Application + +Run the application on the Raspberry Pi with target network parameters: + +```bash +sdb shell /opt/matter/chip-lighting-app --wifi true --discriminator 1234 --passcode 11223344 +``` + +## Commissioning and Control via chip-tool + +Once the application is running on the Raspberry Pi, use `chip-tool` on your +host PC to pair and control the device. + +### Network Commissioning + +Pair the target device over the network. We assign `Node ID = 1` using the +configured passcode: + +```bash +./out/linux-x64-chip-tool/chip-tool pairing onnetwork 1 11223344 +``` + +Verify that the log output displays successful CASE session establishment. + +### Controlling the Cluster State (Toggle) + +Send an On/Off toggle action command to the commissioned lighting application at +`Node ID = 1` on endpoint `1`: + +```bash +./out/linux-x64-chip-tool/chip-tool onoff toggle 1 1 +``` + +## Verification + +- **Raspberry Pi Logs:** The terminal should register an incoming ZCL + interaction model action frame and transition the light attribute state + (`OFF_ACTION` / `ON_ACTION`). +- **PC Terminal Status:** The `chip-tool` output must return a successful + command transmission status. + +## Cleaning Up + +To stop the application on the Raspberry Pi: + +```bash +sdb shell killall chip-lighting-app +``` + +To remove the deployed binary: + +```bash +sdb shell rm -rf /opt/matter/ +``` diff --git a/docs/platforms/tizen/raspberry_pi_tpk.md b/docs/platforms/tizen/raspberry_pi_tpk.md new file mode 100644 index 00000000000000..3184858a1f2cd8 --- /dev/null +++ b/docs/platforms/tizen/raspberry_pi_tpk.md @@ -0,0 +1,140 @@ +# Testing TPK Apps on Raspberry Pi + +This section documents how to compile the Matter lighting application as a +native Tizen package (`.tpk`) for an ARM64 target (Raspberry Pi 4 running Tizen +OS), install it, and test it using `chip-tool`. + +The TPK approach uses the Tizen package manager for proper application lifecycle +management, which is the recommended way for production deployments. This is +different from the [native Linux ARM64 approach](./raspberry_pi_native_apps.md), +which deploys a standalone binary — that works without TPK packaging but +bypasses the Tizen runtime lifecycle. The `--enable-flashbundle` flag is +required to generate the `.tpk` file; without it, only the raw binary is +produced, which cannot be easily installed and run on Tizen. + +## Prerequisites + +- Raspberry Pi 4 running Tizen OS with Wi-Fi configured (see + [Installing Tizen on Raspberry Pi](./raspberry_pi_install.md)) +- `sdb` tool — available inside the Tizen Docker container (see + [Building for Tizen](./building.md#docker-compose-environment)) +- `chip-tool` built for your host PC (see + [Building chip-tool](./building.md#building-chip-tool-for-the-host-pc)) + +## Building + +Start and enter the Tizen compilation environment: + +```bash +docker compose run --rm tizen bash +source scripts/activate.sh +``` + +Compile the application with the `--enable-flashbundle` flag to generate the +`.tpk` bundle: + +```bash +./scripts/build/build_examples.py --target tizen-arm64-light-no-thread --enable-flashbundle build +``` + +The target artifacts and the generated installation bundle will be placed inside +the `out/tizen-arm64-light-no-thread/` directory. + +## Connecting via SDB + +Use `sdb` from the Tizen Docker container. Connect to the device and switch to +root: + +```bash +docker compose run --rm tizen bash +sdb connect RASPBERRY_PI_IP +sdb root on +``` + +## Installing the TPK + +Install the `.tpk` on the device: + +```bash +sdb install out/tizen-arm64-light-no-thread/flashbundle/org.tizen.matter.example.lighting-1.0.0-arm64.tpk +``` + +### Verifying the Installation + +To check if the application is installed and fetch the Package ID: + +```bash +sdb shell pkgcmd -l | grep -i matter +``` + +Expected identifier: + +- **Package ID / App ID:** `org.tizen.matter.example.lighting` + +### Reinstalling + +If the application already exists on the device, you must uninstall it first +before installing a new version: + +```bash +sdb uninstall org.tizen.matter.example.lighting +sdb install out/tizen-arm64-light-no-thread/flashbundle/org.tizen.matter.example.lighting-1.0.0-arm64.tpk +``` + +:::{note} You cannot reinstall an application with a different author +certificate. If you regenerated the certificate, you must uninstall first. ::: + +## Launching the Application + +Native Tizen applications are managed by the platform runtime. Use +`app_launcher` to start the application: + +```bash +sdb shell app_launcher --start org.tizen.matter.example.lighting -- wifi true discriminator 1234 passcode 11223344 +``` + +## Monitoring Application Logs + +Tizen channels application standard outputs and errors through the `dlog` +daemon. To trace execution on the target device, use `dlogutil` with the `--pid` +option: + +```bash +# Launch the app and note the PID from the output +sdb shell app_launcher --start org.tizen.matter.example.lighting -- wifi true discriminator 1234 passcode 11223344 +# Output: successfully launched pid = 473505 + +# Capture logs in real time using the PID +sdb shell dlogutil --pid 473505 +``` + +This will stream Matter engine initializations, mDNS advertisements, and cluster +interaction states. + +## Commissioning and Control via chip-tool + +Open a separate terminal window on your host PC to run the control scripts. + +### Commissioning + +```bash +./out/linux-x64-chip-tool/chip-tool pairing onnetwork 1 11223344 +``` + +### Attribute Cluster Interaction (Toggle Command) + +```bash +./out/linux-x64-chip-tool/chip-tool onoff toggle 1 1 +``` + +### Verification + +Check your active `dlogutil` terminal window. You should see incoming ZCL +interaction frames and the light attribute status logging transitions between +`OFF_ACTION` and `ON_ACTION`. + +## Stopping the Application + +```bash +sdb shell app_launcher --stop org.tizen.matter.example.lighting +``` diff --git a/docs/platforms/tizen/vscode_setup.md b/docs/platforms/tizen/vscode_setup.md new file mode 100644 index 00000000000000..6585250a7d9199 --- /dev/null +++ b/docs/platforms/tizen/vscode_setup.md @@ -0,0 +1,263 @@ +# VS Code Setup for Tizen Development + +This guide describes how to set up Visual Studio Code for Tizen development. It +covers the recommended dev container workflow, the Tizen extension setup, task +integration, and graphical debugging. + +## Dev Container Setup (Recommended) + +The recommended way to develop for Tizen is using VS Code with a dev container. +This approach provides a pre-configured environment with all necessary tools and +SDKs for multiple Tizen targets. + +### Prerequisites + +- **Docker** installed and running on your host machine +- **Dev Containers** extension for VS Code installed + +### Setup Instructions + +1. Open the workspace in VS Code and select "Reopen in Container" when prompted, + or use the Command Palette (`Ctrl+Shift+P`) → + `Dev Containers: Reopen in Container`. + +2. The dev container includes: + + - Tizen SDK 10.0 with support for multiple target architectures (device, + device64) + - All required toolchains (ARM, ARM64, x86) + - Pre-configured environment variables for Tizen development + - `sdb` tool available at `/opt/tizen-sdk/tools/sdb` + +3. The container image is approximately 20GB in size as it includes: + - Multiple Tizen platform rootstraps + - Toolchains for various architectures + - Tizen Studio tools and utilities + +### Environment Variables + +Inside the dev container, the following environment variables are set: + +```bash +declare -x TIZEN_ROOTFS="/tizen_rootfs" +declare -x TIZEN_SDK_ROOT="/opt/tizen-sdk" +declare -x TIZEN_SDK_SYSROOT="/opt/tizen-sdk/platforms/tizen-10.0/tizen/rootstraps/tizen-10.0-device.core" +declare -x TIZEN_SDK_TOOLCHAIN="/opt/tizen-sdk/tools/arm-linux-gnueabi-gcc-14.2" +declare -x TIZEN_VERSION="10.0" +``` + +### Using VS Code Tasks + +The dev container supports VS Code tasks for common Tizen operations. The tasks +are configured in `.vscode/tasks.json` and use the correct paths to Tizen tools. + +> **Note:** The `sdb` tool is located at `/opt/tizen-sdk/tools/sdb` inside the +> dev container. This path is not in the default `PATH` environment variable, so +> tasks must use the full path or the `TIZEN_SDK_ROOT/tools/sdb` variable. + +### Building Applications + +Use the VS Code tasks to build Tizen applications: + +1. Open the Command Palette (`Ctrl+Shift+P`) → `Tasks: Run Task` → + `Build LightingApp (Tizen)` + +2. Or use the terminal inside the container: + ```bash + scripts/run_in_build_env.sh "./scripts/build/build_examples.py --target tizen-arm-light build" + ``` + +## WSL Alternative (Tizen Extension) + +As an alternative to dev containers, you can use WSL with the Tizen extension +installed locally. This approach provides direct access to Tizen tools from VS +Code. + +### Tizen Extension Installation + +1. Install the **C/C++** extension (by Microsoft) – required for the underlying + `cppdbg` debugging engine. +2. Install the **Tizen Extension for Visual Studio Code** (by Samsung) from the + Marketplace. + +Once the extension is installed, it handles the download of the required CLI +package tools: + +1. Open the VS Code Command Palette (`Ctrl+Shift+P`). +2. Search for and select: `Tizen: Package Manager`. +3. Follow the UI prompts to install the **Extension Tools** and the **10.0 + Platform target rootstraps** (specifically ensuring the 64-bit device profile + is downloaded). + +The extension installs the SDK layout into a hidden system extension directory +(typically under `~/.tizen-extension-platform/`). Verify that your shell profile +exposes these automated tools: + +```bash +export | grep TIZEN +``` + +Expected output: + +```text +declare -x TIZEN_CLI_PATH="~/.tizen-extension-platform/server/sdktools/data/tools/ide/bin" +declare -x TIZEN_DOTNET_ROOT="~/.tizen-extension-platform/server/sdktools/dotnet" +declare -x TIZEN_SDK="~/.tizen-extension-platform/server/sdktools/data" +declare -x TIZEN_SDK_ROOT="~/.tizen-extension-platform/server/sdktools/data" +declare -x TIZEN_TOOLS_PATH="~/.tizen-extension-platform/server/sdktools/data/tools" +``` + +The `sdb` tool is installed as part of the Tizen extension and is available at +`~/.tizen-extension-platform/server/sdktools/data/tools/`. + +## VS Code Tasks for Tizen + +VS Code provides built-in task support for common Tizen development operations. +The tasks are configured in `.vscode/tasks.json` in the workspace root. + +### Available Tasks + +1. **Build app:** + + Open the Command Palette (`Ctrl+Shift+P`) → `Tasks: Run Task` → + `Build LightingApp (Tizen)` + +2. **SDB connect to device:** Required to run Tizen commands below if the device + is debugged over network. + + Open the Command Palette → `Tasks: Run Task` → `Connect to device (Tizen)` → + insert IP address and port + +3. **Install app:** Separated from the build step. + + Open the Command Palette → `Tasks: Run Task` → `Install LightingApp (Tizen)` + +4. **Launch with gdbserver attached:** Requires the app to be installed + previously. + + Open the Command Palette → `Tasks: Run Task` → + `Launch LightingApp with gdbserver attached (Tizen)` + +## Graphical Remote Debugging via VS Code + +This section describes how to set up remote debugging with VS Code, allowing you +to hit breakpoints, inspect variables, and view stack traces visually. + +### 1. Launch and Prepare the Process on Target + +Use the `tizen_gdbserver_run.sh` helper script to deploy gdbserver, launch the +app in debug mode, attach gdbserver, and set up port forwarding: + +```bash +./scripts/helpers/tizen_gdbserver_run.sh \ + --app-name "org.tizen.matter.example.lighting" \ + -- \ + wifi true discriminator 1234 passcode 11223344 +``` + +Alternatively, perform the steps manually: + +```bash +# 1. Spawn the application context in frozen debug mode +sdb shell app_launcher --debug --start org.tizen.matter.example.lighting -- wifi true discriminator 1234 passcode 11223344 + +# Note the returned PID from the output, e.g., 473505 + +# 2. Attach gdbserver to the live PID +sdb shell /opt/bin/aarch64-linux-gnu-gdbserver :9999 --attach 473505 + +# 3. Set up port forwarding +sdb forward tcp:9999 tcp:9999 +``` + +### 2. VS Code Workspace Configuration (launch.json) + +Create or update the `.vscode/launch.json` file in your workspace root: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "LightingApp (Tizen aarch64) - Remote Debug", + "type": "cppdbg", + "request": "launch", + "cwd": "${workspaceFolder}/out/tizen-arm64-light-no-thread", + "program": "${workspaceFolder}/out/tizen-arm64-light-no-thread/chip-lighting-app", + "targetArchitecture": "arm64", + "miDebuggerPath": "${env:TIZEN_SDK_ROOT}/tools/aarch64-linux-gnu-gdb-15.1/bin/aarch64-linux-gnu-gdb", + "miDebuggerServerAddress": "localhost:9999", + "additionalSOLibSearchPath": "${workspaceFolder}/out/tizen-arm64-light-no-thread;${env:TIZEN_SDK_SYSROOT_ARM64}/lib64;${env:TIZEN_SDK_SYSROOT_ARM64}/usr/lib64", + "linux": { + "MIMode": "gdb" + }, + "setupCommands": [ + { + "description": "Tell GDB not to stop the app on VS Code internal SIGINT signals", + "text": "handle SIGINT nostop noprint pass", + "ignoreFailures": true + }, + { + "description": "Tell GDB not to stop on standard terminate signals", + "text": "handle SIGTERM nostop noprint pass", + "ignoreFailures": true + }, + { + "description": "Lock down architecture layout to aarch64 inside the GDB engine", + "text": "set architecture aarch64", + "ignoreFailures": false + }, + { + "description": "Redirect sysroot to the local 64-bit Tizen SDK rootstrap directory", + "text": "set sysroot ${env:TIZEN_SDK_SYSROOT_ARM64}", + "ignoreFailures": false + }, + { + "description": "Set absolute prefix to align with local SDK shared object layout", + "text": "set solib-absolute-prefix ${env:TIZEN_SDK_SYSROOT_ARM64}", + "ignoreFailures": true + }, + { + "description": "Enable pretty-printing for complex C++ structures", + "text": "-enable-pretty-printing", + "ignoreFailures": true + } + ], + "stopAtEntry": false + } + ] +} +``` + +The configuration uses `localhost:9999` as the debugger server address because +the `tizen_gdbserver_run.sh` helper script (or `sdb forward`) sets up port +forwarding from the host to the target device. The target build is +`tizen-arm64-light-no-thread` — adjust the `cwd`, `program`, and +`additionalSOLibSearchPath` paths if using a different target. + +### 3. Starting the Debugging Session + +1. Open your source codebase folder in VS Code. +2. Open the file containing your target logic (e.g., + `examples/lighting-app/tizen/src/LightingManager.cpp`). +3. Click to the left of a line number to set a **visual red breakpoint** inside + `LightingManager::InitiateAction`. +4. Navigate to the **Run & Debug** view (`Ctrl+Shift+D`), select **"LightingApp + (Tizen aarch64) - Remote Debug"**, and press **F5**. +5. The VS Code status bar will turn orange, signaling that the graphical wrapper + has successfully established a link with the target `gdbserver`. + +### 4. Verification and Interactive Use + +1. Issue a toggle command from your host PC terminal: + + ```bash + ./out/linux-x64-chip-tool/chip-tool onoff toggle 1 1 + ``` + +2. VS Code will flash, highlighting your line of code in yellow. +3. You can now use the graphic debug interface: + - Track live stack frames in the **Call Stack** panel + - Mouse over variables (like `aAction`) to see data tooltips + - View live component variable fields in the **Variables** pane + - Step through code using the graphical controls (Step Over, Step Into) diff --git a/examples/lighting-app/tizen/README.md b/examples/lighting-app/tizen/README.md index d1b2fe474e9220..4f9b1fd05667d1 100644 --- a/examples/lighting-app/tizen/README.md +++ b/examples/lighting-app/tizen/README.md @@ -1,14 +1,46 @@ # CHIP Tizen Lighting Example -## Building binary +This example runs on Tizen 10 on Raspberry Pi 4. -Activating environment +For full documentation including Docker Compose setup, VS Code extension +configuration, and more, see the +[Tizen Platform Documentation](../../../docs/platforms/tizen/index.md). + +## Building + +### Building with build_examples.py (Recommended) + +The Docker Compose configuration with all required services (tizen, tizen-qemu, +crosscompile) is described in +[Building for Tizen](../../../docs/platforms/tizen/building.md). + +Start and enter the Tizen compilation environment: + +```bash +docker compose run --rm tizen bash +source scripts/activate.sh +``` + +Build the lighting app with TPK packaging: + +```bash +./scripts/build/build_examples.py --target tizen-arm64-light-no-thread --enable-flashbundle build +``` + +The output will be in `out/tizen-arm64-light-no-thread/`. + +### Building with GN and Ninja (Advanced) + +For advanced use cases that require direct control over build arguments, you can +build manually using `gn gen` and `ninja`. + +Activating environment: ```sh source ./scripts/activate.sh ``` -Generating tizen-arm-light +Generating build files for ARM: ```sh gn gen --check \ @@ -19,13 +51,24 @@ gn gen --check \ $PW_PROJECT_ROOT/out/tizen-arm-light ``` -Building tizen-arm-light +Building: ```sh ninja -C $PW_PROJECT_ROOT/out/tizen-arm-light ``` -## Preparing Tizen SDK certificate (optional) +For ARM64 target, adjust the `target_cpu` argument: + +```sh +gn gen --check \ + --fail-on-unused-args \ + --add-export-compile-commands=* \ + --root=$PW_PROJECT_ROOT/examples/lighting-app/tizen \ + "--args=target_os=\"tizen\" target_cpu=\"arm64\" tizen_sdk_root=\"$TIZEN_SDK_ROOT\" tizen_sdk_sysroot=\"$TIZEN_SDK_SYSROOT\"" \ + $PW_PROJECT_ROOT/out/tizen-arm64-light +``` + +## Preparing Tizen SDK Certificate (Optional) When building Matter example application, this step is optional. In case when author certificate and security profile are not found, they will be created @@ -79,6 +122,12 @@ pkgcmd -u -n org.tizen.matter.example.lighting ninja -C $PW_PROJECT_ROOT/out/tizen-arm-light chip-lighting-app:tpk ``` +For ARM64: + +```sh +ninja -C $PW_PROJECT_ROOT/out/tizen-arm64-light chip-lighting-app:tpk +``` + ## Installing TPK Upload TPK package to device under test (DUT). Install it with `pkgcmd` as @@ -88,7 +137,13 @@ follows: pkgcmd -i -t tpk -p org.tizen.matter.example.lighting-1.0.0.tpk ``` -## Launching application +Alternatively, you can use `sdb`: + +```bash +sdb install out/tizen-arm64-light-no-thread/flashbundle/org.tizen.matter.example.lighting-1.0.0-arm64.tpk +``` + +## Launching Application For launching Tizen application one should use `app_launcher`. It is possible to pass user arguments from command line which might be used to control application @@ -102,49 +157,13 @@ e.g.: app_launcher --start=org.tizen.matter.example.lighting discriminator 43 wifi true ``` -## Vscode support - -To run all commands below `sdb` has to be installed on computer and available in -`PATH`. Also vscode has to have the `augustocdias.tasks-shell-input` extension -installed. - -### Tasks - -1. Build app: - - ```text - open the Command Palette (Ctrl+Shift+P) -> - Tasks: Run Task -> - Build LightingApp (Tizen) - ``` - -2. SDB connect to device: required to run Tizen commands below if device is - debugged over network - - ```text - open the Command Palette (Ctrl+Shift+P) -> - Tasks: Run Task -> Connect to device (Tizen) -> - insert IP address and port - ``` - -3. Install app: it is separated from build app step. - - ```text - open the Command Palette (Ctrl+Shift+P) -> - Tasks: Run Task -> - Install LightingApp (Tizen) - ``` - -4. Launch LightingApp with gdbserver attached: require to install app - previously. - - ```text - open the Command Palette (Ctrl+Shift+P) -> - Tasks: Run Task -> - Launch LightingApp with gdbserver attached (Tizen) - ``` - -### Debug +## Debugging To debug app using vscode gdbserver has to be available on the target device, run `./scripts/helpers/tizen_gdbserver_run.sh --help` for more information. + +For more details on debugging with GDB CLI, see +[Debugging with GDB](../../../docs/platforms/tizen/debugging_gdb.md). + +For VS Code graphical debugging and tasks, see +[VS Code Setup for Tizen Development](../../../docs/platforms/tizen/vscode_setup.md). diff --git a/src/test_driver/tizen/README.md b/src/test_driver/tizen/README.md index d8b088db24bf6a..8afd87e1dd31c4 100644 --- a/src/test_driver/tizen/README.md +++ b/src/test_driver/tizen/README.md @@ -3,6 +3,9 @@ Tizen runs mostly on ARM architecture. In order to run tests on Tizen, we need to use QEMU. This document describes how to build and run CHIP tests on QEMU. +For the full Tizen testing documentation, see +[Testing on QEMU Emulator](../../../docs/platforms/tizen/qemu_testing.md). + ## Obtaining Tizen QEMU Docker Image All tools and dependencies required to build and run tests on Tizen on QEMU are