Differences

This shows you the differences between two versions of the page.

--- installingmixonrpi [2026/09/18 00:40] – created wikiadmin
+++ installingmixonrpi [2026/10/27 17:06] (current) – tputman
@@ Line 1: / Line 1: @@
 ====== Installing MIX on a Raspberry Pi ======
-Complete **Raspberry Pi Base Setup for ErgoTech Software** first.
+Complete [[BaseRaspberryPiSetupBookworm]|Raspberry Pi Base Setup]] first.
-These instructions assume MIX is installed in:
+These instructions install MIX in:
 <code text>
 /home/mix/mixruntime
+</code>
+MIX requires **Java 25**.
+The validated Raspberry Pi installation used:
+<code text>
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
 </code>
 The normal MIX web port is **7226** unless ''%%mix.port%%'' in ''%%mix.properties%%'' has been changed.
-The normal addresses are:
+The MIX setup page is:
 <code text>
-http://<Pi-address>:7226
 http://<Pi-address>:7226/setup.html
 </code>
-The first opens the application interface. The second opens the MIX setup page.
+After an MIStudio project is deployed, the validated application URL is:
-===== 1. Install MIX =====
+<code text>
+http://<Pi-address>:7226/index.html
+</code>
-Install MIX using the ErgoTech MIX installation package or installation instructions.
+===== 1. Copy the MIX runtime to the Raspberry Pi =====
-When installation is complete, ''%%/home/mix/mixruntime%%'' should contain files including:
+On the Windows computer, open PowerShell and change to the MIX installation directory for the software release being deployed.
+For example:
+<code text>
+Set-Location "C:\ET\<release>\MIX"
+</code>
+Create the MIX runtime directory on the Raspberry Pi:
+<code text>
+ssh mix@<Pi-address> "mkdir -p /home/mix/mixruntime"
+</code>
+Copy the contents of the MIX runtime directory:
+<code text>
+scp -r .\* mix@<Pi-address>:/home/mix/mixruntime/
+</code>
+After the copy completes, connect to the Pi:
+<code text>
+ssh mix@<Pi-address>
+</code>
+Verify the runtime files:
+<code text>
+ls -la /home/mix/mixruntime
+ls -la /home/mix/mixruntime/scripts
+</code>
+The MIX runtime should contain files and directories including:
 <code text>
-runmix.sh
 mix.jar
 mix.properties
-log4j.mix.xml
+htmlroot/
+lib/
+log4j/
+logs/
+scripts/
+security/
 </code>
-Make the startup script executable:
+The Linux startup script is:
 <code text>
-chmod +x /home/mix/mixruntime/runmix.sh
+/home/mix/mixruntime/scripts/MIX.sh
 </code>
-===== 2. Run MIX automatically as a Linux service =====
+Make the Linux scripts executable:
-Linux uses **systemd** to manage services. A MIX systemd service starts MIX automatically during boot and restarts it if the process stops.
+<code text>
+chmod +x /home/mix/mixruntime/scripts/MIX.sh
+chmod +x /home/mix/mixruntime/scripts/stopmix.sh
+chmod +x /home/mix/mixruntime/scripts/restartmix.sh
+</code>
-MIX console output should also be redirected to its own file. This prevents Java console messages from filling Linux logs such as ''%%syslog%%'' and ''%%daemon.log%%''.
+If the copied MIX installation contains an ''%%ErgoIOTLicense_*.lic%%'' file from another computer, remove or move that file before starting MIX.
-==== If no MIX service exists yet ====
+Each Raspberry Pi must use the runtime license associated with that Pi.
-Create the log directory:
+===== 2. Verify Java 25 =====
+Verify the Java installation:
+<code text>
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
+</code>
+The validated installation reports:
+<code text>
+openjdk version "25.0.3"
+</code>
+MIX can use this Java installation directly without changing the Raspberry Pi's system-wide Java default.
+===== 3. Start MIX manually =====
+Change to the MIX runtime directory:
+<code text>
+cd /home/mix/mixruntime
+</code>
+Start MIX with Java 25:
+<code text>
+MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 \
+./scripts/MIX.sh
+</code>
+Startup output should identify the MIX installation, Java executable, and configured port.
+For example:
+<code text>
+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
+Native libraries: /home/mix/mixruntime/lib
+Debug port:       18050
+</code>
+MIX should also report:
+<code text>
+mix.port:7226
+</code>
+and its MIX build number.
+If a Raspberry Pi runtime license has not yet been installed, MIX will display the system's pre-license key:
+<code text>
+Initializing MIX runtime with prelicense key: <pre-license-key>
+</code>
+Keep this key for the license request.
+===== 4. Install the Raspberry Pi runtime license =====
+Each Raspberry Pi requires an ErgoTech runtime license associated with that system.
+The pre-license key is shown during MIX startup. It can also be viewed from the MIX setup page:
+<code text>
+http://<Pi-address>:7226/setup.html
+</code>
+Select **Get Pre-License Key** and send the displayed key to ErgoTech.
+Copy the license provided for the Raspberry Pi into:
+<code text>
+/home/mix/mixruntime
+</code>
+The filename may include the pre-license key, for example:
+<code text>
+ErgoIOTLicense_<pre-license-key>.lic
+</code>
+If TransSECS has already been licensed on the same Raspberry Pi using the same pre-license key, the Pi-specific ErgoIOT runtime license can also be copied into the MIX runtime directory.
+Start MIX again:
+<code text>
+cd /home/mix/mixruntime
+MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 \
+./scripts/MIX.sh
+</code>
+Verify that startup contains:
+<code text>
+Valid IOT System Runtime License detected.
+</code>
+===== 5. Verify the MIX web server =====
+While MIX is running, verify that port 7226 is listening:
+<code text>
+sudo ss -ltnp | grep 7226
+</code>
+A normal result contains:
+<code text>
+LISTEN ... *:7226 ... java
+</code>
+From a browser on another computer, open:
+<code text>
+http://<Pi-address>:7226/setup.html
+</code>
+Verify that the MIX setup page loads.
+===== 6. Deploy an MIStudio project to the Raspberry Pi =====
+In MIStudio, select the project's **MIX Target**.
+Configure the target with the Raspberry Pi address.
+For example:
+<code text>
+Host Name:      <Pi-address>
+Mix Login Name: ergouser
+Port:           7226
+Target Name:    MIX
+</code>
+Enter the configured MIX password.
+Save the MIStudio project and select **Deploy**.
+During a successful deployment, MIX should:
+  * authenticate the MIStudio deployment request,
+  * stop the currently loaded application logic,
+  * replace the deployed application files,
+  * receive the new ''%%VIBLogic.jar%%'' and application files,
+  * reload the application logic,
+  * continue running without requiring the MIX process to be stopped manually.
+After deployment, open:
+<code text>
+http://<Pi-address>:7226/index.html
+</code>
+Verify that the newly deployed application loads.
+The MIX console should show the deployment files being received and the application logic being reloaded.
+===== 7. Stop the manual MIX process =====
+Before configuring automatic startup, stop the manually started MIX process.
+If MIX is running in the foreground, press:
+<code text>
+Ctrl+C
+</code>
+Verify that no MIX HeadlessController process remains:
+<code text>
+pgrep -af 'com.ergotech.mix.server.HeadlessController'
+</code>
+No output should be returned.
+===== 8. Run MIX automatically as a Linux service =====
+Create the log directory if it does not already exist:
 <code text>
@@ Line 68: / Line 299: @@
 [Service]
-User=root
+User=mix
 WorkingDirectory=/home/mix/mixruntime
-ExecStart=/bin/sh /home/mix/mixruntime/runmix.sh
+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
@@ Line 82: / Line 314: @@
 Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
-Then:
+Reload systemd, enable MIX at boot, and start it:
 <code text>
@@ Line 88: / Line 320: @@
 sudo systemctl enable mix
 sudo systemctl start mix
-sudo systemctl status mix
 </code>
-Look for ''%%active (running)%%''. Press **q** to leave the status display.
+Verify the service:
-==== If MIX already has a service ====
+<code text>
+systemctl status mix --no-pager
+</code>
-Do not replace a working service file merely to add console logging.
+Look for:
-First inspect it:
 <code text>
-sudo systemctl cat mix.service
+Active: active (running)
 </code>
-Create a systemd override directory:
+Verify the MIX Java process:
 <code text>
-sudo mkdir -p /etc/systemd/system/mix.service.d
+pgrep -af 'com.ergotech.mix.server.HeadlessController'
 </code>
-This is the standard Linux location for local changes to an existing service. It keeps the original MIX service definition unchanged.
+The process should use:
-Create:
 <code text>
-sudo nano /etc/systemd/system/mix.service.d/override.conf
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
 </code>
-Paste:
+Verify that MIX is listening on port 7226:
 <code text>
-[Service]
+sudo ss -ltnp | grep 7226
-StandardOutput=append:/home/mix/mixruntime/logs/runmix-console.log
-StandardError=append:/home/mix/mixruntime/logs/runmix-console.log
 </code>
-Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
+===== 9. Verify MIX console logging =====
-Apply and restart:
+MIX console output is written to:
 <code text>
-sudo systemctl daemon-reload
+/home/mix/mixruntime/logs/runmix-console.log
-sudo systemctl restart mix.service
 </code>
-Verify the complete effective configuration:
+Verify:
 <code text>
-sudo systemctl cat mix.service
+tail -n 40 /home/mix/mixruntime/logs/runmix-console.log
 </code>
-===== 3. Verify MIX console logging =====
+Check the MIX build, pre-license key, and license result:
-Run:
 <code text>
-tail -n 20 /home/mix/mixruntime/logs/runmix-console.log
+grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
+/home/mix/mixruntime/logs/runmix-console.log | tail -n 10
 </code>
-You should see MIX and Java startup messages.
+A successfully licensed startup should contain lines similar to:
-It is normal for ''%%/var/log/syslog%%'' to continue containing Linux messages, for example network or WiFi status messages. The important result is which MIX and Java console output now appears in ''%%runmix-console.log%%'' rather than repeatedly filling the Linux system logs.
-===== 4. Get the MIX license =====
-From a browser on a PC, open:
 <code text>
-http://<Pi-address>:7226/setup.html
+Running MIX Build <build-number>
+Initializing MIX runtime with prelicense key: <pre-license-key>
+Valid IOT System Runtime License detected.
 </code>
-Click **Get Pre-License Key**.
+Verify the console log file:
-Send the displayed pre-license key to ErgoTech.
-The ErgoTech license is associated with the individual system. Changing the hostname, IP address, or network configuration does not change the license.
-Copy the ''%%ErgoIOTLicense.lic%%'' file which ErgoTech provides into:
 <code text>
-/home/mix/mixruntime
+ls -l /home/mix/mixruntime/logs/runmix-console.log
 </code>
-Then restart MIX:
+With the validated systemd configuration, the active console log was created as:
 <code text>
-sudo systemctl restart mix
+root root
 </code>
-Opening **Get Pre-License Key** also provides a convenient way to update the Raspberry Pi’s date and time. This is useful on systems which do not have access to a network time server.
+===== 10. Limit the MIX console log =====
-The same setup page contains **Network Configuration** for systems which use MIX to manage the Pi’s network settings.
-===== 5. Limit the MIX console log =====
 Create:
@@ Line 194: / Line 405: @@
 <code text>
 /home/mix/mixruntime/logs/runmix-console.log {
+    su root root
     size 5M
     rotate 5
@@ Line 201: / Line 413: @@
     notifempty
     copytruncate
-    create 0644 root root
 }
 </code>
@@ Line 207: / Line 418: @@
 Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
-Check it:
+Check the rule:
 <code text>
@@ Line 216: / Line 427: @@
   * ''%%/home/mix/mixruntime/logs/runmix-console.log%%''
-  * ''%%5242880 bytes%%'', which is 5 MB
+  * ''%%5242880 bytes%%''
   * ''%%5 rotations%%''
-If the current file is smaller than 5 MB, ''%%logrotate%%'' will say the log does not need rotating. This is normal.
+If the current file is smaller than 5 MB, ''%%logrotate%%'' will report that it does not need rotating. This is normal.
-''%%MIX.log%%'' is already limited by MIX’s log4j configuration and does not need this additional rule.
+To verify the rule completely, force one rotation:
-===== 6. Reboot and verify MIX =====
+<code text>
+sudo logrotate -vf /etc/logrotate.d/runmix-console
+</code>
+Check the result:
+<code text>
+ls -lh /home/mix/mixruntime/logs/runmix-console.log*
+systemctl status mix --no-pager
+pgrep -af 'com.ergotech.mix.server.HeadlessController'
+</code>
+The previous console contents should be copied to:
+<code text>
+runmix-console.log.1
+</code>
+The active ''%%runmix-console.log%%'' should be truncated while the same MIX process remains running.
+Generate a new request:
+<code text>
+curl -s -o /dev/null http://127.0.0.1:7226/setup.html
+sleep 2
+</code>
+Verify that the active log receives new output:
+<code text>
+ls -lh /home/mix/mixruntime/logs/runmix-console.log*
+tail -n 10 /home/mix/mixruntime/logs/runmix-console.log
+</code>
+A successful test should show:
+<code text>
+Default Servlet : GET Request: /setup.html
+</code>
+===== 11. Reboot and verify MIX =====
+Reboot:
 <code text>
@@ Line 229: / Line 482: @@
 </code>
-After about a minute, reconnect and run:
+After the Raspberry Pi comes back online, reconnect:
 <code text>
-systemctl status mix
+ssh mix@<Pi-address>
-tail -n 20 /home/mix/mixruntime/logs/runmix-console.log
+</code>
-df -h /
-ls -lh /var/log/syslog*
+Verify that MIX started automatically:
-ls -lh /var/log/daemon.log*
-cat /var/log/ergotech-boot-maintenance.log
+<code text>
+systemctl status mix --no-pager
+</code>
+Verify the MIX Java process:
+<code text>
+pgrep -af 'com.ergotech.mix.server.HeadlessController'
+</code>
+Verify port 7226:
+<code text>
+sudo ss -ltnp | grep 7226
+</code>
+Verify that the current boot started MIX and accepted the runtime license:
+<code text>
+grep -E "Running MIX Build|Valid IOT System Runtime License detected|Initializing MIX runtime" \
+/home/mix/mixruntime/logs/runmix-console.log | tail -n 10
 </code>
@@ Line 243: / Line 516: @@
   * MIX is ''%%active (running)%%''.
-  * ''%%runmix-console.log%%'' contains recent MIX messages.
+  * MIX is running with Java 25.
-  * The SD card has plenty of free space.
+  * Port 7226 is listening.
-  * ''%%syslog%%'' and ''%%daemon.log%%'' are bounded.
+  * The current MIX build started successfully.
-  * The boot-maintenance log shows a successful run after the reboot.
+  * The Raspberry Pi runtime license is accepted.
+  * ''%%runmix-console.log%%'' contains startup messages from the current boot.
+Finally, open:
+<code text>
+http://<Pi-address>:7226/index.html
+</code>
-If this SD card will become a master image, verify the complete system once more before imaging it.
+and verify that the deployed application is available after the reboot.
+At this point MIX is installed, licensed, configured for automatic startup, accepting MIStudio deployments, serving the deployed application, and rotating its console log correctly.