Complete Raspberry Pi Base Setup first.

MIX requires Java 25 or newer. The Raspberry Pi installation validated with the current MIX runtime used:

/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64

The Raspberry Pi may still use another Java version as its system default. MIX does not require changing the global java command. The MIX service can select Java 25 explicitly with MIX_JAVA_HOME.

These instructions assume MIX is installed in:

/home/mix/mixruntime

The normal MIX web port is 7226 unless mix.port in mix.properties has been changed.

Useful MIX addresses are:

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

The first opens the deployed application. The second opens the MIX setup page.

Use the MIX runtime supplied with the current ErgoTech software release.

A current MIX installation contains files and directories including:

mix.jar
mix.properties
htmlroot/
lib/
log4j/
logs/
scripts/
security/

The Linux startup script is:

scripts/MIX.sh

Current MIX releases no longer use runmix.sh.

The top-level MIX executable included with some installations may be built for x86-64 Linux. On a Raspberry Pi, start MIX directly with scripts/MIX.sh instead.

For example, from Windows PowerShell, if the MIX runtime is installed under:

C:\ET\<release>\MIX

change to that directory:

Set-Location "C:\ET\<release>\MIX"

Create the Raspberry Pi runtime directory:

ssh mix@<Pi-address> "mkdir -p /home/mix/mixruntime"

Copy the contents of the MIX runtime directory:

scp -r .\* mix@<Pi-address>:/home/mix/mixruntime/

After the copy, verify the runtime on the Pi:

ls -la /home/mix/mixruntime
ls -la /home/mix/mixruntime/scripts

Make the Linux scripts executable:

chmod +x /home/mix/mixruntime/scripts/MIX.sh
chmod +x /home/mix/mixruntime/scripts/stopmix.sh
chmod +x /home/mix/mixruntime/scripts/restartmix.sh

If the source installation contains an ErgoIOTLicense_*.lic file belonging to another computer, do not use that license on the Raspberry Pi. Move or remove it before requesting the Pi's license.

Verify the Java installation which MIX will use:

/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version

The validated installation reports Java 25.

Start MIX manually:

cd /home/mix/mixruntime
 
MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 
./scripts/MIX.sh

Startup output should show the selected Java executable and the configured MIX port.

For example:

MIX_INSTALL_DIR:  /home/mix/mixruntime
MIX_WORK_DIR:     /home/mix/mixruntime
MIX properties:   /home/mix/mixruntime/mix.properties
Java executable:  /opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
Debug port:       18050
mix.port:7226

The runtime should also report its MIX build number.

If the Pi does not yet have its runtime license, MIX will display its pre-license key.

The current validation showed:

Initializing MIX runtime with prelicense key: <pre-license-key>

An invalid-license message at this stage is expected until the Raspberry Pi's license file has been installed.

Each Raspberry Pi requires the appropriate ErgoTech runtime license.

The pre-license key can be obtained from MIX startup output or from the MIX setup page:

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

On the setup page, select Get Pre-License Key.

Send the displayed pre-license key to ErgoTech.

Copy the license provided for that Raspberry Pi into:

/home/mix/mixruntime

The license filename may include the pre-license key, for example:

ErgoIOTLicense_<pre-license-key>.lic

Restart MIX after installing the license.

For a manual startup:

cd /home/mix/mixruntime
 
MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 
./scripts/MIX.sh

A successful startup should contain:

Valid IOT System Runtime License detected.

A runtime license generated for the Raspberry Pi was successfully accepted by both MIX and TransSECS on the same Pi during validation.

Opening Get Pre-License Key also provides a convenient way to update the Raspberry Pi's date and time. This can be useful on systems which do not have access to a network time server.

The setup page also contains Network Configuration for installations which use MIX to manage Raspberry Pi network settings.

While MIX is running, verify that port 7226 is listening:

sudo ss -ltnp | grep 7226

A normal result contains:

LISTEN ... *:7226 ... java

From a browser on another computer, open:

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

The MIX setup page should load.

After an application has been deployed, the application can normally be opened at:

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

MIStudio can deploy a project directly to the MIX runtime running on the Raspberry Pi.

In the MIStudio project, select the MIX Target.

Configure:

Host Name:      <Pi-address>
Mix Login Name: ergouser
Port:           7226
Target Name:    MIX

Use the configured MIX password.

Save the project, then select Deploy.

During a successful deployment, the MIX runtime will:

• authenticate the MIStudio deployment request,
• stop and release the currently deployed application logic,
• replace the deployed application files,
• load the new VIBLogic.jar and application files,
• reload the MIX project,
• continue using the Raspberry Pi runtime license.

A successful deployment does not require manually stopping the MIX process.

After deployment, open:

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

and verify that the newly deployed application loads.

For production systems, do not leave the default ergouser password unchanged. MIX reports the user-administration page as:

http://<Pi-address>:7226/servlet/UserManager

Linux uses systemd to manage services.

A MIX systemd service starts MIX automatically during boot and restarts it if the process stops.

MIX console output should also be redirected to its own log file.

First make sure a manually started MIX process is not still running:

pgrep -af 'com.ergotech.mix.server.HeadlessController'

If MIX was started manually, stop it before starting the systemd service.

Create the log directory if necessary:

mkdir -p /home/mix/mixruntime/logs

Create:

sudo nano /etc/systemd/system/mix.service

Paste:

[Unit]
Description=MIX Service
After=network-online.target
Wants=network-online.target
 
[Service]
User=mix
WorkingDirectory=/home/mix/mixruntime
Environment="MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64"
ExecStart=/bin/sh /home/mix/mixruntime/scripts/MIX.sh
Restart=always
RestartSec=60
StandardOutput=append:/home/mix/mixruntime/logs/runmix-console.log
StandardError=append:/home/mix/mixruntime/logs/runmix-console.log
 
[Install]
WantedBy=multi-user.target

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

Then run:

sudo systemctl daemon-reload
sudo systemctl enable mix
sudo systemctl start mix
systemctl status mix --no-pager

Verify that the service shows:

Active: active (running)

The running process should be Java 25 executing:

com.ergotech.mix.server.HeadlessController

Verify:

pgrep -af 'com.ergotech.mix.server.HeadlessController'

Also verify that port 7226 is listening:

sudo ss -ltnp | grep 7226

Do not replace an existing working service without first inspecting it.

Run:

sudo systemctl cat mix.service

Confirm that the effective service configuration uses:

• the intended MIX installation directory,
• scripts/MIX.sh,
• Java 25,
• the correct MIX console log path.

If the existing service does not meet the current requirements, update it using the validated service definition above.

If the existing service already starts MIX correctly and only console redirection needs to be added, a systemd override can be used rather than replacing the original service.

Run:

tail -n 40 /home/mix/mixruntime/logs/runmix-console.log

The log should contain MIX and Java startup messages.

Useful checks include:

grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
/home/mix/mixruntime/logs/runmix-console.log | tail -n 10

A successfully licensed startup should contain lines similar to:

Running MIX Build <build-number>
Initializing MIX runtime with prelicense key: <pre-license-key>
Valid IOT System Runtime License detected.

It is normal for Linux system logs to continue containing operating-system messages such as network or WiFi status messages.

The important result is that MIX and Java console output is written to:

/home/mix/mixruntime/logs/runmix-console.log

When systemd creates this redirected log, the active file may be owned by:

root root

even though MIX itself runs as the mix user.

Create:

sudo nano /etc/logrotate.d/runmix-console

Paste:

/home/mix/mixruntime/logs/runmix-console.log {
    su root root
    size 5M
    rotate 5
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Do not add a create line. The active console file is maintained by systemd and copytruncate allows the running MIX process to continue writing to the same file after rotation.

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

Check the rule:

sudo logrotate -d /etc/logrotate.d/runmix-console

A normal result mentions:

• /home/mix/mixruntime/logs/runmix-console.log
• 5242880 bytes, which is 5 MB
• 5 rotations

If the current file is smaller than 5 MB, logrotate will report that the log does not need rotating. This is normal.

To fully test the rule, force one rotation:

sudo logrotate -vf /etc/logrotate.d/runmix-console

Verify:

ls -lh /home/mix/mixruntime/logs/runmix-console.log*
systemctl status mix --no-pager

The previous contents should be copied to:

runmix-console.log.1

and the active runmix-console.log should be truncated while MIX remains running.

Generate a new MIX request:

curl -s -o /dev/null http://127.0.0.1:7226/setup.html
sleep 2

Then verify that the active log grows again:

ls -lh /home/mix/mixruntime/logs/runmix-console.log*
tail -n 10 /home/mix/mixruntime/logs/runmix-console.log

A successful test will show a new request similar to:

Default Servlet : GET Request: /setup.html

MIX.log is already controlled by MIX's Log4j configuration and does not need this additional console-log rule.

Reboot:

sudo reboot

After the Raspberry Pi comes back online, reconnect with SSH.

Verify the MIX service:

systemctl status mix --no-pager

Verify the MIX Java process:

pgrep -af 'com.ergotech.mix.server.HeadlessController'

Verify port 7226:

sudo ss -ltnp | grep 7226

Verify the post-reboot startup and license:

grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
/home/mix/mixruntime/logs/runmix-console.log | tail -n 10

Also check:

df -h /
ls -lh /var/log/syslog*
ls -lh /var/log/daemon.log*
cat /var/log/ergotech-boot-maintenance.log

Finally, open:

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

and confirm that the deployed application loads without manually starting MIX.

Verify:

• MIX is active (running) after reboot.
• MIX is running with Java 25.
• Port 7226 is listening.
• The runtime reports a valid IOT system license.
• runmix-console.log contains startup messages from the current boot.
• The deployed MIStudio application is available from the browser.
• The SD card has plenty of free space.
• Linux system logs remain bounded.
• The boot-maintenance log shows a successful run after the reboot.

At this point the Raspberry Pi MIX runtime, MIStudio deployment path, automatic startup, licensing, web access, and console-log rotation have been verified.

If this SD card will become a master image, verify the complete system once more before imaging it.