6. Software configuration possibilities

This section describes specific details for the configurability of the software components in the system, such as default configuration files, startup scripts and networking settings.

6.1 Installing new drivers, applications and system packages

With the introduction of overlayfs, applications can be installed to any location just as other general Linux-based systems. To see the modified files, the rw-partition can be viewed in the location referred to in chapter 3.1..

6.1.1 Mounting user partition in rescue system

Normally, the eMMC user partition is not mounted in the rescue system. If access to the user partition is needed from the rescue system, it can be mounted to /main_rootfs manually:

$ sudo mount-main-rootfs.sh

When changes are done, unmount using:

$ sudo umount-main-rootfs.sh

6.1.2 Remounting file system in read-write mode

In very rare cases, editing write-protected files may be required. It is possible to temporarily mount the file system writeable, to allow edit of protected files, using the following commands.

$ sudo mount –o remount,rw <LOWER_DIR_FOR_OVERLAY>

Important: remember to use the following command to remount the file system as write protected again, before shutting down or restarting the device. Note that any changes to the write-protected file system will be overwritten when performing an operating system upgrade.

$ sudo mount –o remount,ro <LOWER_DIR_FOR_OVERLAY>

6.1.3 User libraries

The recommended way of installing user libraries, is to install them with the application and either use RDPATH at linking time to specify the library location or set the environment variable LD_LIBRARY_PATH before executing the application.

Libraries that are used by multiple application in the system can generally be installed in their default locations (such as /usr/lib).

Note, that this approach may overwrite specific system libraries with ones provided with the user application.

For legacy compatibility and flexible configuration, the library locations can also be defined. To do this, copy the files to their respective location (for example /opt/lib/. Then edit /etc/ld.so.conf to include the required directory. Finally, update the used library cache file by executing the following command:

$ sudo ldconfig -C /etc/ld.so.cache

If additional library file locations are needed, the paths of these can be added to above command as parameters.

The library cache file is never automatically updated. But if the file does not exist at system start-up, it is re-created with default version containing information only about the standard libraries.

6.1.4 User binaries

User binaries can be installed in any location in the system. It is advisable to use the provided package manager to manage these binaries. Refer to the programmer’s manual for more information.

If additional levels of binaries are required, the $PATH environment variable must be updated under /etc/profile

6.2 Systemd Management

Systemd is a system and service manager for Linux operating systems. When run as first process on boot (as PID 1), it acts as init system that brings up and maintains userspace services. Separate instances are started for logged-in users to start their services.

Systemd is usually not invoked directly by the user, but is installed as the /sbin/init symlink and started during early boot. The user manager instances are started automatically through the user@.service service.

The basic object that systemd manages and acts upon is a “unit”. Units can be of many types, but the most common type is a “service” (indicated by a unit file ending in .service). To manage services on a systemd enabled device, our main tool is the systemctl command.

The user has the possibility to start applications and scripts by modifying or adding systemd services.

We can start the service by typing:

$ sudo systemctl start weston.service

To stop it again, type:

$ sudo systemctl stop weston.service

To restart the service, type:

$ sudo systemctl restart weston.service

To attempt to reload the service without interrupting normal functionality, type:

$ sudo systemctl reload weston.service

Most systemd service files are not started automatically at boot. To configure this functionality, you need to enable the service. This hooks it up to a certain boot target, causing it to be triggered when that target is started.

To enable a service to start automatically at boot, type:

$ sudo systemctl enable weston.service

Disable the service, type:

$ sudo systemctl disable weston.service

There is a great deal of information one can pull from systemd to get an overview of the system state.

To list all the units systemd has loaded or has attempted to load into memory, including those that are not currently active, type:

$ sudo systemctl list-units --all

A systemd component called journald collects and manages journal entries from all parts of the system. This is basically log information from applications and the kernel.

To see all log entries from current boot, type:

$ sudo journalctl -b

For more information on journalctl, see:

$ journalctl --help

To see an overview of the current state of a service, you can use the status option with the systemctl command.

$ systemctl status weston.service

6.2.1 Systemd targets

In systemd, targets are basically synchronization points which the device can use to bring the device into a specific state. Service and other unit files can be tied to a target and multiple targets can be active at the same time. See Table 6 for a short description of systemd targets.

Note, that with sytstemd, runlevels are no longer used. A note from the manual:

"Runlevels" are an obsolete way to start and stop groups of services used in
SysV init. systemd provides a compatibility layer that maps runlevels to targets,
and associated binaries like runlevel. Nevertheless, only one runlevel can be
"active" at a given time, while systemd can activate multiple targets
concurrently, so the mapping to runlevels is confusing and only approximate.
Runlevels should not be used in new code, and are mostly useful as a shorthand
way to refer the matching systemd targets in kernel boot parameters.

Note, that not all SysV-runlevels do have separate targets on systemd.

Table 6: Systemd targets (with reference to SysV)

Mode (SysV)	Systemd target	Description
To halt the system (0)	poweroff.target, systemctl halt	Shutdown
Single user mode (1)	rescue.target	Administrative tasks
Multi User (2)	multi-user.target	Does not configure network interfaces nor export network services
Multi User with Network (3)	multi-user.target	Start the system normally
Experimental (No User) (4)	multi-user.target	Not used/User-definable
Multi-user with Graphical & Network (5)	graphical.target	Same as multi-user.target + display manager
To reboot a system (6)	reboot.target, systemctl reboot	Reboots the system
Emergency shell	emergency.target	Emergency shell

All targets available on the device, type:

$ systemctl list-unit-files --type=target

Default target:

$ systemctl get-default

6.2.2 Example service

The default target is multi-user.target, so applications should at least have a startup service file for this target.

To start applications in multi-user.target, create a new service file:

$ sudo systemctl edit --full --force mycustomapp.service

Example mycustomapp.service:

[Unit]
Description=mycystomapp description

[Service]
ExecStart=/usr/sbin/mycustomapp start
ExecStop=/usr/sbin/mycustomapp stop

[Install]
WantedBy=multi-user.target

After modifying a unit file, you should reload the systemd process itself to pick up your changes:

$ sudo systemctl daemon-reload

Start new service:

$ sudo systemctl start mycustomapp.service

Enable new service on boot:

$ sudo systemctl enable mycustomapp.service

For more information on systemd and how the service files should be created, see[12]

6.2.3 Power off or reboot the system

To power off the device, type:

$ sudo systemctl poweroff

Reboot the device, type:

$ sudo systemctl reboot

6.3 Text editor

The console text editor nano is available per default for text editing, as well as the vi editor.

6.4 Terminal

It is possible to access a local device by connecting an external keyboard to the device and opening an on screen terminal by pressing down ctrl+alt+F4 keys. The login credentials are stated in chapter 2.1.

6.5 IP address configuration

There are several ways of setting the IP address of a device. The default method is DHCP, but a static IP address can also be used. This can be done through the network interfaces configuration file.

6.5.1 File method for IP address configuration

This method requires knowledge about the interfaces file format, but a sample is given below.

$ sudo nano /etc/systemd/network/eth0.network

Sample of network file setting dynamic IP address:

[Match]
Name=eth0

[Network]
DHCP=ipv4

Sample of network file setting static IP address:

[Match]
Name=eth0

[Network]
Address=192.168.1.20/24
Gateway=192.168.1.1
DNS=192.168.1.1

Once the file has been edited, it is recommended to either reboot the device, or to bring the network interfaces down and up again, for the IP address configuration to take effect:

$ sudo systemctl restart systemd-networkd

6.5.2 Firewall

The system uses iptables for the firewall. The following systemd units are responsible for the IPv4 and IPv6 firewall:

# IPv4
$ systemctl status iptables
# IPv6
$ systemctl status ip6tables

You can see the current active firewall rules with the following commands:

# IPv4
$ sudo iptables-save
# IPv6
$ sudo ip6tables-save

To configure the firewall, the following steps can be used. Add the new firewall rule:

$ sudo iptables -A INPUT -p tcp -s 0/0 -d 0/0 --dport 80 -j DROP

Update the firewall configuration:

# IPv4
$ sudo iptables-save > /etc/iptables/iptables.rules

# IPv6
$ sudo ip6tables-save > /etc/iptables/ip6tables.rules

Reboot and check that the firewall configuration works as desired.

6.6 IP Wireless LAN

The needed radio firmware is loaded at boot. Use the NetworkManager to connect to a Wi-Fi access point:

nmcli device wifi connect SSID password SSID_PASSWORD

6.7 Bluetooth

To use Bluetooth, you need to run the following commands as the root user.

systemctl enable bluetooth-attach
systemctl start bluetooth-attach

** root@v1200:/usr/bin# bluetoothctl
Agent registered>

** [bluetooth]# power on
Changing power on succeeded
[CHG] Controller 00:16:A4:4A:09:37 Powered: yes

** [bluetooth]# scan on
Discovery started
[CHG] Controller 00:16:A4:4A:09:37 Discovering: yes
[NEW] Device 11:75:58:E5:C3:99 TimeBox-mini-light
[NEW] Device 70:26:05:0D:49:46 LE_WH-1000XM2
[bluetooth]#

6.8 Remote access

The methods described in this chapter require an IP address being assigned to the device.

6.8.1 Firewall

To connect to the device from a host, issue the following command (and give password when asked):

$ ssh ccs@X.X.X.X

To connect to a host from the device, issue the following command:

~$ ssh Username@X.X.X.X

Above X.X.X.X is known as an SSH server IP address, with username Username. A password might be necessary.

Please note that root access over SSH is disabled.

Access can be re-enabled using the SUDO command by editing /etc/ssh/sshd_config and the line to:

PermitRootLogin yes

The default login and password can be found in chapter 2.

6.8.2 SCP

To copy a file to the device (while on the host) use the following command (and give password when asked):

$ scp File1 ccs@X.X.X.X:/opt/File

To copy a file from the device (while on the host) use the following command (and give password when asked):

$ scp ccs@X.X.X.X:/opt/File File

To copy a file to the host (while on the device), use the following command:

~$ scp File Username@X.X.X.X:File

To copy a file from the host (while on the device), use the following command:

~$ scp Username@X.X.X.X:File File

Above X.X.X.X is known as an SSH server IP address, username Username. A password might be necessary.

6.8.3 Password-free login for SSH and SCP

Even though the ccs user is password protected, SSH-connections can be configured to connect without password, using identity files. This method is mainly useful for remotely executed scripts or similar.

On the connecting host (not the target device), execute the command below and enter an empty passphrase when prompted.

~$ ssh-keygen -t rsa -f vs_rsa

Copy (or append) the created vs_rsa.pub file into target device as a /etc/ssh/authorized_keys -file.

On the host, move the vs_rsa file to a usable location (e.g. ~/.ssh/ )

Either configure the id-file into use in ssh_config or assign it when executing ssh or scp.

~$ ssh -i ~/.ssh/vs_rsa ccs@X.X.X.X

6.8.4 Remote command execution

After password-free login is enabled, any commands can be started remotely without login.

~$ ssh ccs@X.X.X:X "ls -al /opt/"

If starting services or background tasks, append “&” to command between quotes.

6.9 Weston Graphics

The graphics framework uses the Wayland protocol reference implementation Weston for graphics operations. Wayland is fast and efficient, and is used by most major Linux desktop systems, giving it vast standard support in the Linux user space world.

For instance, Qt has a plugin that enables the Qt libraries to be built for Weston. For Qt applications the impact for that means that it simply needs to be started with a specific flag, ‑platform wayland, and built with the correct development libraries.

Weston includes a windowing system, enabling several applications to be run overlapped.

By default, Weston is not enabled on start up. This can be easily changed with systemctl:

~$ systemctl enable weston

6.9.1 Graphical application launch

In order to launch a graphical application on Weston, the XDG_RUNTIME_DIR environment variable needs to be set. This can easily be done by either adding the following line to the application’s startup script, or running it from the command line before launching the application:

export XDG_RUNTIME_DIR=/run/user/root

6.9.2 Fixed window position

By default, Weston will place any opened window at a random position. In order to overrun this feature, Weston has been patched to read window coordinates from the file /tmp/weston_fixed_coordinates. If it doesn’t exist, or if coordinates provided are negative, it will revert to using the default random positioning. The file needs to be overwritten with new coordinates for each window to be opened at a new position. A typical use case for this feature is showing two windows split screen. Following is an example script which opens two application windows; a pdf-reader at position (0,0) and a text editor at position (640,0):

#!/bin/sh

echo "0 0" > /tmp/weston_fixed_coordinates
/usr/bin/qpdfview &

sleep 5

echo "640 0" > /tmp/weston_fixed_coordinates
/usr/bin/weston-editor &

6.10 Graphical Qt-applications without Weston.

With i.MX8-devices using KMS and the proprietary driver, there is a need for special configuration to force the plugin into the correct color mode: First define the correct mode in kms.json.

{
"device": "/dev/dri/card0",
"outputs": [
{ "name": "LVDS1", "mode": "800x480", "size": "800x480", "format":    "abgr8888" } ]
}

Then export the necessary configuration parameters:

export QT_QPA_EGLFS_KMS_CONFIG="/path-to-directory-with/kms.json"
export QT_QPA_EGLFS_INTEGRATION=eglfs_kms
export QT_QPA_EGLFS_KMS_ATOMIC=1

And finally, launch your application with:

/Application -platform eglfs

There is also a native Vivante platform available, which usage is discouraged as the performance is not on par with EGLFS KMS. To use the EGLFS Vivante platform, export the following configuration:

export QT_QPA_EGLFS_INTEGRATION=eglfs_viv
export QT_QPA_EGLFS_FORCEVSYNC=0
export QT_QPA_EGLFS_FORCE888=1
./application -platform eglfs

6.11 Boot splash

CC Linux comes with a default boot splash screen containing a black background with a white progress bar. The boot splash used is called psplash; third party software released under the GPL2 license. If desired, it is possible to add a picture/logo and change the colors of the boot splash. In order to do so, the psplash source code needs to be modified and the binaries recompiled. Please refer to the document CC Linux - change boot splash appearance which can be found at the Knowledge base on the CrossControl support site.

6.12 Serial Number Broadcast configuration

The device can identify itself over the IP network by sending out its serial number as a broadcast IP packet. The Serial Number Broadcast (SNB) service is started by default at the device boot-up and will broadcast a specific identification message to the local network every fifth second. The frequency of the broadcast can be modified, and the service can be completely disabled using the configuration file /etc/ccsnb.conf. Default values are used if any value is unset or the file does not exist.

# Serial Number Broadcast – configuration.
# Lines beginning with ‘#’ are comments.  Unnecessary options can be omitted.

# Message send interval in seconds
INTERVAL=5

# Service disable switch (DISABLE|OFF|0)
#ACTIVE=DISABLE

# Advanced features only. Use with discretion.
#
# Firmware-field is auto discovered, but can be overwritten. String value
#FIRMWARE=1.0.0
#
# UnitType, if unset '0' is used. String value
UNITTYPE=VS

6.13 Watchdog configuration

The device has watchdog daemon (WDT) that keeps updating watchdog after start. If watchdog is enabled, but it’s not updated often enough or system has crashed, watchdog will reset the system. WDT is default implementation of watchdog daemon and user can replace it but implementing same functionality to their own application. Setting timeout to zero disables watchdog functionality. Watchdog configuration file is /etc/watchdog_timeout.conf

# Set to 20sec by default. For systems with Systemd see
# DefaultTimeoutStopSec.
# If this is shorter than the systemd value, there is a risk that the watchdog
# will reboot the system before all services have shut down.
#
# Timeout = 0 disables the WDT from ever using WDT, but still keeps WDT
# daemon running. In this case it can be disabled/killed without watchdog
# causing reboot.
#
[wdt]
Timeout=20

6.14 USB memory installer

If a USB memory is inserted after startup, it is possible to activate a run time hook to enable automatic software execution. For instance, this function is suitable for production time installers, or automated SW updates, see chapter 7.5.

To activate the automatic execution, add a script named cc-auto.sh to the root of a FAT16/32 formatted USB memory. CC Linux is configured to automatically run any script with this name at insertion of USB memory. By placing commands which copy new applications and perform updates and installations in that script, this feature can be used for creating auto-update of user and system software. There are no specific limits on what user can do with cc-auto.sh file, but it is recommended that all desired commands are applied within the cc-auto.sh script process.

Note: some Windows based editors will leave Windows EOL characters in edited files, including scripts. Such characters may or may not affect the execution of this type of script.

The cc-auto.sh script automatically gets an argument from the OS containing the path to where the USB memory is mounted. Never use absolute paths to the USB memory from within cc-auto.sh as the path may vary.

6.15 Video file playback

Video file playback is supported by the gstreamer multimedia framework, which supports multiple video (MPEG2, H.264/AVC, H.265/HEVC, DivX, Xvid) and container formats (MPEG, AVI, mkv).

Generally, each supported kind of video can be played with the command:

$ gst-launch-1.0 playbin uri=file://path-to-file

There are some exceptions on the i.MX8-based devices using VPU decoding. Gstreamer must be explicitly forced to use the imxvideoconvert_g2d-plugin.

$ gst-launch-1.0 playbin uri=file://path-to-file video-sink="imxvideoconvert_g2d ! queue ! autovideosink"

Additionally, gplay-1.0 should be used (not gst-play1.0). These limitations are related to the platform using a specifically imx-patched version of gstreamer.

This command can also be used to play video files over a network and plays the file automatically so it can be launched from a script. For custom applications, gstreamer-1.0 C API can also be used, see documentation at [9].

http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/index.html

6.16 Audio files playback

Audio playback is also supported by gstreamer multimedia framework, which supports multiple audio codecs (wav, MP3, AAC). Note that the device currently supports only codecs for WAV audio playback. Audio files can be played with the command:

# aplay <audiofile>

This command launches a player and plays the file automatically so it can also be launched from a script.

By default, the device will play on both the speaker and line out simultaneously. To play on one at a time, use amixer to mute the unwanted peripheral.

To mute the speaker:

#amixer set ‘Line Out’ mute

To mute audio out:

#amixer set ‘Speaker’ mute

Note: the speaker in amixer is physically wired to the audio out on the device, and vice versa.

Table 1: Audio playback availability

VS	VI	X900	X1200	V700	V1x00	Vx10	Yukon
No	No	Yes	Yes	No	No	No	No

6.17 Adding user defined fonts to system

CC Linux uses fontconfig to handle installed fonts. Pre-installed fonts reside in /usr/share/fonts/ttf. New fonts can be added to a user specific directory, such as /opt/user-fonts directory. The new fonts need to be added to fontconfig using:

$ fc-cache </opt/user-fonts>

It is possible to list all the installed fonts by running:

$ fc-list

6.18 Triggers

The triggers are configurable actions which can be used to request change for the system state. Triggers are driven by external inputs such as ignition signal and buttons. The following categories of triggers are available.

Wakeup triggers

Causes the device to resume from the suspend mode. The wakeup triggers are configured with the –wakeup_trigger_prefix in ccsettingsconsole.

Startup triggers

Causes the device to start-up from the Off mode. The startup triggers are configured with the –startup_trigger_prefix in ccsettingsconsole.

Action triggers

Causes the device to either suspend or shutdown depending on the trigger configuration. Action triggers are configured with the –action_trigger_prefix in ccsettingsconsole.

On/off signal trigger The on/off signal (device specific implementation) causes the device to suspend or shutdown depending on the trigger configuration. The on/off trigger is configured with the –onoff_signal parameter in ccsettingsconsole.

Please note that supported triggers vary depending on the device used. The CCSettingsConsole help text shows the available trigger configurations. The following trigger configurations are under development and are currently not available:

• IO MCU triggers (startup/action/wakeup triggers)

• Ethernet trigger (startup/wakeup triggers)

• CAN trigger (startup/wakeup triggers)