Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mampfes/esphome_obis_d0
esphome external component to support meters with OBIS D0 interface
https://github.com/mampfes/esphome_obis_d0
d0 d0-interface d0-protocol esphome esphome-component hacktoberfest obis smart-meter smartmeter
Last synced: about 2 months ago
JSON representation
esphome external component to support meters with OBIS D0 interface
- Host: GitHub
- URL: https://github.com/mampfes/esphome_obis_d0
- Owner: mampfes
- License: mit
- Created: 2022-08-28T17:40:20.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-10T12:16:06.000Z (10 months ago)
- Last Synced: 2024-11-02T02:50:42.369Z (about 2 months ago)
- Topics: d0, d0-interface, d0-protocol, esphome, esphome-component, hacktoberfest, obis, smart-meter, smartmeter
- Language: C++
- Homepage:
- Size: 606 KB
- Stars: 45
- Watchers: 3
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ESPHome Smart Meter OBIS D0 Component
This repository adds support for smart meters with OBIS D0 interface to [ESPHome](https://esphome.io).
## Configuration
This component can be easily added as an [external component](https://esphome.io/components/external_components.html) to ESPHome.
Communication with the smart meter is done using UART, so you need to configure the [UART bus](https://esphome.io/components/uart.html#uart).
```yaml
external_components:
- source: github://mampfes/esphome_obis_d0
uart:
id: my_uart
rx_pin: GPIO16
baud_rate: 9600
data_bits: 7
parity: EVEN
stop_bits: 1
obis_d0:
id: my_sm
uart_id: my_uart
on_telegram:
then:
- logger.log: "telegram received"
sensor:
- platform: obis_d0
name: "Consumed Energy"
obis_d0_id: my_sm
obis_code: "1-0:1.8.0*255"
unit_of_measurement: kWh
accuracy_decimals: 4
state_class: total_increasing
device_class: energy
value_regex: "\\d{6}\\.\\d{8}\\*kWh"
text_sensor:
- platform: obis_d0
name: "Device Identification"
obis_d0_id: my_sm
obis_code: "1-0:96.1.0*255"
entity_category: diagnostic
value_regex: "\\w{14}"
- platform: obis_d0
name: "Manufacturer ID"
obis_d0_id: my_sm
obis_code: "id"
entity_category: diagnostic
value_regex: "\\w+"
```
## Configuration Variables
### OBIS D0 platform
- **id** (Optional, [ID](https://esphome.io/guides/configuration-types.html#config-id)): Manually specify the ID used for code generation.
- **uart_id** (Optional, [ID](https://esphome.io/guides/configuration-types.html#config-id)): ID of the [UART Component](https://esphome.io/components/uart.html#uart) if you want to use multiple UART buses.
### Sensor
- **obis_code** (Required, string): Specify the OBIS code you want to retrieve data for from the device.
- **obis_d0_id** (Optional, [ID](https://esphome.io/guides/configuration-types.html#config-id)): ID of the *OBIS D0* Component if you want to manage multiple smart meters.
- **value_regex** (Optional, string): Regular expression to check the validity of the OBIS value. If received value does't match the regular expression, it will be discarded.
- **format** (Optional, string): Format of the OBIS value. Possible choices: `float`, `hex`. Defaults to `float`.
- **timeout** (Optional, [Time](https://esphome.io/guides/configuration-types.html#config-time)): Timeout after which value will be invalidated. Defaults to `5s`.
- All other options form [Sensor](https://esphome.io/components/sensor/index.html#config-sensor).
### Text Sensor
- **obis_code** (Required, string): Specify the OBIS code you want to retrieve data for from the device.
- All other options from [Text Sensor](https://esphome.io/components/text_sensor/index.html#config-text-sensor).
**NOTE**: There is one special OBIS code for text sensors:
`id` returns the manufacturer identification at the beginning of an OBIS telegram (see example above).
### Automations
- **on_telegram** (Optional, [Automation](https://esphome.io/guides/automations.html#automation)): An automation to perform after a complete telegram (consisting of manufacturer identification and OBIS records) has been received.
---
## Hardware
A infrared reader is required to attach to the smart meter.
I am using the "IR-Lese-Schreibkopf" from Hicham Belmadani:
This device is sold on [ebay](https://www.ebay.de/itm/314015465828).
**NOTE:** I'm not responsible or anyhow associated with this offering!
---
## Supported Smart Meters
This section lists supported smart meters:
| Device | Status |
|-|-|
| [eBZ DD3 Drehstromzähler](doc/ebz_dd3.md) | Supported |
| [ISKRA MT174](doc/iskra_mt174.md) | Supported |
| [Logarex LK11 / LK13](doc/logarex.md) | Supported |
| [EasyMeter Q3D](doc/easymeter_q3.md) | Supported |
| [ACE 3000 Type 260](doc/ace_3000_type_260.md) | Supported |
## Important Notes
### Error Detection
The OBIS D0 data format is a textual format based on ASCII characters without error detection and correction mechanisms except the parity bit. Parity errors are detected by the underlying UART layer, but in case of an error the characters are simply omitted - without further notifications to the application. This leads to corrupt readings being read which completely messes the statistics in Home Assistant. Therefore you can specify the expected format for each using regular expressions. If the received data doesn't match the regular expression (e.g. in case of parity error), the data will be discarded.
If anyone knows how to get a notification from the UART layer in case of an error - please let me know!
### ESP-01
The default implementation uses to much flash space (>512k) to be used on an ESP-01. If you want to use an ESP-01, this is possible by using a limited implementation of the regex library. You may activate it by adding `optimize_size: true` to the `obis_d0` component.
```yaml
obis_d0:
id: my_sm
uart_id: my_uart
optimize_size: true
```
This smaller implementation of regex comes with some caveats. They are described in the following section.
#### RegEx compatibility
The [tiny-regex-c library](https://github.com/kokke/tiny-regex-c/tree/master) is used to reduce the size of the resulting executable. This comes with some caveats regarding the regex capabilities.
The library was somewhat extended and should include most required cases. Also error logs were added if the regex contains unsupported features.
#### Unsupported RegEx Features
- `()` any grouping mechanisms are not supported
- `|` branching is not supported
- Additionally the regex must match the entire value, partial matches are detected as an error. \
as if they are surrounded with `^` and `$`