connects E3 (Vitocal, Vitodens, VX3/Vitocharge etc) controller through CAN or DoIP via local access
connects E3 (Vitocal, Vitodens, VX3/Vitocharge etc) controller through CAN or DoIP via local access
New codec O3ESwitch: decodes a device/variant-dependent payload selected by a discriminator byte (e.g. ZigBee device type), with per-case sub-structure and a fallback default case — see discussion #369
New: open3e_topology — reads E3 CAN bus topology from all known devices and produces a text table (stdout), JSON, and a colour-coded HTML report. Requires devices.json as generated by open3e_depictSystem. See Bus Topology Analysis for details.
The following integrations and add ons are available to use open3e functionality within smart home applications:
You created your own extension based on open3e? Great! Please let us know! Just add a new discission topic.
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.
For a detailed step-by-step installation guide (German language) see Wiki, chapt. 030.
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.gitor for the develop branch
pip install git+https://github.com/open3e/open3e.git@developThis 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)
Please see Wiki https://github.com/open3e/open3e/wiki/030-Installation-und-Inbetriebnahme-von-open3E#open3e-aktualisieren
sudo ip link set can0 up type can bitrate 250000In advance of first time starting the client and after every firmware update, run
open3e_depictSystem -sto scan the system and generate devices.json and Open3Edatapoints_6yz.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!
Infos about data points are available here.
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.
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.0open3e -r 1043 -t 1
2412.0
2413.0
2411.0
2412.0
...(more details on Wiki)
open3e -raw -w 396=D601
-> sets domestic hot water setpoint to 47degCopen3e -w 396=47.5
open3e -w TimeSettingSource=NetworkTimeProtocol
open3e -w 0x680.MixerOneCircuitRoomTemperatureSetpoint.Comfort=23
open3e -w 0x680.ExternalDomesticHotWaterTargetOperationMode.Mode=1Remark on using JSON data format: In open3e the order of the data elements is relevant. E.g. passing {"Mode": 1, "State": 0} will work for DID 538, passing {"State": 0, "Mode": 1} will not. We recommend first reading a data point in JSON format and then using the result as a template to create the write access command.
open3e -j -w 396=47.5
-> sets domestic hot water setpoint to 47.5degC
open3e -j -w 538='{"Mode": 1, "State": 0}'
-> sets ExternalDomesticHotWaterTargetOperationMode.Mode to 1 and .State to 0
-> Use -j -r to read data point in json format as template for writing. Always provide valid and complete json data for writing, enclosed in single quotes.
open3e -j -w 0x6a1.2214='{"DischargeLimit": 20.0, "Unknown": 0.0}'
-> sets BackupBoxConfiguration.DischargeLimit to 20% on VX3 on ECU-address 0x6a1open3e -w 0x6a1.BackupBoxConfiguration.DischargeLimit=20.0
-> sets BackupBoxConfiguration.DischargeLimit to 20% on VX3 on ECU-address 0x6a1In case of a "negative response" code when writing data, you may try to use the command line option -f77. However, this is experimental. Always verify the result!
open3e -r 268,269,271,274,318,1043 -m 192.168.0.5:1883:open3e -t 1
-> will periodically scan data points and publish data to broker 192.168.0.5
open3e -r 268,269,271,274,318,1043 -m 192.168.0.5:1883:open3e -t 1 -mfstr "{didNumber}_{didName}"
-> will publish with custom idenNo open issues yet, or sync has not completed.