This article continues from Setting up Raspberry Pi for MIX or TransSECS Deployments (Bookworm)

Complete this setup before installing MIX or the TransSECS built deployment.

This guide was validated using a Raspberry Pi 4 with Raspberry Pi OS Bookworm Legacy 64-bit Lite installed through Raspberry Pi Imager. Sections describing Raspberry Pi 5 hardware, command-line imaging, Java 11, or MIX-specific network configuration are retained as reference information but were not part of this validation.

For a new installation, use a Raspberry Pi 4 or Raspberry Pi 5.

A TransSECS Devices system can normally run on a 1 GB Pi or better (2 GB or 4 GB, for example). If the Raspberry Pi will also display a MIX or MIStudio user interface in a browser, use 4 GB or more.

If your Raspberry Pi came with an OS installed on its microSD Card, you may start with this installation or you may start with a new SD Card and keep this bundled SD Card for reference.

Use a good-quality microSD card. Industrial or high-endurance cards are preferred because the Raspberry Pi may run continuously for years.

Good choices include industrial cards from Transcend or Kingston, and SanDisk High Endurance or SanDisk Ultra.

16 GB is sufficient, and 32 GB is also a good choice. An 8 GB card leaves little spare room and should only be used when all of the log limits in this guide are configured.

A Raspberry Pi 5 has a real-time clock. Install the official Raspberry Pi RTC Battery if the system needs to retain accurate time while power is off.

This guide is written for Raspberry Pi OS Bookworm.

Download and install Raspberry Pi Imager from:

https://www.raspberrypi.com/software/

Raspberry Pi Imager can be run from Windows, Linux, or macOS.

Open Raspberry Pi Imager and:

1. Choose your Raspberry Pi model.
2. Choose the appropriate Raspberry Pi OS Bookworm image.
   1. Raspberry Pi 4 or 5, headless: Raspberry Pi OS (Legacy, 64-bit) Lite
3. Use Lite when the Pi will run TransSECS or MIX without its own graphical display (running headless).
4. Use Desktop when the Raspberry Pi itself will drive a screen, although the kiosk article also describes installing only the graphical packages which are needed.

Bookworm may appear under the Legacy operating-system choices in Raspberry Pi Imager. This guide is specifically written and tested for Bookworm.

Choose the microSD card carefully. The selected device will be erased. Check that the size matches what you expect before continuing.

For a standard MIX system:

A TransSECS-only system may instead use mix or pi or anything which makes sense as the hostname and username.

The examples in these articles use mix. If your login user is pi, substitute pi in paths such as /home/mix.

In Raspberry Pi Imager:

1. Open the OS customization settings.
2. Set the hostname, username, password, time zone, and keyboard layout.
3. Enable SSH. Password authentication may be used. Public-key authentication is also supported and is useful as a fallback if password authentication does not work as expected.
4. Configure WiFi only if the installation requires it.
5. Write and verify the card.

After Raspberry Pi Imager finishes writing and verifying the card, safely remove the microSD card from the computer and insert it into the Raspberry Pi while the Pi is powered off.

Then connect Ethernet if needed and apply power.

This section is an alternative for experienced Linux users and was not part of the Raspberry Pi 4 validation described above.

Experienced Linux users may write a downloaded .img.xz image directly using their normal Linux imaging workflow.

After imaging, create the SSH and user configuration on the boot partition:

sudo touch /media/$USER/bootfs/ssh
echo "mix:$(echo 'ErgoErgo' | openssl passwd -6 -stdin)" | sudo tee /media/$USER/bootfs/userconf.txt

The boot partition mount path varies by Linux distribution. Replace /media/$USER/bootfs with the actual mount point of the SD card's bootfs partition if necessary.

Safely unmount or eject the microSD card before removing it from the computer.

After the first login, set the hostname and correct time zone:

sudo raspi-config nonint do_hostname mix
timedatectl list-timezones
sudo timedatectl set-timezone America/Los_Angeles
sudo reboot

Replace America/Los_Angeles with the correct time zone for the installation such as Europe/Rome.

Connect the Raspberry Pi to the network using Ethernet or the WiFi configuration created in Raspberry Pi Imager, then apply power. Allow about a minute for the first boot.

From Windows Command Prompt, PowerShell, Linux, or macOS:

ssh [email protected]

The first time you connect, SSH asks whether you trust the computer’s fingerprint. Verify that you are connecting to the expected Raspberry Pi, then type yes.

If SSH was configured for password authentication, enter the password configured in Raspberry Pi Imager.

If SSH public-key authentication was configured, the connection may log in without asking for the Raspberry Pi password.

mix.local may take a short time to become available after boot while the Raspberry Pi finishes starting networking and the Avahi/mDNS service. If the first attempt reports that the hostname cannot be resolved, wait briefly and try again.

If mix.local still does not work, connect using the Pi’s IP address, for example:

ssh [email protected]

Replace the example address with the actual address assigned to the Raspberry Pi.

If public-key authentication succeeds but the password configured in Raspberry Pi Imager is rejected, reset the login password after connecting:

sudo passwd mix

Re-imaging the Raspberry Pi generates a new SSH host key.

If SSH reports:

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

and the Raspberry Pi was intentionally re-imaged, remove the saved host key for mix.local:

ssh-keygen -R mix.local

Then reconnect:

ssh [email protected]

SSH will ask you to trust the new fingerprint.

If connecting by IP address, replace mix.local with the saved IP address in the ssh-keygen -R command.

After logging in, verify the basic system information:

hostname
hostname -I
cat /etc/os-release
uname -m
cat /proc/device-tree/model; echo

For this guide, verify that:

• The hostname is the hostname configured during imaging, such as mix.
• Raspberry Pi OS reports Bookworm.
• A Raspberry Pi 4 or 5 using the 64-bit image reports aarch64.
• The reported Raspberry Pi model matches the hardware being configured.

Industrial equipment and host software normally need the Pi to remain at the same IP address.

Configure a fixed IP address when the address, gateway, DNS information, and intended network interface are known for the installation.

For a TransSECS-only system using wired Ethernet:

sudo nmtui

Choose Edit a connection, select the wired Ethernet connection, set IPv4 configuration to Manual, then enter the address, gateway, and DNS information supplied for the installation.

Check the connection name with:

nmcli connection show

After saving, restart the connection.

Replace Wired connection 1 with the actual wired connection name shown by nmcli connection show if it is different.

sudo nmcli connection down "Wired connection 1" && sudo nmcli connection up "Wired connection 1"

Your SSH connection will close if the IP address changed. Reconnect using the new address.

If the installation uses WiFi, configure a fixed address using the network information supplied for that installation.

First identify the active WiFi connection:

nmcli connection show --active

Then edit the connection:

sudo nmtui

Choose Edit a connection, select the WiFi connection, set IPv4 configuration to Manual, then enter the address, gateway, and DNS information supplied for the installation.

After saving, restart the WiFi connection using its connection name:

sudo nmcli connection down "<WiFi connection name>"
sudo nmcli connection up "<WiFi connection name>"

Verify the configured addresses and routes:

ip -br addr
ip route

Reboot once and verify that the fixed address remains configured and that SSH still works using the new address.

MIX systems can also configure networking later through:

http://<Pi-address>:7226/setup.html

Choose Network Configuration.

This MIX setup-page method was not part of the base Raspberry Pi validation described above.

A message such as:

sudo: unable to resolve host mix: Temporary failure in name resolution

usually means the Pi’s current hostname and /etc/hosts do not agree.

Check both:

hostname
cat /etc/hosts

The hostname reported by hostname should match the local hostname entry in /etc/hosts.

For example, a Pi with the hostname mix will normally contain an entry similar to:

127.0.1.1       mix

If correction is required, first make a dated backup:

sudo cp /etc/hosts /etc/hosts.bak.$(date +%Y%m%d_%H%M%S)
sudo nano /etc/hosts

Update the local hostname entry so it matches the current hostname.

Save with Ctrl+O, Enter, Ctrl+X.

If several Pis created from the same image will operate on the same network, give them unique hostnames. For example:

sudo raspi-config nonint do_hostname mix-line3
sudo reboot

After rebooting, verify the hostname and /etc/hosts again:

hostname
cat /etc/hosts

The Linux login username does not need to change when the hostname changes.

Configure Ethernet and WiFi according to the needs of the installation.

Check the available interfaces and their current addresses:

ip -br addr

Check the current network routes:

ip route

Verify that the interface intended for the installation is UP and has the expected IP address.

If both Ethernet and WiFi are configured, the Pi may have addresses on both interfaces. The routing table determines which interface is normally used for outbound network traffic.

If WiFi is not needed, it may be left unconfigured or disabled using the approved network setup for the system.

For MIX systems, network configuration can also be managed through the MIX setup page.

Run this once after the initial setup:

sudo apt update
sudo apt full-upgrade -y
sudo apt install -y librxtx-java libsqlite3-0 rsyslog logrotate fake-hwclock avahi-daemon unzip rsync htop ncdu
sudo reboot

These packages provide serial-port support, SQLite support, system logging, log rotation, Raspberry Pi clock recovery, .local hostname discovery, and several useful support tools.

After rebooting, reconnect with SSH and verify that the logging and hostname-discovery services are running:

systemctl is-active rsyslog
systemctl is-active avahi-daemon

Both should report:

active

For an ErgoTech system which will run continuously in production, software updates should be performed as a planned maintenance task rather than installed automatically.

Automatic operating-system updates can change system libraries, networking components, Chromium, Java-related packages, or other software which the ErgoTech application depends on. Disabling automatic updates helps keep a tested production system in a known configuration.

Stop and disable the two automatic APT update timers:

sudo systemctl disable apt-daily.timer
sudo systemctl stop apt-daily.timer

sudo systemctl disable apt-daily-upgrade.timer
sudo systemctl stop apt-daily-upgrade.timer

The unattended-upgrades service is not installed on every Raspberry Pi OS Bookworm Lite image.

Check whether it exists:

systemctl status unattended-upgrades 2>/dev/null

If the service exists, stop and disable it:

sudo systemctl disable unattended-upgrades
sudo systemctl stop unattended-upgrades

If the service does not exist, no action is required.

The file /etc/update-manager/release-upgrades is also not present on every Raspberry Pi OS Bookworm Lite image.

Check whether it exists:

ls -l /etc/update-manager/release-upgrades

If the file exists, first make a dated backup:

sudo cp /etc/update-manager/release-upgrades /etc/update-manager/release-upgrades.bak.$(date +%Y%m%d_%H%M%S)

Open the configuration file:

sudo nano /etc/update-manager/release-upgrades

Find the line beginning with:

Prompt=

Change it to:

Prompt=never

Save and exit nano:

• Press Ctrl+O to save.
• Press Enter to confirm the filename.
• Press Ctrl+X to exit.

If the file does not exist, do not create it solely for this procedure.

Verify the two APT timers:

systemctl is-enabled apt-daily.timer
systemctl is-active apt-daily.timer

systemctl is-enabled apt-daily-upgrade.timer
systemctl is-active apt-daily-upgrade.timer

Both timers should report:

disabled
inactive

If unattended-upgrades is installed, verify that it is disabled and inactive:

systemctl is-enabled unattended-upgrades
systemctl is-active unattended-upgrades

If /etc/update-manager/release-upgrades exists, verify the setting:

grep '^Prompt=' /etc/update-manager/release-upgrades

It should show:

Prompt=never

These changes do not prevent an administrator from installing updates manually later. Updates can still be performed deliberately during a maintenance period after they have been reviewed and tested.

ErgoTech applications covered by this guide use Java 8 unless ErgoTech support specifies otherwise.

For a 64-bit Raspberry Pi OS installation:

cd /tmp
wget -O java8.tar.gz "https://api.adoptium.net/v3/binary/latest/8/ga/linux/aarch64/jre/hotspot/normal/eclipse"
sudo mkdir -p /opt/java
sudo tar -xzf java8.tar.gz -C /opt/java
ls /opt/java

The ls command shows the folder which was extracted.

For example, during the validated setup the extracted folder was:

jdk8u504-b01-jre

The exact Java version returned by the Adoptium URL can change over time. Use the actual folder name shown by ls /opt/java in the next command.

For the validated setup:

sudo update-alternatives --install /usr/bin/java java /opt/java/jdk8u504-b01-jre/bin/java 100

Replace jdk8u504-b01-jre if the directory actually extracted on the system is different.

Verify the Java version:

java -version

The version should begin with:

openjdk version "1.8.0_

Also verify which Java executable is selected:

readlink -f /usr/bin/java

The path should point to the Java 8 installation under:

/opt/java/

If Java 17, Java 21, or another version is still selected:

sudo update-alternatives --config java

Choose the Java 8 entry under /opt/java, then run:

java -version
readlink -f /usr/bin/java

again to verify the selection.

Java 11 was not part of the Raspberry Pi 4 validation described in this guide.

Only install or select Java 11 when ErgoTech support specifically requires it.

Use the Java 11 version and installation instructions supplied by ErgoTech support.

Linux system logs can grow surprisingly large when a device repeatedly reports an error. A nearly full SD card can make SSH and other commands extremely slow and can eventually make the system unusable.

The goal is to keep the Linux system logs bounded while still retaining useful diagnostic information.

First make a dated backup:

sudo cp /etc/logrotate.d/rsyslog /root/rsyslog.logrotate.bak.$(date +%Y%m%d_%H%M%S)

Inspect the current configuration:

cat /etc/logrotate.d/rsyslog

The exact layout can vary between Raspberry Pi OS versions.

On the Bookworm Lite system used for this validation, the configuration contained one combined block similar to:

/var/log/syslog
/var/log/mail.log
/var/log/kern.log
/var/log/auth.log
/var/log/user.log
/var/log/cron.log
{
        rotate 4
        weekly
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
                /usr/lib/rsyslog/rsyslog-rotate
        endscript
}

There was no existing size or maxsize setting and /var/log/daemon.log was not present.

Edit the configuration:

sudo nano /etc/logrotate.d/rsyslog

For this combined Bookworm block, add:

maxsize 20M

after the weekly line.

For example:

{
        rotate 4
        weekly
        maxsize 20M
        missingok
        notifempty
        compress
        delaycompress
        sharedscripts
        postrotate
                /usr/lib/rsyslog/rsyslog-rotate
        endscript
}

If the system uses a different rsyslog layout with separate log blocks and existing size or maxsize settings, preserve that layout rather than creating log files which do not already exist.

Do not create /var/log/daemon.log solely because it is not present.

Save with Ctrl+O, Enter, Ctrl+X.

Check the configuration before relying on it:

sudo logrotate -d /etc/logrotate.d/rsyslog

The -d option is a safe debug check. It does not actually rotate the logs.

For the validated configuration using maxsize 20M, the output contained a line similar to:

log files >= 20971520 are rotated earlier

Make sure there are no configuration errors.

Cap the systemd journal at 50 MB:

sudo mkdir -p /etc/systemd/journald.conf.d
printf '[Journal]\nSystemMaxUse=50M\n' | sudo tee /etc/systemd/journald.conf.d/size.conf
sudo systemctl restart systemd-journald

Verify the setting:

cat /etc/systemd/journald.conf.d/size.conf
journalctl --disk-usage

The configuration file should contain:

[Journal]
SystemMaxUse=50M

The journal on the validated system was well below this limit. The setting limits future growth; it does not require the journal to already be near 50 MB.

/etc/rc.local is a traditional Linux startup script which is useful for small recovery and housekeeping tasks after a power interruption.

On the Bookworm Lite system used for this validation, /etc/rc.local did not exist initially. Raspberry Pi OS already provided the systemd compatibility service needed to run the file once it existed and was executable.

Check whether the file already exists:

ls -l /etc/rc.local

If the file exists, make a dated backup:

sudo cp /etc/rc.local /etc/rc.local.bak.$(date +%Y%m%d_%H%M%S)

Then create or edit the file:

sudo nano /etc/rc.local

Use:

#!/bin/sh
 
# Print current IP address during boot
_IP=$(hostname -I) || true
if [ "$_IP" ]; then
  printf "My IP address is %s\n" "$_IP"
fi
 
# ErgoTech boot maintenance
echo "Boot maintenance started: $(date)" >> /var/log/ergotech-boot-maintenance.log
 
# Clean stale X11 lock files
rm -f /tmp/.tX0-lock /tmp/.X0-lock
rm -f /tmp/.X11-unix/X0
 
# Ensure /tmp permissions are correct
chmod 1777 /tmp
 
# Remove compressed logs older than 7 days
find /var/log -name "*.gz" -mtime +7 -delete
 
# Trim oversized Linux system logs
find /var/log -maxdepth 1 -type f \
  \( -name "syslog*" \
  -o -name "daemon.log*" \
  -o -name "auth.log*" \
  -o -name "kern.log*" \
  -o -name "messages*" \) \
  -size +20M \
  -exec truncate -s 5M {} \;
 
# Record disk usage
df -h / >> /var/log/ergotech-boot-maintenance.log
 
echo "Boot maintenance finished: $(date)" >> /var/log/ergotech-boot-maintenance.log
 
exit 0

Save with Ctrl+O, Enter, Ctrl+X.

Make the script executable:

sudo chmod +x /etc/rc.local

Check the script for shell syntax errors before running it:

sudo sh -n /etc/rc.local
echo $?

A result of:

0

means the script passed the syntax check.

Test the script manually:

sudo sh -x /etc/rc.local
cat /var/log/ergotech-boot-maintenance.log

The test should complete without shell errors. The maintenance log should contain a start time, disk-usage information, and a finish time.

On the validated Bookworm system, rc-local.service was a static compatibility service and did not need to be enabled manually. Once /etc/rc.local existed and was executable, it ran automatically during boot.

Reboot to verify automatic startup:

sudo reboot

After reconnecting with SSH, check:

systemctl status rc-local.service --no-pager
cat /var/log/ergotech-boot-maintenance.log

The validated system showed:

Active: active (exited)

The maintenance log should contain a new start and finish entry from the reboot.

The MIX kiosk article adds two browser-specific cleanup commands to this file.

The Pi 5 has a built-in real-time clock. With the official RTC battery installed, it can retain the time while power is off.

This Raspberry Pi 5 path was not part of the Raspberry Pi 4 validation described above.

Check:

timedatectl

The RTC time: line should contain a real date and time rather than n/a.

These models do not have a battery-backed real-time clock. fake-hwclock saves an approximate time which Linux can restore after a power interruption.

On the Raspberry Pi 4 used for validation, fake-hwclock was installed with a systemd service and an hourly save task. ErgoTech systems save the clock more frequently so that less time is lost after an unexpected power interruption.

Save the clock every five minutes:

printf '*/5 * * * * root /sbin/fake-hwclock save\n' | sudo tee /etc/cron.d/fake-hwclock-5min

Verify the five-minute task:

cat /etc/cron.d/fake-hwclock-5min

It should show:

*/5 * * * * root /sbin/fake-hwclock save

Check the saved clock value:

cat /etc/fake-hwclock.data

The clock can also be saved manually for testing:

sudo /sbin/fake-hwclock save
cat /etc/fake-hwclock.data

The timestamp should update.

This task may produce normal log entries similar to:

CRON: (root) CMD (/sbin/fake-hwclock save)

Those entries mean the clock-save task is running.

Check the current system time status:

timedatectl

On the Raspberry Pi 4 used for validation, RTC time: n/a was normal.

Verify that the time zone is correct and that the system clock is synchronized when a network time source is available.

If the factory network has no Internet or local time server, the clock may drift. MIX provides another convenient way to set the system time by loading Get Pre-License Key on the setup page. In addition, for SECS/GEM tool applications, the host can also set the Pi's clock by sending the standard S2F31 Date and Time Set Request message. This updates the system clock in the same way as opening the MIX Get Pre-License Key page updates it from the browser.

Reboot:

sudo reboot

After about a minute, reconnect with SSH and run:

java -version
readlink -f /usr/bin/java
cat /var/log/ergotech-boot-maintenance.log
df -h /
timedatectl
ip -br addr
ip route

Verify:

• Java reports version 1.8.0_....
• /usr/bin/java resolves to the Java 8 installation under /opt/java.
• The boot-maintenance log contains a new start and finish entry from the reboot.
• The root filesystem has plenty of free space.
• The system time and time zone are correct.
• The network interface intended for the installation is UP and has the expected IP address.
• The routing table contains the expected gateway.

Also verify that the startup-maintenance service completed successfully:

systemctl status rc-local.service --no-pager

It should show:

Active: active (exited)

For a Raspberry Pi 3 or 4, verify that the saved fake-hardware-clock value exists:

cat /etc/fake-hwclock.data

If a fixed IP address was configured, reconnect using that address after the reboot to confirm that the network configuration persisted.

At this point the SD card can be preserved as a completed base image before TransSECS or MIX is installed.

Before removing the SD card, shut the Pi down cleanly:

sudo shutdown -h now

Wait until the Raspberry Pi has fully shut down before removing power or the microSD card.

A Pi created from the image still needs the correct network settings and a unique hostname when several Pis share a network. Each individual system also requires its own ErgoTech license.