Differences

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

--- installingmixonrpi [2026/10/27 16:13] – tputman
+++ installingmixonrpi [2026/10/27 17:06] (current) – tputman
@@ Line 3: / Line 3: @@
 Complete [[BaseRaspberryPiSetupBookworm]|Raspberry Pi Base Setup]] first.
-MIX requires **Java 25 or newer**. The Raspberry Pi installation validated with the current MIX runtime used:
+These instructions install MIX in:
 <code text>
-/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
+/home/mix/mixruntime
 </code>
-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%%''.
+MIX requires **Java 25**.
-These instructions assume MIX is installed in:
+The validated Raspberry Pi installation used:
 <code text>
-/home/mix/mixruntime
+/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.
-Useful MIX addresses are:
+The MIX setup page is:
 <code text>
-http://<Pi-address>:7226/index.html
 http://<Pi-address>:7226/setup.html
 </code>
-The first opens the deployed application. The second opens the MIX setup page.
+After an MIStudio project is deployed, the validated application URL is:
-===== 1. Install the MIX runtime =====
+<code text>
+http://<Pi-address>:7226/index.html
+</code>
-Use the MIX runtime supplied with the current ErgoTech software release.
+===== 1. Copy the MIX runtime to the Raspberry Pi =====
-A current MIX installation contains files and directories including:
+On the Windows computer, open PowerShell and change to the MIX installation directory for the software release being deployed.
+For example:
 <code text>
-mix.jar
+Set-Location "C:\ET\<release>\MIX"
-mix.properties
-htmlroot/
-lib/
-log4j/
-logs/
-scripts/
-security/
 </code>
-The Linux startup script is:
+Create the MIX runtime directory on the Raspberry Pi:
 <code text>
-scripts/MIX.sh
+ssh mix@<Pi-address> "mkdir -p /home/mix/mixruntime"
 </code>
-Current MIX releases no longer use ''%%runmix.sh%%''.
+Copy the contents of the MIX runtime directory:
-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:
 <code text>
-C:\ET\<release>\MIX
+scp -r .\* mix@<Pi-address>:/home/mix/mixruntime/
 </code>
-change to that directory:
+After the copy completes, connect to the Pi:
 <code text>
-Set-Location "C:\ET\<release>\MIX"
+ssh mix@<Pi-address>
 </code>
-Create the Raspberry Pi runtime directory:
+Verify the runtime files:
 <code text>
-ssh mix@<Pi-address> "mkdir -p /home/mix/mixruntime"
+ls -la /home/mix/mixruntime
+ls -la /home/mix/mixruntime/scripts
 </code>
-Copy the contents of the MIX runtime directory:
+The MIX runtime should contain files and directories including:
 <code text>
-scp -r .\* mix@<Pi-address>:/home/mix/mixruntime/
+mix.jar
+mix.properties
+htmlroot/
+lib/
+log4j/
+logs/
+scripts/
+security/
 </code>
-After the copy, verify the runtime on the Pi:
+The Linux startup script is:
 <code text>
-ls -la /home/mix/mixruntime
+/home/mix/mixruntime/scripts/MIX.sh
-ls -la /home/mix/mixruntime/scripts
 </code>
@@ Line 94: / Line 93: @@
 </code>
-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.
+If the copied MIX installation contains an ''%%ErgoIOTLicense_*.lic%%'' file from another computer, remove or move that file before starting MIX.
-===== 2. Verify Java 25 and start MIX manually =====
+Each Raspberry Pi must use the runtime license associated with that Pi.
-Verify the Java installation which MIX will use:
+===== 2. Verify Java 25 =====
+Verify the Java installation:
 <code text>
@@ Line 104: / Line 105: @@
 </code>
-The validated installation reports Java 25.
+The validated installation reports:
-Start MIX manually:
+<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>
-MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
+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 show the selected Java executable and the configured MIX port.
+Startup output should identify the MIX installation, Java executable, and configured port.
 For example:
@@ Line 124: / Line 137: @@
 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>
-The runtime should also report its MIX build number.
+and its MIX build number.
-If the Pi does not yet have its runtime license, MIX will display its pre-license key.
+If a Raspberry Pi runtime license has not yet been installed, MIX will display the system's pre-license key:
-The current validation showed:
 <code text>
@@ Line 138: / Line 155: @@
 </code>
-An invalid-license message at this stage is expected until the Raspberry Pi's license file has been installed.
+Keep this key for the license request.
-===== 3. Install the Raspberry Pi MIX license =====
+===== 4. Install the Raspberry Pi runtime license =====
-Each Raspberry Pi requires the appropriate ErgoTech runtime license.
+Each Raspberry Pi requires an ErgoTech runtime license associated with that system.
-The pre-license key can be obtained from MIX startup output or from the MIX setup page:
+The pre-license key is shown during MIX startup. It can also be viewed from the MIX setup page:
 <code text>
@@ Line 150: / Line 167: @@
 </code>
-On the setup page, select **Get Pre-License Key**.
+Select **Get Pre-License Key** and send the displayed key to ErgoTech.
-Send the displayed pre-license key to ErgoTech.
+Copy the license provided for the Raspberry Pi into:
-Copy the license provided for that Raspberry Pi into:
 <code text>
@@ Line 160: / Line 175: @@
 </code>
-The license filename may include the pre-license key, for example:
+The filename may include the pre-license key, for example:
 <code text>
@@ Line 166: / Line 181: @@
 </code>
-Restart MIX after installing the license.
+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.
-For a manual startup:
+Start MIX again:
 <code text>
 cd /home/mix/mixruntime
-MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
+MIX_JAVA_HOME=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64 \
 ./scripts/MIX.sh
 </code>
-A successful startup should contain:
+Verify that startup contains:
 <code text>
@@ Line 183: / Line 198: @@
 </code>
-A runtime license generated for the Raspberry Pi was successfully accepted by both MIX and TransSECS on the same Pi during validation.
+===== 5. Verify the MIX web server =====
-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.
-===== 4. Verify the MIX web server =====
 While MIX is running, verify that port 7226 is listening:
@@ Line 209: / Line 218: @@
 </code>
-The MIX setup page should load.
+Verify that the MIX setup page loads.
-After an application has been deployed, the application can normally be opened at:
+===== 6. Deploy an MIStudio project to the Raspberry Pi =====
-<code text>
+In MIStudio, select the project's **MIX Target**.
-http://<Pi-address>:7226/index.html
-</code>
-===== 5. Deploy an MIStudio project directly to the Raspberry Pi =====
+Configure the target with the Raspberry Pi address.
-MIStudio can deploy a project directly to the MIX runtime running on the Raspberry Pi.
+For example:
-In the MIStudio project, select the **MIX Target**.
-Configure:
 <code text>
@@ Line 232: / Line 235: @@
 </code>
-Use the configured MIX password.
+Enter the configured MIX password.
-Save the project, then select **Deploy**.
+Save the MIStudio project and select **Deploy**.
-During a successful deployment, the MIX runtime will:
+During a successful deployment, MIX should:
   * authenticate the MIStudio deployment request,
-  * stop and release the currently deployed application logic,
+  * stop the currently loaded application logic,
   * replace the deployed application files,
-  * load the new ''%%VIBLogic.jar%%'' and application files,
+  * receive the new ''%%VIBLogic.jar%%'' and application files,
-  * reload the MIX project,
+  * reload the application logic,
-  * continue using the Raspberry Pi runtime license.
+  * continue running without requiring the MIX process to be stopped manually.
-A successful deployment does not require manually stopping the MIX process.
 After deployment, open:
@@ Line 253: / Line 254: @@
 </code>
-and verify that the newly deployed application loads.
+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:
+The MIX console should show the deployment files being received and the application logic being reloaded.
-<code text>
+===== 7. Stop the manual MIX process =====
-http://<Pi-address>:7226/servlet/UserManager
-</code>
-===== 6. Run MIX automatically as a Linux service =====
+Before configuring automatic startup, stop the manually started MIX process.
-Linux uses **systemd** to manage services.
+If MIX is running in the foreground, press:
-A MIX systemd service starts MIX automatically during boot and restarts it if the process stops.
+<code text>
+Ctrl+C
-MIX console output should also be redirected to its own log file.
+</code>
-First make sure a manually started MIX process is not still running:
+Verify that no MIX HeadlessController process remains:
 <code text>
@@ Line 275: / Line 274: @@
 </code>
-If MIX was started manually, stop it before starting the systemd service.
+No output should be returned.
-==== If no MIX service exists yet ====
+===== 8. Run MIX automatically as a Linux service =====
-Create the log directory if necessary:
+Create the log directory if it does not already exist:
 <code text>
@@ Line 315: / Line 314: @@
 Save with **Ctrl+O**, **Enter**, **Ctrl+X**.
-Then run:
+Reload systemd, enable MIX at boot, and start it:
 <code text>
@@ Line 321: / Line 320: @@
 sudo systemctl enable mix
 sudo systemctl start mix
+</code>
+Verify the service:
+<code text>
 systemctl status mix --no-pager
 </code>
-Verify that the service shows:
+Look for:
 <code text>
@@ Line 330: / Line 334: @@
 </code>
-The running process should be Java 25 executing:
+Verify the MIX Java process:
 <code text>
-com.ergotech.mix.server.HeadlessController
+pgrep -af 'com.ergotech.mix.server.HeadlessController'
 </code>
-Verify:
+The process should use:
 <code text>
-pgrep -af 'com.ergotech.mix.server.HeadlessController'
+/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java
 </code>
-Also verify that port 7226 is listening:
+Verify that MIX is listening on port 7226:
 <code text>
@@ Line 348: / Line 352: @@
 </code>
-==== If MIX already has a service ====
+===== 9. Verify MIX console logging =====
-Do not replace an existing working service without first inspecting it.
+MIX console output is written to:
-Run:
 <code text>
-sudo systemctl cat mix.service
+/home/mix/mixruntime/logs/runmix-console.log
 </code>
-Confirm that the effective service configuration uses:
+Verify:
-  * 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.
-===== 7. Verify MIX console logging =====
-Run:
 <code text>
@@ Line 377: / Line 366: @@
 </code>
-The log should contain MIX and Java startup messages.
+Check the MIX build, pre-license key, and license result:
-Useful checks include:
 <code text>
@@ Line 394: / Line 381: @@
 </code>
-It is normal for Linux system logs to continue containing operating-system messages such as network or WiFi status messages.
+Verify the console log file:
-The important result is that MIX and Java console output is written to:
 <code text>
-/home/mix/mixruntime/logs/runmix-console.log
+ls -l /home/mix/mixruntime/logs/runmix-console.log
 </code>
-When systemd creates this redirected log, the active file may be owned by:
+With the validated systemd configuration, the active console log was created as:
 <code text>
@@ Line 408: / Line 393: @@
 </code>
-even though MIX itself runs as the ''%%mix%%'' user.
+===== 10. Limit the MIX console log =====
-===== 8. Limit the MIX console log =====
 Create:
@@ Line 432: / Line 415: @@
 }
 </code>
-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**.
@@ Line 446: / 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 report that 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.
-To fully test the rule, force one rotation:
+To verify the rule completely, force one rotation:
 <code text>
@@ Line 457: / Line 438: @@
 </code>
-Verify:
+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 contents should be copied to:
+The previous console contents should be copied to:
 <code text>
@@ Line 470: / Line 452: @@
 </code>
-and the active ''%%runmix-console.log%%'' should be truncated while MIX remains running.
+The active ''%%runmix-console.log%%'' should be truncated while the same MIX process remains running.
-Generate a new MIX request:
+Generate a new request:
 <code text>
@@ Line 479: / Line 461: @@
 </code>
-Then verify that the active log grows again:
+Verify that the active log receives new output:
 <code text>
@@ Line 486: / Line 468: @@
 </code>
-A successful test will show a new request similar to:
+A successful test should show:
 <code text>
@@ Line 492: / Line 474: @@
 </code>
-''%%MIX.log%%'' is already controlled by MIX's Log4j configuration and does not need this additional console-log rule.
+===== 11. Reboot and verify MIX =====
-===== 9. Reboot and verify MIX =====
 Reboot:
@@ Line 502: / Line 482: @@
 </code>
-After the Raspberry Pi comes back online, reconnect with SSH.
+After the Raspberry Pi comes back online, reconnect:
-Verify the MIX service:
+<code text>
+ssh mix@<Pi-address>
+</code>
+Verify that MIX started automatically:
 <code text>
@@ Line 522: / Line 506: @@
 </code>
-Verify the post-reboot startup and license:
+Verify that the current boot started MIX and accepted the runtime license:
 <code text>
@@ Line 529: / Line 513: @@
 </code>
-Also check:
+Verify:
-<code text>
+  * MIX is ''%%active (running)%%''.
-df -h /
+  * MIX is running with Java 25.
-ls -lh /var/log/syslog*
+  * Port 7226 is listening.
-ls -lh /var/log/daemon.log*
+  * The current MIX build started successfully.
-cat /var/log/ergotech-boot-maintenance.log
+  * The Raspberry Pi runtime license is accepted.
-</code>
+  * ''%%runmix-console.log%%'' contains startup messages from the current boot.
 Finally, open:
@@ Line 544: / Line 528: @@
 </code>
-and confirm that the deployed application loads without manually starting MIX.
+and verify that the deployed application is available after the reboot.
-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.
+At this point MIX is installed, licensed, configured for automatic startup, accepting MIStudio deployments, serving the deployed application, and rotating its console log correctly.