diff --git a/README.md b/README.md
index af317cddd563107611af12b72fd43ca89fd21231..1d31e1fa1ede19b3e2a615992f7f081de9c57944 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,70 @@
 # prometheus_dyson
-Prometheus client for DysonLink fans (Pure Hot+Cool)
+Prometheus client for DysonLink fans (e.g; Pure Hot+Cool).
+
+This code only supports Pure Hot+Cool fans at the moment. It should be trivial
+to extend to other fan types (I just don't have one to test).
+
+## Dependencies
+
+pip install libpurecoollink
+pip install prometheus_client
+
+## Metrics
+
+### Environmental
+
+Name | Type | Description
+---- | ---- | -----------
+humidity | gauge | relative humidity percentage
+temperature | gauge | ambient temperature in celsius
+voc | gauge | volatile organic compounds (range 0-10?)
+dust | gauge | dust level (range 0-10?)
+
+### Operational
+
+Name | Type | Description
+---- | ---- | -----------
+fan_mode | enum | AUTO, FAN (what the fan is set to)
+fan_state | enum | FAN, OFF (what the fan is actually doing)
+fan_speed | gauge | 0-10 (or -1 if on AUTO)
+oscillation | enum | ON, OFF
+focus_mode | enum | ON, OFF
+heat_mode | enum | HEAT, OFF (OFF means "in cooling mode")
+heat_state | enum | HEAT, OFF (what the fan is actually doing)
+heat_target | gauge | target temperature (celsius)
+quality_target | gauge | air quality target (1, 3, 5?)
+filter_life | gauge | hours of filter life remaining
+
+## Usage
+
+### Configuration
+
+This script reads `config.ini` (or another file, specified with `--config`)
+for your DysonLink login credentials.
+
+### Args
+```
+% ./prometheus_dyson.py --help
+usage: ./prometheus_dyson.py [-h] [--port PORT] [--config CONFIG]
+
+optional arguments:
+  -h, --help       show this help message and exit
+  --port PORT      HTTP server port
+  --config CONFIG  Configuration file (INI file)
+```
+
+### Scrape Frequency
+
+I scrape at 15s intervals. Metrics are updated at approximately 30 second
+intervals by libpurecoollink.
+
+### Other Notes
+
+libpurecoollink by default uses a flavour of mDNS to automatically discover
+the Dyson fan. This is overridable (but this script doesn't at the moment).
+The mDNS dependency makes Dockerising this script somewhat challenging at
+the moment.
+
+## Dashboard
+
+I've provided a sample Grafana dashboard in `grafana.json`.