inetbox.py

This is a software implementation of a Truma iNet box, a device for controlling mobile heater and AC units by Truma and Alde.

This software is not provided, endorsed, supported, or sponsored by Truma or Alde. It may or may not be working with their products. Please read the license file, in particular:

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM.

That said, it is working for me, and I hope it will work for you, too.

inetbox.org in Homeassistant

Hardware Requirements

This has been tested with a Truma Combi 4 and the CP Plus control panel (inet ready). I don't see why this wouldn't be working with the Combi 6 and E models as well.

Important: Your CP Plus needs to be "inet ready".

The software runs on a Raspberry Pi, any newer model should do. This could also be ported to a Pi Pico Microcontroller, but I haven't done that yet.

You need a LIN to UART Transceiver (Affiliate Link!) for connecting the Raspberry Pi to the LIN bus. On the transceiver module, the connections are as follows:

• 12V connects to a 12V power supply that also powers the Combi and CP Plus.
• TX connects to GPIO 15 on the Raspberry Pi (RX).
• RX connects to GPIO 14 on the Raspberry Pi (TX).
• LIN connects to the RJ12 connector (see below), Pin 3.
• GND connects to the RJ12 connector (see below), Pin 5.
• The second GND should connect to one of the GND pins on the Raspberry Pi.
• The other pins (INH and SLP) are not used.

The RJ12 connector (alias 6P6C, the one with 6 pins) goes to any port on the Truma Combi heating, or using a splitter module (Affiliate Link!) into the existing connection between Combi and the control panel. Use standard RJ12 cables for the connection. The relevant pins are highlighted in this picture:

Installation

You first need to enable UART on the Pi. For this, follow the steps listed under "Configure UART on Raspberry Pi" on this website until the step to reboot the Pi.

You should also enable access to the serial port for the pi user:

sudo adduser pi dialout

Then log out and log in again or reboot to activate the permission.

Then install the software:

• If pip3 is not installed, run sudo apt install python3-pip first.
• Then run pip3 install inetbox_py[truma_service] if you want to install everything.
• Alternatively, run pip3 install inetbox_py to just install the library in case you want to develop your own code using it.

There is also a systemd service to run the script at every startup. The details are explained below.

Adding /home/pi/.local/bin to your PATH

At the end of the above-described installation, you might get the following warning:

  Installing collected packages: PyYAML, paho-mqtt, pyserial, miqro, bitstruct, inetbox-py
  WARNING: The scripts pyserial-miniterm and pyserial-ports are installed in '/home/pi/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
  WARNING: The script truma_service is installed in '/home/pi/.local/bin' which is not on PATH.
  Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.

Then add /home/pi/.local/bin to your PATH (e.g., at the end of ~/.bashrc) using the following commands. The first one adds export PATH="$HOME/.local/bin:$PATH" to the logged in user's .bashrc, and the second command reloads the .bashrc settings without the need to relogin:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
. ~/.bashrc

Using the MQTT Service

In the following, the MQTT service will be explained. You need an MQTT broker running (e.g. Mosquitto) for this to work and you should be familiar with basic MQTT concepts.

Configuration

Define the MQTT broker by creating the file /etc/miqro.yml with the broker settings as follows (adapt as needed):

broker:
  host: localhost
  port: 1883
  keepalive: 60
  
log_level: INFO

services: {}

If you need to configure MQTT authentication and/or TLS settings, follow these instructions.

By default, the application uses the serial port /dev/serial0. This should work fine on all Raspberry Pi versions, but in case you want to use a different port, you need to configure it in /etc/miqro.yml by adding a services section for the truma service like this (replacing the empty services: {} section above):

services:
  truma:
    serial_device: /dev/ttyS0

To run the service:

truma_service

Initializing

This script plays the role of the inet box. You might need to initialize CP Plus again to make the fake inet box known to the system. This is an easy step that can safely be repeated (no settings are lost): After starting the software, go to the settings menu on the CP Plus and select "PR SET". The display will show "Init..." and after a few seconds, the initialization will be completed.

Does it work?

If the connection works, it can take up to a minute to receive the first status data. Everything is fine if you see the last line shown in the following in the service output:

2022-10-02 14:20:38,787  truma.main  WARNING    Service configuration for truma not found in 'services' section of configuration file /etc/miqro.yml. Using empty configuration.
2022-10-02 14:20:38,788  truma.main  INFO       started
2022-10-02 14:20:38,790  truma.main  INFO       Using serial device /dev/serial0
2022-10-02 14:20:38,792  truma.main  INFO       Loop stats:
2022-10-02 14:20:38,793  truma.main  INFO        - Loop(_update_online_status) called 0 times, average duration 0.0s, load=0%
2022-10-02 14:20:38,794  truma.main  INFO        - Loop(send_status) called 0 times, average duration 0.0s, load=0%
2022-10-02 14:20:38,806  truma.main  INFO       MQTT connected, client=<paho.mqtt.client.Client object at 0xb5ee3090>, userdata=None, rc=0
2022-10-02 14:20:38,806  truma.main  INFO       Subscribing to ...
2022-10-02 14:20:38,807  truma.main  INFO         - service/truma/set/#
2022-10-02 14:20:38,807  truma.main  INFO         - service/truma/enabled
2022-10-02 14:21:27,234  inet-lin  INFO         Received status data from cp plus

Debugging

If you want to enable debugging, you can set the environment variables DEBUG_LIN=1, DEBUG_PROTOCOL=1, and DEBUG_APP=1, to debug the LIN bus (byte level communication), the protocol layer (handing LIN bus specifics), and the application layer (handling the actual data), respectively.

Example:

DEBUG_LIN=1 truma_service

Specify LOG_DIR to additionally write all logs to a file in the specified directory. Make sure that the directory exists and that the user running the service has write access to it.

Important: Enabling all log options will result in a lot of output. Make sure to disable them again after debugging.

You can also specify debug settings in the miqro.yml file:

services:
  truma:
    log_dir: /var/log/truma
    debug_app: True
    debug_lin: True
    debug_protocol: True

MQTT Topics

When started, the service will connect to the LIN bus and publish any status updates acquired from there. When you send a command to modify a setting (e.g., to turn on the heating), the service will send the command to the LIN bus and publish the new status once the setting has been confirmed.

Note: Since Dec. 2025, Homeassistant entities are created as well.

MQTT topics for receiving status

service/truma/error - some error messages are published here

service/truma/update_status - status of sending updates to the heater. The status can only be updated when initiated by the heater, which may take a couple of seconds.

service/truma/cp_plus_status - status of the connection to the CP Plus.

service/truma/display_status/# - frequent updates from CP Plus, similar to what is shown on the display. Note that not all values have been decoded yet.

service/truma/control_status/# - less frequent updates, but includes values that can be modified. These are the values that would otherwise be available in the Truma inet app.

Note: Some values in control_status and the values of update_status and cp_plus_status can be translated to improve the user interface. This is especially useful when using this application with Homeassistant. To enable this, set language to one of the supported languages (see inetbox/truma_service.py); defaults to none. This does not affect values in display_status. While the default values are in English, setting the language to en can stil improve the user interface.

Changing settings

In general, before changing any settings, restart the service (sudo systemctl restart miqro_truma) and wait a minute or so until the first set of values has been published. Then publish a message to service/truma/set/<setting> (where <setting> is one of the settings published in service/truma/control_status/#) with the value you want to set.

For example:

mosquitto_pub -t 'service/truma/set/target_temp_water' -m '40'

or

mosquitto_pub -t 'service/truma/set/target_temp_room' -m '10'; mosquitto_pub -t 'service/truma/set/heating_mode' -m 'eco'

There are some spec