NOTE: I am no longer using this tool myself since I have converted my Envoy Vue for use with esphome. I will try to respond to issues here but this code will no longer be maintained.
This project provides a client application for the Emporiá Energy Smart Home Monitor cloud data storage. It allows users to save their electricity usage to an InfluxDB database and/or in JSON format. By default, the downloader will run continuously and download datasets periodically. However, it can also be used to just download a single dataset.
The project assumes deployment to a Unix platform but will work on any other platform that supports java with only minor modifications (i.e. path to the logging directory).
All external API dependencies are managed via maven, which is needed for compilation.
You can compile the downloader application yourself or download the latest version (1.4) from the github repository.
Generate the executable jar (it will be saved to the dist/ directory in the project
directory) using the command 'mvn package'.
The executable jar can be run with the following options (see also config.properties.example):
Option Description
------ -----------
--config <String> configuration file; CLI parameters override
configured parameters! (default:
/Users/helgew/dev/projects/emporia-
downloader/config.properties)
-d, --debug enable debug messages.
--disable-influx disable the uploading to InfluxDB
--help display help text
--history, --offset <A number plus time unit history to download if no prior data is
(one of 's', 'm', 'h', 'd', 'w', 'M', or 'y')> available.
For example, '--history 3w' downloads the last 3
weeks of data.
Note that the availability of data is subject to
Emporia's data retention policies. (default:
3h)
--influx-bucket <String> InfluxDB bucket (default: electricity/autogen)
--influx-measurement <String> InfluxDB measurement name
If left empty, measurements will be saved by
channel.
--influx-org <String> InfluxDB server org
--influx-port <Integer> InfluxDB server port (default: 8086)
--influx-token <String> InfluxDB server token
--influx-url <String> InfluxDB server URL (default: http://localhost)
--logfile <String> log to this file (default:
/Users/helgew/dev/projects/emporia-
downloader/application.log)
--password <String> password
-q, --quiet do not print any messages to the console except
for errors.
--raw output raw JSON readings to STDOUT
--scale <One of 's', 'm', 'h', 'd', 'w, 'M', or scale of the data
'y'> For example, '--scale d' will download a
datapoint per day. (default: 1S)
--sleep <Integer> number of minutes to sleep between cycles.
This parameter will be adjusted such that it is
always greater than the scale.
If a value of 0 is given, the downloader exits
after one dataset has been downloaded.
(default: 5)
--username <String> username
The username and password parameters are required. All parameters can be
configured in the configuration file (see config.properties.sample). Command line options take
precedent over parameters configured in the configuration file.
All data displayed and saved to InfluxDB will be in Kilowatt-hours with the exception of per-second data saved to InfluxDB, which will be in Watts for historical reasons.
The following use cases assume that additional parameters (e.g. username, password, and
InfluxDB-related settings) are configured in config.properties.
java -jar emporia-downloader.1.4.jar --config config.properties
This assumes that InfluxDB specific parameters are configured in config.properties and that
all other parameters are left as defaults.
java -jar emporia-downloader.1.4.jar --scale h --history 1d
In this case, the downloader will download and save the historical data and then go into a continuous loop where it will sleep for an hour and then download new data. All data saved to InfluxDB will be in Kilowatt-hours.
java -jar emporia-downloader.1.4.jar --history 1h --raw --sleep 0
The downloader will download and print in JSON format the per-second usage for each device going back by an hour. The data shown will be in Kilowatt-hours but any data saved to InfluxDB will be in Watts. There will be two lines per device and channel combination as the downloader splits the download into chunks with no more than 2000 datapoints.
To create a docker container, execute the following command:
docker build -t emporia-downloader .
(On Apple silicon-based Macs, use docker build -t emporia-downloader -f Dockerfile.mac .)
This will create a container named 'emporia-downloader'. To run the container, copy the env.example
file to a file named .env and edit it to your liking (note the mandatory settings!). Afterward,
you can run the container like so:
docker run --env-file .env --rm -it --name=emporia emporia-downloader:latest
This project is licensed under the GPL version 3 License - see the LICENSE.txt file for details.
Our privacy policy is detailed in privacy-policy.txt