Add installation and usage instructions

2024-05-17 11:53:54 +01:00
parent ea07932714
commit 0b1717f63c
1 changed files with 123 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,123 @@
-# hass-pico-w-dashboard
+# Raspberry Pi Pico W Home Assistant Dashboard
+
+## Requirements
+
+- Raspberry Pi Pico W
+- Waveshare 1.3" LCD display (part number [Pico-LCD-1.3](https://www.waveshare.com/product/pico-lcd-1.3.htm))
+- WiFi network with WPA/WPA2/WPA3 Personal authentication within range
+- [Home Assistant](https://www.home-assistant.io/)
+- [`rshell`](https://github.com/dhylands/rshell) on a computer with a USB port
+- A USB to Micro USB cable
+
+## Installation
+
+1. First flash the Pico W with the MicroPython firmware via the UF2 bootloader. [See Raspberry Pi's instructions.](https://www.raspberrypi.com/documentation/microcontrollers/micropython.html#drag-and-drop-micropython)
+
+2. Then clone this repository:
+
+    ```bash
+    git clone https://github.com/mgrove36/home-assistant-pi-pico-w-dashboard.git && cd home-assistant-pi-pico-w-dashboard
+    ```
+
+3. Edit `env.py` in this directory to contain [your settings](#settings).
+
+4. Plug in the Pico W using a USB to Micro USB cable, and start `rshell`:
+
+    ```bash
+    rshell
+    ```
+
+5. Check the board is connected:
+
+    ```bash
+    boards
+    ```
+        
+    Which should return something similar to the following:
+
+    ```
+    pyboard @ /dev/ttyACM0 connected Epoch: 1970 Dirs:
+    ```
+
+6. Copy the project onto the Pico W:
+
+    ```bash
+    cp -r * /pyboard/
+    ```
+
+The dashboard will now run whenever the Pico W is provided with power.
+
+## Settings
+
+The `env.py` file contains all settings for the dashboard. The variables are set as follows:
+
+- `HOSTNAME`: The hostname of the Pi Pico W, used when connecting to WiFi.
+- `SSID`: The SSID of the WiFi network to connect to.
+- `WIFI_PASSWORD`: The WPA key (password) of the WiFi network to connect to.
+- `HASS_URL`: The base URL of the Home Assistant instance to connect to. It should start with `http://` or `https://`, and **not** end in a `/`.
+- `TOKEN`: The long-lived access token used to connect to Home Assistant. You can generate one by following the instructions [here](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token).
+- `SCREENS`: A list of the screens to be displayed on the dashboard. Each screen is represented by a dictionary. Their requirements are detailed [below](#screens).
+
+### Screens
+
+The `SCREENS` settings variable is a list of dicts. Each dict must contain the following key-value pairs:
+
+- `name`: A string, denoting the name of the screen to be displayed at the top of it.
+- `type`: An integer:
+    - `0`: A lights dashboard, for interacting with up to four light entities.
+    - `1`: A media dashboard, for interacting with one media player entity.
+
+Each dashboard type has additional required data, detailed below
+
+#### Lights dashboards (type `0`)
+
+Lights dashboards (type `0`) must contain the following additional key-value pairs:
+- `entities`: A list of dicts, with each dict representing an individual light entity. Each dict must have the following key-value pairs:
+    - `id`: A string, storing the entity ID of the light.
+    - `name`: A string, storing a short name for the entity to display on the dashboard.
+
+#### Media dashboards (type `1`)
+
+Media dashboards (type `1`) must contain the following additional key-value pairs:
+- `entity`: A string, storing the entity ID of the media player.
+
+### Example `env.py` file
+
+The below example file connects to Home Assistant at `https://hass.example.com` via a WiFi network named `MyNetwork`, and shows a dashboard with one lights screen and one media screen.
+
+```py
+HOSTNAME="mypico"
+SSID = 'MyNetwork'
+WIFI_PASSWORD = 'MyPassword'
+HASS_URL = "https://hass.example.com"
+TOKEN = "xxxx.xxxx.xxxx"
+SCREENS = [
+    {
+        "name": "Downstairs",
+        "type": 0,
+        "entities": [
+            {
+                "id": "light.bedroom_light",
+                "name": "Bedroom"
+            },
+            {
+                "id": "light.kitchen_light",
+                "name": "Kitchen"
+            },
+            {
+                "id": "light.hallway_light",
+                "name": "Hallway"
+            },
+            {
+                "id": "light.downstairs_lights",
+                "name": "Downstairs"
+            }
+        ]
+    },
+    {
+        "name": "Living Room",
+        "type": 1,
+        "entity": "media_player.living_room"
+    }
+]
+```