Getting started with PixieBoard

Note: If you’re installing the latest PXBoard Image for PXBoard PRO+ you might encounter some errors. While we get them solved, you can use the following workaround solution:

sudo pacman -S ca-certificates-utils #to rebuild the cert stores
sudo nmtui #Then select your wifi network & password
git clone https://github.com/pixierepo/pixieboard-setup
sudo sh pixieboard-setup/scripts/quick-conf.sh

After these steps, your PXBoard system will be correctly configured and behaving as you would expect.

Getting started with PixieBoard

In this tutorial you will learn how to set-up your PixieBoard for the first time and configure it so you can start working on your next Edge Computing project. You will learn how to create a new bootable microSD card, use the wireless networking features, install packages and configure basic settings to enable PixieBoards full capabilities.

You can use any computer running Windows, Mac or Linux to complete the steps in this guide.

Why Arch ?

We chose Arch Linux because it is one of the best documented Linux distributions. Apart from that, it is a rolling distro, enabling us to provide our users with the newest, most stable, secure and better performing set of packages.

All hardware onboard PixieBoard is supported through a set of packages “name-of-package-PixiePro” that we created and maintain up to date in our repository. This allows our users to build solutions with improved performance and making the best use of the features available in NXP’s i.MX6 QuadPlus, Quad and DualLite processors.

Everything in this guide is aligned (or tries to be) to the way Arch Linux does Linux, so don’t hesitate in visiting the ArchWiki if you want to learn more details regarding any of the steps in this tutorial.

PixieBoard PRO+

Prepare your setup

For this setup you will need a few things, please take a look at the following list to make sure you have everything you need:

• PixieBoard (PRO+, PRO or DUO).
• MicroSD card (16 GB or more) and a USB adapter.
• WiFi/Bluetooth Antenna.
• Power Supply (5 VDC, 2 A).
• Micro USB to USB cable.

If you are planning to use a monitor or TV as screen, you will also need:

• TV or Screen with 1080p resolution and HDMI input.
• microHDMI to HDMI cable.
• USB keyboard.

Downloads

OS and Tools

Code & Modules Inc. maintains and provides an up-to-date image of Arch Linux. We chose Arch because being a rolling distro, you will have access to the latest and most secure set of packages. Download the corresponding image for your PixieBoard:

• PixieBoard PRO+ (i.MX6 QuadPlus, 4GB RAM, 4G LTE)
• PixieBoard PRO (i.MX6 Quad, 2GB RAM, 4G LTE)
• PixieBoard DUO (i.MX6 DualLite, 1GB RAM, 3G GSM)

Make sure to extract the contents of the zip to get a .img file and remember its location.

Windows

You will need to download and install a couple of applications to flash the microSD card with the OS and to communicate with PixieBoard.

• To flash the microSD card we recommend using Win32 Disk Imager.
• As serial and ssh terminal, we will use PuTTY.

Mac

For doing this steps in a Mac, you will only need a reliable serial terminal. There are many options out there, but we recommend using Serial (You can also install this program from the App Store).

Linux

The only program you would need is screen, which will be used as serial terminal to communicate with PixieBoard.

Prepare a bootable microSD card

If you ordered a Starter Kit from Treats 4 Geeks or Amazon you can skip this steps and jump to the next section “Booting your PixieBoard for the first time”.

Windows

• Insert the microSD card into your computer using the USB Adapter.
• Open Win32 Disk Imager.
• In the Image File box, select the extracted .img file using the blue folder icon on the right.
• In the Device box, select your microSD card volume.
• Click the Write button and wait for the process to complete (it can take several minutes).
• A message box letting you know of the successful write process will appear. Extract the microSD card from your computer.

Image Capture of Win32 Disk Imager

We have found that sometimes this process will not succeed if you are using a microSD to SD adapter and the built-in port of your computer. If this happens to you, try using a microSD-USB adapter.

Mac

• Insert the microSD card into your computer.
• Open the Disk Utility app (Applications/Utilities).
• On the side panel, select your microSD card under External.
• On the top tools bar, click on Unmount.

Image Capture of Disk Utility App, note the name of the device in the bottom right corner.

• Remember the name of your device in the bottom-right corner of the table in the main Window (In my case it’s disk2). We will refer to this as “your-device” in a later step.
• Open the Terminal app (Applications/Utilities).
• Navigate to the location of the OS image file you downloaded and extracted in the first step of this guide.
• Write the OS to the microSD card using the following command where “downloaded-file.img” corresponds to the OS image file (.img) you downloaded and “your-device” corresponds to your microSD:

sudo dd if="downloaded-file.img" of=/dev/your-device bs=4m

• Introduce your password and wait for the process to complete. (It can take several minutes).
• When the process is complete, extract the microSD card from your computer.

Linux

• Insert the microSD card into your computer.
• To find out the name of your drive, type the following command into a terminal window:

sudo fdisk -l

Introduce your password if prompted for it. You sould get a list of the storage devices detected by your system. Identify your microSD card by looking at the description in the sub-title. Remember the name of your disk, it should look something like “/dev/sdb” (we will refer to the last part of the name as “your-disk” in following steps of this guide.

• Unmount all the devices of your disk:

sudo umount /dev/your-disk*

• Navigate to the location of the OS image file you downloaded and extracted in the first step of this guide.
• Write the OS to the microSD card using the following command where “downloaded-file.img” corresponds to the OS image file (.img) you downloaded and “your-device” corresponds to your microSD:

sudo dd if="downloaded-file.img" of=/dev/your-device bs=4M

• Introduce your password and wait for the process to complete. (It can take several minutes).
• When the process is complete, extract the microSD card from your computer.

Booting your PixieBoard for the first time

Now that you have your microSD card programmed with Arch Linux, its time to boot your system for the first time, but first, make sure to follow these steps:

Reference for antennas connectors placement.

• Insert the microSD card into Port A (primary) slot.
• Connect all your antennas to the right ports. Remember that PixieBoard is featured with MIMO interfaces for both WiFi and the cellular modem, this means that you can use 1 or 2 antennas for each interface to improve performance.

Reference for PixieBoards ports.

• Connect your microUSB cable to the USB OTG port of your PixieBoard and the other end to your computer.
• Plug in your power supply to the 5V DC Input Jack of your PixieBoard and connect the other end to a power source.

If you plan to use a screen for your PixieBoard (optional)

• Connect the microHDMI cable to your PixieBoard and the other end to your screen.
• Connect your USB keyboard to PixieBoard.

Logging in for the first time

Your PixieBoard should be booting for the first time now. Remember that by default the OS image is configured with a standard user with root privileges:

• Username: pixiepro
• Password: pixiepro

If you are not using a screen, you will need to use a serial terminal to log into your system. To connect your serial terminal follow these steps, depending on your OS:

Windows

If you are using Windows 10, wait for the system to identify that PixieBoard is connected and install the corresponding drivers automatically. When this process is done, you will be notified that the device has been installed correctly as a serial port, you can use Device Manager to find out which port is being used.

PixieBoard is connected in port COM4.

• Now, open PuTTY and select “Serial” as connection type.
• Write the name of the port in the field for “Serial line” (In our example, it would be “COM4”).
• Click on “Open” and a new window will appear prompting you for your username and password. Enter pixiepro for both. If only a black screen appears press the enter key to prompt for the username.

Mac

For Mac users we recommend using the Serial application, however you can follow the steps for Linux if you want to use the built-in tools of your system.

• Open the Serial application. A dialog asking you to choose a port should appear. Choose the one called “Gadget Serial v2.4-CDC” and click the “Open” button.
• A new window will appear asking you for your username and password. Enter pixiepro for both. If no message is displayed in the window press the enter key to prompt for the username.

Linux

• Use the following command to identify the port used for PixieBoard:

dmesg | grep tty

Remember the name of the device with the following description: “USB ACM device” (In our example, the device is called “ttyACM0”).

Use dmesg to identify PixieBoard as a USB to Serial device.

• Use the screen command to start your session through this port:

sudo screen /dev/ttyACM0

• Enter pixiepro as your user and password for login.

At this point, you should be able to login to your PixieBoard and start using it as any Linux system. We recommend to complete the following steps to ensure you have the latest kernel versions.

Connect to your WiFi network

As you know, your PixieBoard has very powerful wireless interfaces and the OS provided is already loaded with the tools needed to start using them immediately. Use Network Manager’s CLI to connect to your WiFi:

sudo nmtui

• You will be prompted for your password, enter pixiepro.
• A menu will appear, use your arrow keys to select the option “Activate a connection”.

Network Manager CLI to connect to a WiFi network.

• Select the network you want to use from the list of available networks and enter your passcode.
• If you have no problem connecting to this network, you will return to the list of available networks. Use the “Back” and “Quit” options or “ESC” key exit the menu.
• You can test your connectivity by issuing a ping to a known server:

sudo ping codeandmodules.com

You should see a response from the server similar to the one below:

Using ping to test connectivity.

You can learn your IP by issuing the command:

ip addr

or

hostname --ip-addresses

The first command will show you the configuration of all the detected interfaces, while the second one will only show you the active IP addresses. Remember this IP address for a future step, especially if you are in a Windows system.

Set a hostname

Another important step when configuring you PixieBoard is to set a hostname. This will let you identify your PixieBoard an even connect to it by using its name instead of the assigned IP.

• Run the Network Manager CLI again:

sudo nmtui

• Select the option “Set system hostname”.
• Enter the new hostname for your PixieBoard. Remember to use a unique name that is easy to remember.
• if you reboot your PixieBoard now, you will see that the new hostname is now assigned to your system.

Upgrade your system to the latest set of packages

Having the latest packages installed in your PixieBoard will help your system be more secure and stable. In Arch Linux, packages are installed using the pacman tool. The option -S stands for “sync” and it usually means that a new package (or group of packages) will be installed directly from the repository.

Your PixieBoard is preconfigured to access the community and proprietary repositories. To update the database of repositories use:

sudo pacman -Sy

To upgrade to the latest set of packages, run:

sudo pacman -Su

You can run both commands at the same time by issuing:

sudo pacman -Syu

Reboot your system:

sudo reboot

Turn your system OFF safely

This is usually a forgotten step, but to avoid damaging the contents of your microSD card, it is recommended to halt your system before unplugging it:

sudo halt

After issuing the halt command, wait 30 seconds before unplugging it from the power source AND the USB.

Set the correct time and date, timezone and encoding

As you know, having the correct time and timezone configuration will allow your Linux system to communicate correctly and securely with other systems across the internet. Some servers won’t even let a badly configured system start a connection. Also, there are some packages that depend on having the correct encoding to function correctly.

Time and date

To set the local time of the system clock directly:

timedatectl set-time "yyyy-MM-dd hh:mm:ss"

However, if your system is going to be connected to the internet, you can use NTP service to keep it in sync. First, install ntp:

sudo pacman -S ntp

After the installation is complete, enable the service daemon:

sudo systemctl enable ntpd

Start the service:

sudo systemctl start ntpd

Tell the system to use NTP:

sudo timedatectl set-ntp true

Finally, sync the system clock and the hardware (RTC) clock:

sudo hwclock --systohc

Timezone

To set the correct timezone, simply run the following command:

timedatectl set-timezone America/Los_Angeles

If you don’t know your timezone, you can check the list with:

timedatectl list-timezones

You can check the correct configuration of your system with the command:

timedatectl status

Time, date and timezone configured correctly.

Locale and encoding

As stated in the Arch Linux wiki, locales are used by many libraries to render text correctly, display regional monetary values and many other things. It is recommended to have your system locales correctly configured to avoid problems in the future.

Edit the configuration file using nano:

sudo nano /etc/locale.gen

Find the line corresponding to you and uncomment that line (by removing the “#” symbol at the start of the line). In our case, we are using “en_US.UTF-8 UTF-8”.

Uncommenting the correct lines in /etc/locale.gen

Now, run the following command to generate the correct configurations:

sudo locale-gen
sudo localectl set-locale LANG=en_US.UTF-8

And reboot your PixieBoard.

Use SSH to access your PixieBoard

SSH lets you control your PixieBoard remotely. This is very convenient when your PixieBoard is deployed somewhere you many not have cable access to it. Also, there’s the advantage of using less cables.

To use it, simply enable the service:

sudo systemctl enable sshd

Now, you can access it from a terminal in your computer.

Windows

If you are using Windows you can use PuTTY again. Simply write the username and IP address of your PixieBoard in the space for “Host Name” and click the “Open” button.

Connecting by SSH using PuTTY

When doing this the first time, you will be asked if you trust the device and if you want to save the keys. Simply say “Yes”.

Mac and Linux

Simply open a new Terminal window and connect to your PixieBoard from there:

ssh pixiepro@Your-PixieBoards-ip-address

Connecting to your PixieBoard by Hostname

It is very likely that your IP address will be assigned dynamically. What this means is that it may change in the future and you will need to learn it again to connect remotely to your PixieBoard.

Fortunately, if you are a Mac or Linux user, you can use Zeroconf (Bonjour / Avahi) to connect to your system by hostname. You only need to install and enable the service. Then reboot:

sudo pacman -S avahi
sudo systemctl enable avahi-daemon
sudo reboot

Now, you can connect to your PixieBoard by hostname (replace “Your-Hostname” with the name you chose in an earlier step):

ssh pixiepro@Your-Hostname.local

Connecting to PixieBoard by hostname

You can also connect to your computer by Hostname.local if your computer is running zeroconf or Bonjour. In order to enable your pixie to resolve .local hosts you need to do the following:

Install nss-mdns:

sudo pacman -S nss-mdns

And edit the config file in /etc/nsswitch.conf to include mdns_minimal [NOTFOUND=return] before resolve and dns in the hosts line:

sudo nano /etc/nsswitch.conf
hosts: ... mdns_minimal [NOTFOUND=return] resolve [!UNAVAIL=return] dns ...

There you go. No more cables :)

Further Information and links

If you want to learn any more details about the steps in this guide, don’t hesitate to stop by the Wiki at Treats4Geeks and off course, the ArchWiki.

So this is it! Your PixieBoard is now up and running, correctly configured and connected to your wireless network. Please let me know in the comments if you have any questions, improvements or suggestions for future posts.

Also, follow Code & Modules and myself on Twitter (@codeandmodues and @cheperuiz).