====== Installing Deployments from TransSECS Servers or Devices on a Raspberry Pi ======

Complete [[BaseRaspberryPiSetupBookworm] | Raspberry Pi Base Setup]] first.

These instructions apply to both **TransSECS Devices** and **TransSECS Servers**.

The examples assume:

<code text>
/home/mix/secs
</code>

If your login user is ''%%pi%%'', the equivalent location is ''%%/home/pi/secs%%''.

===== 1. Java requirement =====

Current TransSECS deployments require **Java 25**.

The validated ARM64 Java installation is:

<code text>
/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64
</code>

Verify Java before installing the deployment:

<code text>
/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin/java -version
</code>

The output should identify Zulu/OpenJDK 25.

Do not assume the Pi's default ''%%java%%'' command points to the correct version. Other ErgoTech software on the Pi may use a different Java installation.

===== 2. Build the TransSECS deployment =====

In TransSECS Builder, open the desired project and select:

**Tools → Build**

The generated deployment directory contains the files required to run the TransSECS application outside the Builder.

A GEM Host deployment normally includes files such as:

<code text>
ErgoTechConfiguration.properties
GEMHostRuntime.jar
run.sh
logging configuration
runtime dependencies
</code>

Copy the **complete generated deployment**, including all JAR files and supporting files, to the Raspberry Pi.

===== 3. Copy the TransSECS deployment to the Pi =====

Use SFTP or SCP rather than ordinary FTP.

SSH/SFTP uses port 22 and does not require a separate FTP server on the Pi.

==== Using scp ====

From a PC in the directory containing the deployment folder:

<code text>
ssh mix@192.168.1.50 "mkdir -p /home/mix/secs"
scp -r GEMHostDeployment/. mix@192.168.1.50:/home/mix/secs/
</code>

Replace the IP address with the Pi's actual address.

==== Using sftp ====

<code text>
sftp mix@192.168.1.50
cd /home/mix/secs
lcd GEMHostDeployment
put -r *
quit
</code>

==== Using a graphical file-transfer program ====

WinSCP or FileZilla can also be used.

Choose:

^Setting ^Value                             ^
|Protocol|SFTP                              |
|Host    |Pi IP address or ''%%mix.local%%''|
|Port    |22                                |
|User    |''%%mix%%''                       |
|Password|''%%ErgoErgo%%''                  |

Copy all files and folders inside the generated deployment directory into:

<code text>
/home/mix/secs
</code>

===== 4. Set Linux permissions =====

Files copied from Windows may not retain Linux execute permissions.

On the Pi:

<code text>
cd /home/mix/secs
chmod +x run.sh
ls -l run.sh
</code>

The permissions should include executable bits, for example:

<code text>
-rwxr-xr-x
</code>

===== 5. Test the deployment manually =====

Run the deployment using Java 25:

<code text>
cd /home/mix/secs

PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH \
./run.sh
</code>

On the first start, TransSECS should report a **prelicense key**.

For example:

<code text>
Initializing TransSecs runtime with prelicense key: 387508361
</code>

Record the prelicense key and send it to ErgoTech.

Press **Ctrl+C** to stop the application after recording the key.

If a usable prelicense key is not generated, contact ErgoTech before continuing.

==== Serial or SECS-I equipment ====

For a serial connection, the Pi's serial library is normally under:

<code text>
/usr/lib/jni
</code>

Edit:

<code text>
nano run.sh
</code>

Set the library path to:

<code text>
export LD_LIBRARY_PATH=./:../lib/:/usr/lib/jni
</code>

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

HSMS network connections do not require this change.

===== 6. Install the runtime license =====

ErgoTech will provide a runtime license associated with the Pi's prelicense key.

The license filename may include the prelicense number, for example:

<code text>
ErgoIOTLicense_387508361.lic
</code>

Use the exact license file supplied by ErgoTech.

If MIX has already been licensed on the same Raspberry Pi using the same prelicense key, the same Pi-specific ErgoIOT runtime license can be copied into the TransSECS deployment directory.

Copy it into the TransSECS deployment folder:

<code text>
scp ErgoIOTLicense_387508361.lic mix@192.168.1.50:/home/mix/secs/
</code>

Run the deployment again:

<code text>
cd /home/mix/secs

PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH \
./run.sh
</code>

The runtime should proceed through license validation and start normally.

Press **Ctrl+C** to stop the application before continuing with permanent installation.

===== 7. Configure the GEM/HSMS target =====

A GEM Host deployment may create:

<code text>
GEMHostProperties.xml
</code>

after its first startup.

Check the configured equipment connection:

<code text>
grep -n -A1 -B1 -E 'equipmentHostName|activePort|deviceId' GEMHostProperties.xml
</code>

A configuration may look similar to:

<code text>
deviceId
1

equipmentHostName
192.168.0.191

activePort
5010
</code>

Use the hostname or IP address, port, and device ID appropriate for the installation.

If the equipment endpoint is running on another computer, do not use:

<code text>
localhost
</code>

Use the remote equipment computer's network address instead.

After changing the configuration, start the deployment again:

<code text>
PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH \
./run.sh
</code>

===== 8. Verify HSMS / SECS-GEM communication =====

Check:

<code text>
SECSMessages.log
</code>

for successful communications.

Useful messages include:

<code text>
Successful Select
S1F13
S1F14
S6F11
S6F12
LINKTEST_REQ
</code>

For a GEM event, a normal exchange may include:

<code text>
S6F11 W
S6F12 <B 0x0>
</code>

An S6F12 value of 0 indicates that the SECS event was acknowledged.

For a remote HSMS connection, you can also verify that the network socket is established from either endpoint.

===== 9. Verify configured database or historical outputs =====

If the TransSECS project includes a database or historical connection, verify the downstream destination separately.

A successful SECS acknowledgement confirms that the GEM message was handled, but it does not by itself prove that downstream data was stored successfully.

Check the TransSECS logs for database-related errors and verify that new records actually appear in the configured database.

==== Databricks example ====

A successfully initialized Databricks connection may report:

<code text>
Connection: "SparkSQL" Version: 3.3.3 Driver: "DatabricksJDBC"
</code>

For a Databricks deployment using Zerobus, verify that new rows appear in the configured target table.

For example:

<code sql>
SELECT *
FROM workspace.default.process_log_live
ORDER BY ts DESC
LIMIT 20;
</code>

Verify that the newest rows correspond to events generated after the Raspberry Pi TransSECS runtime was started.

===== 10. Run TransSECS automatically as a Linux service =====

Linux uses **systemd** to manage background services.

Running TransSECS as a service allows it to start automatically when the Pi boots and restart automatically if the application stops.

Create the service:

<code text>
sudo nano /etc/systemd/system/transsecs.service
</code>

Paste:

<code text>
[Unit]
Description=TransSECS
After=network-online.target
Wants=network-online.target

[Service]
User=mix
WorkingDirectory=/home/mix/secs
Environment="PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStart=/bin/sh /home/mix/secs/run.sh
Restart=always
RestartSec=10
StandardOutput=append:/home/mix/secs/transsecs-console.log
StandardError=append:/home/mix/secs/transsecs-console.log

[Install]
WantedBy=multi-user.target
</code>

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

Tell systemd about the new service:

<code text>
sudo systemctl daemon-reload
sudo systemctl enable transsecs
sudo systemctl start transsecs
sudo systemctl status transsecs
</code>

Look for:

<code text>
active (running)
</code>

Press **q** to leave the status display.

Check the TransSECS console log:

<code text>
tail -n 20 /home/mix/secs/transsecs-console.log
</code>

You should see recent TransSECS startup messages.

If you use:

<code text>
tail -f /home/mix/secs/transsecs-console.log
</code>

the command remains open and displays new messages as they arrive.

Press **Ctrl+C** to return to the command prompt.

===== 11. Limit the TransSECS console log =====

Create:

<code text>
sudo nano /etc/logrotate.d/transsecs-console
</code>

Paste:

<code text>
/home/mix/secs/transsecs-console.log {
    su root root
    size 5M
    rotate 5
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
</code>

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

Check the configuration safely:

<code text>
sudo logrotate -d /etc/logrotate.d/transsecs-console
</code>

The output should mention the TransSECS console log, a 5 MB threshold, and 5 rotations.

There should be no error messages.

''%%copytruncate%%'' allows logrotate to rotate the console log without stopping TransSECS.

TransSECS application-generated log files may also have their own rollover configuration. Review the logging configuration included with the deployment before creating additional Linux logrotate rules for those files.

===== 12. Reboot and verify =====

Reboot the Pi:

<code text>
sudo reboot
</code>

Reconnect after the Pi is available:

<code text>
ssh mix@192.168.1.50
</code>

Check the service:

<code text>
systemctl status transsecs
</code>

Check the console log:

<code text>
tail -n 20 /home/mix/secs/transsecs-console.log
</code>

Check disk usage:

<code text>
df -h /
</code>

Check Linux log sizes:

<code text>
ls -lh /var/log
</code>

Verify:

  * TransSECS is ''%%active (running)%%''.
  * Java 25 is being used.
  * The console log contains recent application messages.
  * The expected HSMS/SECS connection is established.
  * The SD card has sufficient free space.
  * Linux log files remain reasonably small.
  * Any configured database or historical destination is receiving new data.

===== Troubleshooting =====

==== run.sh: Permission denied ====

If:

<code text>
./run.sh
</code>

returns:

<code text>
Permission denied
</code>

restore executable permission:

<code text>
chmod +x run.sh
</code>

Then try again.

==== Cannot connect to equipment =====

Check the GEM Host configuration:

<code text>
grep -n -A1 -B1 -E 'equipmentHostName|activePort|deviceId' GEMHostProperties.xml
</code>

Confirm:

  * The equipment hostname or IP address is correct.
  * The HSMS port is correct.
  * The device ID is correct.
  * The equipment application is running.
  * The equipment machine is listening on the configured port.
  * The Pi can reach the equipment machine over the network.

==== TransSECS starts but downstream data does not appear ====

Check both:

<code text>
SECSMessages.log
</code>

and:

<code text>
/home/mix/secs/transsecs-console.log
</code>

Confirm that SECS/GEM events are being received, then check the configured database or historical destination for connection, authentication, authorization, or write errors.

Do not rely only on an S6F12 ACK to determine whether downstream storage succeeded.