more human-readable docs

README.md

@@ -1,47 +1,67 @@
-# Ansible Collection - artyorsh.smarthome
+# Ansible Collection - Smarthome
 
-[![Test (Ubuntu 22.04)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml/badge.svg?event=push)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml)
 [![Ansible Galaxy](https://img.shields.io/badge/collection-artyorsh.smarthome-blue)](https://galaxy.ansible.com/artyorsh/smarthome)
+[![Test (Ubuntu 22.04)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml/badge.svg?event=push)](https://github.com/artyorsh/ansible-collection-smarthome/actions/workflows/test-ubuntu-lts.yml)
 
-## Description
-
-All-in-one installation scripts for a selfhosted [HomeAssistant](https://www.home-assistant.io) instance, with a purpose of making
-Zigbee-based IoT devices accessible through Apple HomeKit.
+Effortlessly connect your IoT infrastructure to Apple Home ✨
 
-## Tech stack
+## Description
 
-- [linuxserver/homeassistant](https://docs.linuxserver.io/images/docker-homeassistant)
-- [koenkk/zigbee2mqtt](https://hub.docker.com/r/koenkk/zigbee2mqtt)
-- [eclipse-mosquitto](https://hub.docker.com/_/eclipse-mosquitto)
+This collection is a set of Ansible roles, aiming to simplify the deployment and configuration
+of <a href="https://home-assistant.io" target="_blank">HomeAssistant</a>,
+<a href="https://www.zigbee2mqtt.io" target="_blank">Zigbee2MQTT</a>
+and <a href="https://mosquitto.org" target="_blank">Mosquitto</a>,
+making them ready to connect to Apple Home.
 
 ## Requirements
 
-A Zigbee Adapter. See [prerequisites](https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites).
+- A <a href="https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites" target="_blank">ZigBee Adapter</a>.
+- Docker. Please refer to <a href="https://github.com/geerlingguy/ansible-role-docker?tab=readme-ov-file#ansible-role-docker" target="_blank">ansible-role-docker</a> to install it with Ansible.
 
 ## Installation
 
-Install the collection via ansible-galaxy:
-
 ```
-ansible-galaxy collection install git+https://github.com/artyorsh/ansible-role-smarthome.git,master
+ansible-galaxy collection install artyorsh.smarthome
+```
+
+## Usage
+
+<!-- TODO: enable mqtt in HA by default! -->
+<!-- see https://www.home-assistant.io/integrations/alarm_control_panel.mqtt/#state_topic -->
+<!-- see https://www.home-assistant.io/integrations/alarm_control_panel.mqtt/#command_topic -->
+
+1. <a href="https://www.zigbee2mqtt.io/guide/getting-started/#installation" target="_blank">Find the ZigBee adapter</a>
+2. [Run the playbook](#example-playbook)
+3. <a href="https://www.home-assistant.io/integrations/homekit/#setup" target="_blank">Enable the HomeKit integration in AppleHome</a> (starting from step 1)
+
+For a real-world usage example, see my <a href="https://github.com/artyorsh/infra" target="_blank">infra playbooks</a>.
+
+## Example Playbook
+
+```yaml
+- hosts: localhost
+
+  vars:
+    smarthome_zigbee_coordinator: /dev/ttyUSB0
+
+  roles:
+    - artyorsh.smarthome.smarthome
 ```
 
-## Using this collection
+By default, HomeAssistant and Zigbee2MQTT containers are deployed on ports 8123 and 8124.
 
-Please refer to the example in [smarthome/readme.md](./roles/smarthome/readme.md#example-playbook) for all-in-one installation.
+## Configuration
 
-...Or to [homeassistant/readme.md](./roles/homeassistant/readme.md#example-playbook),
-[zigbee2mqtt/readme.md](./roles/zigbee2mqtt/readme.md#example-playbook)
-and [mosquitto/readme.md](./roles/mosquitto/readme.md#example-playbook)
-for installing containers individually.
+- The [smarthome](./roles/smarthome/README.md) role is a shortcut to deploy everything in one go
+- Please refer to the role documentation pages for more configuration options:
+  - [homeassistant](./roles/homeassistant/README.md)
+  - [zigbee2mqtt](./roles/zigbee2mqtt/README.md)
+  - [mosquitto](./roles/mosquitto/README.md)
 
 ## More information
 
 - [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
-- [HomeAssistant Docker](https://www.home-assistant.io/installation/linux#docker-compose)
-- [HomeAssistant HomeKit Bridge](https://www.home-assistant.io/integrations/homekit)
-- [Zigbee2MQTT Getting started](https://www.zigbee2mqtt.io/guide/getting-started)
-- [Zigbee2MQTT Docker](https://www.zigbee2mqtt.io/guide/installation/02_docker.html)
+- [HomeAssistant / HomeKit Integration](https://www.home-assistant.io/integrations/homekit)
 - [Using HomeKit component inside docker](https://community.home-assistant.io/t/using-homekit-component-inside-docker/45409/45?page=2)
 
 ## License

roles/homeassistant/README.md

@@ -1,29 +1,32 @@
 # smarthome.homeassistant
 
-Builds and installs a custom [lscr.io/linuxserver/homeassistant](https://hub.docker.com/r/linuxserver/homeassistant) image, discoverable in a bridge network ([See comments](https://community.home-assistant.io/t/using-homekit-component-inside-docker/45409/45?page=2) from [@irvinlim](https://github.com/irvinlim)).
+Builds and installs a custom [lscr.io/linuxserver/homeassistant](https://hub.docker.com/r/linuxserver/homeassistant) image, discoverable within a bridge network.
 
-Also installs [angelnu/mdns_repeater](https://github.com/angelnu/docker-mdns_repeater), to allow the container to send/receive mdns broadcast messages.
+## Why a Custom Image?
+
+When HomeAssistant is deployed in a bridge network, the HomeKit integration is not discoverable by Apple Home.
+To resolve this, the HomeAssistant image is built using the original linuxserver image with [avahi-tools enabled](./templates/homeassistant-avahi-dockerfile.j2). For more details, please refer to this <a href="https://community.home-assistant.io/t/using-homekit-component-inside-docker/45409/45?page=2" target="_blank">community thread</a> for more details.
 
 ## Role Variables
 
 - `homeassistant_port`
   - Default: `8123`
-  - Description:
+  - Description: The port on which HomeAssistant will be accessible.
   - Type: int
   - Required: no
 - `homeassistant_network`
   - Default: `homeassistant`
-  - Description:
+  - Description: The name of the Docker network.
   - Type: str
   - Required: no
 - `homeassistant_install_dir`
   - Default: `/opt/docker/homeassistant`
-  - Description:
+  - Description: The directory where HomeAssistant will be installed.
   - Type: str
   - Required: no
 - `homeassistant_env`
   - Default: `{}`
-  - Description: Docker container environment. See [linuxserver/homeassistant](https://docs.linuxserver.io/images/docker-homeassistant/#environment-variables-e)
+  - Description: Docker container environment variables. See [linuxserver/homeassistant](https://docs.linuxserver.io/images/docker-homeassistant/#environment-variables-e)
   - Type: str
   - Required: no
 - `homeassistant_config`
@@ -33,12 +36,12 @@ Also installs [angelnu/mdns_repeater](https://github.com/angelnu/docker-mdns_rep
   - Required: no
 - `homeassistant_homekit_config`
   - Default: See [homeassistant_homekit_config_default](./vars/main.yml)
-  - Description: Configuration for [HomeKit integration](https://www.home-assistant.io/integrations/homekit)
+  - Description: Configuration for the [HomeKit integration](https://www.home-assistant.io/integrations/homekit)
   - Type: object
   - Required: no
 - `homeassistant_mdns_host_network_interface`
   - Default: `eth0`
-  - Description: Host network interface from which mDNS requests are sent to HomeAssistant container
+  - Description: The host network interface from which mDNS requests are sent to the HomeAssistant container.
   - Type: str
   - Required: no
 
@@ -49,15 +52,22 @@ Also installs [angelnu/mdns_repeater](https://github.com/angelnu/docker-mdns_rep
 ## Example Playbook
 
 ```yaml
-- role: "artyorsh.smarthome.homeassistant"
+- hosts: localhost
+
+  roles:
+    - artyorsh.smarthome.homeassistant
 ```
 
-### Include specific HomeAssistant entries
+### Only include specific HomeAssistant entries
 
 ```yaml
-- role: "artyorsh.smarthome.homeassistant"
+- hosts: localhost
+
   vars:
     homeassistant_homekit_config:
       filter:
         include_entity_globs: ["light.*"]
+
+  roles:
+    - artyorsh.smarthome.homeassistant
 ```

roles/mosquitto/README.md

@@ -42,9 +42,13 @@ Installs the [eclipse-mosquitto](https://github.com/eclipse/mosquitto/tree/maste
 ## Example Playbook
 
 ```yaml
-- role: "artyorsh.smarthome.mosquitto"
+- hosts: localhost
+
   vars:
     mosquitto_user:
       name: "mosquitto"
       password: "changeme"
+
+  roles:
+    - artyorsh.smarthome.mosquitto
 ```

roles/zigbee2mqtt/README.md

@@ -4,8 +4,8 @@ Installs the [koenkk/zigbee2mqtt](https://hub.docker.com/r/koenkk/zigbee2mqtt/)
 
 ## Requirements
 
-- A Zigbee Adapter. See [prerequisites](https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites).
-- An MQTT server. See [mosquitto role](../mosquitto/readme.md).
+- A <a href="https://www.zigbee2mqtt.io/guide/getting-started/#prerequisites" target="_blank">ZigBee Adapter</a>.
+- An [MQTT server](../mosquitto/readme.md).
 
 ## Role Variables
 
@@ -52,12 +52,16 @@ Installs the [koenkk/zigbee2mqtt](https://hub.docker.com/r/koenkk/zigbee2mqtt/)
 ## Example Playbook
 
 ```yaml
-- role: "artyorsh.smarthome.zigbee2mqtt"
+- hosts: localhost
+
   vars:
     zigbee2mqtt_device: "/dev/ttyUSB0"
     zigbee2mqtt_config:
       mqtt:
         server: "mqtt://mosquitto"
         user: "mosquitto"
         password: "changeme"
+
+  roles:
+    - artyorsh.smarthome.zigbee2mqtt
 ```