Skip to content

Commit

Permalink
docs: Adds information about SolarEdge configuration
Browse files Browse the repository at this point in the history 
fixes #22
  • Loading branch information
@hferentschik
hferentschik committed Apr 22, 2022
1 parent 0d5d753 commit dbee87d
Show file tree
Hide file tree
Showing 4 changed files with 183 additions and 76 deletions.
19 changes: 19 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Contribution guidelines

## Filing issues

File issues using the standard
[Github issue tracker](https://github.com/hferentschik/balena-weather/issues) for the repository.
Before you submit a new issue, we recommend that you search the list of issues to see if anyone already submitted a similar issue.

## Contributing patches

Thank you for your contributions! Please follow this process to submit a patch:

* Create an issue describing your proposed change to the repository.
* Fork the repository and create a topic branch.
* Submit a pull request with the proposed changes.

## Questions?

If you run into issues or have any questions about contributions feel free to reach out on the [balena Forums](https://forums.balena.io).
196 changes: 120 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,34 @@
# Balena Weather Station

A Raspberry Pi weather station, running on a [Balena](https://www.balena.io/) multi-container application where you can add more services. This project is inspired by the [Raspberry Pi weather station](https://projects.raspberrypi.org/en/projects/build-your-own-weather-station/0).
A Raspberry Pi based weather station, running a [extensible](#extending-the-balena-weather-station) Balena [multi-container application](https://www.balena.io/docs/learn/develop/multicontainer/) inspired by the [Raspberry Pi weather station](https://projects.raspberrypi.org/en/projects/build-your-own-weather-station/0) project.

![Weather Station](./images/weather_station.png)

The following sections describe the hardware, wiring and configuration of the Balena Weather Station.

<!-- MarkdownTOC levels="2,3,4" autolink="true" indent=" " -->

- [Balena Weather Station](#balena-weather-station)
- [Hardware](#hardware)
- [Wiring](#wiring)
- [Deploy the code](#deploy-the-code)
- [Via Deploy with Balena](#via-deploy-with-balena)
- [Via the `balena` CLI](#via-the-balena-cli)
- [Configure the Balena Weather Station](#configure-the-balena-weather-station)
- [DT parameters and overlays](#dt-parameters-and-overlays)
- [Device Variables](#device-variables)
- [Access to the Grafana interface](#access-to-the-grafana-interface)
- [Individual service descriptions](#individual-service-descriptions)
- [Sensors](#sensors)
- [MQTT, Telegraf and InfluxDB](#mqtt-telegraf-and-influxdb)
- [UI and API](#ui-and-api)
- [Powering the Raspberry Pi via the 5V rail](#powering-the-raspberry-pi-via-the-5v-rail)
- [Extending the Balena Weather Station](#extending-the-balena-weather-station)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)

<!-- /MarkdownTOC -->

## Hardware

![Raspberry Pi 3](./images/raspberry_pi.png)
Expand All @@ -14,25 +37,24 @@ Let's start with the hardware used for this project.

- 1 [Raspberry Pi 3](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) - the heart of the weather station.
Balena Weather Station is also compatible with the Raspberry Pi 4.
- 1 [Sparkfun Weather Meter Kit](https://www.sparkfun.com/products/15901) - the main weather station components including anemometer, windvane and raingauge.
- 1 [Prototyping HAT for Raspberry Pi](https://www.robotshop.com/en/prototyping-hat-raspberry-pi-b-2ba3b.html) - my aim was to build a permanent weather station (see picture above). For this reason I opted for the Prototyping HAT and soldering the components together.
- 1 [Sparkfun Weather Meter Kit](https://www.sparkfun.com/products/15901) - the main weather station components, including an anemometer, wind vane and rain gauge.
- 1 [Prototyping HAT for Raspberry Pi](https://www.robotshop.com/en/prototyping-hat-raspberry-pi-b-2ba3b.html) - I aimed to build a permanent weather station (see picture above). For this reason, I opted for the Prototyping HAT and soldering.
You can also use a [GPIO extender board](https://www.sparkfun.com/products/13717) with a breadboard for a less permanent solution.
- 1 [MCP3008](https://www.microchip.com/en-us/product/MCP3008) - a 8-channel, 10-bit ADC with SPI interface.
It is used to convert the analog voltage provided by the windvane's into a digital value.
- 1 [SHT-30](https://www.adafruit.com/product/4099) - a wheater proof humidity sensor which also includes a temperature sensor.
The temperature measures by the SHT-30 is also stored in InfluxDB, however, the default Grafana dashboard does not include its value.
- 1 [DS18B20](https://www.amazon.com/Eiechip-Waterproof-Temperature-Thermometer-Resistance/dp/B07MB1J43W/) - standard 1-wire bus water proof temperature sensor.
- 2 4.7k&#8486; resistors - used for the vindvane's voltage divider circuit as well as a pull up resistor for the temperature sensor.
- 1 [Raspberry Pi IP54 Outdoor Project Enclosure](https://sixfab.com/product/raspberry-pi-ip54-outdoor-iot-project-enclosure/) - a weather proof enclosure for the Raspberry Pi.

The folling paragraph shows how the components are connected schematically.
It is used to convert the analog voltage provided by the wind vane into a digital value.
- 1 [SHT-30](https://www.adafruit.com/product/4099) - a wheater proof humidity sensor that includes a temperature sensor.
The temperature measurements by the SHT-30 are also stored in InfluxDB.
However, the default Grafana dashboard does not include them.
- 1 [DS18B20](https://www.amazon.com/Eiechip-Waterproof-Temperature-Thermometer-Resistance/dp/B07MB1J43W/) - standard 1-wire bus waterproof temperature sensor.
- 2 4.7k&#8486; resistors - used for the wind vane's voltage divider circuit as well as a pull-up resistor for the temperature sensor.
- 1 [Raspberry Pi IP54 Outdoor Project Enclosure](https://sixfab.com/product/raspberry-pi-ip54-outdoor-iot-project-enclosure/) - a weatherproof enclosure for the Raspberry Pi.

### Wiring

The following diagram shows the schematics of Balena Weather.
The anemometer, windvane and raingauge are symbolised by their main electric component.
The following diagram provides the schematics of the Balena Weather Station.
The anemometer, wind vane and rain gauge are symbolised by their main electric component.

**NOTE**: The Sparkfun Weather station comes per default with RJ11 connectors which has 6 pins.
**NOTE**: The Sparkfun Weather station comes per default with 6-pin RJ11 connectors.
The middle four pins are connected, but only two cables are used.
Refer to the [Sparkfun Weather Meter Kit manual](https://cdn.sparkfun.com/assets/d/1/e/0/6/DS-15901-Weather_Meter.pdf) to see which cables are relevant for each of the components.

Expand All @@ -42,26 +64,28 @@ Refer to the [Sparkfun Weather Meter Kit manual](https://cdn.sparkfun.com/assets

### Via [Deploy with Balena](https://www.balena.io/docs/learn/deploy/deploy-with-balena-button/)

Running this project is as simple as deploying it to a balenaCloud application. You can do it in just one click by using the button below:
Running this project is as simple as deploying it to a balenaCloud application.
You can do it in just one click by using the button below:

[![balena deploy button](https://www.balena.io/deploy.svg)](https://dashboard.balena-cloud.com/deploy?repoUrl=https://github.com/hferentschik/balena-weather)

Follow instructions, click Add a Device and flash an SD card with that OS image dowloaded from balenaCloud. Enjoy the magic 🌟Over-The-Air🌟!
Follow instructions, click Add a Device and flash an SD card with that OS image downloaded from balenaCloud.
Enjoy the magic 🌟Over-The-Air🌟!

### Via [Balena-Cli](https://www.balena.io/docs/reference/balena-cli/)
### Via the `balena` [CLI](https://www.balena.io/docs/reference/balena-cli/)

If you would like to add more services get the balena CLI and follow next steps:
If you would like to add more services, get the `balena` CLI and follow these steps:

- Sign up on [balena.io](https://dashboard.balena.io/signup)
- Create a new application on balenaCloud.
- Clone this repository to your local workspace.
- Using [Balena CLI](https://www.balena.io/docs/reference/cli/), push the code with `balena push <application-name>`
- See the magic happening, your device is getting updated 🌟Over-The-Air🌟!
- Using the `balena` [CLI](https://www.balena.io/docs/reference/cli/), push the code with `balena push <application-name>`
- See the magic happening; your device is getting updated 🌟Over-The-Air🌟!

## Configure the Balena Weather Station

On the software side Balena Weather Station is built as a Balena [multi container application](https://www.balena.io/docs/learn/develop/multicontainer/).
The services comprising Balena Weather are defined in [docker-compose.yml](./docker-compose.yml).
On the software side, the Balena Weather Station is built as a [multi container application](https://www.balena.io/docs/learn/develop/multicontainer/).
Services are defined in [docker-compose.yml](./docker-compose.yml).

![balena-weather-station-balenaCloud](https://user-images.githubusercontent.com/173156/162697086-bbefacde-8c5d-45c3-9083-caf1bb614b72.png)

Expand All @@ -73,13 +97,13 @@ For the sensors to work, the Balena [device or fleet configuration](https://gith

### Device Variables

Define your Device Variables to get some calculations done and configure your MQTT message broker.
The following Device Variables are supported by the Balena Weather Station:

![Balena Device Variables](./images/device_variables.png)

Variable Name | Value | Description | Default
------------ | ------------- | ------------- | -------------
**`SAMPLE_RATE`** | `INT` | The default sample rate for each of the containers is 15 minutes (specified in seconds). | 900
**`SAMPLE_RATE`** | `INT` | The default sample rate for each container is 15 minutes (specified in seconds). | 900
**`MQTT_USER`** | `STRING` | Username to authenticate with the MQTT message broker |
**`MQTT_PASSWORD`** | `STRING` | Password to authenticate with the MQTT message broker |
**`LATITUDE`** | `FLOAT` | Specify your `LATITUDE` for the `api` service that calculates sunrise and sunset |
Expand All @@ -88,26 +112,34 @@ Variable Name | Value | Description | Default

### Access to the Grafana interface

Once all the services are deployed properly on the device, you will be able to access to the Weather Station Grafana interface using `http://<local-ip-address>/weather` or using the balena public address adding `/weather` at the end.
Once all the services are successfully deployed, you will be able to access the Weather Station Grafana interface using the local device address `http://<local-ip-address>/weather` or the Balena public address `http://<public-ip-address>/weather` respectively.

**TIP**: Assuming your fleet is called _weather_, you can retrieve the public URL using:

```sh
balena device public-url $(balena devices -a weather --json | jq -r .[].id)
```

![Grafana Dash](./images/dash.png)

## More information about the Balena Weather Station
## Individual service descriptions

The following sections describe the various services in more detail.

### Sensors

Each of the service build subdirectory contains a README as well providing additional information.
Each service is contained in its own subdirectory.
The README in each subdirectory provides additional information for each service.

- [Anemometer](./anemometer/README.md) - Anemometer (wind speed) sensor of the weather station.
- [Humidity](./humidity/README.md) - Humidity and temperature sensor SHT-30.
- [Raingauge](./raingauge/README.md) - Raingauge sensor of the weather station.
- [Temperature](/temperature/README.md) - Additional DS18B20 temperature sensor.
I am using an additonal temperetature sensor to the SHT-30 temperature sensor which I place in the shade.
The SHT-30 on the other hand is in direct sunlight.
- [Windvane](/windvane/README.md) - Windvane sensor of the weather station.
- For more information refer to the _api_ [README](./api/README.md).

### Message queue and database
### MQTT, Telegraf and InfluxDB

- [MQTT](./mqtt/README.md) - [Eclipse Mosquitto](https://hub.docker.com/r/arm64v8/eclipse-mosquitto) container which acts as message broker to which all sensors are sending their data.
The Telegraf container reads from the Mosquitto queue and pushes the metrics into InfluxDB.
Expand All @@ -119,69 +151,81 @@ Each of the service build subdirectory contains a README as well providing addit
### UI and API

- [NGINX](./nginx) - NGINX listening on port 80 and acting as reverse proxy.
- [API](./api/README.md) - A Ruby based [Sinatra](http://sinatrarb.com) used for exposing REST APIs for the weather app.
- [Grafana Dashboard](./dashboard/README.md) - the Grafana dashboard displaying all weather data.
- [API](./api/README.md) - A Ruby based [Sinatra](http://sinatrarb.com) app used for exposing REST APIs for Grafana (using the JSON datasource plugin).
- [Grafana Dashboard](./dashboard/README.md) - the Grafana dashboard displaying all data.

### InfluxDB
## Powering the Raspberry Pi via the 5V rail

In order to inspect or modify the data stored in the Influx database you can connect directly to the _influxdb_ container and start the [`influx` CLI](https://docs.influxdata.com/influxdb/v1.8/tools/shell/):
I decided to power the Raspberry Pi via the 5V power rail.
The following links provide information on how to do so.

```sh
$ balena ssh <app-name> influxdb
? Select a device amazing-smoke (a36de3)
root@265d8274d16b:/# influx
Connected to http://localhost:8086 version 1.8.0
InfluxDB shell version: 1.8.0
```
- [Raspberry Pi Fuse](https://www.petervis.com/Raspberry_PI/Raspberry_Pi_Dead/Raspberry_Pi_Fuse.html)
- [Power requirements of the Pi](https://raspberrypi.stackexchange.com/questions/51615/raspberry-pi-power-limitations)

In order to get human-readable dates use the `precision rfc3339` command:
## Extending the Balena Weather Station

```sh
> precision rfc3339
> use weather
Using database weather
> show measurements
name: measurements
name
----
humidity
rain
temperature
water-temperature
wind-direction
wind-speed
```
The [balena-weather](https://github.com/hferentschik/balena-weather) GitHub repo contains a [_solar_](https://github.com/hferentschik/balena-weather/tree/solar) branch with the required changes to add electricity production data for a SolarEdge solar panel installatio.

To select the entries of a measurement:
![SolarEdge](./images/solar_edge.png)

```sh
> SELECT * FROM "water-temperature"
2021-06-18T06:05:05Z DS18B20 22.0625 sensors
...
```
The data itself is provided by the [balena-solar-edge](https://github.com/hferentschik/balena-solar-edge) service.
_balena-solar-edge_ uses the [SolarEdge Monitoring Server API](https://www.solaredge.com/sites/default/files/se_monitoring_api.pdf) to retrieve the data and then pushes the data to MQTT.

To delete entries from a measurement use te [`DROP SERIES`](https://docs.influxdata.com/influxdb/v1.8/query_language/manage-database/#drop-series-from-the-index-with-drop-series) query:
The service can easily be added to [docker-compose.yml](./docker-compose.yml) like so:

```sh
> DROP SERIES FROM "water-temperature"
```yaml
solar:
image: hferentschik/solar-edge:0.0.1
restart: always
depends_on:
- mqtt
```

### Powering via 5V rail

In my case I decided to power the Raspberry Pi via the 5V power rail.
The following links provide information on how to do so.

- [Raspberry Pi Fuse](https://www.petervis.com/Raspberry_PI/Raspberry_Pi_Dead/Raspberry_Pi_Fuse.html)
- [Power requirements of the Pi](https://raspberrypi.stackexchange.com/questions/51615/raspberry-pi-power-limitations)
To keep the SolarEdge data seperate from the weather data, it gets stored into its own InfluxDB database.
To do this a new Telegraf configuration file (_solar-edge.conf_) gets added to the _/etc/telegraf/telegraf.d_ directory of the telegraf service.
The configuration follows the [Telegraf Best Practices](https://www.influxdata.com/blog/telegraf-best-practices/) in order to keep the configuration for the weather and solar part seperate.
In particular the use of _tagpass_ is important to ensure that only data from the _solar_ MQTT topic ges added to the _solar_ database.

```toml
###############################################################################
# OUTPUT PLUGINS #
###############################################################################
[[outputs.influxdb]]
alias = "influxdb_solar"
timeout = "1s"
database = "solar"
urls = [ "http://influxdb:8086" ]
[outputs.influxdb.tagpass]
topic = [ "solar" ]

###############################################################################
# INPUT PLUGINS #
###############################################################################
[[inputs.mqtt_consumer]]
alias = "mqtt_solar"
servers = [ "mqtt:1883" ]
topics = [ "solar" ]
json_name_key = "measurement"
data_format = "json"
json_time_key = "time"
json_time_format = "2006-01-02T15:04:05"
tag_keys = [
"tags_name", "tags_image", "tags_model"
]
# username = "mqtt"
# password = "pass"
```

### Other resources
Last but not least, the Grafana dash needs to be updated to display the solar data.
The required changes are part of _dashboard.json_ in the dashboar service.

- [Balena Masterclass](https://github.com/balena-io/balena-cli-masterclass/blob/master/README.md)
- [Pinout](https://pinout.xyz/)
Using this approach other services can be added as well.

## Contributing

This project is open for contributors!
Contributions, questions, and comments are all welcomed and encouraged!

If you want to contribute, follow the [contribution guidelines](./CONTRIBUTING.md) when you open issues or submit pull requests.

## Troubleshooting

Expand Down
Binary file added images/solar_edge.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
44 changes: 44 additions & 0 deletions telegraf/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,50 @@ docker stop influxdb
docker network rm telegraf
```

### InfluxDB

In order to inspect or modify the data stored in the Influx database you can connect directly to the _influxdb_ container and start the [`influx` CLI](https://docs.influxdata.com/influxdb/v1.8/tools/shell/):

```sh
$ balena ssh <app-name> influxdb
? Select a device amazing-smoke (a36de3)
root@265d8274d16b:/# influx
Connected to http://localhost:8086 version 1.8.0
InfluxDB shell version: 1.8.0
```

In order to get human-readable dates use the `precision rfc3339` command:

```sh
> precision rfc3339
> use weather
Using database weather
> show measurements
name: measurements
name
----
humidity
rain
temperature
water-temperature
wind-direction
wind-speed
```

To select the entries of a measurement:

```sh
> SELECT * FROM "water-temperature"
2021-06-18T06:05:05Z DS18B20 22.0625 sensors
...
```

To delete entries from a measurement use te [`DROP SERIES`](https://docs.influxdata.com/influxdb/v1.8/query_language/manage-database/#drop-series-from-the-index-with-drop-series) query:

```sh
> DROP SERIES FROM "water-temperature"
```

## References

* Telegraf [configuration](https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md)
Expand Down

0 comments on commit dbee87d

Please sign in to comment.