Skip to content

Latest commit

 

History

History
1022 lines (777 loc) · 18.6 KB

config-doc.md

File metadata and controls

1022 lines (777 loc) · 18.6 KB
Raw

MQTT IO Configuration

The software is configured using a single YAML config file. This document details the config options for each section and provides examples for each section.

mqtt

Type: dict
Required: yes

Contains the configuration data used for connecting to an MQTT server.

Example:

mqtt:
  host: test.mosquitto.org
  port: 8883
  topic_prefix: mqtt_io
  discovery: yes
  tls:
    enabled: yes
    ca_certs: mosquitto.org.crt
    certfile: client.crt
    keyfile: client.key

  • mqtt.host

Type: string
Required: yes

Host name or IP address of the MQTT server.

  • mqtt.port

Type: integer
Required: no
Default: 1883
Minimum value: 1
Minimum value: 65535

Port number to connect to on the MQTT server.

  • mqtt.user

Type: string
Required: no

Username to authenticate with on the MQTT server.

  • mqtt.password

Type: string
Required: no

Password to authenticate with on the MQTT server.

  • mqtt.client_id

Type: string
Required: no

MQTT client ID to use on the MQTT server.

  • mqtt.topic_prefix

Type: string
Required: no

Prefix to use for all topics.

For example, a topic_prefix of home/livingroom would make a digital input called "doorbell" publish its changes to the home/livingroom/input/doorbell topic.

  • mqtt.clean_session

Type: boolean
Required: no

Whether or not to start a clean MQTT session on every MQTT connection.

  • mqtt.protocol

Type: string
Required: no
Default: 3.1.1
Allowed:
- '3.1'
- 3.1.1

Version of the MQTT protocol to use.

This renders in the documentation as a float, but should always be set within quotes.

  • mqtt.keepalive

Type: integer
Required: no
Default: 10
Unit: seconds
Minimum value: 1

How frequently in seconds to send ping packets to the MQTT server.

  • mqtt.status_topic

Type: string
Required: no
Default: status

Topic on which to send messages about the running status of this software.

Sends the payloads configured in status_payload_running, status_payload_stopped and status_payload_dead.

  • mqtt.status_payload_running

Type: string
Required: no
Default: running

Payload to send on the status topic when the software is running.

  • mqtt.status_payload_stopped

Type: string
Required: no
Default: stopped

Payload to send on the status topic when the software has exited cleanly.

  • mqtt.status_payload_dead

Type: string
Required: no
Default: dead

Payload to send on the status topic when the software has exited unexpectedly.

Uses MQTT Last Will and Testament to make the server automatically send this payload if our connection fails.

  • mqtt.discovery

Type: boolean
Required: no

Enable Home Assistant MQTT discovery of our configured devices.

  • mqtt.discovery_prefix

Type: string
Required: no
Default: homeassistant

Prefix for the Home Assistant MQTT discovery topic.

  • mqtt.discovery_name

Type: string
Required: no
Default: MQTT IO

Name to identify this "device" in Home Assistant.

  • mqtt.client_module

Type: string
Required: no
Default: mqtt_io.mqtt.asyncio_mqtt

MQTT Client implementation module path.

There's currently only one implementation, which uses the asyncio-mqtt client.

mqtt.tls

Type: dict
Required: no

TLS/SSL settings for connecting to the MQTT server over an encrypted connection.

Example:

mqtt:
  host: localhost
  tls:
    enabled: yes
    ca_certs: mosquitto.org.crt
    certfile: client.crt
    keyfile: client.key

    • mqtt.tls.enabled

Type: boolean
Required: yes

Enable a secure connection to the MQTT server.

Most of these options map directly to the tls_set() arguments on the Paho MQTT client.

    • mqtt.tls.ca_certs

Type: string
Required: no

Path to the Certificate Authority certificate files that are to be treated as trusted by this client. More info

    • mqtt.tls.certfile

Type: string
Required: no

Path to the PEM encoded client certificate. More info

    • mqtt.tls.keyfile

Type: string
Required: no

Path to the PEM encoded client private key. More info

    • mqtt.tls.cert_reqs

Type: string
Required: no
Default: CERT_REQUIRED
Allowed:
- CERT_NONE
- CERT_OPTIONAL
- CERT_REQUIRED

Defines the certificate requirements that the client imposes on the MQTT server. More info

By default this is CERT_REQUIRED, which means that the broker must provide a certificate.

    • mqtt.tls.tls_version

Type: string
Required: no

Specifies the version of the SSL/TLS protocol to be used. More info

By default the highest TLS version is detected.

    • mqtt.tls.ciphers

Type: string
Required: no

Which encryption ciphers are allowable for this connection. More info

    • mqtt.tls.insecure

Type: boolean
Required: no

Configure verification of the server hostname in the server certificate. More info

If set to true, it is impossible to guarantee that the host you are connecting to is not impersonating your server. This can be useful in initial server testing, but makes it possible for a malicious third party to impersonate your server through DNS spoofing, for example. Do not use this function in a real system. Setting value to true means there is no point using encryption.

gpio_modules

Type: list
Required: no

List of GPIO modules to configure for use with inputs and/or outputs.

Each of the entries in this list should be a dict using the following variables.

Some modules require extra config entries, specified by the modules themselves. Until the documentation is written for the individual modules, please refer to the CONFIG_SCHEMA value of the module's code in the repository. TODO: Link this to the pending wiki pages on each module's requirements.

Example:

gpio_modules:
  - name: rpi_gpio
    module: raspberrypi
  
  - name: pcf
    module: pcf8574
    i2c_bus_num: 1
    chip_addr: 0x20

  • gpio_modules.*.name

Type: string
Required: yes

Your name for this configuration of the module. Will be referred to by entries in the digital_inputs and/or digital_outputs sections.

  • gpio_modules.*.module

Type: string
Required: yes

Name of the module in the code. This is listed in the README's "Supported Hardware" section in brackets.

  • gpio_modules.*.cleanup

Type: boolean
Required: no
Default: true

Whether to run the module's cleanup() method on exit.

sensor_modules

Type: list
Required: no

List of sensor modules to configure for use with sensor inputs.

Each of the entries in this list should be a dict using the following variables.

Some modules require extra config entries, specified by the modules themselves. Until the documentation is written for the individual modules, please refer to the CONFIG_SCHEMA value of the module's code in the repository. TODO: Link this to the pending wiki pages on each module's requirements.

Example:

sensor_modules:
  - name: dht
    module: dht22
    type: AM2302
    pin: 4
  
  - name: ds
    module: ds18b
    type: DS18S20
    address: 000803702e49

  • sensor_modules.*.name

Type: string
Required: yes

Your name for this configuration of the module. Will be referred to by entries in the sensor_inputs section.

  • sensor_modules.*.module

Type: string
Required: yes

Name of the module in the code. This is listed in the README's "Supported Hardware" section in brackets.

  • sensor_modules.*.cleanup

Type: boolean
Required: no
Default: true

Whether to run the module's cleanup() method on exit.

stream_modules

Type: list
Required: no

List of stream modules to configure.

Each of the entries in this list should be a dict using the following variables.

Some modules require extra config entries, specified by the modules themselves. Until the documentation is written for the individual modules, please refer to the CONFIG_SCHEMA value of the module's code in the repository. TODO: Link this to the pending wiki pages on each module's requirements.

Example:

stream_modules:
  - name: network_switch
    module: serial
    device: /dev/ttyUSB1
    baud: 115200
    interval: 10

  - name: ups
    module: serial
    type: /dev/ttyUSB0
    baud: 9600
    interval: 1

  • stream_modules.*.name

Type: string
Required: yes

Your name for this configuration of the module. Will be used in the topic on which the stream's data is published and the topic on which messages can be sent for writing to the stream.

  • stream_modules.*.module

Type: string
Required: yes

Name of the module in the code. This is listed in the README's "Supported Hardware" section in brackets.

  • stream_modules.*.cleanup

Type: boolean
Required: no
Default: true

Whether to run the module's cleanup() method on exit.

  • stream_modules.*.retain

Type: boolean
Required: no

Whether to set the retain flag on MQTT messages publishing data received from the stream.

  • stream_modules.*.read_interval

Type: float
Required: no
Default: 60
Unit: seconds
Minimum value: 0.01

How long to wait between polling the stream for new data.

  • stream_modules.*.read

Type: boolean
Required: no
Default: true

Whether to poll this stream for incoming data and publish it on an MQTT topic.

  • stream_modules.*.write

Type: boolean
Required: no
Default: true

Whether to subscribe to MQTT messages on a topic and write messages received on it to the stream.

digital_inputs

Type: list
Required: no

  • digital_inputs.*.name

Type: string
Required: yes

  • digital_inputs.*.module

Type: string
Required: yes

  • digital_inputs.*.pin

Type: ['string', 'integer']
Required: yes

  • digital_inputs.*.on_payload

Type: string
Required: no
Default: 'ON'

  • digital_inputs.*.off_payload

Type: string
Required: no
Default: 'OFF'

  • digital_inputs.*.inverted

Type: boolean
Required: no

  • digital_inputs.*.interrupt_payload

Type: string
Required: no
Default: INT

  • digital_inputs.*.pullup

Type: boolean
Required: no

  • digital_inputs.*.pulldown

Type: boolean
Required: no

  • digital_inputs.*.interrupt

Type: string
Required: no
Allowed:
- rising
- falling
- both

  • digital_inputs.*.interrupt_for

Type: list
Required: no

  • digital_inputs.*.bouncetime

Type: integer
Required: no
Default: 100
Minimum value: 1

  • digital_inputs.*.retain

Type: boolean
Required: no

  • digital_inputs.*.poll_interval

Type: float
Required: no
Default: 0.1

  • digital_inputs.*.poll_when_interrupt_for

Type: boolean
Required: no
Default: true

digital_inputs.*.ha_discovery

Type: dict
Required: no

    • digital_inputs.*.ha_discovery.component

Type: string
Required: no
Default: binary_sensor

digital_outputs

Type: list
Required: no

  • digital_outputs.*.name

Type: string
Required: yes

  • digital_outputs.*.module

Type: string
Required: yes

  • digital_outputs.*.pin

Type: ['string', 'integer']
Required: yes

  • digital_outputs.*.on_payload

Type: string
Required: no
Default: 'ON'

  • digital_outputs.*.off_payload

Type: string
Required: no
Default: 'OFF'

  • digital_outputs.*.inverted

Type: boolean
Required: no

  • digital_outputs.*.timed_set_ms

Type: integer
Required: no

  • digital_outputs.*.initial

Type: string
Required: no
Allowed:
- high
- low

  • digital_outputs.*.publish_initial

Type: boolean
Required: no

  • digital_outputs.*.retain

Type: boolean
Required: no

digital_outputs.*.ha_discovery

Type: dict
Required: no

    • digital_outputs.*.ha_discovery.component

Type: string
Required: no
Default: switch

sensor_inputs

Type: list
Required: no

  • sensor_inputs.*.name

Type: string
Required: yes

  • sensor_inputs.*.module

Type: string
Required: yes

  • sensor_inputs.*.retain

Type: boolean
Required: no

  • sensor_inputs.*.interval

Type: integer
Required: no
Default: 60
Minimum value: 1

  • sensor_inputs.*.digits

Type: integer
Required: no
Default: 2

  • sensor_inputs.*.unit_of_measurement

Type: string
Required: no

  • sensor_inputs.*.expire_after

Type: integer
Required: no
Minimum value: 1

sensor_inputs.*.ha_discovery

Type: dict
Required: no

    • sensor_inputs.*.ha_discovery.component

Type: string
Required: no
Default: sensor

logging

Type: dict
Required: no
Default:
formatters:
  default:
    datefmt: '%Y-%m-%d %H:%M:%S'
    format: '%(asctime)s %(name)s [%(levelname)s] %(message)s'
handlers:
  console:
    class: logging.StreamHandler
    formatter: default
    level: INFO
loggers:
  mqtt_io:
    handlers:
    - console
    level: INFO
    propagate: true
version: 1