MQTT Client App

MQTT Client for Barionet Flexa

Version	Changelog	Date	Download
1.0.0	Initial Release	29 Jul 2025	package.zip

Application Version: 1.0.0
Compatible Firmware: Flexa Firmware min. v2.3.0
Device Compatibility: Barionet M44, UX8 Extension

Overview

The Barionet MQTT Application provides industrial-grade MQTT control for Barionet devices, enabling remote relay control and digital input monitoring. The application features automatic hardware detection, robust error handling, and comprehensive logging capabilities.

Key Features

Relay Control: MQTT-based control of up to 20 relays
Digital Input Monitoring: Real-time monitoring of up to 20 digital inputs
Hardware Auto-Detection: Automatic detection of built-in IOs and UX8 IO extensions
High Availability: Automatic MQTT re-connection with exponential backoff
Production Logging: Remote syslog integration with structured logging
Health Monitoring: Built-in health checks and system monitoring
Graceful Shutdown: Proper cleanup and status reporting

Supported Hardware

Barionet Base Unit: Relays/Inputs 1-4 (always available)
1x UX8 Extension: Relays/Inputs 5-12 (auto-detected)
2x UX8 Extensions: Relays/Inputs 13-20 (auto-detected)

Compatible Hardware

Primary Platform: The IO Tunnel Application is designed for Barionet M44 devices running the Flexa Firmware v2.3.0.

Extension Support: Up to (2x) UX8 extension module can be connected via USB, the system gains an additional 16 digital inputs and 16 relays, bringing the total capacity to 20 inputs and 20 relays per set.

Installation Process

Installing the IO Tunnel Application requires uploading a package file directly to your Barionet device through its web interface. This process is straightforward but requires careful attention to ensure proper installation.

NOTE: If your Barionet M44 is already running an application you must RESET TO DEFAULTS before proceeding and installing a new one.

Step 1: Access the Device Web Interface

Open your web browser and navigate to your Barionet device's IP address
Enter your administrator username and password when prompted
Wait for the main interface to load completely before proceeding
Barionet M44 User Interface

Step 2: Upload the Application Package

Navigate to the HOME tab in the main menu
Locate the "Upload" button next to “Install Package” within the page
Click the file selection button and browse to the “package.zip” which was downloaded from this page
Choose an appropriate version number for tracking purposes (this can be any number you prefer for identification)
Click the UPLOAD button to begin the installation process

Step 3: Device Reboot and Verification

After the upload completes, your Barionet device will automatically initiate a reboot sequence. This reboot is necessary to properly integrate the new application into the system. The reboot process typically takes 30..40s

Wait for the device to complete its reboot cycle
Reconnect to the web interface using the same IP address and credentials
Navigate back to the HOME tab
Verify that the IO Tunnel application appears with a status of "running"

Configuration

After successfully installing the application on your Barionet you will notice a new tab “MQTT” where the application can be configured.

The configuration is distributed across the following sections:

MQTT Configuration Parameters

Required Parameters

Parameter	Description	Example
`mqtt_broker`	MQTT broker IP address or hostname	`"192.168.1.100"`
`mqtt_port`	MQTT broker port number	`1883`
`mqtt_client_id`	Unique MQTT client identifier	`"barionet_device1"`
`mqtt_device_id`	Device ID used in MQTT topics	`"device1"`

Optional Parameters

Parameter	Default	Range	Description
`mqtt_username`	`null`		MQTT authentication username (use `"null"` for none)
`mqtt_password`	`null`		MQTT authentication password (use `"null"` for none)
`mqtt_keepalive`	`60`	10-3600	MQTT connection keepalive interval (seconds)
`mqtt_qos`	`1`	0, 1, 2	Quality of Service level for MQTT messages
`mqtt_retain`	`false`		Default retain flag for published messages

Last Will and Testament Parameters

Parameter	Default	Description
`mqtt_last_will_topic`	`"barix/{device_id}/status"`	Topic for Last Will message
`mqtt_last_will_payload`	`"offline"`	Payload for Last Will message
`mqtt_last_will_qos`	`1`	QoS level for Last Will message
`mqtt_last_will_retain`	`true`	Retain flag for Last Will message

Hardware Configuration Parameters

Parameter	Default	Range	Description
`hardware_poll_interval`	`0.1`	0.001-10.0	Digital input polling interval (seconds)

Logging Configuration Parameters

Parameter	Default	Options	Description
`logging_level`	`"INFO"`	DEBUG, INFO, WARNING, ERROR, CRITICAL	Application log level
`logging_syslog_enabled`	`true`		Enable/disable remote syslog logging
`logging_syslog_server`	`"localhost"`		Remote syslog server IP address (i.e. “192.168.75.43”)
`logging_syslog_port`	`514`	1-65535	Remote syslog server port

Application Configuration Parameters

Parameter	Default	Range	Description
`application_reconnect_delay`	`5.0`	1.0-300.0	Base delay for MQTT reconnection (seconds)
`application_max_reconnect_attempts`	`10`	1-100	Maximum MQTT reconnection attempts
`application_health_check_interval`	`300.0`	30.0-3600.0	Health check interval (seconds)

MQTT Topics

The application implements a structured MQTT topic hierarchy based on the device ID configuration.

Topic Structure

All topics follow the pattern: barix/{device_id}/{function}/{number}/{action}

Where:

{device_id}: Value from mqtt_device_id configuration parameter
{function}: Type of operation (relay, input, status)
{number}: Hardware number (1-20 for relays/inputs)
{action}: Action type (set, status)

Device Status Topics

Device Online/Offline Status

Topic: barix/{device_id}/status

Direction: Application → MQTT Broker

Payloads:

"online" - Device is connected and operational
"offline" - Device is disconnected (via Last Will and Testament)

Characteristics:

QoS: 1
Retained: Yes
Published automatically on connection/disconnection

Example:

CODE

Topic: barix/device1/status
Payload: "online"

Relay Control Topics

Relay Command Topic

Topic: barix/{device_id}/relay/{relay_num}/set

Direction: MQTT Client → Application

Payloads:

"ON" or "1" - Turn relay ON
"OFF" or "0" - Turn relay OFF

Characteristics:

QoS: Configurable (default: 1)
Retained: No
Case insensitive

Examples:

CODE

Topic: barix/device1/relay/1/set
Payload: "ON"

Topic: barix/device1/relay/5/set  
Payload: "0"

Relay Status Topic

Topic: barix/{device_id}/relay/{relay_num}/status

Direction: Application → MQTT Broker

Payloads:

"ON" - Relay is energized
"OFF" - Relay is de-energized

Characteristics:

QoS: Configurable (default: 1)
Retained: Yes
Published automatically after relay state changes
Published on application startup for all available relays

Examples:

CODE

Topic: barix/device1/relay/1/status
Payload: "ON"

Topic: barix/device1/relay/3/status
Payload: "OFF"

Digital Input Topics

Input State Topic

Topic: barix/{device_id}/input/{input_num}

Direction: Application → MQTT Broker

Payloads:

"1" - Input is closed/active (high)
"0" - Input is open/inactive (low)

Characteristics:

QoS: Configurable (default: 1)
Retained: No
Published only on state changes (not periodic)
Published on application startup for all available inputs

Examples:

CODE

Topic: barix/device1/input/1
Payload: "1"

Topic: barix/device1/input/8
Payload: "0"

Topic Wildcards for Monitoring

Monitor All Device Topics

CODE

barix/device1/#

Monitor All Relay Status

CODE

barix/device1/relay/+/status

Monitor All Input Changes

CODE

barix/device1/input/+

Monitor Specific Relay

CODE

barix/device1/relay/1/status

Hardware Support

Hardware Detection

The application automatically detects available hardware on startup by checking for the existence of GPIO device files:

Relays: /dev/gpio/rel{1-20}/value
Inputs: /dev/gpio/in{1-20}/value

Hardware Configurations

Base Barionet Unit

Relays: 1-4
Inputs: 1-4
Status: Always available

Base + 1x UX8 Extension

Relays: 1-12
Inputs: 1-12
Status: Auto-detected based on highest available I/O number

Base + 2x UX8 Extensions

Relays: 1-20
Inputs: 1-20
Status: Auto-detected based on highest available I/O number

Hardware Status Logging

The application logs hardware detection results:

CODE

INFO - Hardware detection complete: 12 relays, 12 inputs, 1 UX8 extensions

I/O Numbering

Hardware I/O is numbered sequentially:

Base Unit: 1, 2, 3, 4
First UX8: 5, 6, 7, 8, 9, 10, 11, 12
Second UX8: 13, 14, 15, 16, 17, 18, 19, 20

Monitoring and Logging

Log Levels

The application supports five log levels (configured via logging_level):

Level	Description	Use Case
`DEBUG`	Detailed diagnostic information	Development and troubleshooting
`INFO`	General information messages	Normal operation monitoring
`WARNING`	Warning messages for potential issues	Production monitoring
`ERROR`	Error messages for failed operations	Production alerts
`CRITICAL`	Critical errors causing application failure	Emergency alerts

Log Destinations

Syslog Logging

When: Always enabled (unless logging_syslog_enabled: false)
Format: hostname barionet[PID]: LEVEL - message
Facility: LOCAL0 (hardcoded)
Use: Production logging and monitoring

Log Message Types

Startup/Shutdown Messages

CODE

INFO - Loading configuration from config.json
INFO - Starting hardware detection...
INFO - Hardware detection complete: 8 relays, 8 inputs, 1 UX8 extensions
INFO - Starting Barionet MQTT application...
INFO - MQTT connected successfully
INFO - Barionet MQTT application started successfully

Hardware Operation Messages

CODE

INFO - Relay 3 set to ON
INFO - Input 7 state changed to 1
WARNING - Failed to read initial state for input 12: Permission denied

MQTT Communication Messages

CODE

INFO - MQTT connection attempt 1/10
INFO - Subscribed to barix/device1/relay/1/set
DEBUG - Received MQTT message: barix/device1/relay/3/set = ON
DEBUG - Published to barix/device1/relay/3/status: ON

Error Messages

CODE

ERROR - Failed to connect to MQTT broker: [Errno 111] Connection refused
WARNING - MQTT connection lost, attempting to reconnect...
ERROR - Failed to set relay 5 to True: [Errno 2] No such file or directory

Health Check Messages

CODE

INFO - Health check: 8 relays, 8 inputs, MQTT connected: True

Software Disclaimer

IMPORTANT:

This software application ("Software") is provided "AS IS" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the author, developer, or distributor be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Software or the use or other dealings in the Software.

Use at Your Own Risk: The user assumes all responsibility and risk for the use of this Software. The author makes no representations or warranties regarding the accuracy, reliability, completeness, or timeliness of the Software or its suitability for any particular purpose.

No Support Obligation: The provision of this Software does not create any obligation to provide technical support, maintenance, updates, enhancements, or modifications. The Software is provided for educational and reference purposes only.

Third-Party Dependencies: This Software may utilize third-party libraries and components. The user is responsible for ensuring compliance with all applicable licenses and terms of use for such dependencies.

Network and Security: The user is solely responsible for implementing appropriate security measures and network configurations. The author is not responsible for any security vulnerabilities, data breaches, or network disruptions that may result from the use of this Software.

Compliance: Users are responsible for ensuring that their use of this Software complies with all applicable laws, regulations, and organizational policies in their jurisdiction.

Limitation of Liability: Under no circumstances shall the total liability of the author exceed zero dollars ($0.00) for any damages arising out of or related to the use of this Software.

By using this Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this disclaimer.