Skip to content

Getting Started

A device that is in factory reset mode has a single task, to make installation of the user container possible. This guide describes the steps needed to get a fully functional Linux device.

Factory reset

A factory reset can be initialized by pressing and holding one of the buttons as you connect the device to a power supply.

Factory reset instruction

  1. Power off the device and wait until the power LED turns off completely

  2. Press and hold either button B1 or B2, or both buttons

  3. With the button still held down, turn the power supply back on

  4. LED D to LED A will illuminate in sequence (yellow). This takes about 5 seconds

  5. All four LEDs (LED A to LED D) blink rapidly in yellow six times

  6. LED A to LED D will turn off in sequence (yellow). Release the held button before the last LED goes out

    1. LED A to LED D blink rapidly in green six times, to confirm successful initialization of the reset sequence

    2. If the button is still held when the yellow LEDs go out, the reset sequence fails. LED A to LED D blink rapidly in red six times to signal this, and the device proceeds with a normal boot

  7. If initialization of reset sequence was successful, after a short delay, the LEDs will show a running pattern while the factory reset is being performed

Note

The current push button design exhibits insufficient sensitivity, requiring a firm press to register activation rather than relying solely on the clicking sensation for feedback.

Following the factory reset the device will reboot and enter the initialization mode.

A factory reset can always be used to reset a device and recover from a misconfigured system.

Warning

The factory reset will wipe all user data, including previously installed containers

Initialization mode

In the initialization mode the device can be configured with a new user container, a Linux distribution root file system with applications and libraries.

The power LED will be blinking when the device is in initialization mode and the user LEDs will light up in a color corresponding to the current stage of the setup process.

  • Yellow: Mass storage is setup and waiting for user input.
  • Blue: System upgrade is installing.
  • Green: Container is installing.
  • Red: An error has occurred check mass storage for further logs.

In initialization mode the device will behave as an USB mass storage device with a file system as described below.

The finished configuration file structure may look like this:

|-- README.md
|-- container
|   |-- container-config.yaml
|   |-- meta.tar.xz
|   `-- rootfs.tar.xz
`-- host
    |-- buildinfo
    `-- upgrade
        `-- kvaser-image-edge-imx8mp-wl400s.multi-mender

Container definition

The container definition is placed in the /container directory. The definition requires two files, rootfs.tar.xz containing the user container root file system and container-config.yaml with the container configuration for the desired container.

Warning

The yaml file format is formatting sensitive, make sure the indenting of the file below is kept.

The /container/container-config.yaml file contents follow the format below:

name: my-hostname-%S
interfaces:
    - eth0
    - mlan0
    - mmlan0
users:
    root:
        password: root
# More than one password can be configured. Note: The ubuntu user usually
# only exist in an Ubuntu container, for other distros remove the following
# lines.
    ubuntu:
        password: ubuntu

The name field supports template strings which can be used to generate a host name dynamically

Format string Replacement
%S The device serial number
%E The device full EAN string
%e The last 7 characters of the EAN string

The name field will be used as host name and the users with passwords fields must be configured to be able to use the console login.

If the name field is left out, edge-%e-%S is used as a default name.

The interfaces configuration will define which interfaces are available in the container. The mlan0 and mmlan0 is a special case as the corresponding AP and WiFi-Direct interfaces will also be added to the user container. The table below shows which interfaces are related.

Client AP WiFi-Direct
mlan0 uap0 wfd0
mmlan0 muap0 mwfd0

The users section is for setting passwords for the different users.

Warning

Only users already available in the container can be used. A configuration file with a user name not already setup in the image will cause the whole installation to fail.

The /container directory can optionally contain a meta.tar.xz file which will be used for configuration if it exists. The meta.tar.xz file is created during the image build process. Currently only templating information is used, typically for replacing hostname in the user containers system configuration.

Note

Be sure to safely eject the mass storage device before proceeding to make sure that the configuration is completely written to the device

Onboarding

Host system upgrade

To replace the host system, an upgrade image (with .multi-mender file ending) can be placed in /host/upgrade/.

If a host system upgrade is requested, it will be performed before the user container is installed. The system will reboot after a host system upgrade is requested and before user container install.

User container install

The configuration and images will be installed and the system will reboot into to the configured user container system. In case of a failed upgrade, the device will reappear as a USB mass storage device, but now with an error log file that can be used for debugging.

After a successful initialization the device will be controlled by the user container installed.

Note

During initialization mode no other interfaces except the USB mass storage device will be enabled

Onboarding a standard LXC image

There are a number of prebuilt Linux distributions available for download at LXC Image Server.

LXC Images

Compatibility

Note

Kvaser will mainly verify the functionality for the Debian image. The other distributions are supported by LXC, but need to be verified by the customer.

Known limitations

  • Only a container image with init systems that launch getty on /dev/console will have USB console support

Example - Onboarding Debian

Start by finding the latest Debian image. It is important to use the arm64 default image (not the cloud image).

Debian download link

The images are downloadable from a tree structure at https://images.linuxcontainers.org/images/. The latest Debian image builds can be found at https://images.linuxcontainers.org/images/debian/bookworm/arm64/default/.

Follow the build date link to get to the build output files.

Build output files

For initialization the rootfs.tar.xz and meta.tar.xz need to be downloaded.

Put the files on the USB mass storage device in the /container directory.

The configuration need to be complemented with a container-config.yaml file as described above in the section Container definition.

Access the Debian system

Once configured and rebooted, the device will be accessible as an USB ACM serial device when plugged in to an USB host. The pre-release devices will present two serial ports. One port is for user container access and the other port is for debugging and will only be used by Kvaser. The debug port will be removed before the final release of Kvaser Edge. The debug port will have a boot message like Kvaser Linux distro 0.3.0 kvaser-edge-nnnnnn host_console. On Linux the ports will be accessible from /dev/ttyACMx and on Windows as COMx ports.

The USB serial device will be connected to the Debian console terminal (/dev/console).

After a successful login it is possible to run any shell command available in the used distribution, like setting up the network connection or using apt for installing new packages.

Setting up services

The following instructions assumes that an ethernet internet connection is established.

Update Debian package database

Before installing any new services the Debian package database must be updated.

apt update
Install ssh server

The ssh server is installed using the USB serial terminal.

apt install -y openssh-server

The default configuration does not allow root login as a security measure. During development it is possible to enable root login by following the steps below.

  • Edit /etc/ssh/sshd_config

    • Change the line containing PermitRootLogin prohibit-password to PermitRootLogin yes

  • Restart the ssh service

    • systemctl restart ssh
Setup wireless network

First the wpa_supplicant service need to be installed.

apt install -y wpasupplicant
# Disable default service
systemctl disable --now wpa_supplicant.service

Note

In the user container there is no udev. Standard services containing device unit configurations wont work, i.e. Requires=sys-subsystem-net-devices-%i.device.

Edit the service definition file by changing the line Requires=sys-subsystem-net-devices-%i.device to #Requires=sys-subsystem-net-devices-%i.device (see line 6 below).

$ systemctl edit --full wpa_supplicant-nl80211@.service
$ systemctl cat wpa_supplicant-nl80211@.service
# /etc/systemd/system/wpa_supplicant-nl80211@.service
[Unit]
Description=WPA supplicant daemon (interface- and nl80211 driver-specific version)
#Requires=sys-subsystem-net-devices-%i.device
After=sys-subsystem-net-devices-%i.device
Before=network.target
Wants=network.target
...

Create a configuration for login to a WiFi network named TestWifi and start the service.

$ wpa_passphrase TestWifi > /etc/wpa_supplicant/wpa_supplicant-nl80211-mlan0.conf
systemctl daemon-reload
systemctl enable --now wpa_supplicant-nl80211@mlan0
Enable DHCP client for wireless network

Create the file /etc/systemd/network/mlan0.network with the contents.

$ cp /etc/systemd/network/eth0.network /etc/systemd/network/mlan0.network
$ vim /etc/systemd/network/mlan0.network
$ cat /etc/systemd/network/mlan0.network
[Match]
Name=mlan0

[Network]
DHCP=true

[DHCPv4]
UseDomains=true

[DHCP]
ClientIdentifier=mac

Enable the service.

networkctl reload
Check the WiFi connection status
$ networkctl status mlan0
● 7: mlan0
                     Link File: n/a
                  Network File: /etc/systemd/network/mlan0.network
                         State: routable (configured)
                  Online state: online
...

Custom Image

Building Customized Image Using mkosi

License compliance

Source Code Offer

Release notes

Release Notes

Container environment specifics

User Container