Getting Started with MaaXBoard - Headless Setup

Previously, I showed you how to set up MaaXBoard with a monitor and keyboard here. This one focuses on getting setup headlessly via TTL, and configuring it to work with remote desktop.

Note: this tutorial is applicable for MaaXBoard Mini, with a couple slight modifications that are noted.

FLASH THE SD CARD

Currently, (March 2020) the only working image is the Debian image. An Android9 image is in development.

• Download the Debian image from the "Reference Designs" tab on Element14.
• Unzip it using a program like 7zip (you should end up with a.img file)
• Download and install Balena Etcher. Select your image and flash it to an SD card (SD card should be between 8 and 64GB).

CONNECT TO THE BOARD

1. Install CoolTerm (or another SSH client, like PuTTY or Cyberduck).

3. Connect the board to your USB-to-TTL cable. Connect pin 6 (the 3rd from the edge) to GND, pin 7 to RX (the white wire in this case) and pin 8 to TX (the green wire in this case).

4. Insert your prepared SD card into the slot

5. Connect to your MaaXBoard via serial using your SSH client. Baudrate should be 115200, data bits are 8, and stop bits are 1.

6. Connect the USB-C to power

NOTE: If you use a USB-C cable to power your board, don't plug it into your computer's USB ports, since it may draw more power than your USB ports can supply. You can also purchase the recommended 5V 3A power supply for the board here.

Connect via CoolTerm

Open CoolTerm and configure your settings. Baud rate should be 115200, data bits 8, and stop bits 1. I like to set the terminal mode to "line mode" and "filter ASCII Escape sequences" to reduce the gibberish.

Click "Connect" in CoolTerm.

You should see all the log messages while booting like in the picture below with the AVNET logo and the login prompt:

At this point you can log into the board with the default credentials:

User: root

Pass: avnet

CONNECT TO WIFI

The board also has an ethernet port. If you would prefer to connect that way, just plug in your ethernet cable. It should connect automatically, and you can skip to the next section. Otherwise, type the following:

nmcli r wifi on 
nmcli dev wifi

You should see a list of available WIFI networks.

nmcli dev wifi con "YOUR_SSID" password "YOUR_PASSWORD" ifname wlan0 
nmcli device con wlan0

(NOTE: include the quote marks around your SSID and password)

This is what you should see:

NOTE: MaaXBoard works with both 2.5 and 5gHZ WIFI, but not both together in the same SSID. If you see this error:

Error - secrets were required but not provided.

It's likely that you are on a dual-band or tri-band router that combines 2.5 and 5gHZ into a single SSID. The fix is to split the SSIDs apart (most routers have a button to split bands). Once you have split the bands, try deleting and reconnecting to a single band:

nmcli con delete <SSID>
nmcli r wifi off 
nmcli r wifi on

Save your wifi credentials:

Now we want to allow the board to reconnect on reboot. We will create a wpa_supplicant configuration file with the same credentials. Use the nano editor to create the file, in your serial console type the command:

nano /etc/wpa_supplicant/wpa_supplicant.conf

This will open a new empty file. You can write the following instructions into it by typing each line and pressing enter.

ctrl_interface=DIR=/var/run/wpa_supplicant

GROUP=wheel network={

ssid="YOUR_SSID"

scan_ssid=1

key_mgmt=WPA-PSK

psk="YOUR_PASSWORD"

}

In CoolTerm it will look like this mess:

Save the file with the command “CTRL-O” and close the editor with the command “CTRL-X" and "Y" for yes.

The story

Check to make sure you have the correct image:

cat /etc/*release
uname -a

I'm on Debian GNU/Linux 10, and it's Linux MaaXBoard 4.14.78.

Make sure your Advanced Package Tool (or APT) is up to date.

apt update

Note: you may need to update the mirrors for apt by editing /etc/apt/sources.list. I commented out the local chinese mirrors and added the main repo for buster as well as the security update and ftp repos at the top:

• deb http://deb.debian.org/debian buster main
• deb http://security.debian.org/ buster/updates main contrib non-free
• deb-src http://security.debian.org/ buster/updates main contrib non-free
• deb http://ftp.us.debian.org/debian/ buster main contrib non-free
• deb-src http://ftp.us.debian.org/debian/ buster main contrib non-free

Fixes for missing/out of date packages in the image

NOTE: There is more information about these fixes here. This version of Debian has a problem with apt. Enter this to fix it:

apt-get update --fix-missing
apt-get install libdevil1c2 -y
apt-get reinstall libqmi-glib5 -y

If using MaaXBoard: rename the symbolic link for libOpenVG to something else so that you no longer see the error "[package name] is not a symbolic link."

mv /usr/lib/aarch64-linux-gnu/libOpenVG.so /usr/lib/aarch64-linux-gnu/libOpenVG.so.OLD

If using MaaXBoard Mini: libOpenVG.so will be in a different folder, so rename it like this:

mv /usr/lib/libOpenVG.so /usr/lib/libOpenVG.so.OLD

Once you've run these commands you should now be able to install any packages you need using apt. For instance, install git (you'll need it later):

apt install wget git

CONNECT VIA SSH

Get your board's IP address by typing:

ifconfig

You should see something similar to the following output log:

This shows the IP address of your wifi connection, in this case 10.0.0.245.

Reboot the board by typing:

reboot

Disconnect the FTDI cable. I found that when I just unplugged the USB and left UART pins attached, SSH and Remote Desktop weren't able to connect (it gave me the error "operation timed out"), so I had to completely disconnect the FTDI cable. If anyone can explain to me why that is, I'd be grateful.

Connect using SSH:

Make sure your host computer is on the same network as the MaaXBoard. We will use SSH from the laptop to connect to the board. Open a terminal and type:

ssh root@10.0.0.245

If you are using windows you can either use Cygwin or PuTTY (https://www.putty.org/ ) to get a connection to the board, simply launch the app and use the same ip address you noted before.

Use the password "avnet" to login via SSH:

Make SSH faster:

SSH can be really slow. Usually the cause of this is the remote SSH server doing reverse dns lookup on every command. To disable this, open the sshd_config file and uncomment the line near the bottom of the file: "UseDNS = NO" to turn off DNS:

nano /etc/ssh/sshd_config

If it's still really slow, you can also uncomment the line "GSSAPIAuthentication no" at the top of the file to prevent it from trying to figure out if it should do encrypted authentication on every command.

Save the file with CTRL+O and exit the editor with CTRL+X. Now sync and reboot:

sync
reboot

Once the board is up and running (few minutes) reconnect to the same IP address with SSH:

ssh root@[IP ADDRESS]

How to connect when your IP address changes

If you're like me and have dozens of IOT devices on your desk, your IP address will probably change frequently, as other devices come on and off the network. If ssh doesn't work, I log into my router and check "attached devices" to find my MaaXBoard's new IP address.

Sometimes, you may even get a message like this when you try to connect via SSH:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

This means that your MaaXBoard is using an IP address that was previously used by a device that was connected to your host computer. To fix this, simply invalidate the existing ssh key with ssh-keygen:

ssh-keygen -R 192.168.1.30

Now you should be able to connect, and you'll be prompted to generate a new ssh key.

Use Multicast DNS

Alternatively, you can use multicast DNS (mDNS) to give your MaaXBoard a name like 'maaxboard.local' which is used instead of the IP address to connect to it. This way, if your IP address changes you don't have to worry about it. To do this, install avahi-daemon:

sudo dpkg --configure -a
sudo apt-get install avahi-daemon

You can check the name of your board or change it, open your hostname file:

sudo nano /etc/hostname

Your mDNS name will be the name defined here, plus the extension .local, e.g. maaxboard.local. You can change it to anything you like. Now, reboot the board:

sudo reboot

After reboot, if you have Avahi running on your host computer (default in macs) you can ping maaxboard.local and you should see a result. You can now use the name to connect to maaxboard.local via ssh:

ssh root@maaxboard.local

Note: you will still have to use the command ssh-keygen -R maaxboard.local if DHCP assigns an IP address to the board that has been previously used.

EXPAND THE FILESYSTEM

By default, the image takes up as little space on the SD card as possible. You can see how much space is used on the SD card by typing:

df -h

Note: can be a bit slow.

As you can see from the output, we're only using 6.4G of the SD card, and 91% of the filesystem partition is already full:

By expanding the filesystem, we'll get the entire SD card worth of space to use for files. In your ssh console 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 40% of the SD card, with 8.2G of available space. So much room for activities!

Increase the swap file size

The next step is mandatory if you plan to compile OpenCV on the board itself instead of using pre-compiled packages. Compiling large projects like OpenCV requires a lot of memory and the 2G of RAM available on the MaaXBoard will saturate quickly. We need a larger swapfile (another 2G) to keep up with the full build.

NOTE: frequent access in r/w to an sdcard is sub-optimal since will reduce the life of the sdcard itself. But in this case we plan to increase the size, compile, reduce the size of the swap file … an acceptable compromise if you don’t want / cannot cross-compile. The following command will tell you that there is no active swap file (because there is no output log):

swapon –show

We do create a file of 2G with these commands (remember: 2Gbytes = 1024*1024*2):

fallocate -l 2G /swapfile
dd if=/dev/zero of=/swapfile bs=1024 count=2097152
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

You can check the swap creation with “swapon –show” again:

swapon -show

To make sure that the swap file is activate at boot we need to add one line to the /etc/fstab file. Open the file with the nano editor by typing:

nano /etc/fstab

Add this line at the beginning of the file:

/swapfile swap swap defaults 0 0

Save the file with CTRL+X and "Y" to save. Now sync and reboot:

sync
reboot

Once the board is up and running again (few minutes) reconnect to the same IP address with SSH:

ssh root@[IP ADDRESS]

Login and check the status:

swapon -show

We have less space left, since 2G are taken from the swap file:

Changing Timezone

If you want to set the clock to your timezone, first check the list of available timezones to find the applicable one:

timedatectl list-timezones

If using MaaXBoard Mini: for some reason on MaaXBoard Mini Debian, the /etc folder doesn't have root permissions, so you will need to set root permissions like this:

chown root /etc

You can now set the correct reference time to your board:

timedatectl set-timezone "America/Los_Angeles"

Use Bluetooth

Execute the following instructions on the serial terminal:

hciattach /dev/ttymxc3 bcm43xx 115200 
hciconfig hci0 up

Put the device that you wish to connect to in pairing mode, and then scan to find its address. You can then connect to it using its address.

hcitool scan
hcitool cc {address}

CONFIGURE REMOTE DESKTOP

MaaXBoard comes preconfigured with Weston/Wayland https://wayland.freedesktop.org/ as window manager. This is an excellent choice for desktop setup but you want have a chance to properly use remote desktop (RDP) to connect to your board from your laptop to run tests & exercise. We will use an X11 lightweight alternative : XFCE4

Install the system with the command (using -y flags here to bypass where it asks you if you're OK with how much space these take up):

apt install xfce4 -y

I recommend installing the following packages to make sure copy/paste works correctly from guest to host:

apt install xfce4-clipman-plugin -y
apt install xfce4-goodies -y

We also need to stop Weston at boot time .. so that we save resources. Edit the /etc/rc.local file with the nano editor

nano /etc/rc.local

and add the following line before the “exit 0” at the bottom:

service weston stop

NOTE: if you would like to install X11 themes in the future make sure you install them under /usr/share/themes

Now we will install the RDP package (for remote desktop support) and few common utilities:

apt install xrdp -y
apt install gkrellm terminator htop sudo gnupg -y
apt-get install --reinstall cpufrequtils 
apt-get install --reinstall libcpufreq0

CREATE A NON-ROOT USER

So far we have operated as user “root”. This is not the best way to operate on a linux system. Normally we use a low-privilege user and we leverage the “sudo” command when we need to perform system level commands. Let’s create a user “ebv” with password “ebv”

NOTE: Why ebv? Because Gianluca who wrote the original tutorial works at Avnet subsidiary EBV :-D of course, feel free to use a longer and stronger password.

useradd -m -d /home/ebv -s /bin/bash -G sudo -U ebv
passwd ebv

The first command creates the user. The second one will set the password for “ebv” user.

Now we are ready for a final sync abd reboot, just to make sure all the startup scripts are correct.

sync
reboot

Once the board is back up use your RemoteDesktop app on Windows or Mac, or “rdesktop” on linux and connect to the board IP address with the user ebv.

Below are screenshots from my RemoteDesktop app on Mac:

Select “use default config” (will be a one-time only setup) for common settings.

You now have a full “headless” development system directly on your board, you can ether connect via SSH or RemoteDesktop. When working on python scripts this will be more useful since we can use our favorite editor (in our case Geany editor).

NOTE: use “GKrellMonitor” from the Applications->System menu to monitor your cpu/wlan/memory status.

Feel free to install your favorite text editor, in our case it will be Geany editor. To do so we open a terminal (either via SSH or from the remote desktop application bar on the bottom) and we use the “sudo” command as user “ebv” :

sudo apt-get install geany

I found that Chromium didn't work for mels, so instead I installed firefox (Debian stable requires firefox-esr):

sudo apt install firefox-esr

You can then launch it from the terminal by typing

firefox

Congratulations! Now you have a MaaxBoard fully configured for headless remote desktop development.

SAVE YOUR IMG FILE

Once you've gone through all of these steps, you'll likely want to save your headless image so you can easily get set up on another MaaXBoard. Most imaging software, like Win32Disk imager, or the dd command in linux, aren't smart enough to figure out the partition sizes of the image, so even if your image only takes up 7GB of your 32GB SD card, the software will copy a 32GB image. This can especially be a problem because 32GB SD cards come in different sizes. Some have as little as 28GB of usable space.

You'll want to use software that only copies the used partitions of the image file. There are a couple of good ways to do this that save your image file in the smallest size possible.

The first step is to repartition your MaaXBoard's image using fdisk (similar to what you did earlier when you deleted the partition) to create an unused partition that the software will know to delete.

Write your resized file:

• On Mac, I highly recommend Apple Pi Baker. Download it from here and give this developer a tip! When running the imager, be sure to select "Enable Linux Partition Resize" under options so that you get an image in the smallest size possible:

• On Linux, I recommend shrink - a super simple command line applet that will compress your image to the smallest size possible. Simply follow the instructions on github. Again, give this person a tip!