Yocto is a customizable version of embedded linux that is favored by silicon vendors like NXP. How is it different than other more familiar versions like Debian? The following is an excerpt from “Yocto or Debian for Embedded Systems” that sums up the difference between Debian and Yocto:
Compared to Debian, Yocto has a steep learning curve and long build times. Also, there are fewer tutorials, and you can't just apt-get packages.
Instead, Yocto images include customizable "layers" (like a parfait! Everybody loves parfait!). Layers can be software components like eIQ, NXP's suite of machine learning tools, or hardware components like meta-imx, the i.MX board support package that updates the FSL Community BSP. Layers contain "recipes." For instance, eIQ contains recipes for packages like Tensorflow and OpenCV.
There are lots of tutorials where you can learn more about Yocto. However, you won't need any extra knowledge to follow along with this tutorial to get up and running.
GETTING STARTEDTo get started with MaaXBoard running Yocto, it's easiest to have an external display and a keyboard. You will need these if you plan to run any of the OpenCV examples, or use the camera. You can also set up headlessly using a USB to TTL serial converter (FTDI cable). MaaXBoard Mini doesn't have an HDMI port so you'll probably want to set up headlessly, although you could also setup with a MIPI display. I cover both methods of setting up below.
Optionally, you can attach an ethernet cable, touchscreen, and/or camera (either the MaaXBoard MIPI-CSI camera or a USB camera).
Download the Yocto image for MaaXBoard or MaaXBoard Mini from Element14. This tutorial covers setup for both MaaXBoard and MaaXBoard Mini. There are only a couple of differences, which I'll point out as we go.
You'll notice that the unzipped image is under 3GB, compared to the MaaXBoard Debian image which is 7GB.
setting up headlesslyUnzip and burn the SD card with the appropriate Yocto image for your board. I recommend using balena etcher. After burning, insert the SD card in your MaaXBoard.
Plug your FTDI cable into GND, RX and TX on your MaaXBoard's 40 pin raspberry pi compatible header. I'm using this ftdi cable from Adafruit.
Plug your board into a 5V 2-3A type-C power supply. You should now be able to use a serial terminal application like TeraTerm to login to your MaaXBoard. Go to settings (Setup > serial port in TeraTerm) and provide the settings shown below to connect (use the Com port that corresponds to your own MaaXBoard). Then login with the username "root" and password "avnet" (you may not need to enter a password if logging on to regular MaaXBoard):
The first time you login, the system will reboot. You can then connect to wifi (see instructions below) in order to connect via SSH.
setting up with an external monitorMaaXBoard (but not MaaXBoard Mini) supports HDMI with 4K resolution. To get started, simply plug in a monitor or external display. The first time that you login, you'll see the default Yocto background. After rebooting, you should see the Wayland UI:
This is the Weston Wayland compositor. If you ever want to change how the UI behaves, you can type simply type weston --help or man weston.
The sidebar contains the following applications:
- Wayland Terminal(default terminal application)
- QtFM(file manager based on QT)
- Chromium(web browser)
- WiFi_Config (this is the GUI camera application that can also be run from the terminal by running
./wifi_sta_connect.sh
) - Camera(this is the GUI camera application that can also be run from the terminal by running
./camera
) - Video(plays video files)
- 3D Examples(plays some impressive 3D examplesthat use the GPU development library)
- QT Examples(more demos that showcase Yocto file system integrated QT5.9.4)
In order to use python and some other useful features, you'll need to switch to bash because the environmental variables aren't set for the default Wayland terminal on Yocto. Switch by simply typing:
bash
expand the file systemThe eIQ examples that we will be using in the next tutorial, which will cover running AI/ML on Yocto, require downloading large models from the internet. Because of this, I recommend using a 32GB or 64GB SD card. You'll also need to expand the file system so that you can use the entire SD card. You can see how much space is used on the SD card by typing:
df -h
As you can see, we're using 88% of the space available for the Yocto operating system. Type the command:
fdisk /dev/mmcblk0
- Enter “p” to show the partition list.
- Copy the "Start" number for the 2nd partition:
- Delete the second partition by entering “d” and then “2” for partition number.
- Create a new primary partition: press “n, ” then “p” for primary, then “2” for partition number.
- For the FIRST SECTOR address, enter the number you saved earlier. For LAST SECTOR, accept the suggested full size. You can also specify a specific size, like +10G to make a 10gb partition. Hit return.
- DO NOT delete the signature of the partition (“N”)
- Now write to the file system with command “w”.
- Synchronize the file system with command “sync”.
Finally we can resize the filesystem with the command:
resize2fs /dev/mmcblk0p2
This will resize the partition, if we do another “df –h” we can see the difference from the previous output. Now we're only using 14% of the SD card for the operating system, with 23G of available space.
Simply plug your ethernet cable into the board. You should be able to tell if you are connected to the internet by pinging any website:
ping google.com
Stop it using CTRL-C.
connect to wifiOn the default Yocto image, you'll find scripts to connect to bluetooth and WIFI inside the root user directory (/home/root
). I've also provided these scripts as attachments under the code section of this project in case you're using a custom built image that doesn't come with them.
Run the following script to connect to wifi (no quotation marks around SSID and password):
./wifi_sta_connect.sh YOUR_SSID YOUR_PASSWORD
To disconnect wifi, run the script:
./wifi_stop.sh
If you want MaaXBoard to connect to WIFI on startup, you can start the script at boot by piggypacking on another service that runs at startup: /etc/rc.local. Edit the file:
nano /etc/rc.local
Right below the first uncommented line (echo 3000 > ...
) add this line:
sh /home/root/wifi_sta_connect.sh YOUR_SSID YOUR_PASSWORD
The process to connect MaaXBoard Mini to WIFI on startup is slightly different. Create a new directory in etc/ named wpa_supplicant/. Move the file etc/wpa_supplicant.conf, which should have been autopopulated with your SSID and password when you connected, to the /etc/wpa_supplicant directory:
mkdir -p /etc/wpa_supplicant
cp /etc/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
systemctl start wpa_supplicant@wlan0
ystemctl enable wpa_supplicant@wlan0
create a new userFor added security it's a good idea to create a new user. Do this by typing:
adduser [YOUR USERNAME]
You should be prompted to enter the password. You can always change the password simply by typing:
passwd [YOUR USERNAME]
SSHOn MaaXBoard, you can now easily SSH to the board from your host PC:
ssh root@YOUR_SSID
Note: on MaaXBoard Mini, you'll need to uncomment the line "PermitRootLogin yes
" in your sshd_config file before you can connect via SSH. Edit sshd_config by typing:
nano /etc/ssh/sshd_config
set a static IP addressIf you need to set a static IP address, first set up the default route or gateway:
ip route show
Add the route info and then set the static IP address (use eth0 instead of wlan0 if setting a static IP using ethernet):
route add default gw 192.168.1.1
ifconfig wlan0 192.168.1.27
Here is another good tutorial showing how to remove and manage static IP addresses using route.
Note: to set a static IP address on MaaXBoard Mini, edit /etc/dhcpcd.conf
and add the following info (using your own chosen IP address):
interface eth0
static ip_address=192.168.1.27/24
static routers=192.168.1.1
static domain_name_servers=192.168.2.252 8.8.8.8
To use bluetooth on MaaXBoard, execute the following script (see attached code, or find it in the root user directory):
./bluetooth_start.sh
It's slightly more complex to use bluetooth on the MaaXBoard Mini's Lite image. Start bluetooth with these commands:
hciattach /dev/ttymxc3 bcm43xx 3000000
hciconfig hci0 up
Then use bluetoothctl to connefct to a bluetooth device (here, E8:EC:A3:21:57:6C is the address of the Bluetooth device, change it according to your device):
bluetoothctl
[bluetooth]# power on
[bluetooth]# pairable on
[bluetooth]# agent on
[bluetooth]# default-agent
[bluetooth]# scan on
[bluetooth]# scan off
[bluetooth]# pair E8:EC:A3:21:57:6C
[bluetooth]# trust E8:EC:A3:21:57:6C
[bluetooth]# connect E8:EC:A3:21:57:6C
[Mi Sports BT Earphones Basic]# quit
PERIPHERALSsetting up with touchscreenBesides allowing 4K HDMI on MaaXBoard, Yocto also supports MIPI-DSI as well as MIPI-LVDS on both MaaXBoard and MaaXBoard Mini, so it compatible with the MaaXBoard 7" touchscreen. I saved this step for after WIFI is set up because it is easiest to do via SSH. The screen resolutions for each are here:
For MaaXBoard Mini, MIPI-DSI will be enabled by default.
For MaaXBoard, you'll have to edit your uEnv.txt file to enable MIPI displays. One way to do this is to unplug your MaaXBoard, remove the SD card, and insert it into your host PC using an SD card reader. Open the file uEnv.txt and comment the line that says ftd_file=em-sbc-imx8m.dtb
. Uncomment the line that says #fdt_file=em-sbc-imx8m-dcss-dsi.dtb
(or possibly #ftd_file="maaxboard-dcss-mipi.dtb" if it's your own build of Yocto):
You can also edit uEnv.txt from the MaaXBoard's line command without removing the SD card by typing:
cd run/media/mmcblk0p1
nano uEnv.txt
Note: on MaaXBoard Mini you'll have to first mount the first partition of the SD card. Use the following commands:
mkdir mount
mount /dev/mmcblk0p1 mount/
nano mount/uEnv.txt
Attach the MIPI-DSI touchscreen to your MaaXBoard. The blue side of the flex connector faces the edge of the board. Insert the SD card in your MaaXBoard (if you removed it) and plug it back into power.
To calibrate the touchscreen on the MaaXBoard, connect via SSH and type:
ssh root@MYIPADDRESS
ts_calibrate
To test on MaaXBoard Mini, type:
evtest /dev/input/touchscreen0
The touchscreen will prompt you to calibrate by touching each corner of the screen:
To adjust the backlight brightness, send a value between 1 (dimmest) and 9 (brightest):
echo 7 > /sys/class/backlight/backlight/brightness
It's possible to set up sleep mode so that the display sleeps after a period of between 0 (display will never sleep) and 600 (sleeps after 10 minutes, or 600 seconds). Touching the display will wake it back up.
To set it to sleep after 10 minutes, use this command:
consoleblank=600
cameraIf using the MIPI-CSI camera, attach it so that the blue side faces the ethernet and USB ports. If using a USB camera, simply plug it into one of the USB ports.
To start the camera on MaaXBoard, from your root user directory simply run:
./Camera
You can also run the camera from the camera icon in the UI sidebar. The camera application will be shown on the screen:
Choose uvcvideo when you use the USB camera, and choose mx6s-csi when you use MIPI-CSI camera.
Note: On MaaXBoard Mini, to take a photo and save it to a specific location, run the following command:
gst-launch-1.0 v4l2src device=[video] num-buffers=1 ! jpegenc ! filesink location=[filename]
In above command, replace [video] with the camera device ID and [filename] with the path and name of saved file. For example:
gst-launch-1.0 v4l2src device=/dev/video0 num-buffers=1 ! jpegenc ! filesink location=sample.jpg
Copy the photo to another device, such as your computer to display it.
You can also record a video in mp4 format with this command:
gst-launch-1.0 -e v4l2src device=/dev/video0 num-buffers=100 ! video/x-raw,format=YUY2,framerate=30/1, width=640, height=480 ! videoconvert ! x264enc ! video/x-h264, profile=baseline ! mp4mux ! filesink location=output.mp4
In above command, modify the camera device ID, the width and height of the video, the path and name of saved file, etc. The video file can be copied to another device, such as computer to display it, or use the gst-play-1.0 command to display it on the screen directly:
gst-play-1.0 output.mp4
USBMaaXBoard has two USB 3.0 interfaces and MaaXBoard Mini has four USB 2.0
On both, USB0 is the only USB port that not only supports USB host mode, but also supports USB Device function, which could be used to burn the system image, or as a USB network adapter.
To see your USB devices, plug them into your MaaXBoard or MaaXBoard Mini and run:
ls /dev/sd*
Storage nodes for USB are named /dev/sda. You can use mount command to mount the device for further use.
THAT'S IT!If you want to learn more, the Yocto guides for MaaXBoard and MaaXBoard Mini by Embest on Element14 includes additional instructions for configuring a USB network device, open a WiFi hotspot, controlling the onboard buttons and LEDs, using a MIPI-LVDS screen, and testing the UART.
Next, check out this guide to building your own Yocto image for MaaXBoard.
Coming Soon: I'm working on using the eIQ layer that harnesses ArmNN to run machine learning inference more efficiently on the MaaXBoard. I'll be publishing a project featuring that shortly!
Comments