Viessmann E3 CAN do

e3oncan adapter for ioBroker

Note: Navigation links in this document work best when viewed on GitHub. Relative links to other documents (e.g. data-points.md) also open on GitHub.

Eine deutsche Version dieser Dokumentation ist verfügbar: README.de.md

Table of contents

• Overview
• What's new in v1.2.0
• Quick start
• Configuration guide
  • Step 1 – CAN adapter
  • Alternative: open3e-esp32 gateway
  • Step 2 – Device scan and energy meter detection
  • Step 3 – Data point scan
  • Step 4 – Assignments and schedules
• Bus topology analysis
• e3oncan datapoints tab
• Reading data points
• Writing data points
• Raw interface of the gateway
• Data points and metadata
• Energy meters
  • E380 data and units
  • E3100CB data and units
• FAQ and limitations
• Donate
• Changelog

Overview

Viessmann E3 series devices (One Base ecosystem) exchange a large amount of data over the CAN bus. This adapter taps into that communication and makes the data available inside ioBroker.

Two modes of operation work independently and can be combined:

Which modes are available depends on your device topology. See the device topology discussion for details. For inspiration on what you can do with the adapter, see the use cases discussion.

Important parts of this adapter are based on the open3e project. A Python-based collect-only implementation using MQTT is available at E3onCAN.

What's new in v1.2.0

Only an ESP32 on the CAN bus, everything over TCP/IP

With the open3e-esp32 gateway, the Viessmann CAN bus needs only an ESP32 with a CAN transceiver. The ioBroker host needs no CAN adapter: it communicates with the gateway completely over TCP/IP, through the gateway's REST API (UDS reads and writes) and an MQTT broker (passively received frames). The adapter's functionality stays the same: device and data point scan, Collect, energy meters, schedules and writes. Writes additionally require Raw write to be enabled on the gateway. Local CAN adapters keep working unchanged. Setup is described in Alternative: open3e-esp32 gateway.

Raw interface for external decoders

The gateway exposes raw UDS data and raw CAN frames for software that decodes them on its own. In gateway mode the adapter uses this path; the meaning of the bytes stays with ioBroker's own codec. See Raw interface of the gateway.

Gateway health and self-healing

The connection state follows the gateway's own health. If the gateway becomes unhealthy, the log says whether the broker or the CAN bus is at fault, and the connection is marked as down. When the gateway recovers, the adapter restarts itself to reconnect.

Quick start

Prerequisites

• A USB-to-CAN or CAN adapter connected to the external or internal CAN bus of your Viessmann E3 device.
• A Linux-based host system (only Linux is supported).
• The CAN adapter is up and visible in the system, e.g. as can0 (verify with ifconfig).
• Refer to the open3e project wiki for CAN adapter setup details.

Important: Make sure no other UDSonCAN client (e.g. open3e) is running while setting up this adapter for the first time. Parallel UDS communication will cause errors in both applications.

First-time setup – at a glance

1. Install the adapter and open its configuration dialog.
2. Configure your CAN adapter(s) on the CAN Adapter tab and save.
3. Scan for E3 devices on the List of UDS Devices tab.
4. Scan for data points on the List of Data Points tab (takes up to 5 minutes).
5. Set up read schedules on the Assignments tab and save.

The detailed steps are described in the Configuration guide below.

Configuration guide

Step 1 – CAN adapter

Open the adapter configuration dialog and go to the CAN Adapter tab.

• Enter the name of your CAN interface (default: can0).
• Check Connect to adapter for each interface you want to use.
• Press SAVE. The adapter instance will restart and connect to the CAN bus.

If you have a second CAN bus (e.g. internal bus), configure it as the second adapter here. A second Assignments tab will appear once the second adapter is configured.

Alternative: open3e-esp32 gateway

Instead of a local CAN adapter, a bus can be read through an open3e-esp32 gateway. Set Connection type to open3e-esp32 gateway for that bus and fill in:

• Gateway REST URL, e.g. http://open3e-esp32.local
• Gateway MQTT broker URL, e.g. mqtt://broker.local, and the MQTT base topic. The base topic must match the gateway's own mqtt.baseTopic setting (default open3e).
• MQTT username and password, if the broker needs them.

On every start the adapter tells the gateway which CAN IDs to relay raw. The list is derived from the energy meters and the Collect IDs of your devices, so you don't configure it on the gateway.

The gateway needs open3e-esp32 version 0.2.0 or newer. That version provides the raw API version 1 this adapter expects, and the adapter logs the firmware version it finds at each start.

Rules for gateway mode:

• The gateway's own data point selection (Datenpunkte tab) is independent of ioBroker's. Configure the data points to read and their schedules in ioBroker as usual; open3e-esp32 polls and publishes its own selection to its own decoded MQTT topics at the same time, and the two don't interfere. The one setting the adapter does manage on the gateway is the relayed raw CAN ID list (see above): a change made there by hand in the gateway's web UI stays only until the next adapter restart.
• Writing data points requires Rohes Schreiben on the gateway. In gateway mode every write goes through the gateway's raw write path. Enable Rohes Schreiben freigeben under the gateway's Settings → Bus tab, next to Schreiben freigeben. The adapter never sets this switch itself, because it bypasses the open3e data point checks.
• Only one master may talk on a bus. Don't run another open3e instance, for example on a Raspberry Pi, on the same bus.

Step 2 – Device scan and energy meter detection

Go to the List of UDS Devices tab and press the Scan button.

• The scan takes a few seconds. You can watch progress in the adapter log (open a second browser tab).
• All E3 devices found on the bus will be listed. You can rename devices in the second column — these names are used as identifiers in ioBroker's object tree.
• Press SAVE when done. The instance will restart.

During the device scan, the adapter also reads the device's data format configuration (data point 382), including temperature units (°C or °F) and date/time formats. This is stored and used during subsequent data point scans.

Energy meter detection

While the device scan runs, the adapter passively listens on the CAN bus for broadcasts from E380 and E3100CB energy meters. No additional scan time is needed — detection happens in parallel. The result is stored and shown:

• In the adapter configuration dialog (List of UDS Devices tab) as a text summary.
• In the e3oncan datapoints page as individual cards for each detected meter type (see below).

Step 3 – Data point scan

Go to the List of Data Points tab, press Start scan … and confirm with OK.

Be patient – the scan may take up to 5 minutes. Progress is visible in the adapter log.

What the scan does:

• Discovers all available data points for each device.
• Adds metadata (description, unit, read/write access) to each data point object.
• Sets physical units based on the device format configuration found in step 2.
• Creates the full object tree for each device in ioBroker.
• Detects Collect-capable devices by passively listening for their time broadcasts on the CAN bus (no extra scan time needed — runs in parallel). A pin icon appears in the device card header of the e3oncan datapoints page for each detected device.

This step is not strictly mandatory for read-only use, but it is strongly recommended – and required if you want to write to any data point.

Restart after the scan if you plan to write. A data point newly discovered by this scan is recorded on disk right away, but the running adapter instance keeps using the data point dictionary it loaded at startup until it restarts. Writing to a data point the scan just found will fail with an "Encoding of data failed" error until you restart the adapter once. Data points that were already known before the scan are unaffected.

Save data point values to object tree during scan

By default the scan also writes the current value of each data point into the object tree (json, raw, tree states). You can adjust the behavior using the option Save data point values ​​in the object tree during scan above the scan button. If this option is disabled, the adapter updates values and metadata for already existing data point objects, but does not create new ones – those are created automatically the first time data is received after the scan.

This option is useful if you want to avoid a large number of state writes during the scan (e.g. on systems with many devices). If you previously ran a scan with values stored and now want a clean slate, you can safely delete any device's json, raw, or tree sub-objects from the ioBroker object tree — the adapter will recreate them automatically when it next receives data. Note: Deleting a large number of objects at once causes ioBroker to fire many internal events simultaneously, which can briefly spike RAM usage. Delete in small batches if your system is under memory pressure.

Note on history adapters: Deleting objects does not delete the historical data stored by a history adapter (History, InfluxDB, SQL). The recorded values remain in the adapter's backend and reappear in charts once the state ID is re-created. However, the history subscription configuration (the "enabled" flag on the object) is lost when an object is deleted and must be re-enabled manually on the new object.

Warning: Never delete the info channel (e.g. e3oncan.0.info). It holds scan results, energy meter detection, delays, active flags, bus topology summaries, and the CAN connection state. Deleting it will cause loss of configuration that cannot be automatically recovered.

Bus topology analysis

After the scan completes, the adapter automatically generates a bus topology summary and stores it in two states in the info channel: info.topology (JSON) and info.topologyHtml (HTML). See Bus topology analysis below for details.

After the scan, browse and manage the discovered data points using the e3oncan datapoints page (see below).

Step 4 – Assignments and schedules

The recommended way to configure read schedules and per-device Collect mode is the e3oncan datapoints page (see below).

Energy meters

If the device scan detected E380 or E3100CB energy meters, a card for each detected meter appears in the e3oncan datapoints page. Activate collecting with the Collect toggle on the card. Use the Delay (s) field to set the minimum interval between value updates in ioBroker. The default of 5 seconds is recommended — energy meters transmit more than 20 values per second, and setting this to 0 will put significant load on ioBroker.

Press Save & Close when done. Check the object tree to verify that data is being collected.

Bus topology analysis

After the data point scan, the adapter analyses all bus topology data collected during the scan and stores the result in two states in the info channel:

Displaying the HTML table

The easiest way to display the topology in ioBroker is to use a dashboard tool that can render HTML states:

• jarvis: Add a stateHTML widget → select e3oncan.x.info.topologyHtml.
• vis / vis2: Add a basic – String (unescaped) or HTML widget → select e3oncan.x.info.topologyHtml.

Note: The info.topology and info.topologyHtml states may be too large for the standard ioBroker admin state editor dialog to display. This is a known limitation of the admin UI for large string states. The states are written correctly and can be consumed normally by scripts and widgets.

e3oncan datapoints tab

The e3oncan datapoints page is the primary place for browsing data points and configuring UDSonCAN read schedules and per-device Collect mode. It opens in a new browser tab when you click the Datapoints link button in the adapter's instance row in the ioBroker admin instances view.

Browsing data points

All devices and any detected energy meters are shown as expandable cards, starting collapsed so you get an overview of your whole system at a glance. Click a card header to expand it. The search box filters by name or ID, and matching cards are expanded automatically.

If a data point scan has not been performed yet for a device, a warning banner is shown at the top of the page as a reminder. If a scan has been done but the Collect auto-detection introduced in v1.x has not yet run, an info banner recommends running a new data point scan. This hint can be permanently dismissed per instance with the Don't show again button.

Device cards

Each device card lists its data points with ID, name, codec, and schedule settings. The Collect toggle and min. update time appear in the card header. If Collect traffic from the device was detected during the data point scan, a green pin icon is shown in the card header as a confirmation. If any data points are scheduled, a green N scheduled badge appears — click it to expand the card and show only the scheduled data points. Click the badge again to remove the filter; clicking the card header removes the filter and collapses or fully expands the card, depending on whether the badge had opened it.

Energy meter cards

If energy meters were detected during the device scan (see Step 2), a card for each detected meter appears at the top of the page. Use the Collect toggle to activate data collection, and the Delay (s) field to set the minimum interval between value updates in ioBroker.

Scheduling

For each data point you can:

• Check On start – the data point is read once when the adapter starts.
• Enter an Interval (s) – the data point is read repeatedly at that interval.

Both options can be combined. Use the schedule filter (All / On Start / Interval) to quickly focus on already-scheduled data points.

Topology

The Topology button in the toolbar opens the bus topology diagram in a modal dialog. The diagram is generated automatically after each data point scan (see Bus topology analysis). The button is disabled until topology data is available.

Saving

Press Save to apply your changes without closing the tab. Save & Close saves and closes the tab, returning you to the instances view. Discard & Close closes the tab without saving — no adapter restart is triggered. An Unsaved changes badge appears whenever there are pending changes.

Note: When saving, the schedules for all devices shown in this tab are rebuilt from the current UI state. Schedules for devices not listed here (e.g. added directly in the adapter configuration dialog) are preserved unchanged. If the same device has schedules in both places, the datapoints tab wins on save. Duplicate entries are removed automatically.

Reading data points

Data points are read automatically according to the schedules you configured. Values appear in ioBroker's object tree under the device name, organised into json, raw and tree sub-objects with human-readable names and metadata.

Reading a specific data point on demand

You can request any data point at any time by editing the state e3oncan.0.<DEVICE>.cmnd.udsReadByDid and entering a list of data point IDs, for example [3350, 3351, 3352]. If the data point is available on the device, the value will appear in the object tree and can be used in read schedules.

The numerical scan range is currently limited (e.g. 256–3338 in version 0.11.0). Use udsReadByDid to probe data points outside this range.

Writing data points

Writing is intentionally simple: change the value of the corresponding state in ioBroker and save it without checking the Acknowledged (ack) checkbox. The adapter detects the unacknowledged write and sends it to the device.

About 2.5 seconds after writing, the adapter reads the data point back from the device and stores the confirmed value. If the state is not acknowledged after this, check the adapter log for error details.

Whitelist of writable data points

Writing is restricted to data points on a whitelist, stored at:

e3oncan.0.<DEVICE>.info.udsDidsWritable

You can extend the list by editing this state. Save it without checking Acknowledged.

Some data points cannot be changed even if whitelisted – the device will return a negative response. The adapter then retries with an alternative service (internal CAN bus only). Always verify write operations by checking whether the value was acknowledged.

Raw interface of the gateway

The open3e-esp32 gateway offers two raw paths for software that decodes CAN data on its own:

• REST: GET /api/rawread returns the unmodified UDS response bytes for up to 10 data point IDs per request. POST /api/rawwrite sends raw value bytes with service 0x2E, and only while Rohes Schreiben freigeben is enabled on the gateway.
• MQTT: CAN IDs listed in the gateway's rawCanIds setting are published unchanged to <base topic>/raw/<id-hex>, as {"dlc": 8, "data": "21fa01b3...", "ts": 1725455669123}.

Neither path uses the open3e codec or the data point database, so nothing is decoded or validated on the gateway. In gateway mode, ioBroker.e3oncan uses this interface, and its own codec decides what the bytes mean. Protocol details and the scan endpoints are in docs/raw-gateway-api.md.

Data points and metadata

For detailed information about how data points are structured, how variant data points and metadata work, and how temperature/date/time formats are handled, please refer to data-points.md.

Energy meters

Energy meters are detected automatically during the device scan. No manual configuration is needed. The adapter assigns a state name in ioBroker's object tree based on where each meter was found:

e380 (without suffix) is used for CAN address 98 on the UDS CAN channel to preserve backward compatibility with existing installations. e3100cb is always used for the E3100CB.

The collect delay (default 5 s) can be adjusted per meter type in the e3oncan datapoints page. Changes take effect after the adapter restarts.

E380 data and units

Up to two E380 energy meters are supported. Data point IDs depend on the device's CAN address:

• CAN address 97: data points with even IDs
• CAN address 98: data points with odd IDs

E3100CB data and units

FAQ and limitations

Why use Collect and UDSonCAN together?

Collect gives you real-time data for everything the devices exchange among themselves – fast-changing values like energy flow, and slowly changing values like temperatures, all updated the moment they change. UDSonCAN lets you access data that is not broadcast spontaneously, typically setpoints and configuration values. Combining both gives you the most complete and up-to-date picture of your system.

Which devices support Collect mode?

At present, the collect protocol is known for:

• Vitocal / HPMUMASTER (Collect ID 0x693, internal CAN bus)
• Vitocharge VX3 and Vitoair / EMCUMASTER (Collect ID 0x451, external and internal CAN bus)

The Collect CAN IDs are assigned automatically based on the UDS device name during the device scan. A device not listed above will not have a Collect ID assigned automatically; it can be entered manually in the adapter configuration.

Can I use open3e at the same time?

Yes, with conditions. If you only use Collect mode in this adapter, open3e can run alongside it without any restrictions. If you use UDSonCAN here, do not run open3e for the same devices simultaneously – this causes sporadic communication errors in both applications.

The adapter stopped working after a Node.js upgrade. What do I do?

From adapter version 1.0.3, the native CAN module (socketcan) uses N-API and no longer requires rebuilding after a Node.js upgrade. If you are running an older version, upgrade the adapter first. If the problem persists after upgrading, please open an issue.

What is different from the open3e project?

• Direct integration into ioBroker: configuration via dialogs, data visible directly in the object tree.
• Real-time Collect mode in addition to UDSonCAN.
• Writing data is simpler: just change a state value and save without acknowledging.
• No MQTT required (though MQTT is of course available via normal ioBroker configuration).
• 64-bit integer encoding for writes is limited to values below 2^52 (4,503,599,627,370,496). Decoding works correctly over the full 64-bit range.

Can I request data points outside the scan range?

Yes. Edit the state e3oncan.0.<DEVICE>.cmnd.udsReadByDid and enter a list of data point IDs, e.g. [3350, 3351, 3352, 3353]. Available data points will appear in the object tree and can be used in read schedules. Unavailable data points produce a "Negative response" message in the log.

Donate

If you enjoyed this project — or just feeling generous, consider buying me a beer. Cheers! :beers:

Changelog

1.2.0 (2026-10-15)

• (MyHomeMyData) Added open3e-esp32 gateway as optional connection type per CAN bus (REST for UDS, MQTT for passively received frames)
• (MyHomeMyData) Gateway: device and data point scan run on the gateway's scan engine, with progress in the log
• (MyHomeMyData) Gateway: energy meters and Collect devices are detected as on a local bus
• (MyHomeMyData) Gateway: relayed CAN IDs are configured automatically on each start
• (MyHomeMyData) Gateway: connection state follows the gateway's health; the adapter restarts itself when the gateway recovers
• (MyHomeMyData) Requires Node.js 22.22.2 or newer, or Node.js 24.15 or newer. The adapter is tested with Node.js 22, 24 and 26
• (MyHomeMyData) Fixed the connection state after a reconnect during the device scan: a local CAN bus that stops afterwards is now reported and sets the connection state to disconnected

1.1.3 (2026-09-11)

• (MyHomeMyData) Fixed CAN connection dropping unexpectedly and never recovering on a healthy bus (updated socketcan to 4.3.1, which stops treating a recoverable socket error the same as a real disconnect). Refer to issue #255.

1.1.2 (2026-07-16)

• (MyHomeMyData) Fixed missing update of meta data (unit, description) when user changes device specific data point definition

1.1.1 (2026-07-06)

• (MyHomeMyData) Update of list of data points for E3 devices to version 20260705 (common)
• (MyHomeMyData) Fixed duplicate display of variant data points in data point list of WebUI

1.1.0 (2026-07-05)

• (MyHomeMyData) Update of list of data points for E3 devices to version 20260701 (common) and 20260630 (variant)
• (MyHomeMyData) Added codec O3ESwitch for device-dependent data point structures selected by a discriminator byte
• (MyHomeMyData) Added optional decimals parameter to numeric codecs to round decoded values
• (MyHomeMyData) Added update of meta data during startup, when structure of data point has changed

Older versions

Older changelog entries are available in CHANGELOG_OLD.md.

License

MIT License

Copyright (c) 2024-2026 MyHomeMyData juergen.bonfert@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.