diff --git a/README.md b/README.md index 70b8ae7..12e13de 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,13 @@ ## Why? -To get the [tagging](https://github.com/home-climate-control/esphome2influxdb/wiki/Tagging) right, in a lightweight package. +To get the [tagging](./docs/tagging.md) right, in a lightweight package. ## How? Execute `./gradlew installDist` to get an executable shell script, and run `./build/install/esphome2influxdb/bin/esphome2influxdb ${your-config-file}.yaml`. -Or, [build and run the Docker image](https://github.com/home-climate-control/esphome2influxdb/wiki/Build-with-Docker). +Or, [build the Docker image](./docs/build/docker.md). -For further details, see [esphome2influxdb Wiki](https://github.com/home-climate-control/esphome2influxdb/wiki). +For further details, see detailed documentation at [./docs](./docs/index.md). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..92d8f9c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +esphome2influxdb: Docs +== + +## Quickstart + +1. `apt install mosquitto` or your favorite MQTT broker +1. Configure [ESPHome MQTT Client Component](https://esphome.io/components/mqtt.html) on your ESPHome devices +1. [Install InfluxDB](https://docs.influxdata.com/influxdb/v1.8/introduction/install/) +1. Build and run `esphome2influxdb` ([Gradle](./build/gradle.md) or [Docker](./build/docker.md)) +1. [Configure your tags](./tagging.md) +1. PROFIT!!! + +## Current Limitations + +* Currently works only with [ESPHome Sensor](https://esphome.io/components/sensor/index.html) components, more to come. +* The project's just been open sourced, documentation is coming, keep checking this wiki for updates. + +## Further Down the Rabbit Hole + +[Home Climate Control Project](https://github.com/home-climate-control/dz) diff --git a/docs/minimal-configuration.md b/docs/minimal-configuration.md new file mode 100644 index 0000000..28ef42f --- /dev/null +++ b/docs/minimal-configuration.md @@ -0,0 +1,35 @@ +esphome2influxdb: Minimal Configuration +== + +## Before you start + +Keep in mind: this configuration will just start capturing data, you need to configure [tagging](./tagging.md) to make it meaningful. + +## Running as a script + +This will get you going: +``` +sources: + - host: localhost + +targets: + - host: localhost +``` +[[download source](https://github.com/home-climate-control/esphome2influxdb/blob/master/src/main/resources/esphome2influxdb-localhost.yaml)] + +## Running in Docker + +This is a bit more complicated - `localhost` refers to the container itself (which has nothing other than `esp2influxdb` running), you need to [configure container networking](https://docs.docker.com/config/containers/container-networking/) to make hostnames resolve (look for `--dns` and related options). Or, just provide the IP. +``` +sources: + - host: ${mqtt-broker-ip-or-hostname} + +targets: + - host: ${influxdb-ip-or-hostname} +``` +[download source](https://github.com/home-climate-control/esphome2influxdb/blob/master/src/main/resources/esphome2influxdb.yaml) + +Read more: [Build with Docker](./build/docker.md) + +--- +[^^^ Index](./index.md) diff --git a/docs/tagging.md b/docs/tagging.md new file mode 100644 index 0000000..baaa44f --- /dev/null +++ b/docs/tagging.md @@ -0,0 +1,171 @@ +esphome2influxdb: Tagging +== + +# The General Idea + +Everyone wants their own tags and doesn't care about what others do. Here, have it your way - tags are free form. + +# Examples + +They're all going to look pretty similar and boring - the only difference is tags. + +## Temperature Sensors + +### Climate Control Zone +``` + - type: sensor + topicPrefix: /esphome/7AC96F + source: htu21df-bedroom-master-temperature + tags: + location: Master Bedroom + zone: Master Bedroom + building: house + protocol: I2C + hardware: HTU21D-F + type: indoor + medium: air + measurement: temperature + measurementUnit: °C +``` +### HVAC Unit +You heed four sensors to keep an eye on a HVAC unit: air temperature on return and supply, and refrigerant temperature on pressure and suction lines. +``` + - type: sensor + topicPrefix: /esphome/E475FA + source: hvac-north-air-return + tags: + location: hvac-north + building: workshop + protocol: 1-Wire + hardware: DS18B20 + type: unit + medium: air + measurement: temperature + measurementUnit: °C + + - type: sensor + topicPrefix: /esphome/E475FA + source: hvac-north-air-supply + tags: + location: hvac-north + building: workshop + protocol: 1-Wire + hardware: DS18B20 + type: unit + medium: air + measurement: temperature + measurementUnit: °C + + - type: sensor + topicPrefix: /esphome/E475FA + source: hvac-north-refrigerant-suction + tags: + location: hvac-north + building: workshop + protocol: 1-Wire + hardware: DS18B20 + type: unit + medium: refrigerant + measurement: temperature + measurementUnit: °C + + - type: sensor + topicPrefix: /esphome/E475FA + source: hvac-north-refrigerant-pressure + tags: + location: hvac-north + building: workshop + protocol: 1-Wire + hardware: DS18B20 + type: unit + medium: refrigerant + measurement: temperature + measurementUnit: °C + +``` + +### Water Heater +``` + - type: sensor + topicPrefix: /esphome/45FB71 + source: water-heater-out + tags: + location: Water Heater + zone: Water Heater + building: house + protocol: 1-Wire + hardware: DS18B20 + type: unit + medium: water + measurement: temperature + measurementUnit: °C +``` +## Other Sensors +### Pressure Sensor +``` + - type: sensor + topicPrefix: /esphome/794221 + source: bme280-bathroom-master-pressure + tags: + location: Master Bathroom + building: house + protocol: I2C + hardware: BME280 + type: indoor + medium: air + measurement: pressure + measurementUnit: hPa +``` + +### Humidity Sensor +``` + - type: sensor + topicPrefix: /esphome/794221 + source: bme280-bathroom-master-humidity + tags: + location: Master Bathroom + building: house + protocol: I2C + hardware: BME280 + type: indoor + medium: air + measurement: relative humidity + measurementUnit: "%" +``` +### VOC Sensor +``` + - type: sensor + topicPrefix: /esphome/5459EA + source: bme680-0-gas-resistance + tags: + location: Kitchen + building: house + protocol: I2C + hardware: BME680 + type: indoor + medium: air + measurement: gas resistance + measurementUnit: Ω +``` + +### CO2 sensor +``` + - type: sensor + topicPrefix: /esphome/26EFE2 + source: scd40-0-co2 + tags: + location: Workshop + zone: Back Wall + building: workshop + protocol: I2C + hardware: SCD40 + type: indoor + medium: air + measurement: "carbon dioxide" + measurementUnit: ppm + busDeviceCount: 1 + macOUI: 40F520 +``` + +--- +[^^^ Index](./index.md)