This image talks to devices from Brultech Research over their serial port, using siobrultech-protocols to decode the data, and then sends the data to an MQTT server.
This image works well with Home Assistant, and will automatically create sesnors if MQTT Discovery is enabled. Additionally, it creates named senors to easily integrate into the native Energy Management.
Below is an example of the the minimum amount of configuration needed. See Configuration Options for more details and additional options.
---
device:
channels:
- number: 1
device_com: "COM1"
name: "House Energy Monitor"
mqtt:
broker: "mqtt.mybroker.com"---
services:
brultech:
container_name: "serial2mqtt"
devices:
- "/dev/serial/by-id/usb-XXXXX:/dev/ttyUSB0"
image: "ghcr.io/sdwilsh/brultech-serial2mqtt:main"
volumes:
- "/etc/localtime:/etc/localtime:ro"
- "<config path>:/config:ro"All published images support multiple architectures. The images are currently published with support for the folowing:
- linux/amd64
- linux/arm/v7
- linux/arm64
The available images are:
| Image | Description |
|---|---|
| ghcr.io/sdwilsh/brultech-serial2mqtt:main | Bleeding edge tracking the main branch. |
The configuration file supports !secret strings, as documented for Home Assistant.
| Name | Type | Supported Options | Description |
|---|---|---|---|
| channels | list | See channels config | Channels to monitor and send to MQTT. |
| device_com | str | Either COM1 or COM2 |
Which COM port on the device this serial connection is attached to. |
| name | str | Any string | The name of the device to be used in Home Assistant Discovery. |
Optional Device Configuration Options
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| baud | int | 115200 | Any int | The baud rate to communicate with the attached device. |
| packet_delay_clear_seconds | int | 3 | 1-12 | The amount of time to wait for the attached device to finish sending a packet before attempting to send a command to it. |
| send_interval_seconds | int | 8 | 5-256 | The frequency in which to have the device send packets. |
| type | str | GEM |
Either ECM or GEM |
What type of device this serial connection is attached to. |
| url | str | /dev/ttyUSB0 | Any pyserial URL | The local connection to the device. |
| Name | Type | Supported Options | Description |
|---|---|---|---|
| number | int | 1-32 | The channel number in the device. |
Optional Channel Configuration Options
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| home_assistant | bool | True if type is normal |
Any bool | If the entity for this channel should be enabled by default in Home Assistant. |
| name | str | Channel {number} |
Any str | The name of the entity in Home Assistant. |
| type | str | normal | See channel types | The type of channel to support net-metering and aggregation. |
| Channel Type | Description |
|---|---|
| normal | Power flows through one direction in this channel. |
| main | Power may flow through in both directions (depending on other channels like solar existing), and represents power coming in and going out from an electricity provider. |
| solar_downstream_main | Power flows in two directions from/to a solar inverter, with a main channel between it and the electricity provider. |
| solar_upstream_main | Power flows in two directions from/to a solar inverter, without a main channel between it and the electricity provider. |
| Name | Type | Supported Options | Description |
|---|---|---|---|
| broker | str | Any str | The MQTT broker to connect to. |
Optional MQTT Configuration Options
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| birth_message | dict | {} |
See birth message | The birth message to send when we connect to the MQTT broker. |
| client_id | Jinja2 template str | brultech-serial2mqtt-{serial} | Any Jinja2 template str | The client ID to use when connecting to the MQTT broker. device_serial is available to use in the template. |
| home_assistant | dict | {} |
See home assistant | Configuration on how Home Assistant communicates with the MQTT broker. |
| password | str | None | Any str | The password to use to connect to the MQTT broker. |
| port | int | 1883 | Any int | The port to connect to the broker on. |
| qos | int | 0 | 0-2 | The qos to use for messages sent to the MQTT broker. |
| tls_options | dict | {} |
See tls options | TLS Options to use when connecting to the MQTT broker. Only used when usetls is True. |
| topic_prefix | Jina2 template str | brultech-serial2mqtt-{serial} | Any Jinja2 template str | The root topic to publish status messages on. device_serial is available to use in the template. |
| username | str | None | Any str | The username to connect to use to connect to the MQTT broker. |
| usetls | bool | False | Any bool | Use TLS when connecting to the MQTT broker. |
| will_message | dict | {} |
See will message | The will message to send when we disconnect from the MQTT broker. |
The birth message is sent under the topic prefix configured in the MQTT config, /status.
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| payload | str | online | Any str | The payload to use when sending the birth message. |
| qos | int | 0 | 0-2 | The qos to use for the birth message. |
| retain | bool | True | Any bool | If the retain flag is set on the birth message. |
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| birth_message | dict | {} |
See birth message | The birth message configuration of Home Assistant. See Home Assistant documentation. |
| discovery_prefix | str | homeassistant | Any str | The topic prefix Home Assistant is configured to listen to for discovery configurations. |
| enable | bool | True | Any bool | If the Home Assistant discovery configuration should be sent or not. |
| skip_packets | int | 37 |
> 0 |
The number of packets received from the device to skip before updating Home Assistant. Default updates Home Assistant about once every five minutes. |
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| payload | str | online | Any str | The payload Home Assistant is configured to use when sending the birth message. |
| qos | int | 0 | 0-2 | The qos Home Assistant is configured to use for the birth message. |
| topic | str | homeassistant/status | Any str | The topic Home Assistant is configured to use when sending the birth message. |
Corresponds directly to asyncio-mqtt's TLSParameters.
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| ca_certs | str | None | Any str | Path to CA certificate files to be trusted by this client. |
| certfile | str | None | Any str | Path to a PEM encoded client certificate file. |
| keyfile | str | None | Any str | Path to a PEM encoded private key file. |
| keyfile_password | str | None | Any str | Password to decrypt either certfile or keyfile (if encrypted). |
| cert_reqs | bool | True | Any bool | Enforce certificate requirements. Set to False to connect to, e.g., self-signed hosts. |
| ciphers | str | None | Any str | Allowable encryption ciphers for this connection (set to None to use the defaults). |
| tls_version | str | tls1.2 | None, tls1, tls1.1, tls1.2 | Version of the SSL/TLS protocol to use. |
The well message is sent under the topic prefix configured in the MQTT config, /status.
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| payload | str | online | Any str | The payload to use when sending the will message. |
| qos | int | 0 | 0-2 | The qos to use for the will message. |
| retain | bool | True | Any bool | If the retain flag is set on the will message. |
Optional Logging Configuration Options
| Name | Type | Default | Supported Options | Description |
|---|---|---|---|---|
| level | str | info | critical, error, warning, info, or debug |
The logging level the application should print messages to stdout with. |
| logs | dict | {} |
Any dict of levels | A dict of Python named-logs and the level in which to log them to stdout. |
If you are having issues connecting to your device, it can be useful to enable logging of the underlying siobrultech-protocols library. Add this to your configuration:
logging:
logs:
siobrultech_protocols: "debug"
python3.11 -m venv .venv
source .venv/bin/activate
# Install Requirements
pip install -r requirements.txt
# Install Dev Requirements
pip install -r requirements-dev.txt
# One-Time Install of Commit Hooks
pre-commit install
Tests are run with pytest.
To build for a single plaform, use the following command:
docker buildx build . -f docker/Dockerfile --platform {platform}See Docker's documentation on working with buildx.