Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
O

open3e

> 编程语言
Open source

connects E3 (Vitocal, Vitodens, VX3/Vitocharge etc) controller through CAN or DoIP via local access

200 stars0 likes0 views
WebsiteGitHub

About

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.

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.

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:

bash
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

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

or for the develop branch

bash
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

bash
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_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.

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} 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 0x6a1

Using complex addressing

open3e -w 0x6a1.BackupBoxConfiguration.DischargeLimit=20.0
-> sets BackupBoxConfiguration.DischargeLimit to 20% on VX3 on ECU-address 0x6a1

Extended writing service (internal can bus only, experimental)

In 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!

Publish data points to mqtt

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 iden

Issues· 13 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Pythoncandoipgebaeude-automatisierunghome-assistant

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言