What is brultech-serial2mqtt?

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.

Table of Contents

• Getting Started
  • Minimum Configuration
  • Docker Compose
• Supported Architectures
• Configuration Options
  • Device
  • Channels
  • MQTT
  • Logging
• Debugging
• Contributing

Getting Started

Minimum Configuration

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"

Docker Compose

---
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"

Supported Architectures

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.

Configuration Options

The configuration file supports !secret strings, as documented for Home Assistant.

Device

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.

Channels

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

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.

MQTT

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.

Birth Message

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.

Home Assistant

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.

Home Assistant Birth Message

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.

TLS Options

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.

Will Message

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.

Logging

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.

Debugging

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"

Contributing

Setup

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

Testing

Tests are run with pytest.

Docker Builds

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.