diff --git a/README.md b/README.md index 4caa76b..085322d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,188 @@ # flowercare -A python script which reads the values of configured flowercare sensors periodically and sends them via mqtt +A python script which reads the values of configured flowercare sensors periodically and sends them via mqtt. + +## Basic features + +* Fetch values either for one or multiple sensors in a configurable interval +* Read temperature, moisture, light, conductivity and battery values +* Send the data to one topic per sensor +* Configure a different interval either per sensor or per value of a sensor +* Resend the last fetched value if only other values are currently fetched for a sensor + +## Basic setup + +First we clone the repository, then we install some packages and register the system service. + +### Clone repository + +You can install the script to any directory you like. Only make sure to replace the path in the service file later! + +```bash +git clone https://github.com/Tom-Hirschberger/flowercare.git +``` + +### Python packages + +```bash +sudo pip3 install miflora +sudo pip3 install bluepy +sudo pip3 install paho-mqtt +sudo pip3 install json5 +``` + +### System service + +A service file to register the script as systemd service is included in this repository. +**Make sure to replace the user and the paths with the ones in your setup!** + +Copy the service file to systemd directory: + +```bash +sudo cp flowercare.service /etc/systemd/system/ +``` + +Register the service to autostart: + +```bash +sudo systemctl enable flowercare.service +``` + +After you created the flowercare.json file (or a other named file if you replaced the name in the service file) you can control the service with the following commands: + +Start: + +```bash +sudo systemctl start flowercare.service +``` + +Stop: + +```bash +sudo systemctl stop flowercare.service +``` + +Status: + +```bash +sudo systemctl status flowercare.service +``` + +## Configuration + +The configuration is structured in different parts: "general", "mqtt" an "sensors". + +You will learn to find your sensors and how to configure the differnt sections. You can use the example configuration ([flowercare.json.example](./flowercare.json.example)) as a start. + +### Find the addresses of your sensors + +First we need to know the mac addresses of the sensors (basically the bluetooth hardware address). Credits to [https://tutorials-raspberrypi.de](https://tutorials-raspberrypi.de/raspberry-pi-miflora-xiaomi-pflanzensensor-openhab/). +Enable bluetooth on your divice and use the following command to search for your sensors: + +```bash +sudo hcitool lescan +``` + +The output will look something like: + +```bash +LE Scan ... +C4:7C:8D:66:1A:C3 (unknown) +C4:7C:8D:66:1A:C3 Flower care +D4:36:39:C7:DB:BD (unknown) +``` + +The ones with name "Flower care" are the ones we need the addresses of. + +### General section + +| Option | Description | Type | Default +|-------- | ----------- | ---- | ------- +| sleep | The time between intervals of fetching new values in seconds. Be careful with fetching the values to often. Fetching the values costs a lot of energy and the battery will be drained very quickly if the interval is to small. | Integer | 1800 | +| resendValueOnPartialSkip | It is possible to fetch values of sensors in different intervals than the general "beat" of the module. If no new values are fetched but you want to send a output via MQTT that contains all keys you can send the last fetched values instead. | Boolean | True | + +### MQTT section + +| Option | Description | Type | Mandatory | Default | +|-------- | ----------- | ---- | --------- | ------- | +| clientName | The name that will be used to register this client to the MQTT broker. | String | true | None | +| host | The hostname or IP of the MQTT broker. | String | true | None | +| port | The network port of the MQTT broker. Usally 1883. | Integer | true | None | +| username | The username to connect to the MQTT broker. | String | false | None | +| password | The password to connect to the MQTT broker. | String | false | None | + +### Sensors section + +| Option | Description | Type | Mandatory | Default | +|-------- | ----------- | ---- | --------- | ------- | +| topic | The MQTT topic the result object should be send to. | String | true | None | +| name | The name of the sensor. Currently this value will be used for debug output only. | String | true | None | +| mac | The bluetooth address of the sensor. | String | true | None | +| readTemperature | Should the temperature value be fetched? | Boolean | false | false | +| readMoisture | Should the moisture value be fetched? | Boolean | false | false | +| readLight | Should the light value be fetched? | Boolean | false | false | +| readConductivity | Should the conductivity value be fetched? | Boolean | false | false | +| readBattery | Should the battery value be fetched? | Boolean | false | false | +| interval | Normally all sensors get fetched after each sleep. You can change this behavior with this option. See the "inveral" section for all options | Integer or Dictionary | 1 | + +#### interval + +The interval to fetch the values of a sensor can either be a simple Integer (which it is in default with value 1) or a dictionary. If it is set to a interger all enabled values (read...) will be fetched each "interval" times. + +The dictionary can contain a differnt interval for each value. Meaning you can fetch i.e. the light value more often than i.e. the battery level. + +| Option | Description | Type | Mandatory | Default | +|-------- | ----------- | ---- | --------- | ------- | +| temperature | The interval of the temperature value. | Integer | false | 1 | +| moisture | The interval of the moisture value. | Integer | false | 1 | +| light | The interval of the light value. | Integer | false | 1 | +| conductivity | The interval of the conductivity value. | Integer | false | 1 | +| battery | The interval of the battery value. | Integer | false | 1 | + + +### Example + +The following example contains all possible configuration options: + +```json +{ + "general": { + "sleep": 1800, + "resendValueOnPartialSkip": true + }, + "mqtt": { + "clientName": "mirroreg-flowercare", + "host": "10.1.1.1", + "port": 1883, + "username": "test", + "password": "test123" + }, + "sensors": [ + { + "topic": "flowercare/flowerone", + "interval": 1, + "name": "flowerone", + "mac": "AA:BB:CC:DD:EE:FF", + "readTemperature": true, + "readMoisture": true, + "readLight": false, + "readConductivity": false, + "readBattery": true + }, + { + "topic": "flowercare/flowertwo", + "interval": { + "temperture": 1, + "moisture": 2, + "battery": 5 + }, + "name": "flowertwo", + "mac": "AA:BB:CC:AA:BB:CC", + "readTemperature": true, + "readMoisture": true, + "readBattery": true + } + ] +} +``` +>>>>>>> main diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..8a9ecc2 --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.0.1 \ No newline at end of file diff --git a/flowercare.json.example b/flowercare.json.example index 9a6d822..0d75032 100644 --- a/flowercare.json.example +++ b/flowercare.json.example @@ -33,7 +33,7 @@ "moisture": 2, "battery": 5 }, - "name": "flowerone", + "name": "flowertwo", "mac": "AA:BB:CC:AA:BB:CC", "readTemperature": true, "readMoisture": true, diff --git a/flowercare.py b/flowercare.py index 7632c1e..48d068a 100755 --- a/flowercare.py +++ b/flowercare.py @@ -147,4 +147,4 @@ def restoreSkipConfig(intervalConfig=0, key=None): except: pass - time.sleep(config["general"]["sleep"]) + time.sleep(config.get("general",{}).get("sleep",1800))