UDP Legacy API

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

Overview

The UDP Command API provides a network interface for controlling and monitoring IO operations on the Barionet M44 device. This application is specifically designed to offer drop-in replacement compatibility for installations where legacy Barionet 50 or Barionet 100 devices are deployed, providing customers with a seamless upgrade path to the modern Barionet M44 hardware.

Key Features

• Retro-compatible API: Uses the same IO Addressing scheme as legacy Barionet devices

• Extended functionality: Leverages additional capabilities available on the Barionet M44

• UDP-based communication: Simple, lightweight protocol for real-time control

• Flexible notifications: Real-time state change and periodic status updates

• Security features: IP filtering and password authentication

• UX8 extension support: Automatic detection and configuration of UX8 expansion modules

• Broadcast support: Network-wide device discovery capabilities

Compatible Hardware

Primary Platform: The application is designed for Barionet M44 devices running the Flexa Firmware v2.3.1

Extension Support: When (2x) UX8 extension modules are 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 device.

Application API

Communication Protocol

The API uses UDP protocol for all communications. Commands are sent as text strings and responses are returned in a structured format.

Default Port: 12301 (configurable)
Maximum Message Size: 256 bytes
Character Encoding: UTF-8

Command Terminators

The following terminators are accepted for incoming commands:

• \r (carriage return)

• \n (line feed)

• \00 (null terminator)

• Any combination of the above

All responses are terminated with \r.

Command Format

Commands must be sent in lowercase. Invalid case will return cmderr\r or command failed\r

Supported Commands

1. version

Returns device and firmware information.

Request: version
Response: version,Product_Name Image_Name Firmware_Version\r
Example Response: version,Barionet_M44 core-image-barix-flexa 2.3.1\r
Error Response: command failed\r (if system information cannot be retrieved)

2. c=65535

Returns the DHCP hostname configuration. This command supports broadcast responses for device discovery.

Request: c=65535
Response: <BARIONET><NAME>hostname</NAME></BARIONET>\r
Example Response: <BARIONET><NAME>BarionetM44</NAME></BARIONET>\r
No Hostname Configured: <BARIONET><NAME>DHCP HOSTNAME NOT CONFIGURED</NAME></BARIONET>\r (if not configured)
Error Response: command failed\r

Note: This command must be typed exactly as shown (case-sensitive). The DHCP Hostname can be configured in the SETTINGS tab of the web configuration panel of the device.

3. getio,address

Reads the current value of an IO address.

Request: getio,A where A is the address number
Response: state,A,V\r where V is the current value
Example Request: getio,201
Example Response: state,201,1\r
Error Response: cmderr\r (if address is invalid or not readable)

Validation:

• Address must be a valid, readable IO address

• See Appendix for valid address ranges

4. setio,address,value

Writes a value to an IO address.

Request: setio,A,V where A is the address and V is the value
Response: state,A,V\r confirming the written value
Example Request: setio,1,1
Example Response: state,1,1\r
Error Response: cmderr\r (if address is not writable or value is invalid)

Special Functions for 1-bit addresses (relays, outputs, virtual IOs):

1. Toggle Function (value = 999):

   • Toggles the current state (0→1 or 1→0)

   • Example: setio,1,999 toggles relay 1

2. Timed Function (value = 2-998 or 1000-9999):

   • Sets output to 1 and automatically resets to 0 after value/10 seconds

   • Example: setio,2,100 enables relay 2 for 10 seconds

   • Example: setio,3,3000 enables relay 3 for 300 seconds

   • Multiple timers can run simultaneously

   • New timer overwrites existing timer for same address

   • Manual setio,A,0 cancels active timer

Validation:

• Address must be writable

• Value must be within valid range for address bit size:

  • 1-bit: 0-1 (plus special values 2-998, 999, 1000-9999)

  • 4-bit: 0-15

  • 16-bit: 0-65535

  • 32-bit: 0-4294967295

5. iolist

Returns a summary of system IO configuration.

Request: iolist
Response: io,AI,DI,AO,DO,0,R,T\r
Where:

• AI = Number of analog inputs

• DI = Number of digital inputs

• AO = Number of analog outputs

• DO = Number of digital outputs

• 0 = Reserved (always 0) - N° of IR interfaces on legacy devices

• R = Number of relays

• T = Number of temperature sensors detected

Example Response for BM44 with no UX8 connected and 5 temp sensors: io,4,4,0,0,0,4,5\r
Error Response: cmderr\r

Command Concatenation

Multiple commands can be sent in a single message using & as separator.

Format: command1&command2&command3
Response: response1&response2&response3\r

Example:

• Request: setio,1,1&getio,201&version

• Response: state,1,1&state,201,0&version,Barionet_M44 core-image-barix-flexa 2.3.1\r

Password Authentication

When a password is configured, all commands must be prefixed with the authentication string.

Format: a=PASSWORD&command
Example: a=secret123&getio,1
Error Response: operation not allowed\r (if password is incorrect or missing)

Note: For concatenated commands, the password is only required once at the beginning:

• a=PASSWORD&command1&command2&command3

Notifications

The notification service provides two types of status updates sent via UDP to a configured target address.

Configuration Requirements

To enable notifications, set the following parameters in the web configuration (UDP API tab):

• Enable UDP State Info: true

• UDP Target Address: "IP:PORT" (e.g., "192.168.1.100:12302")

Real-time State Change Notifications

Sends immediate notifications when monitored IO addresses change state.

Format: statechange,address,value\r
Example: statechange,201,1\r (input 201 changed to 1)

Monitored Addresses:

• Built-in relays (1-4)

• Built-in digital inputs (201-204)

• UX8 relays (11-42, if detected)

• UX8 inputs (211-242, if detected)

Periodic State Dump

Sends regular status updates at configured intervals.

Configuration: UDP State Info Interval (seconds) - if 0 periodic state is disabled.

Format: Multiple state messages concatenated:

state,1,0\rstate,2,1\rstate,3,0\rstate,4,0\rstate,201,1\rstate,202,0\r...

Included Addresses:

• All relay states (built-in and UX8)

• All digital input states (built-in and UX8)

Installation Process

Installing the 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

1. Open your web browser and navigate to your Barionet device's IP address

2. Enter your administrator username and password when prompted

3. Wait for the main interface to load completely before proceeding

   

Step 2: Upload the Application Package

1. Navigate to the HOME tab in the main menu

2. Locate the "Upload" button next to “Install Package” within the page

3. Click the file selection button and browse to the “package.zip” which was downloaded from this page

4. Choose an appropriate version number for tracking purposes (this can be any number you prefer for identification)

5. 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

1. Wait for the device to complete its reboot cycle

2. Reconnect to the web interface using the same IP address and credentials

3. Navigate back to the HOME tab

4. Verify that the IO Tunnel application appears with a status of "running"

   

Configuration Overview

Once successfully installed, the configuration interface becomes available through the UDP API tab in your device's web interface. This dedicated configuration page provides access to all settings necessary to establish communication between the device and the server.

The configuration system is designed to be intuitive, each setting includes helpful descriptions and validation to prevent configuration errors that could disrupt communication.

Security Features

Allowed IP Addresses (IP Filtering)

Restrict access to the UDP API to specific IP addresses by configuring Allowed IP Addresses.

Format: Comma-separated IP addresses
Example: "192.168.1.100, 192.168.1.101, 10.0.0.50"
Default: Empty string (all IPs allowed)

When an IP is blocked:

• No response is sent to the client

• Attempt is logged (if syslog is enabled)

Password Protection

Enable password authentication by setting the Password parameter.

Configuration: "password": "your_secret_password"
Usage: Prefix all commands with a=password&
Example: a=mysecret&getio,1

Syslog Integration

Enable remote logging by configuring Syslog parameters in the web configuration.

Logged Events:

• Server startup/shutdown

• All incoming UDP messages

• Command processing results

• Authentication failures

• Blocked IP attempts

• IO state changes (if notifications enabled)

• Timer events

• Errors and warnings

Syslog Facility: LOCAL0

Appendix: IO Address Reference

Full description of Barionet M44 IO Addresses that can be controlled by the IoMapping utility:

Built-in IO

UX8 Extension IO

IMPORTANT NOTICE

This implementation supports up to 4 UX8 extension modules, with corresponding addresses reserved in the IO addressing table. However, at the time of this documentation, only configurations with up to 2 UX8 extensions have been fully tested and validated. While the system is designed to handle 4 extensions, configurations using 3 or 4 UX8 modules have not yet undergone comprehensive testing.

Virtual IO

System Information

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.