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.
This document has been tested on:
- x64 host machine to build (cross-compile) the example
- running Ubuntu for 64bit PC(AMD64) desktop 20.04 LTS.
- NXP i.MX 8M Mini EVK board to run the example
- 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.
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 https://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.
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 thedd
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 theof
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, an environment setup script is also generated, and there are prompt lines telling the user to source the script each time when using the SDK in a new shell, for example:
$ . /opt/fsl-imx-xwayland/5.10-hardknott/environment-setup-cortexa53-crypto-poky-linux
-
Build the example application:
Assuming that the working directory has been changed the CHIP Linux Examples code, all the other steps are the same.
# If the all-clusters example is to be built $ cd ~/connectedhomeip/examples/all-clusters-app/linux # If the lighting example is to be built $ cd ~/connectedhomeip/examples/lighting-app/linux # If the thermostat example is to be built $ cd ~/connectedhomeip/examples/thermostat/linux $ git submodule update --init $ source third_party/connectedhomeip/scripts/activate.sh $ PLATFORM_CFLAGS='-DCHIP_DEVICE_CONFIG_WIFI_STATION_IF_NAME=\"mlan0\"", "-DCHIP_DEVICE_CONFIG_LINUX_DHCPC_CMD=\"udhcpc -b -i %s \"' $ PKG_CONFIG_SYSROOT_DIR=${PKG_CONFIG_SYSROOT_DIR} \ PKG_CONFIG_LIBDIR=${PKG_CONFIG_PATH} \ gn gen out/aarch64 --args="target_os=\"linux\" target_cpu=\"arm64\" arm_arch=\"armv8-a\" import(\"//build_overrides/build.gni\") target_cflags=[ \"--sysroot=${SDKTARGETSYSROOT}\", \"${PLATFORM_CFLAGS}\" ] target_ldflags = [ \"--sysroot=${SDKTARGETSYSROOT}\" ] custom_toolchain=\"\${build_root}/toolchain/custom\" target_cc=\"${OECORE_NATIVE_SYSROOT}/usr/bin/aarch64-poky-linux/aarch64-poky-linux-gcc\" target_cxx=\"${OECORE_NATIVE_SYSROOT}/usr/bin/aarch64-poky-linux/aarch64-poky-linux-g++\" target_ar=\"${OECORE_NATIVE_SYSROOT}/usr/bin/aarch64-poky-linux/aarch64-poky-linux-ar\"" $ ninja -C out/aarch64
The executable file is built under out/aarch64, it can be executed on the i.MX 8M Mini EVK which running the Yocto image previously generated as described in the sections above.
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 <interface id>
Use the specific Bluetooth interface for BLE advertisement and connections.
interface id
: the number afterhci
when listing BLE interfaces using thehciconfig
command, for example,--ble-device 1
means usinghci1
interface. Default:0
.The BLE device on i.MX 8M Mini EVK is a module based on the NXP 88W8987 Wi-Fi/Bluetooth SoC.
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 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.
- Connect the i.MX 8M Mini EVK to ethernet via the onboard
ethernet port, then use the
In order to test the CHIP protocol functions, another device on the same network is needed to run the ChipDeviceController 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.
- Boot up Ubuntu on the Raspberry Pi
- Clone this connectedhomeip project
- Follow Python ChipDeviceController 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 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
andzcl Thermostat SetpointRaiseLower 8889 1 0 mode=1 amount=10
are Python CHIP Device Controller commands, not shell commands. The 3840 is the target device'sdiscriminator
. The 20202021 is thesetup pin code
. 8889 is thenode 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
AddWiFiNetwork
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
EnableNetwork
triggers the Wi-Fi AP connecting operation on i.MX8 Mini EVK.chip-device-ctrl > zcl NetworkCommissioning AddWiFiNetwork 8889 0 0 ssid=str:${SSID} credentials=str:${PASSWORD} breadcrumb=0 timeoutMs=5000 chip-device-ctrl > zcl NetworkCommissioning EnableNetwork 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.
-