# Building and Running CHIP Linux Examples for i.MX 8M Mini EVK This document describes how to build below Linux examples with the NXP embedded Linux Yocto SDK and then run the output executable files on the **NXP i.MX 8M** **Mini EVK** development board. - [CHIP Linux All-clusters Example](../examples/all-clusters-app/linux/README.md) - [CHIP Linux Lighting Example](../examples/lighting-app/linux/README.md) - [CHIP Linux Thermostat Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/thermostat/linux) - [CHIP Linux CHIP-tool Example](../examples/chip-tool/README.md) - [CHIP Linux OTA-provider Example](../examples/ota-provider-app/linux/README.md) This document has been tested on: - x64 host machine to build (cross-compile) the example 1. running Ubuntu for 64bit PC(AMD64) desktop 20.04 LTS. - **NXP i.MX 8M Mini EVK** board to run the example 1. running Yocto image generated from the NXP released Yocto source code. The Yocto Project is an open source collaboration project focused on embedded Linux OS development. For more information about this project, see the [Yocto Project page](https://www.yoctoproject.org/).
- [Building and Running CHIP Linux Examples for i.MX 8M Mini EVK](#building-and-running-chip-linux-examples-for-imx-8m-mini-evk) - [Building](#building) - [Commandline arguments](#commandline-arguments) - [Running the Examples on i.MX 8M Mini EVK](#running-the-examples-on-imx-8m-mini-evk)
## Building Before building the CHIP Linux Examples, the Yocto source code released by NXP needs to be downloaded, then the Yocto SDK and the EVK Linux SD card image need to be generated. - Download the Yocto source code and generate the Yocto SDK and the SD card image The Yocto source code is maintained with a repo manifest, the tool `repo` is used to download the source code. This document is tested with the i.MX Yocto 5.10.35_2.0.0 release. Run the commands below to download this release: ``` mkdir ~/bin curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo export PATH=${PATH}:~/bin ``` ``` mkdir yocto # this directory will be the top directory of the Yocto source code cd yocto repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-hardknott -m imx-5.10.35-2.0.0.xml repo sync ``` To build the Yocto Project, some packages need to be installed. The list of packages required are: ``` sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \ build-essential chrpath socat cpio python3 python3-pip python3-pexpect \ xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \ pylint3 xterm ``` More information about the downloaded Yocto release can be found in the corresponding i.MX Yocto Project User’s Guide which can be found at [NXP official website](https://www.nxp.com/imxlinux). Change the current directory to the top directory of the Yocto source code and execute the commands below to generate the Yocto SDK: ``` MACHINE=imx8mmevk DISTRO=fsl-imx-xwayland source ./imx-setup-release.sh -b bld-xwayland bitbake imx-image-core -c populate_sdk ``` After the execution of the previous two commands, the SDK installation file can be found at tmp/deploy/sdk as a shell script. With the test environment of this document, the installation file name is: > fsl-imx-xwayland-glibc-x86_64-imx-image-core-cortexa53-crypto-imx8mmevk-toolchain-5.10-hardknott.sh Change the current directory to the top directory of the Yocto source code and execute the commands below to generate the Yocto SD card image: ``` MACHINE=imx8mmevk DISTRO=fsl-imx-xwayland source ./imx-setup-release.sh -b bld-xwayland echo "IMAGE_INSTALL_append += \"libavahi-client\"" >> conf/local.conf bitbake imx-image-core ``` The Yocto image can be found at tmp/deploy/images/imx8mmevk/imx-image-core-imx8mmevk.wic.bz2. The `bzip2` command should be used to unzip this file then the `dd` command should be used to program the output file to a microSD card by running the commands below. Then the microSD card can be used with the **i.MX 8M Mini EVK**. **Be cautious when executing the `dd` command below, make sure the `of` represents the microSD card device!**, `/dev/sdc` in the command below represents a microSD card connected to the host machine with a USB adapter, however the output device name may vary. ``` bzip2 -d imx-image-core-imx8mmevk-20210812084502.rootfs.wic.bz2 sudo dd if=imx-image-core-imx8mmevk-20210812084502.rootfs.wic of=/dev/sdc bs=4M conv=fsync ``` - Install the NXP Yocto SDK and set toolchain environment variables. Execute the SDK installation file with root permission. ``` sudo tmp/deploy/sdk/fsl-imx-xwayland-glibc-x86_64-imx-image-full-cortexa53-crypto-imx8mmevk-toolchain-5.10-hardknott.sh ``` After the Yocto SDK is installed on the host machine, to use the SDK when building the CHIP Linux Examples, export a shell environment variable named `IMX_SDK_ROOT` to specify the path of the SDK, for example: ``` export IMX_SDK_ROOT=/opt/fsl-imx-xwayland/5.10-hardknott ``` - Build the example application: Building those examples with the Yocto SDK specified by the `IMX_SDK_ROOT` has been integrated into the tool `build_examples.py` and the tool `imxlinux_example.sh`. Choose one of them to build the examples. Assuming that the working directory is changed to the top level directory of this project. ``` git submodule update --init source scripts/activate.sh # If the all-clusters example is to be built ./scripts/build/build_examples.py --target imx-all-clusters-app build # or ./scripts/examples/imxlinux_example.sh examples/all-clusters-app/linux examples/all-clusters-app/linux/out/aarch64 # If the lighting example is to be built ./scripts/build/build_examples.py --target imx-lighting-app build # or ./scripts/examples/imxlinux_example.sh examples/lighting-app/linux examples/lighting-app/linux/out/aarch64 # If the thermostat example is to be built ./scripts/build/build_examples.py --target imx-thermostat build # or ./scripts/examples/imxlinux_example.sh examples/thermostat/linux examples/thermostat/linux/out/aarch64 # If the chip-tool example is to be built ./scripts/build/build_examples.py --target imx-chip-tool build # or ./scripts/examples/imxlinux_example.sh examples/chip-tool examples/chip-tool/out/aarch64 # If the ota-provider example is to be built ./scripts/build/build_examples.py --target imx-ota-provider-app build # or ./scripts/examples/imxlinux_example.sh examples/ota-provider-app/linux examples/ota-provider-app/linux/out/aarch64 ``` If the `build_examples.py` is used, the executable files are built in the subdirectories under out/, the subdirectory name is the same as the argument specified after the option `--target` when build the examples. If the `imxlinux_example.sh` is used, the executable files are built in the directory specified by the second parameter when build the examples. The executable files can be executed on the **i.MX 8M Mini EVK** which running the Yocto image previously generated as described in the sections above. ## Commandline arguments The generated executable files supports to work with below commandline argument: - `--wifi` Enables Wi-Fi management feature. Required for Wi-Fi provisioning. The Wi-Fi device on **i.MX 8M Mini EVK** is a module based on the NXP 88W8987 Wi-Fi/Bluetooth SoC. - `--ble-device ` Use the specific Bluetooth interface for BLE advertisement and connections. `interface id`: the number after `hci` when listing BLE interfaces using the `hciconfig` command, for example, `--ble-device 1` means using `hci1` interface. Default: `0`. The BLE device on **i.MX 8M Mini EVK** is a module based on the NXP 88W8987 Wi-Fi/Bluetooth SoC. ## Running the Examples on i.MX 8M Mini EVK The steps and commands to run any of the examples are quite similar. Thermostat-app is used as an example below. - Prerequisites By following the [Building](#building) section of this document, the Yocto image is cross-compiled and programmed to a microSD card. Follow the steps below to setup the environment needed to run the example on the **i.MX 8M Mini EVK**: - Plug the microSD card with Yocto image into the SD-card slot of the **i.MX 8M** **Mini EVK**. - Change the boot switch on the **i.MX 8M Mini EVK** board to boot from MicroSD/SDHC2 based on the silkscreen print on the board. - Use a Type-A to Micro-B cable to connect the DEBUG port of the **i.MX 8M** **Mini EVK** to a host machine, and use a serial communication program like minicom or Putty to connect to the debug interface. - Power on the board to boot up the Yocto image, logging in with user name `root` via the serial communication program. There is password for the root user in the default Yocto image configuration. - Copy the executable file chip-lighting-app to the **i.MX 8M Mini EVK**, using either of the two methods below: - Connect the **i.MX 8M Mini EVK** to ethernet via the onboard ethernet port, then use the `scp` command on the host machine to copy the executable file to the **i.MX 8M Mini EVK**. - Use a U-disk to copy the executable file between the build machine and the **i.MX 8M Mini EVK**. In order to test the CHIP protocol functions, another device on the same network is needed to run the [ChipDeviceController](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/python) tool to communicate with the **i.MX 8M Mini EVK**. The ChipDeviceController can be a laptop / workstation. Bluetooth functionality is mandatory on this device. For the test environment used with this document, a Raspberry Pi is used to run the ChipDeviceController tool. Follow the steps below to setup the controller environment on a Raspberry Pi: - Install Ubuntu Server 20.04.2 LTS on the Raspberry Pi with reference to this page: [Install Ubuntu on a Raspberry Pi](https://ubuntu.com/download/raspberry-pi). - Boot up Ubuntu on the Raspberry Pi - Clone this connectedhomeip project - Follow Python ChipDeviceController [README.md](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/python/README.md) document. Refer to the "Building and installing" part to build the tool. - Running - Initialize the BT device on the **i.MX 8M Mini EVK** board ``` modprobe moal mod_para=nxp/wifi_mod_para.conf # Load the Wi-Fi/BT firmware hciattach /dev/ttymxc0 any 115200 flow # Initialize the BT device ``` - Find the Bluetooth device id for **i.MX 8M Mini EVK** by executing the command below. The number following string `hci` is the Bluetooth device id, `0` in this example. ``` $ hciconfig hci0: Type: Primary Bus: USB BD Address: 00:1A:7D:DA:71:13 ACL MTU: 310:10 SCO MTU: 64:8 UP RUNNING RX bytes:73311 acl:1527 sco:0 events:3023 errors:0 TX bytes:48805 acl:1459 sco:0 commands:704 errors:0 ``` - Run the Linux Example App ``` /home/root/thermostat-app --ble-device 0 --wifi # The bluetooth device used is hci0 and support wifi network ``` - Run [ChipDeviceController](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/python) on the controller device to communicate with **i.MX 8M Mini EVK** running the example. ``` $ sudo out/python_env/bin/chip-device-ctrl # execute the tool chip-device-ctrl > connect -ble 3840 20202021 8889 # connect to i.MX 8M Mini EVK chip-device-ctrl > zcl Thermostat SetpointRaiseLower 8889 1 0 mode=1 amount=10 # send command to i.MX 8M Mini EVK via BLE ``` (Note that the last two commands `connect -ble 3840 20202021 8889` and `zcl Thermostat SetpointRaiseLower 8889 1 0 mode=1 amount=10` are Python CHIP Device Controller commands, not shell commands. The 3840 is the target device's `discriminator`. The 20202021 is the `setup pin code`. 8889 is the `node id` and if not input 8889 a random node id will be assigned.) After the previous commands are executed, inspect the logs of both the **i.MX 8M Mini EVK** and the controller device to observe connection and control events. - Provision the **i.MX 8M Mini EVK** to a Wi-Fi AP with the following commands by `NetworkCommissioning` Cluster. Command `AddOrUpdateWiFiNetwork` sends the target Wi-Fi AP's SSID and password. The `${SSID}` and `${PASSWORD}` should be in plaintext format. At this moment, Wi-Fi is still idle on the **i.MX8 Mini EVK**. Command `ConnectNetwork` triggers the Wi-Fi AP connecting operation on **i.MX8 Mini EVK**. chip-device-ctrl > zcl NetworkCommissioning AddOrUpdateWiFiNetwork 8889 0 0 ssid=str:${SSID} credentials=str:${PASSWORD} breadcrumb=0 timeoutMs=5000 chip-device-ctrl > zcl NetworkCommissioning ConnectNetwork 8889 0 0 networkID=str:${SSID} breadcrumb=0 timeoutMs=15000 - Make sure the controller device is connected to the same network of this Wi-Fi AP because the Wi-Fi connection is established between the Wi-Fi AP and the **i.MX8 Mini EVK** and mDNS only works on local network. Resolve the target device with DNS-SD and update the address of the node. chip-device-ctrl > close-ble # Shutdown the BLE connection chip-device-ctrl > resolve 8889 # The 8889 is the node ID. chip-device-ctrl > zcl Thermostat SetpointRaiseLower 8889 1 0 mode=1 amount=10 # Now the ZCL command will be send via IP network.