TSH202B MQTT App

Application Version: 3.1.0
Compatible Firmware: Flexa Firmware min. v2.3.0
Device Compatibility: Barionet M44

Overview

The TSH202B MQTT Application provides industrial-grade temperature and humidity monitoring for Barionet M44 devices. It reads data from a Teracom TSH202B v3 sensor over the 1-Wire bus and publishes the values via MQTT. The application includes a built-in live status web page, automatic sensor discovery, and robust error handling.

Compatible Hardware

Primary Platform: Barionet M44 running Flexa Firmware v2.3.0 or later.

Sensor: Teracom TSH202B v3 (also compatible with TSH206v3 — same scratchpad format, sub-family code 0xFF).

Hardware Connection

The Barionet M44 does not provide a 3.3 V output. Power the sensor from the 5 VDC (VBUS) of the USB connector. The TSH202B accepts a supply of +4.0 to +5.5 V, so 5V is within specification.

Connect it to the Barionet M44 as follows.

Wiring Notes

• Keep cable length under 10 m for reliable operation without a line driver.

• After wiring, verify the sensor appears in sysfs: ls /sys/bus/w1/devices/ should show an entry starting with 01-.

• If nothing appears, check that the w1_gpio kernel module is loaded: lsmod | grep w1

Installation Process

Installing the TSH202B MQTT 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.

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 TSH202B MQTT application appears with a status of "running"

Barionet M44 Home Tab

Configuration Overview

Once successfully installed, the TSH202B MQTT application configuration interface becomes available through the TSH202B MQTT tab in your device's web interface. This dedicated configuration page provides access to all settings necessary to establish communication between devices and configure input-to-relay mappings.

The configuration system is designed to be intuitive while providing the flexibility needed for complex installations. Each setting includes helpful descriptions and validation.

TSH202B MQTT Configuration Tab

MQTT Broker

Required Parameters

Optional Parameters

Last Will and Testament Parameters

TSH202B Sensor

Status Web Page

Hardware

Logging

Application

Status Web Page

The application includes a built-in HTTP server that serves a live auto-refreshing status page. It is available as soon as the application starts — even before the sensor is wired up, making it useful for diagnostics.

Access

http://<device-ip>:8090/

The page auto-refreshes every 10 seconds and displays:

• Current temperature (°C)

• Current relative humidity (%RH)

• Last update timestamp and age

• Sensor 1-Wire ROM ID

• MQTT connection status

• Last sensor error (if any)

JSON API

A machine-readable JSON endpoint is also available:

http://<device-ip>:8090/status.json

Example response:

{"temperature": 23.4375, "humidity": 60.0625, "rom_id": "01-000123456789",

"last_update": 1749730000, "error": null, "mqtt_connected": true}

MQTT Topics

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

Topic Structure

All sensor topics follow the pattern:

barix/{device_id}/sensor/{measurement}

Where:

• {device_id}: Value from the mqtt_device_id configuration parameter

• {measurement}: temperature, humidity, or json

Device Status Topic

Online / Offline

Topic: barix/{device_id}/status

Direction: Application → MQTT Broker

Sensor Topics

Temperature

Topic: barix/{device_id}/sensor/temperature

Payload: numeric string in °C to 4 decimal places, e.g. 23.4375

Humidity

Topic: barix/{device_id}/sensor/humidity

Payload: numeric string in %RH to 4 decimal places, e.g. 60.0625

JSON Combined

Topic: barix/{device_id}/sensor/json

A single retained message combining both readings plus metadata:

{"temperature": 23.4375, "humidity": 60.0625,

"unit_temp": "C", "unit_hum": "percent",

"timestamp": 1749730000, "device": "device1",

"sensor": "TSH202B", "rom_id": "01-000123456789"}

Topic Wildcards for Monitoring

1-Wire Protocol Details

The TSH202B v3 follows the Teracom 1-Wire protocol specification (R1.12). On Linux the sensor is accessed via the w1 sysfs interface at /sys/bus/w1/devices/<rom_id>/rw.

Scratchpad Memory Layout

Read Sequence

1. Skip ROM [CCh] + Convert [44h] — trigger measurement

2. Wait 800 ms for conversion to complete

3. Skip ROM [CCh] + Read Scratchpad [BEh] — read 9 bytes

4. Verify CRC-8 of bytes 0–7 against byte 8

5. Decode temperature (signed int16) and humidity (unsigned int16)

6. Multiply both by 0.0625 to obtain final values

Decoding Example

From Teracom specification R1.12, Appendix A:

Sub-family code: 0xFF (verified at startup via Read Functional Register [93h]).

Monitoring and Logging

Log Levels

Log Message Examples

Startup

INFO - Using config.json

INFO - USB subsystem enabled (wrote 1 to /sys/kernel/bm44/usb_enable)

INFO - TSH202B ready: ROM ID=01-000123456789 path=/sys/bus/w1/devices/01-000123456789

INFO - Status web page available at http://<device-ip>:8090/

INFO - MQTT connected

INFO - TSH202B MQTT application running

Normal Operation

INFO - TSH202B [01-000123456789]: temperature=23.4375°C humidity=60.0625%RH

DEBUG - Published barix/device1/sensor/temperature = 23.4375

INFO - Health check: MQTT connected=True sensor ROM=01-000123456789

Sensor Recovery

WARNING - Sensor CRC error (1): Scratchpad CRC mismatch: calculated=0x3A, received=0x9E

WARNING - 5 consecutive sensor errors — re-scanning 1-Wire bus

INFO - TSH202B detected: ROM ID=01-000123456789 path=/sys/bus/w1/devices/01-000123456789

No Sensor Connected

WARNING - TSH202B sensor not found on 1-Wire bus at startup. Check wiring

and that the w1 kernel module is loaded. Will keep retrying in the background.

WARNING - No TSH202B sensor detected on 1-Wire bus — retrying in 30s

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.