Skip to content

Getting started

This guide describes the steps needed to get started using a Kvaser Edge device as a fully functional Linux device. Its primary purpose is to show how to configure, install and run a user LXC container. A new device is set up from initialization mode, which can always be returned to with a factory reset as described below.

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 initialization mode the device can be configured with a new user container, a Linux distribution root file system with applications and libraries. It can also serve as a USB CAN interface with the CAN channels appearing in the Kvaser Device Guide.

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 set up to load the user container, or the device can be used as a USB interface.
  • 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 presents itself as a 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
    |-- host-config.yaml
    `-- upgrade
        `-- keos-<version>-kvaser-wl.multi-mender

Onboarding

The upgrade and installation of the device is performed using the USB mass storage device presented when the device is in initialization mode. It is done by placing the desired files under the corresponding directories and then power cycling the device to start the installation process. The files and their placement are described below.

Note

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

Host system upgrade

To upgrade KEOS, 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 a user container install.

If no container was installed, inspect the new buildinfo and log file to verify the upgrade was successful, otherwise inspect /host/buildinfo from the installed container.

User container install

To install a user container, place a container definition under/container, the container definition requires two files:

  • rootfs.tar.xz, which contains the user container root file system
  • container-config.yaml, which contains the configuration for the container

Along with these files some optional files can also be provided for further customization:

  • meta.tar.xz, which is used to handle name templating for the container
  • host-config.yaml, which contains the configuration for the host system (it should be placed under /host instead of /container)

More information about rootfs.tar.xz and meta.tar.xz can be found in Onboarding a standard LXC image. More information on the container and host configuration files can be found in Device configuration, but examples of the configuration files are given below.

container-config.yaml example:

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

An optional host-config.yaml can be placed under /host containing the host configuration.

host-config.yaml example:

can_driver: socketcan

After a power cycle, the system installs the container definition and boots into the configured user container system. An additional reboot is performed if a host upgrade has been requested alongside the container install. In case of a failed upgrade and/or installation, 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.

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 as described above.

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. On Linux the port 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 [email protected]
$ systemctl cat [email protected]
# /etc/systemd/system/[email protected]
[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
...