Package: inetbox-py
inetbox.pyThis 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 thelicensefile, 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.Hardware RequirementsThis 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 aLIN to UART Transceiver(Affiliate Link!) for connecting the Raspberry Pi to the LIN bus. On the transceiver module, the connections are as follows:12Vconnects to a 12V power supply that also powers the Combi and CP Plus.TXconnects to GPIO 15 on the Raspberry Pi (RX).RXconnects to GPIO 14 on the Raspberry Pi (TX).LINconnects to the RJ12 connector (see below), Pin 3.GNDconnects to the RJ12 connector (see below), Pin 5.The secondGNDshould connect to one of the GND pins on the Raspberry Pi.The other pins (INHandSLP) are not used.The RJ12 connector (alias 6P6C, the one with 6 pins) goes to any port on the Truma Combi heating, or using asplitter 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:InstallationYou first need toenable UARTon the Pi. For this, follow the steps listed under "Configure UART on Raspberry Pi" onthis websiteuntil the step to reboot the Pi.You should also enable access to the serial port for thepiuser:sudoadduserpidialoutThenlog out and log in againorrebootto activate the permission.Then install the software:Ifpip3is not installed, runsudo apt install python3-pipfirst.Then runpip3 install inetbox_py[truma_service]if you want to install everything.Alternatively, runpip3 install inetbox_pyto 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 PATHAt the end of the above-described installation, you might get the following warning: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/binto your PATH (e.g., at the end of~/.bashrc) using the following commands. The first one addsexport PATH="$HOME/.local/bin:$PATH"to the logged in user's.bashrc, and the second command reloads the.bashrcsettings without the need to relogin:echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
. ~/.bashrcUsing the MQTT ServiceIn 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.ConfigurationDefine the MQTT broker by creating the file/etc/miqro.ymlwith the broker settings as follows (adapt as needed):broker:host:localhostport:1883keepalive:60log_level:INFOservices:{}If you need to configure MQTT authentication and/or TLS settings, followtheseinstructions.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.ymlby adding aservicessection for thetrumaservice like this (replacing the emptyservices: {}section above):services:truma:serial_port:/dev/ttyS0To run the service:truma_serviceInitializingThis 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 plusDebuggingIf you want to enable debugging, you can set the environment variablesDEBUG_LIN=1,DEBUG_PROTOCOL=1, andDEBUG_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_serviceSpecifyLOG_DIRto 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 themiqro.ymlfile:services:truma:log_dir:/var/log/trumadebug_app:Truedebug_lin:Truedebug_protocol:TrueMQTT TopicsWhen 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.MQTT topics for receiving statusservice/truma/error- some error messages are published hereservice/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.Changing settingsIn 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 toservice/truma/set/<setting>(where<setting>is one of the settings published inservice/truma/control_status/#)with the value you want to set.For example:mosquitto_pub-t'service/truma/set/target_temp_water'-m'40'ormosquitto_pub-t'service/truma/set/target_temp_room'-m'10';mosquitto_pub-t'service/truma/set/heating_mode'-m'eco'There are some specifics for certain settings:target_temp_roomandheating_modemust both be enabled for the heating to work. It's best to set both together as in the example above.target_temp_roomcan be set to 0 to turn off the heating, and 5-30 degrees otherwise.heating_modecan be set tooff,ecoandhighand defines the fan intensity for room heating.target_temp_watermust be set to one of0(off),40(equivalent to selecting 'eco' on the display),60('high'), or200(boost)energy_mixandel_power_levelshould be set together. You don't need to set these values unless you have a Combi E-version.energy_mixcan be one ofnone/gas/electricity/mixel_power_levelcan be set to0/900/1800when electric heating or mix is enabledNote: Since some settings only work together, liketarget_temp_roomandheating_mode, the service does not apply changes immediately. Instead, changed settings are collected and only applied after a wait time of about a seconds. To change this time, set theupdates_buffer_timesetting in themiqro.ymlfile to the desired wait time in seconds.The topicservice/truma/update_statusgives information about the status of the pushed setting changes:waiting_for_cp_plusmeans that there is no connection yet to CP Plus and settings will only be applied after a connection has been established. In normal circumstances, this can take up to a minute.waiting_commitmeans that the service waits for more changes (see above) before applying them.waiting_trumameans that the service waits for the CP Plus to ask for a settings update before the service can send the changed settings. This should not take more than about 10 seconds.idlemeans that there are no pending setting changes.The topicservice/truma/cp_plus_statusgives information about the connection to CP Plus:onlinemeans that the service is connected to CP Plus and is receiving status updates.waitingmeans that the service is not connected to CP Plus and is not receiving status updates. This can happen after a restart of the service. When you send a settings change command, theupdate_statuswill bewaiting_for_cp_plusuntil the service is connected.Installing the Systemd ServiceAfter you have tested that the software works for you, to install a systemd service using this software, runas root:pip3installinetbox_py[truma_service]truma_service--install
systemctlenablemiqro_truma
systemctlstartmiqro_trumaTake carenot to run the service and the script in parallelas this will lead to errors (MQTT connection failures withrc=7in the log file and errors connecting to the serial interface).UpdatingIf you have installed the service and want to update it, runas root:pip3install--upgradeinetbox_py[truma_service]systemctlrestartmiqro_trumaAdvanced Use: Reading Low-Level LIN Log FilesThe toolbin/read-logfile.pycan be used to read log files created by, for example, a LIN bus logger. The file will be interpreted and the data will be printed to stdout.Usage:python3 bin/read-logfile.py logfile.logThe log file is expected to have the following format:<timestamp> <databyte[0]> <databyte[1]> <databyte[..]> <x> <y>where data bytes are stored in hexadeximal representation and<x>and<y>are ignored. This is an example file:00000,025   61                                                        9634    Checksum 
00000,076   E2                                                        9615    Checksum 
00000,126   3C  01  06  B8  40  03  00  00  FF      FC     classic    9615     
00000,177   7D                                                        9615    Checksum 
00000,228   D8                                                        9615    Checksum 
00000,279   3C  7F  06  B2  00  17  46  00  1F      4B     classic    9615     
00000,329   7D                                                        9615    ChecksumEmpty lines are ignored.If your file looks different, use--firstto define the first data byte position (in the format above, 1), and--lastto define the end of the data bytes (in the format above, -2). The values are interpreted as python slice indices, so you can use negative values to count from the end.InternalsWhat does this software do internally?The software tries to emulate the workings of the Truma iNet box. It plays the role of a 'slave' device on the LIN bus and listens for messages from the CP Plus. Selected messages are answered appropriately as to make the CP Plus think that the iNet box is present and working, and to send commands to the CP Plus.Two specific LIN messages are directly used to communicate with the CP Plus:PID 0x18- the first bit defines whether a command for changing settings is ready at the iNet box. If the first bit is1, the CP Plus will send a message on the transport layer (see below) to request the settings update. SeeInetboxLINProtocol.answer_to_d8_messageininetbox/inetbox.pyfor details.PIDs 0x20-0x22- contain frequent status updates closely resembling what is shown on the CP Plus display. It is unclear to me if the original iNet box observes these messages at all. Settings cannot be changed via these messaged. SeeInetboxApp.parse_*ininetbox/inetbox.pyfor the implementation.The settings transfer from the CP Plus to the iNet box and vice versa (for modifying settings) is done via status buffers exchanged via the LIN transport layer. The relevant parts of the transport layer are implemented in this software. Please see the LIN specification for details on this layer. The low-level communication is based on the messages with PIDs 0x3C and 0x3D.Messages on the transport layer are identified by an 'SID'. The following SIDs are known:SID 0xB9- likely a heartbeat request or similar. The expected answer is just a0x00byte.SID 0xB0- assign NAD (network address) command. Has to be answered, empty payload.SID 0xBA- request for data upload (i.e., from iNet box to CP Plus). The payload is a status buffer (see below).SID 0xBB- data download (i.e., from CP Plus to iNet box). The payload is a status buffer (see below).A number of different status buffer types exist both for reading values from CP Plus as well as for writing values to CP Plus. The buffers can be identified by two bytes that follow a 10-byte preamble that is always the same. For example:ID 0x14, 0x33: Coming from the CP Plus, this buffer contains most settings for heating (like target water temperature, current temperature, etc.).ID 0x0C, 0x32: This status buffer is similar to the above, but is sent from the iNet box to the CP Plus for changing settings.SeeInetboxApp.STATUS_*ininetbox/inetbox.pyfor details on the known buffer types.AcknowledgementsThis project is based on the work of theWomoLIN project, especially the initial protocol decoding and the inet box log files.