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.

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 (2GB or 4GB, 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.

Experienced Linux users may write a downloaded .img.xz image directly using dd.

When using dd, create the SSH and user configuration on the boot partition after imaging:

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

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 Ethernet and power, then 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:

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.

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, the folder may look similar to:

jdk8u504-b01-jre

The exact Java version changes over time. Use the actual folder name shown by ls /opt/java in the next command rather than copying the example version literally.

For example:

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

Replace jdk8u504-b01-jre with the directory which was actually extracted on the system.

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.

Only install or select Java 11 when ErgoTech support asks for it.

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

Register the extracted Java 11 installation using its actual folder name and a lower priority than Java 8.

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 current Raspberry Pi OS Bookworm Lite, the configuration may contain 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
}

In this layout, there may be no existing size or maxsize setting and /var/log/daemon.log may not exist.

Edit the configuration:

sudo nano /etc/logrotate.d/rsyslog

For the 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, set the applicable system-log limits to 20M while preserving the existing layout.

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

Do not change the other logrotate settings.

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 a configuration using maxsize 20M, the output should contain a line similar to:

log files >= 20971520 are rotated earlier

Make sure there are no configuration errors.

Also 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 current journal may be much smaller than 50 MB. The setting limits future growth; it does not require the journal to already be near that size.

/etc/rc.local is a traditional Linux startup script which runs near the end of the boot process. On a Raspberry Pi it is useful for small recovery and housekeeping tasks after a power interruption.

On Raspberry Pi OS Bookworm Lite, /etc/rc.local may not exist on a fresh installation. The systemd compatibility service is already provided and will automatically run /etc/rc.local at boot when the file exists and is 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

Replace the file with:

#!/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.

rc-local.service is a static compatibility service on Raspberry Pi OS Bookworm. It does not need to be enabled manually. Once /etc/rc.local exists and is executable, systemd will run it 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 service should show:

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.

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 Raspberry Pi OS Bookworm, fake-hwclock is 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 (/usr/sbin/fake-hwclock)

Those entries mean the clock-save task is running.

Check the current system time status:

timedatectl

On a Raspberry Pi 3 or 4, RTC time: n/a is normal because these models do not have a battery-backed real-time clock.

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 which 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 used as a base master 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.