20220327 Home Assistant documentation

Repairs broken internal hyperlinks by restoring internal anchors.

Restored anchors converted to null-anchor form.

Fixes some spacing and alignment errors (apparent in MacDown authoring
tool).

Prefers multi-line command syntax over `&&` form which can be confusing
to new users (quasi standard followed in other IOTstack documentation).

Prefers `$ ` prompt form for commands users should execute. This is
another quasi-standard.

Explicitly sets `cd ~/IOTstack` where its omission might produce
unexpected results.

Adds code-fence rendering hints where appropriate.

Signed-off-by: Phill Kelley <[email protected]>

Author: Paraphraser

docs/Containers/Home-Assistant.md

@@ -2,7 +2,7 @@
 
 Home Assistant is a home automation platform. It is able to track and control all devices at your home and offer a platform for automating control.
 
-## References
+## <a name="references"></a>References
 
 - [Home Assistant home page](https://www.home-assistant.io/)
 
@@ -13,7 +13,7 @@ Home Assistant is a home automation platform. It is able to track and control al
 - [DockerHub](https://hub.docker.com/r/homeassistant/home-assistant/)
 
 
-## Home Assistant: two versions
+## <a name="twoVersions"></a>Home Assistant: two versions
 
 There are two versions of Home Assistant:
 
@@ -31,7 +31,7 @@ Technically, both versions of Home Assistant can be installed on your Raspberry
 
 IOTstack used to offer a menu entry leading to a convenience script that could install Supervised Home Assistant but that stopped working when Home Assistant changed their approach. Now, the only method supported by IOTstack is Home Assistant Container.
 
-### Installing Home Assistant Container
+### <a name="installHAContainer"></a>Installing Home Assistant Container
 
 Home Assistant (Container) can be found in the `Build Stack` menu. Selecting it in this menu results in a service definition being added to:
 
@@ -56,7 +56,7 @@ $ cd ~/IOTstack
 $ docker-compose up -d
 ```
 
-### Installing Supervised Home Assistant
+### <a name="installHASupervised"></a>Installing Supervised Home Assistant
 
 The direction being taken by the Home Assistant folks is to supply a ready-to-run image for your Raspberry Pi. That effectively dedicates your Raspberry Pi to Home Assistant and precludes the possibility of running alongside IOTstack and containers like Mosquitto, InfluxDB, Node-RED, Grafana, PiHole and WireGuard.
 
@@ -106,12 +106,12 @@ The first time you use PiBuilder, the process boils down to:
 
 	where «name» is the name you give to your Raspberry Pi (eg "iot-hub").
 
-After step 9, Supervised Home Assistant will be running. The `04_setup.sh` script also deals with the [random MACs](#why-random-macs-are-such-a-hassle) problem. After step 11, you'll be able to either:
+After step 9, Supervised Home Assistant will be running. The `04_setup.sh` script also deals with the [random MACs](#aboutRandomMACs) problem. After step 11, you'll be able to either:
 
 1. Restore a backup; or
 2. Run the IOTstack menu and choose your containers.
 
-## Why random MACs are such a hassle
+## <a name="aboutRandomMACs"></a>Why random MACs are such a hassle
 
 > This material was originally posted as part of [Issue 312](https://github.com/SensorsIot/IOTstack/issues/312). It was moved here following a suggestion by [lole-elol](https://github.com/lole-elol).
 
@@ -171,7 +171,8 @@ Random MACs are not a problem for a **client** device like a phone, tablet or la
 
 It is not just configuration-time SSH sessions that break. If you decide to leave Raspberry Pi random Wifi MAC active **and** you have other clients (eq IoT devices) communicating with the Pi over WiFi, you will wrong-foot those clients each time the Raspberry Pi reboots. Data communications services from those clients will be impacted until those client devices time-out and catch up.
 
-## Using bluetooth from the container
+## <a name="usingBluetooth"></a>Using bluetooth from the container
+
 In order to be able to use BT & BLE devices from HA integrations, make sure that bluetooth is enabled and powered on at the start of the (Rpi) host by editing `/etc/bluetooth/main.conf`:
 
 ```conf
@@ -190,7 +191,7 @@ UP
 ```
 ref: https://scribles.net/auto-power-on-bluetooth-adapter-on-boot-up/
 
-## HTTPS with a valid SSL certificate
+## <a name="httpsWithSSLcert"></a>HTTPS with a valid SSL certificate
 
 Some HA integrations (e.g google assistant) require your HA API to be
 accessible via https with a valid certificate. You can configure HA to do this:
@@ -209,77 +210,91 @@ your RPi hostname is raspberrypi)
 2. Make sure you have duckdns working.
 3. On your internet router, forward public port 443 to the RPi port 443
 4. Add swag to ~/IOTstack/docker-compose.yml beneath the `services:`-line:
-```
-  swag:
-    image: ghcr.io/linuxserver/swag
-    cap_add:
-      - NET_ADMIN
-    environment:
-      - PUID=1000
-      - PGID=1000
-      - TZ=Etc/UTC
-      - URL=<yourdomain>.duckdns.org
-      - SUBDOMAINS=wildcard
-      - VALIDATION=duckdns
-      - DUCKDNSTOKEN=<token>
-      - CERTPROVIDER=zerossl
-      - EMAIL=<e-mail> # required when using zerossl
-    volumes:
-      - ./volumes/swag/config:/config
-    ports:
-      - 443:443
-    restart: unless-stopped
-```
-    Replace the bracketed values. Do NOT use any "-characters to enclose the values.
+
+	```yaml
+	  swag:
+	    image: ghcr.io/linuxserver/swag
+	    cap_add:
+	      - NET_ADMIN
+	    environment:
+	      - PUID=1000
+	      - PGID=1000
+	      - TZ=Etc/UTC
+	      - URL=<yourdomain>.duckdns.org
+	      - SUBDOMAINS=wildcard
+	      - VALIDATION=duckdns
+	      - DUCKDNSTOKEN=<token>
+	      - CERTPROVIDER=zerossl
+	      - EMAIL=<e-mail> # required when using zerossl
+	    volumes:
+	      - ./volumes/swag/config:/config
+	    ports:
+	      - 443:443
+	    restart: unless-stopped
+	```
+
+	Replace the bracketed values. Do NOT use any "-characters to enclose the values.
 
 5. Start the swag container, this creates the file to be edited in the next step:
-   ```
-   cd ~/IOTstack && docker-compose up -d
-   ```
 
-    Check it starts up OK: `docker-compose logs -f swag`. It will take a minute or two before it finally logs "Server ready".
+	```bash
+	$ cd ~/IOTstack
+	$ docker-compose up -d
+	```
+
+	Check it starts up OK: `docker-compose logs -f swag`. It will take a minute or two before it finally logs "Server ready".
 
 6. Enable reverse proxy for `raspberrypi.local`. `homassistant.*` is already by default. and fix homeassistant container name ("upstream_app"):
-      ```
-      sed -e 's/server_name/server_name *.local/' \
-          volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf.sample \
-          > volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
-      ```
+
+	```bash
+	$ cd ~/IOTstack
+	$ sed -e 's/server_name/server_name *.local/' \
+	  volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf.sample \
+	  > volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
+	```
 
 7. Forward to correct IP when target is a container running in "network_mode:
    host" (like Home Assistant does):
-   ```
-   cat << 'EOF' | sudo tee volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
-   #!/bin/sh
-   DOCKER_GW=$(ip route | awk 'NR==1 {print $3}')
-
-   sed -i -e "s/upstream_app .*/upstream_app ${DOCKER_GW};/" \
-       /config/nginx/proxy-confs/homeassistant.subdomain.conf
-   EOF
-   sudo chmod u+x volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
-   ```
+
+	```bash
+	cd ~/IOTstack
+	cat << 'EOF' | sudo tee volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
+	#!/bin/sh
+	DOCKER_GW=$(ip route | awk 'NR==1 {print $3}')
+	
+	sed -i -e "s/upstream_app .*/upstream_app ${DOCKER_GW};/" \
+	   /config/nginx/proxy-confs/homeassistant.subdomain.conf
+	EOF
+	sudo chmod u+x volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
+	```
+
    (This needs to be copy-pasted/entered as-is, ignore any "> "-prefixes printed
    by bash)
 
 8. (optional) Add reverse proxy password protection if you don't want to rely
    on the HA login for security, doesn't affect API-access:
-    ```
-    sed -i -e 's/#auth_basic/auth_basic/' \
-        volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
-    docker-compose exec swag htpasswd -c /config/nginx/.htpasswd anyusername
-    ```
+
+	```bash
+	$ cd ~/IOTstack
+	$ sed -i -e 's/#auth_basic/auth_basic/' \
+		volumes/swag/config/nginx/proxy-confs/homeassistant.subdomain.conf
+	$ docker-compose exec swag htpasswd -c /config/nginx/.htpasswd anyusername
+	```
+
 9. Add `use_x_forwarded_for` and `trusted_proxies` to your homeassistant [http
    config](https://www.home-assistant.io/integrations/http). The configuration
    file is at `volumes/home_assistant/configuration.yaml` For a default install
    the resulting http-section should be:
-   ```
+
+   ```yaml
    http:
       use_x_forwarded_for: true
       trusted_proxies:
         - 192.168.0.0/16
         - 172.16.0.0/12
         - 10.77.0.0/16
    ```
+
 10. Refresh the stack: `cd ~/IOTstack && docker-compose stop && docker-compose
     up -d` (again may take 1-3 minutes for swag to start if it recreates
     certificates)
@@ -292,10 +307,12 @@ your RPi hostname is raspberrypi)
     are just testing)
 
     Or from the command line in the RPi:
-    ```
-    curl --resolve homeassistant.<yourdomain>.duckdns.org:443:127.0.0.1 \
+
+    ```bash
+    $ curl --resolve homeassistant.<yourdomain>.duckdns.org:443:127.0.0.1 \
         https://homeassistant.<yourdomain>.duckdns.org/
     ```
+
     (output should end in `if (!window.latestJS) { }</script></body></html>`)
 
 13. And finally test your router forwards correctly by accessing it from