New: Complex addressing mode available for MQTT commands (listener mode)

Open3E interface

Connects E3 'OneBase' device through CAN UDS or doip
Read data points
Listen to commands on mqtt
Write data points in raw and json data format
Experimental write support for service 77

Smart Home Integrations and Add Ons

The following integrations and add ons are available to use open3e functionality within smart home applications:

HomeAssistant Integration: Automatically connects to the Open3e server and handles automatic device/integration/entity setup based on configuration sent by Open3e. Data is then automatically refreshed. Refer to https://github.com/MojoOli/open3e-ha and https://github.com/open3e/open3e/wiki/090-Homeassistant
HomeAssistant Add-On: If you have your CAN Adapter attached to the device which is running HomeAssistant you can run this Add-on to read the data from CAN. It is working good together with the HomeAssistant Integration mentioned above. Refer to https://github.com/flecke-m/ha-addons/tree/main/open3e Please note the HomeAssistant dependency that the Add-On only works with HAOS and Supervised installations see: https://www.home-assistant.io/installation/
Adapter for ioBroker: Adapter ioBroker.e3oncan is based on open3e and completely replaces open3e. Thus, no installation of open3e is needed when using the adapter. Refer to https://github.com/MyHomeMyData/ioBroker.e3oncan and https://github.com/open3e/open3e/wiki/095-ioBroker-Adapter
Open3E is also available for docker environment. Refer to https://hub.docker.com/u/fleckem
Using Smart Grid Ready Function of Vitocal 250: Refer to https://github.com/open3e/open3e/wiki/099-%C3%9Cber-openE3-hinaus-%E2%80%90-Smart-Grid-Ready

You created your own extension based on open3e? Great! Please let us know! Just add a new discission topic.

Installation

There is a Video Tutorial (German languge) available from CRYDTEAM - thank you very much for it! Find the according web site here. The final 1/3 is related to Home Assistant, but the first part shows the complete installation process of open3e and hardware very vividly.

Hint: An installation guide is available also in German language.

For a fresh Raspberry PI install git, python3 and python-pip first:

sudo apt install git python3 python3-pip

Optional, but highly recommended is creating a virtual environment before the installation. Basic instructions, see here: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments

Now install the latest version of open3e via

pip install git+https://github.com/open3e/open3e.git

or for the develop branch

pip install git+https://github.com/open3e/open3e.git@develop

This will install open3e along with all dependencies.

If you get the error "error: externally-managed-environment" you could add --break-system-packages to the previous command, but better install using a virtual environment - venv (please see: https://stackoverflow.com/questions/75608323/how-do-i-solve-error-externally-managed-environment-every-time-i-use-pip-3)

Update/upgrade to latest Version (later)

Please see Wiki https://github.com/open3e/open3e/wiki/030-Installation-und-Inbetriebnahme-von-open3E#open3e-aktualisieren

Setup CAN Bus

sudo ip link set can0 up type can bitrate 250000

Depict System

In advance of first time starting the client and after every firmware update, run

open3e_depictSystem [-s]

to scan the system and generate devices.json and Open3Edatapoints_678.py files. Use open3e with cmd line argument -cnfg devices.json afterwards. Pls. make sure to use same working directory for open3e as used for running open3e_depictSystem. By using the optional switch -s data files for simulation get created.

To refer to a specific device, you have to use "complex addressing mode", e.g. to read dids 268 and 269 of device 0x680 use -cnfg devices.json -r 0x680.268,0x680.269. Do not use option -dev in this context.

It's possible to change naming of devices by editing devices.json: When you change "0x680": { to "vitocal": { you can use read commands like -r vitocal.268,vitocal.269. New naming will also be used for paramter {device}within MQTT topics (see below).

Further information is available here.

The depicting scans take several minutes (usually 10..20) - please be patient!

Usage

For more detailed description of the command line arguments see also the according section in the Wiki.

usage: open3e [-h] [@argsfile] [-c CAN] [-d DOIP] [-dev DEV] [-a] [-r READ] [-raw] [-w WRITE] [-f77] [-t TIMESTEP] [-m MQTT] [-mfstr MQTTFORMATSTRING] [-muser MQTTUSER:PASSW] [-mcid mqtt-client-id] [-j] [-v] [-l CMND-TOPIC] [-tx ECUADDR] [-cnfg DEVICES.JSON]

options:
-h, --help              show this help message and exit
-c CAN, --can CAN       use can device, e.g. can0. `-c can0` is default, can be omitted.
-d DOIP, --doip DOIP    use doip access, e.g. 192.168.1.1
(*)-dev DEV, --dev DEV     boiler type --dev vdens or --dev vcal || pv/battery --dev vx3, --dev vair(*)
-a, --scanall           dump all dids
-r READ, --read READ    read did, e.g. 257,258
-raw, --raw             return raw data for all dids
-w WRITE, --write WRITE
                        write did, e.g. `-w 396=D601 -raw` 
-f77, --forcesid77      force the use of serive 0x77 for writing of a did
-t TIMESTEP, --timestep TIMESTEP (seconds)
                        read continuous with delay in s
-m MQTT, --mqtt MQTT  publish to server, e.g. 192.168.0.1:1883:TOPICNAME
-mfstr MQTTFORMATSTRING, --mqttformatstring MQTTFORMATSTRING
                        mqtt formatstring e.g. {ecuAddr:03X}_{device}_{didNumber:04d}_{didName}
-muser MQTTUSER:PASSW, --mqttuser MQTTUSER:PASSW
                        mqtt username:password
-mcid MQTT-CLENT-ID, --mqttclientid MQTT-CLENT-ID
                        set mqtt client id of open3e
-tx ECUADDR, --ecuaddr ECUADDR
                        sets the default ECU Address different from 0x680
-cnfg DEVICES.JSON, --config DEVICES.JSON 
                        use multi-ECU configuration file. `-cnfg devices.json` created by Open3E_depictSystem is default, can be omitted.
-j, --json              send JSON structure via MQTT
-v, --verbose           verbose info
-l, --listen            mqtt topic to listen for commands, e.g. `open3e/cmnd`
@argsfile               use arguments given in a file. Seperate line for each argument. No linebreak after final entry.

(*) Attention! The option -dev DEV, --dev DEV is deprecated and may be removed in future versions.

Since V0.4.0 -cnfg devices.json is default and does not need to get specified.

Since V0.5.0 all data point codecs definitions are checked for correct length values. If you get an assert error please check you customer specific data point codec definitions!

IMPORTANT: When addressing sub-items of data points, ALWAYS use ecu.did.sub format (including ecu!) otherwise intended did.sub will get interpreted as ecu.did and cause unintended access or failure!

For details regarding the different ways of addressing data points (complex, named) refer to the Wiki

Remark: Do not start more than one instance of open3e! Doing so, could lead to conflicts on CAN bus causing open3e to stop with errors. If you want to read several lists of data points with diffetent time schedules or you want to read and write data points in parallel, pls. use listener mode of open3e (see below). It's possible to add a read command when starting the listener mode.

regarding the following examples: Please be aware of that not all data points exist with every device.

Read DIDs

open3e -c can0 -cnfg devices.json -r 268 -v
268 FlowTempSensor 27.2

open3e -c can0 -cnfg dev -r 318 -v
318 WaterPressureSensor 1.8 

open3e -c can0 -r 377 -v
377 IdentNumber 7XXXXXXXXXXXXX 

open3e -r 1043 -v
1043 FlowMeterSensor 2412.0 

open3e -r 1664 -v
1664 ElectricalEnergyStorageStateOfCharge 44 

open3e @myargs
    with content of file myargs:
    -c
    can0
    -cnfg
    devices.jsom
    -r
    1664
    -v

open3e -r 424 -v
0x680 424 MixerOneCircuitRoomTemperatureSetpoint {"Comfort": 23.0, "Standard": 21.0, "Reduced": 15.0, "Increased": 0.0, "Duration": 0}

open3e -r MixerOneCircuitRoomTemperatureSetpoint
{"Comfort": 23.0, "Standard": 21.0, "Reduced": 15.0, "Increased": 0.0, "Duration": 0}

open3e -r 0x680.MixerOneCircuitRoomTemperatureSetpoint.Comfort
22.0

Interval Readout

open3e -r 1043 -t 1
2412.0
2413.0
2411.0
2412.0
...

Write DID

(more details on Wiki)

Using raw data format

open3e -raw -w 396=D601
-> sets domestic hot water setpoint to 47degC

Using encoder data format

open3e -w 396=47.5

open3e -w TimeSettingSource=NetworkTimeProtocol

open3e -w 0x680.MixerOneCircuitRoomTemperatureSetpoint.Comfort=23

open3e -w 0x680.ExternalDomesticHotWaterTargetOperationMode.Mode=1

Using json data format

Remark on using JSON data format: In open3e the order of the data elements is relevant. E.g. passing `{"Mode": 1, "State": 0}

Open3e

Install / Use

README