# Coreflux MQTT Broker

## Overview

This guide walks you through setting up the Coreflux MQTT Broker on a Revolution Pi (ARM64) industrial edge device, deploying LOT (Language of Things) actions from VS Code, and running Python-based vibration severity calculations directly inside the MQTT broker with no cloud dependency.

### Data flow

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2FDEsbpF3fUarx0seaxn7C%2FCoreflux.mp4?alt=media&token=e018d5e2-6777-4dbe-b1d2-5d09b9ab0cde>" %}

## Prerequisites

### Hardware

* Revolution Pi (ARM64) or any edge device with Ethernet. Learn abou the hardware requirement here: <https://docs.coreflux.org/quick-start/installation>
* Network connection between your dev PC and RevPi
* Vibration sensor with IO-Link (or simulated data)

### Software (Development PC)

* Visual Studio Code
* [LoT Language](https://docs.coreflux.org/lot-language/introduction) Support by Coreflux extension (VS Code marketplace)
* Python 3.11.9 from python.org (Not Microsoft Store version, see troubleshooting)

### Software (Revolution Pi)

* [Coreflux MQTT Broker ](https://docs.coreflux.org/)for Linux ARM64
* Python 3.11.x (installed via apt)
* python3.11-dev package
* Node-RED (optional, for visualization)

***

### 1. Installing Coreflux on Revolution Pi

{% stepper %}
{% step %}

#### Download and Extract

Download the Linux ARM64 build of Coreflux MQTT Broker from coreflux.org. Transfer it to your RevPi via SCP or download directly:

```shellscript
# On RevPi — create install directory
mkdir ~/coreflux
cd ~/coreflux

# Extract the downloaded zip
unzip CorefluxMQTTBroker_linux-arm64_1.10.0.zip

# Make binary executable
chmod +x CorefluxMQTTBroker

```

{% endstep %}

{% step %}

#### Install the Coreflux MQTT Broker

The installation instructions are given on this page: <https://docs.coreflux.org/quick-start/installation#raspberry-pi>

Start the broker to verify it works:

```shellscript
cd ~/coreflux
sudo ./CorefluxMQTTBroker
```

You should see the broker start and listen on port 1883. Press Ctrl+C to stop after confirming startup.

{% hint style="info" %}
Default Credentials

The default Coreflux broker credentials are username: root, password: coreflux. These are required when connecting from VS Code or MQTT clients.
{% endhint %}
{% endstep %}

{% step %}

### Install VS Code&#x20;

Install the open source code editor i.e., VS Code, on your computer: <https://code.visualstudio.com/>
{% endstep %}

{% step %}

### Install LoT extension in VS Code

LoT (Language of Things) is a human-readable language for IoT automation. It uses near-English syntax to define logic, data structures, and integrations—all executed directly within the Coreflux MQTT broker.\
\
The LoT extension lets you interact with the Coreflux MQTT broker from VS Code. To install LoT, go to the extension in VS Code and search for LoT.

<figure><img src="https://1831238825-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2FtFG5xNDYcgdXQyuL2ZV1%2Fimage.png?alt=media&#x26;token=cabc906d-f3d2-4e39-bc3b-9cc583b67c50" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Learning LoT

To learn how LoT interacts with Coreflux MQTT Broker, check this repository, which has many sample codes and exercises: <https://github.com/CorefluxCommunity/Language-Of-Things-Training/tree/main>
{% endstep %}

{% step %}

#### Configure VS Code Connection

In your LoT project folder, create or edit the .broker file with credentials embedded in the URL:

```shellscript
mqtt://root:coreflux@<RevPi-IP>:1883
#username: root, password: coreflux
```

{% hint style="warning" %}
Authentication Required

Without credentials in the .broker file, the VS Code extension will connect but receive PermissionDenied errors when trying to subscribe to $SYS/Coreflux/ system topics. This causes the 'Entity not found on broker' error in the LOT notebook.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### 2. Setting Up Python Runtime on Revolution Pi

Coreflux uses an embedded Python runtime located in \~/coreflux/python\_runtime/. On Linux ARM64, this requires manually copying the system Python shared libraries into this folder.

{% stepper %}
{% step %}

#### Install Required Python Packages

```shellscript
sudo apt update
sudo apt install python3.11 python3.11-dev python3.11-full -y
```

{% hint style="info" %}
Why python3.11-dev?

The -dev package installs the shared library files (libpython3.11.so) that embedded runtimes need to load Python via the C API. Without it, the broker finds the python\_runtime folder but cannot initialize Python.
{% endhint %}
{% endstep %}

{% step %}

### Find the Shared Library Files

{% code overflow="wrap" expandable="true" %}

```shellscript
find /usr/lib -name "libpython3.11*" 2>/dev/null

# Expected output:
# /usr/lib/aarch64-linux-gnu/libpython3.11.so.1
# /usr/lib/aarch64-linux-gnu/libpython3.11.so.1.0
# /usr/lib/python3.11/config-3.11-aarch64-linux-gnu/libpython3.11.so

```

{% endcode %}
{% endstep %}

{% step %}

### Copy Files to python\_runtime

```shellscript
# Clear existing contents
sudo rm -rf /home/pi/coreflux/python_runtime/*

# Copy Python executable
sudo cp /usr/bin/python3 /home/pi/coreflux/python_runtime/python

# Copy Python standard library
sudo cp -r /usr/lib/python3.11 /home/pi/coreflux/python_runtime/

# Copy shared libraries (critical — broker loads these at runtime)
sudo cp /usr/lib/aarch64-linux-gnu/libpython3.11.so.1 /home/pi/coreflux/python_runtime/
sudo cp /usr/lib/aarch64-linux-gnu/libpython3.11.so.1.0 /home/pi/coreflux/python_runtime/

```

{% endstep %}

{% step %}

#### Confirm Python Loads at Broker Startup

Start the broker and look for these lines in the output:

<pre class="language-shellscript"><code class="lang-shellscript"><strong>sudo ./CorefluxMQTTBroker
</strong>
# Look for:
# INF  Embedded Python runtime initialized at: /home/pi/coreflux/python_runtime
# INF  Python runtime initialized successfully    &#x3C;-- this is what we want
# INF  Python Entity Provider initialized
</code></pre>

{% hint style="success" %}
&#x20;Python Working

When you see 'Python runtime initialized successfully' instead of 'Python runtime not available,  scripts disabled', the Python integration is ready.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### 3. Troubleshooting

#### 3.1 Python Version Compatibility

{% hint style="warning" %}
Use Python 3.11 Only

Coreflux 1.10.0 is only compatible with Python 3.11. Using Python 3.12, 3.13, or 3.14 will cause 'Python runtime not available' even if all files are correctly copied. Always verify with: python3 --version
{% endhint %}

#### 3.2 Windows — Microsoft Store Python

On Windows, if Python is installed via the Microsoft Store, the where Python command returns:

```
C:\Users\YourName\AppData\Local\Microsoft\WindowsApps\python.exe
```

{% hint style="warning" %}
&#x20;Microsoft Store Python Incompatible

The Microsoft Store Python is a stub launcher — it does not contain python311.dll or the Lib/ folder that Coreflux needs. Always install Python from python.org using the Windows installer (64-bit). Download: <https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe>
{% endhint %}

#### 3.3 Windows- Copying Python to python\_runtime

After installing Python 3.11.9 from python.org, copy the full installation into the broker folder. This is in case you are running Coreflux Broker on Windows

```shellscript
# First confirm real Python path (should NOT be WindowsApps)
where python

# Copy to broker runtime folder
xcopy /E /I "C:\Users\YourName\AppData\Local\Programs\Python\Python311\*" "C:\Downloads\CorefluxMQTTBroker_win-x64_1.10.0\python_runtime\"

```

#### 3.4 Port 1883 Already in Use (Linux)

If you see 'MQTT Port 1883 is in use by unknown process', another instance of Coreflux is already running (possibly managed by pm2 or systemd):

```shellscript
# Find what is using port 1883
sudo lsof -i :1883

# Kill the process (use the PID shown)
sudo kill -9 <PID>

# If managed by pm2
pm2 stop all

# If managed by systemd
sudo systemctl stop coreflux
```

#### 3.5 'Entity Not Found on Broker' Error

This error appears in the LoT notebook when clicking the play button, but the action has never been deployed, or the broker has restarted and lost the action. The play button in a .lotnb file deploys the action to the broker; it does not auto-persist between broker restarts unless the action file is saved in the broker's persistent storage location.

{% hint style="info" %}
Deployment Tip

After restarting the broker, re-run all cells in your .lotnb file using 'Run All' to redeploy all actions.
{% endhint %}

***

### 4. Vibration Severity Example

#### 4.1 The Python Script- VibrationCalc.py

Create this file in your VS Code project. It will be deployed to the broker's python\_scripts folder:

```shellscript
# Script Name: VibrationCalc
import math

# Calculate 3-axis vibration magnitude using Euclidean distance formula
def sqrt_sum_of_squares(x, y, z):
    try:
        result = math.sqrt(float(x)**2 + float(y)**2 + float(z)**2)
        return result
    except (ValueError, TypeError):
        return 0  # Return safe default if sensor sends bad/missing data
```

{% hint style="info" %}
ISO 10816 Reference

The output of this function is vibration severity in mm/s RMS. According to ISO 10816: Zone A (0-0.7 mm/s) = excellent, Zone B (0.7-1.8) = acceptable, Zone C (1.8-4.5) = monitor, Zone D (>4.5) = danger.
{% endhint %}

#### 4.2 The LOT Action

Create a new .lotnb file in VS Code with this LOT action code:

```shellscript
DEFINE ACTION OpenPLC
ON EVERY 1 SECONDS DO
    # Pull latest RMS vibration readings from MQTT topics every second
    SET "x_vrms" WITH (GET TOPIC "X_VRMS" AS DOUBLE)
    SET "y_vrms" WITH (GET TOPIC "Y_VRMS" AS DOUBLE)
    SET "z_vrms" WITH (GET TOPIC "Z_VRMS" AS DOUBLE)

    # Hand off all 3 axes to Python and get back a single severity score
    CALL PYTHON "VibrationCalc.sqrt_sum_of_squares"
        WITH ({x_vrms}, {y_vrms}, {z_vrms})
        RETURN AS {vibration_severity}

    # Push the combined severity score out for dashboards/alerts to consume
    PUBLISH TOPIC "output/vibration_severity" WITH {vibration_severity}
```

#### 4.3 Deploy from VS Code

1. Open the .lotnb file in VS Code
2. Confirm the status bar shows 'MQTT: Connected to mqtt://\<RevPi-IP>:1883.'
3. Enter your user credentials:
   1. Username: root
   2. Password: coreflux
4. Click the ▶ play button on the LOT action cell to deploy
5. Check the COREFLUX ENTITIES panel — the action should appear
6. Publish test messages to X\_VRMS, Y\_VRMS, Z\_VRMS topics
7. Subscribe to output/vibration\_severity to see results

<figure><img src="https://1831238825-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2FafqSj9PEtQ2tajEkLzq0%2Fimage.png?alt=media&#x26;token=85b685b8-a20d-479f-9f2d-dae4745532d4" alt="" width="563"><figcaption></figcaption></figure>

#### 4.4 Test with MQTT Client

In the following example, we are reading actual vibration data via OPC UA. You can just replace the vibration data source in the flow for your use-case.

The source code for this flow is shared in the resource section.

<figure><img src="https://1831238825-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2FWlS2ds1YPubLbGVLxMWo%2Fimage.png?alt=media&#x26;token=0379d414-6de2-47b1-b328-6f8c4b715194" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="https://1831238825-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2FA0xzFp5uJfDufIN7Lq8M%2Fimage.png?alt=media&#x26;token=f64f3e5c-5eda-4680-9050-2f02b2a694d6" alt="" width="563"><figcaption></figcaption></figure>

#### 4.5 ISO 10816 Severity Classification Table

<table data-header-hidden><thead><tr><th width="99.66668701171875">Zone</th><th width="138.6666259765625">RMS (mm/s)</th><th width="144.6666259765625">Classification</th><th>Action</th></tr></thead><tbody><tr><td>Zone</td><td>RMS (mm/s)</td><td>Classification</td><td>Action</td></tr><tr><td>A</td><td>0 – 0.7</td><td>Excellent</td><td>New or recently serviced machine</td></tr><tr><td>B</td><td>0.7 – 1.8</td><td>Acceptable</td><td>Normal long-term operation</td></tr><tr><td>C</td><td>1.8 – 4.5</td><td>Monitor</td><td>Tolerable short-term, investigate</td></tr><tr><td>D</td><td>> 4.5</td><td>Danger</td><td>Shutdown recommended immediately</td></tr></tbody></table>

***

### 5. Network Configuration on Revolution Pi

#### &#xD;5.1 Check Current IPs

```shellscript
hostname -I
ip addr show | grep "inet "
```

#### &#xD;5.1 Assign Static IP to eth1

If you need to assign a static IP to the second Ethernet port (e.g. for direct connection to a PLC or IO-Link master):

```shellscript
# Create network config file
sudo nano /etc/network/interfaces.d/eth1


# Add these lines:
auto eth1
iface eth1 inet static
    address 192.168.100.10
    netmask 255.255.255.0
```

```shellscript
# If ifup does not apply the config, use ip commands directly:
sudo ip addr flush dev eth1
sudo ip addr add 192.168.100.10/24 dev eth1
sudo ip link set eth1 up

# Verify
ip addr show eth1
```

### 6. Managing the Coreflux Broker

#### 6.1 Start with Visible Logs

```shellscript
cd ~/coreflux
sudo ./CorefluxMQTTBroker 2>&1 | tee coreflux.log
```

#### 6.2 Run in Background (pm2)

```shellscript
# Start with pm2
pm2 start ./CorefluxMQTTBroker --name coreflux
pm2 save

# View status
pm2 status

# View logs
pm2 logs coreflux

# Stop
pm2 stop coreflux

```

#### 6.3 Run in Background (pm2)

```shellscript
# Check if broker is running and on which port
sudo lsof -i :1883

# Kill specific PID
sudo kill -9 <PID>

# Kill all instances
sudo pkill -f CorefluxMQTTBroker

```

## Resources:

#### Node-RED flow

{% file src="<https://1831238825-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLd2M9UNfMTnw9DjDdZJz%2Fuploads%2Fj4nExfcukMBzjHNlFTIa%2Fcoreflux_flow.txt?alt=media&token=65916d87-a5a2-458f-b5eb-ece462270fbf>" %}

## Quick Reference

| Item                               | Value / Command                                       |
| ---------------------------------- | ----------------------------------------------------- |
| Broker port                        | 1883                                                  |
| Default credentials                | root / coreflux                                       |
| .broker file format                | mqtt://root:coreflux@\<IP>:1883                       |
| Python version (required)          | 3.11.x — do NOT use 3.12+                             |
| python\_runtime location (Linux)   | /home/pi/coreflux/python\_runtime/                    |
| python\_runtime location (Windows) | CorefluxMQTTBroker\_win-x64\_1.10.0\python\_runtime\\ |
| Key apt package                    | python3.11-dev                                        |
| Check broker port                  | sudo lsof -i :1883                                    |
| View broker logs                   | sudo ./CorefluxMQTTBroker 2>&1 \| tee coreflux.log    |
| Deploy action from VS Code         | Click ▶ play button on .lotnb cell                    |
| Output topic                       | output/vibration\_severity                            |