## About

This is an addon for [qToggleServer](https://github.com/qtoggle/qtoggleserver).

It pushes events to an MQTT broker.


## Install

If you run [qToggleOS](https://github.com/qtoggle/qtoggleos), this add-on is already installed.

Otherwise, install it using pip:

    pip install qtoggleserver-mqtt


## Driver & Parameters

This is add-on provides an [event handler](https://github.com/qtoggle/qtoggleserver/wiki/Event-Handlers) that will
connect to the MQTT broker and will push desired events in a specified format.

The message payload is constructed from a template, as indicated by
[Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications). By default, no templates
are specified and the payload will be the template context serialized as JSON.

### `driver`: `qtoggleserver.mqtt.MqttEventHandler`

### `server`

 * type: `string`
 * default: required
 * example: `"test.mosquitto.org"`

### `port`

 * type: `integer`
 * default: `1883`

### `tls_enable`

Controls TLS support.

 * type: `boolean`
 * default: `false`

### `tls_verify`

Whether to verify the server-supplied certificate. Disabling this will effectively disable server authentication,
ensuring only data transmission encryption.

 * type: `boolean`
 * default: `true`

### `tls_ca`

Full path to CA file, for self-signed certificates.

 * type: `string`
 * default: `null`

### `tls_cert`

Full path to client certificate file, for client authentication.

 * type: `string`
 * default: `null`

### `tls_key`

Full path to client certificate key file, for client authentication.

 * type: `string`
 * default: `null`

### `username`

Indicates a username to supply for authentication. The value is in fact a template that can be customized following the
rules  described in [Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications). The
available context is limited however to `device_attrs`.
 
 * type: `string`
 * default: `null`

### `password`

Indicates a password to supply for authentication. 

 * type: `string`
 * default: `null`

### `client_id`

Indicates the MQTT client id to use. The value is in fact a template that can be customized following the rules
described in [Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications). The
available context is limited however to `device_attrs`.

 * type: `string`
 * default: `{{device_attrs.name}}`

### `reconnect_interval`

Represents the interval, in seconds, between two (re)connection attempts to the MQTT server.

 * type: `integer`
 * default: `5`

### `topic`

Indicates the MQTT topic to which to publish the message. The value is in fact a template that can be customized
following the rules described in
[Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications). The available context
can be used to construct topics specific to each device, port, event type, etc.

 * type: `string`
 * default: `{{device_attrs.name}}`

### `json_context_fields`

Used only when `template` and `templates` are unset, when the payload consists of a JSON-dumped context. Indicates which
context fields to include in the payload. If `null`, will include all fields.

 * type: `string[]`
 * default: `null`

### `qos`

Sets the QoS MQTT level:

 * `0` - at most once
 * `1` - at least once
 * `2` - exactly once

 * type: `integer`
 * default: `0`

### `client_logging`

Indicates whether the logs generated by the MQTT client will be added to the qToggleServer logging system or not.

 * type: `boolean`
 * default: `false`

### `filter`

See [Event Handlers](https://github.com/qtoggle/qtoggleserver/wiki/Event-Handlers) for details on filtering events.

 * type: `dictionary`
 * default: `null`

### `template`

See [Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications) for details on
specifying templates. Keep in mind that default templates for this driver are `null`.

 * type: `string`
 * default: `null`

### `templates`

See [Template Notifications](https://github.com/qtoggle/qtoggleserver/wiki/Template-Notifications) for details on
specifying templates. Keep in mind that default templates for this driver are `null`.

 * type: `dictionary`
 * default: `null`
