Complete Raspberry Pi Base Setup first.

These instructions apply to both TransSECS Devices and TransSECS Servers.

The examples assume:

/home/mix/secs

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

Current TransSECS deployments require Java 25.

The validated ARM64 Java installation is:

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

Verify Java before installing the deployment:

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

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.

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:

ErgoTechConfiguration.properties
GEMHostRuntime.jar
run.sh
logging configuration
runtime dependencies

Copy the complete generated deployment, including all JAR files and supporting files, to the Raspberry 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.

From a PC in the directory containing the deployment folder:

ssh [email protected] "mkdir -p /home/mix/secs"
scp -r GEMHostDeployment/. [email protected]:/home/mix/secs/

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

sftp [email protected]
cd /home/mix/secs
lcd GEMHostDeployment
put -r *
quit

WinSCP or FileZilla can also be used.

Choose:

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

/home/mix/secs

Files copied from Windows may not retain Linux execute permissions.

On the Pi:

cd /home/mix/secs
chmod +x run.sh
ls -l run.sh

The permissions should include executable bits, for example:

-rwxr-xr-x

Run the deployment using Java 25:

cd /home/mix/secs
 
PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH \
./run.sh

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

For example:

Initializing TransSecs runtime with prelicense key: 387508361

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.

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

/usr/lib/jni

Edit:

nano run.sh

Set the library path to:

export LD_LIBRARY_PATH=./:../lib/:/usr/lib/jni

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

HSMS network connections do not require this change.

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

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

ErgoIOTLicense_387508361.lic

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:

scp ErgoIOTLicense_387508361.lic [email protected]:/home/mix/secs/

Run the deployment again:

cd /home/mix/secs
 
PATH=/opt/java/zulu25.34.17-ca-fx-jdk25.0.3-linux_aarch64/bin:$PATH \
./run.sh

The runtime should proceed through license validation and start normally.

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

A GEM Host deployment may create:

GEMHostProperties.xml

after its first startup.

Check the configured equipment connection:

grep -n -A1 -B1 -E 'equipmentHostName|activePort|deviceId' GEMHostProperties.xml

A configuration may look similar to:

deviceId
1
 
equipmentHostName
192.168.0.191
 
activePort
5010

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:

localhost

Use the remote equipment computer's network address instead.

After changing the configuration, start the deployment again:

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

Check:

SECSMessages.log

for successful communications.

Useful messages include:

Successful Select
S1F13
S1F14
S6F11
S6F12
LINKTEST_REQ

For a GEM event, a normal exchange may include:

S6F11 W
S6F12 <B 0x0>

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.

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.

A successfully initialized Databricks connection may report:

Connection: "SparkSQL" Version: 3.3.3 Driver: "DatabricksJDBC"

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

For example:

SELECT *
FROM workspace.default.process_log_live
ORDER BY ts DESC
LIMIT 20;

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

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:

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

Paste:

[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

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

Tell systemd about the new service:

sudo systemctl daemon-reload
sudo systemctl enable transsecs
sudo systemctl start transsecs
sudo systemctl status transsecs

Look for:

active (running)

Press q to leave the status display.

Check the TransSECS console log:

tail -n 20 /home/mix/secs/transsecs-console.log

You should see recent TransSECS startup messages.

If you use:

tail -f /home/mix/secs/transsecs-console.log

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

Press Ctrl+C to return to the command prompt.

Create:

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

Paste:

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

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

Check the configuration safely:

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

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.

Reboot the Pi:

sudo reboot

Reconnect after the Pi is available:

ssh [email protected]

Check the service:

systemctl status transsecs

Check the console log:

tail -n 20 /home/mix/secs/transsecs-console.log

Check disk usage:

df -h /

Check Linux log sizes:

ls -lh /var/log

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.

If:

./run.sh

returns:

Permission denied

restore executable permission:

chmod +x run.sh

Then try again.

Check the GEM Host configuration:

grep -n -A1 -B1 -E 'equipmentHostName|activePort|deviceId' GEMHostProperties.xml

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.

Check both:

SECSMessages.log

and:

/home/mix/secs/transsecs-console.log

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.