search

freeranger / evologger

EvoHome Logger
MIT License
12 stars 4 forks source link

readme

Evo Logger Build Status

Purpose

To allow you to read your actual and desired temperatures from your EvoHome system (and others) and log them to a variety of destinations.

Destinations include "data stores" such as .csv files or influxdb database for further ingestion by Excel or grafana respectively, or directly to graphing websites such as emoncms

Getting Started

  1. Clone the entire repo to your preferred location.
  2. Configure the global settings in the [DEFAULT] section of config.ini
  3. Configure each plugin in config.ini according to your needs - see the README.md file with each plugin for details on how to configure it. All plugins live in the "plugins" folder - you can delete ones you don't want (and remove the relevant config.ini section) or add disabled to the relevant config.ini section to explicitly disable it
  4. run it!
    • Locally
      • pip3 install -r requirements.txt to add the required python packages (for all plugins)
      • python3 evologger.py to start the application (add -h for help)
    • In Docker
      • See below to run in Docker

Running in Docker

A Docker image is available that you can download and run docker pull freeranger/evologger:latest You will need to map your own configuration file into the container as the built in one is not configured. You may also for example map a volume/file for csv output rather than storing in the container volume.

It is beyond the scope of this document to describe how to use docker but as an example you could do something like this: docker run --rm -it -v $(pwd)/config.docker.ini:/evologger/config.ini freeranger/evologger

which will map the file config.docker.ini in the current folder into the running container

The Dockerfile is included in this repo so you can build and run the container locally if you wish: From the source folder:

  1. docker build -t evologger .
  2. Run:
    • docker run --rm -it evologger (to run in the foregound with coloured output)
    • docker run --rm -d evologger (to run in detached mode)

Note If you are running services in other containers on the same host that you wish to accerss (e.g. Influx) then you need to use host.docker.internal in place of the host name or IP you would otherwise use - or you could use a docker compose file and ensure they are in the same docker network

[DEFAULT] config.ini settings

[DEFAULT]
pollingInterval=600     - Frequency in seconds to read temperatures from input plugins and write them to the output plugins.  0 => do once, then exit
                          It is recommended that this is set to no less than 5 minutes as some of the api's used by plugins (e.g. plot.ly) limit the numer of api calls you can make per day.
Outside=<zone name>     - Name you want to use for your outside "zone" (if you have one) when reading the external temperature - used by some input plugins, e.g. darksky.net, netatmo
HotWater=Hot Water      - Name you want to use for the Hot Water "zone" (if you have one) when reading the temperature - used by some plugins, e.g. evohome, console
debug=<true|false>      - If true then output/log debug level info.  This must be true to debug into plugins too
httpDebug=<true|false>  - IF trye then http requests/responses are logged at the debug level

Plugins

Evologger supports a "plugin" architecture where you can add new input sources and output destinations simply by adding the plugin to the plugins directory and adding any necessary configuration to the config.ini file.

Any plugins you don't want to use, it's probably best to remove their section(s) from the config.ini file completely.

Available plugins

Inputs
Outputs

See the readme file in each plugin's folder for instructions on any specific configuration or initialisation steps required.

All plugins support the following options in config.ini:

disabled=<true|false>   - If true then the plugin is disabled completely and will never be invoked
simulation=<true|false> - if true then input plugins will return random values rather than contacting the
                          source whilst output plugins will write to the debug log but not the actual
                          destination.  Default: false if not present
debug=<true|false>      - If true then write to the debug log.  If not present then follows the debug setting
                          in the [DEFAULT] section of the config file.  If present and false (the only time it
                          makes sense to add this value) then do not write debug output for this specific plugin only
                          even if the [DEFAULT] setting is to debug

Creating your own plugins

Plugins come in two flavours - input plugins and output plugins. Input plugins are sources of temperature data and output plugins are where you record that data.

The simplest way to get started with your own plugin is to look at one of the existing ones - eg. darksky.net for input or csv for output.

There are a few rules you must follow for your plugin:

Limitations

Changelog

3.0.0 (2022-02-06)

2.0.0 (2021-12-28)

1.0.0 (2017)

Initial release

Disclaimer I am not a Python programmer - this is probably awful python code, but it works for me - use at your own risk.