Metadata-Version: 2.4
Name: moat-kv-ha
Version: 0.5.14
Summary: Home Assistant connector for MoaT-KV
Author-email: Matthias Urlichs <matthias@urlichs.de>
Project-URL: homepage, https://m-o-a-t.org
Project-URL: repository, https://github.com/M-o-a-T/moat
Keywords: MoaT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Home Automation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: moat-kv~=0.71.25
Requires-Dist: moat-lib-config~=0.2.0
Requires-Dist: moat-lib-run~=0.2.0
Requires-Dist: moat-util~=0.64.0
Dynamic: license-file

# MoaT-KV-HA

% start synopsis
% start main

This module is a link between Home Assistant and Moat-KV.

The core of this module is concerned with assembling appropriate
configuration for MQTT.

Message transport and translation is performed by a [MoaT-Link
Gate](moat-link-gate) instance.

% end synopsis

## Features

- set up standard config for Home Assistant in MoaT-KV
- command-line support to register (or not) devices

% end main

## Principle of Operation

Home Assistant talks via MQTT. MoaT-KV has a quite versatile MQTT adapter.
Thus we can store Home Assistant's entitiy configuration, plus their state,
plus the commands Home Assisant issues to get things to change their state,
in MoaT-KV.

MQTT can only transmit binary data. DistHASS thus creates a few codecs that
support binary data (translating them to on/off), integers/floats, and JSON.

Thus, bottom to top:

- Mosquitto on port 51883

  - basic installation, does not need persistence or retained messages

- MoaT-KV, using Mosquitto as a backbone

  - a special user with conversion rules for JSON etc.

- DistMQTT

  - retained messages are stored in MoaT-KV
  - transparent channels to forward MQTT messages unmodified, if required
  - anything else is broadcast as a MoaT-KV message
  - uses port 1883

- Home Assistant, or anything else MQTTish for that matter

  - must use MQTT 3.11

If you have devices that only can use MQTT 3.1, you can teach them to talk
directly to Mosquitto, via a transparent range.

## Setup

- Run `moat kv ha init -i`

- Add a MoaT-KV user for Home Assistant and set its `conv` parameter to `hassco`:

  ```
  moat kv auth user param NAME conv hassco
  ```

- Start Moat-MQTT with something like this configuration:

  ```
  kv:
      server:
          host: '127.0.0.1'
          port: 27586
          auth: "password name=NAME password=PASSWORD"
      topic: [mqtt, msg]
      transparent:
      - [home,ass,event]
      - [home,ass,state]
      retain: [home, ass]
  listeners:
      default:
          max-connections: 500
          type: tcp
      local-tcp:
          bind: 127.0.0.1:1883
      remote-tcp:
          bind: 10.107.3.18:1883
  timeout-disconnect-delay: 2
  plugins: ['auth_anonymous']
  auth:
      allow-anonymous: true
  ```

  If you have devices that use MQTT directly, modify the
  `transparent` list to include your current MQTT prefixes.

- Modify Home Assistant's MQTT integration to do autodiscovery.
  If you've set it up via the GUI, the file you need is
  `.storage/core.config_entries`. Find the entry with `"domain":
  "mqtt"` and modify its `data` entry to read:

  ```
  "data": {
      "broker": "127.0.0.1",
      "discovery": true,
      "discovery_prefix": "home/ass/dyn",
      "port": 1883,
  },
  ```

- Run `moat kv ha conv`.

  This teaches MoaT-KV to auto-convert the Home Assistant data so that
  everything in MoaT-KV sees binary states as booleans, temperatures are
  floats, the configuration's JSON is a real data structure, and so on.

  Without this conversion, it's all strings. We don't want that.

- Restart Home Assistant.

- Run `moat kv ha add light foo bar`.

  A new light should show up in the Home Assistant GUI.

  You can try to turn it on, but it will go off by itself a second or two
  later because there's no device yet.

- Run `moat kv ha state light foo bar True`.

  This command changes the state manually.

  In Home Assistant, the light's indicator turns on.

- Adding an actual device that monitors the light's MoaT-KV command entry / its
  [MoaT-KV-]MQTT command topic, actually affects the hardware, and changes the
  state, is your job.
