solar-grabber/README.md

# Solar Grabber

Solar Grabber is a web service that provides a REST API layer over various
cloud sites/services/APIs to get statistical data of your solar panels.

The services that are currently supported are
[Hoymiles](https://global.hoymiles.com) and
[My Autarco](https://my.autarco.com).

## Building & running

First, you need to provide settings in the file `Rocket.toml` by setting the
username, password and other cloud service-specific settings.
You can copy and modify `Rocket.toml.example` for this and uncomment the part
relevant for the service you want to use.
For example, to configure Solar Grabber to use the My Autarco service:

```toml
[default]
# ...

# Put your solar cloud service settings below and uncomment them based on the
# service you want to use.
[default.service]
kind = "MyAutarco"
username = "foo@domain.tld"
password = "secret"
site_id = "abc123de"
```

You can also change this configuration to use a different address and/or port.
(Note that Rocket listens on `127.0.0.1:8000` by default for debug builds, i.e.
builds when you don't add `--release`.)

```toml
[default]
address = "0.0.0.0"
port = 2399

# ...
```

This will work independent of the type of build. For more about Rocket's
configuration, see: <https://rocket.rs/v0.5-rc/guide/configuration/>.

### Using cargo

Using Cargo it is easy to build and run Solar Grabber. just run:

```shell
$ cargo run --release
...
   Compiling solar-grabber v0.1.0 (/path/to/solar-grabber)
    Finished release [optimized] target(s) in 9m 26s
     Running `/path/to/solar-grabber/target/release/solar-grabber`
```

### Using Docker (Compose)

Using `docker-compose` it is easy (to build and) run using a Docker image.
If you do not change `docker-compose.yml` it will use `Rocket.toml` from
the current working directory as configuration:

```console
$ docker-compose up
...
```

To use Docker directly, run to build an image and the run it:

```console
$ docker build --rm --tag solar-grabber:latest .
...
$ docker run --rm -v ./Rocket.toml:/app/Rocket.toml -p 2399:8000 solar-grabber-latest
...
```

This also uses `Rocket.toml` from the current working directory as configuration.
You can alternatively pass a set of environment variables instead. See
`docker-compose.yml` for a list.

## API endpoint

The `/` API endpoint provides the current statistical data of your solar panels
once it has successfully logged into the cloud service using your credentials.
There is no path and no query parameters, just:

```http
GET /
```

### Response

A response uses the JSON format and typically looks like this:

```json
{"current_w":23.0,"total_kwh":6159.0,"last_updated":1661194620}
```

This contains the current production power (`current_w`) in Watt,
the total of produced energy since installation (`total_kwh`) in kilowatt-hour
and the (UNIX) timestamp that indicates when the information was last updated.

## License

Solar Grabber is licensed under the MIT license (see the `LICENSE` file or
<http://opensource.org/licenses/MIT>).