# Flux MQTT

An interface to connect to MQTT broker, sending and handling messages.

It uses `Tortoise`, check their documentation to understand how this library
perform the configuration, handling, and delivery of MQTT messages.

`FluxMQTT` describes how to define a connection specification and how to send a message.

`FluxMQTT.Handler` describes how to handle MQTT messages defined in a connection.

## Application Configuration

```elixir
import Config

# Default values
config :flux_mqtt,
  broker: [
    host: "emq",
    port: 1883
  ],
  client: [
    name: "client",
    auth: [
      authenticate?: true,
      username: "client",
      password: "password"
    ],
    correlation: [
      create_correlation_id?: true,
      base: 36,
      length: 8,
      as: :sufix,
      separator: "_"
    ]
  ],
  initial_state: [],
  topics: []
```

### Configuration Options

- `broker` - Set the MQTT broker. Options are:

  - `host` - The MQTT broker hostname. Defaults to `emq`.

  - `port` - The MQTT broker port. Defaults to `1883`.

- `client` - Set the service settings as a broker client. Options are:

  - `name` - The name of the client. Defaults to `client`. It is suggested to
  set the name as the name of the service.

  - `auth` - Set broker authentication settings. Options are:

    - `authenticate?` - If `true`, define the connection specification with
    `username` and `password` (see below). Defaults to `true`.

    - `username` - The username to be used as service authentication.
    Defaults to `client`.

    - `password` - The username's password. Defaults to `password`.

  - `correlation` - Set the client correlation settings. Options are:

    - `create_correlation_id?` - If `true`, the service `client_id` will be
    defined with `client.name` and a correlation string. Defaults to `true`.

    - `base` - The base to be used when generating a correlation id. Must have a
    value in the range `2..36`. Defaults to `36`.

    - `length` - How many characters will be defined for the correlation id.
    Defaults to `8`.

    - `as` - `:sufix` sets the correlation id before the client name. `:prefix`
    sets the correlation id after the client name. Defaults to `:sufix`.

    - `separator` - The separator between the correlation id and the client name.
    Defaults to `_`.

- `initial_state` - A keyword list with data to be set as the handler initial
state. Defaults to an empty list.

- `topics` - A list of `{topic, qos}` elements from which the handler will
receive messages. Defaults to an empty list.