From fbc1eb4e318969c587d7870c48799eb26dc92ea9 Mon Sep 17 00:00:00 2001 From: Magnus Persson Date: Fri, 28 Jan 2022 17:15:12 +0100 Subject: [PATCH] Updated docs --- src_docs/source/api.rst | 114 ++++++++++++++++++----------------- src_docs/source/releases.rst | 7 ++- src_docs/source/services.rst | 38 ++++++++++++ 3 files changed, 101 insertions(+), 58 deletions(-) diff --git a/src_docs/source/api.rst b/src_docs/source/api.rst index 0dac7ac..e066dd2 100644 --- a/src_docs/source/api.rst +++ b/src_docs/source/api.rst @@ -128,18 +128,18 @@ Retrive the data used for formula calculation data via an HTTP GET command. Payl POST: /api/config/device ======================== -Used to update device settings via an HTTP POST command. Payload is in JSON format. +Used to update device settings via an HTTP POST command. + +Payload should be in standard format used for posting a form. Such as as: `id=value&mdns=value` etc. Key value pairs are shown below. * ``temp-format`` can be either ``C`` (Celcius) or ``F`` (Farenheight) -.. code-block:: json +.. code-block:: - { - "id": "ee1bfc", - "mdns": "gravmon", - "temp-format": "C", - "sleep-interval": 30 - } + id=ee1bfc + mdns=gravmon + temp-format=C + sleep-interval=30 POST: /api/config/push @@ -147,26 +147,26 @@ POST: /api/config/push Used to update push settings via an HTTP POST command. Payload is in JSON format. -.. code-block:: json +Payload should be in standard format used for posting a form. Such as as: `id=value&mdns=value` etc. Key value pairs are shown below. - { - "id": "ee1bfc", - "http-push": "http://192.168.1.50/ispindel", - "http-push2": "", - "http-push-h1": "", - "http-push-h2": "", - "http-push2-h1": "", - "http-push2-h2": "", - "brewfather-push": "", - "influxdb2-push": "http://192.168.1.50:8086", - "influxdb2-org": "Qwerty", - "influxdb2-bucket": "Qwerty", - "influxdb2-auth": "Qwerty" - "mqtt-push": "192.168.1.50", - "mqtt-port": 1883, - "mqtt-user": "Qwerty", - "mqtt-pass": "Qwerty", - } +.. code-block:: + + id=ee1bfc + http-push=http://192.168.1.50/ispindel + http-push2= + http-push-h1= + http-push-h2= + http-push2-h1= + http-push2-h2= + brewfather-push= + influxdb2-push=http://192.168.1.50:8086 + influxdb2-org= + influxdb2-bucket= + influxdb2-auth= + mqtt-push=192.168.1.50 + mqtt-port=1883 + mqtt-user= + mqtt-pass= POST: /api/config/gravity @@ -181,14 +181,14 @@ Used to update gravity settings via an HTTP POST command. Payload is in JSON for ``gravity-temp-adjustment`` is defined as "on" or "off" when posting since this is the output values from a checkbox, when reading data it's sent as boolean (true,false). -.. code-block:: json +Payload should be in standard format used for posting a form. Such as as: `id=value&mdns=value` etc. Key value pairs are shown below. - { - "id": "ee1bfc", - "gravity-formula": "0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436", - "gravity-format": "P", - "gravity-temp-adjustment": "off" - } +.. code-block:: + + id=ee1bfc + gravity-formula=0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436, + gravity-format=P + gravity-temp-adjustment=off POST: /api/config/hardware @@ -200,15 +200,15 @@ Used to update hardware settings via an HTTP POST command. Payload is in JSON fo ``gyro-temp`` is defined as "on" or "off" when posting since this is the output values from a checkbox, when reading data it's sent as boolean (true,false). -.. code-block:: json +Payload should be in standard format used for posting a form. Such as as: `id=value&mdns=value` etc. Key value pairs are shown below. - { - "id": "ee1bfc", - "voltage-factor": 1.59, - "temp-adjustment": 0, - "gyro-temp": "off", - "ota-url": "http://192.168.1.50/firmware/gravmon/" - } +.. code-block:: + + id=ee1bfc + voltage-factor=1.59 + temp-adjustment=0 + gyro-temp=off + ota-url=http://192.168.1.50/firmware/gravmon/ POST: /api/config/formula @@ -219,21 +219,21 @@ Used to update formula calculation data via an HTTP POST command. Payload is in * ``a1``-``a4`` are the angles/tilt readings (up to 5 are currently supported) * ``g1``-``g4`` are the corresponding gravity reaadings (in SG) -.. code-block:: json +Payload should be in standard format used for posting a form. Such as as: `id=value&mdns=value` etc. Key value pairs are shown below. - { - "id": "ee1bfc", - "a1": 22.4, - "a2": 54.4, - "a3": 58, - "a4": 0, - "a5": 0, - "g1": 1.000, - "g2": 1.053, - "g3": 1.062, - "g4": 1, - "g5": 1 - } +.. code-block:: + + id=ee1bfc + a1=22.4 + a2=54.4 + a3=58 + a4=0 + a5=0 + g1=1.000 + g2=1.053 + g3=1.062 + g4=1 + g5=1 Calling the API's from Python @@ -242,6 +242,8 @@ Calling the API's from Python Here is some example code for how to access the API's from a python script. Keys should always be present or the API call will fail. +The requests package converts the json to standard form post format. + .. code-block:: python import requests diff --git a/src_docs/source/releases.rst b/src_docs/source/releases.rst index 011e2b6..311350d 100644 --- a/src_docs/source/releases.rst +++ b/src_docs/source/releases.rst @@ -6,14 +6,17 @@ Releases v0.8.0 ------ -* Added option to set http headers (2 per endpoint) +* Added option to set http headers (2 per http endpoint) * Added possibility to view last 10 errors on device page. +* Added instructions for how to configure integration with Fermentrack +* Added instructions for how to configure integration with Ubidots +* Added instructions for how to configure integration with HomeAssistant v0.7.1 ------ * Defined mqtt port was ignored, used default values. -* Extended length of HTTP url fields from 100 to 120 chars. +* Extended length of HTTP url fields from 100 to 120 chars. v0.7.0 ------ diff --git a/src_docs/source/services.rst b/src_docs/source/services.rst index 69e3166..7ce6aac 100644 --- a/src_docs/source/services.rst +++ b/src_docs/source/services.rst @@ -28,6 +28,7 @@ GravityMon can be installed and used as an iSpindle. Just register the device as http://myservername/ispindel + UBIdots +++++++ @@ -79,3 +80,40 @@ format template that can be used. For information on customizing the format see "rssi": ${rssi} } + +Home Assistant ++++++++++++++++ + +`HomeAssistant `_ is a platform for home automation and can collect sensor data +from multiple devices. + +This setup uses the MQTT integration with home assistant to collect values from the device. + +This part of the configuration goes into the home assistant configuration.yaml file. The example assumes that the +device is named `gravmon2` + +:: + + sensor: + - platform: mqtt + name: "gravmon2_gravity" + state_topic: "gravmon/gravmon2/gravity" + - platform: mqtt + name: "gravmon2_battery" + state_topic: "gravmon/gravmon2/battery" + - platform: mqtt + name: "gravmon2_rssi" + state_topic: "gravmon/gravmon2/rssi" + + +Enter the name of the MQTT server in Home Assistant in the URL. You might need to install that option +first. This is the format needed to submit the data to the correct topics as needed above. You can add as +many sensors / topics as you want. + +:: + + gravmon/${mdns}/tilt:${angle}| + gravmon/${mdns}/temperature:${temp}| + gravmon/${mdns}/temp_units:${temp-unit}| + +