Updated docs for 0.8
This commit is contained in:
Magnus Persson
parent
63fd80e750
commit
9a2f86fed7
@ -1 +1 @@
|
||||
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta name="description" content=""><title>Beer Gravity Monitor</title><link href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous"><script src="https://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script><script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js" crossorigin="anonymous"></script></head><body class="py-4"><!-- START MENU --><nav class="navbar navbar-expand-sm navbar-dark bg-primary"><a class="navbar-brand" href="/index.htm">Beer Gravity Monitor</a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation"><span class="navbar-toggler-icon"></span></button><div class="collapse navbar-collapse" id="navbar"><ul class="navbar-nav mr-auto"><li class="nav-item"><a class="nav-link" href="/index.htm">Home <span class="sr-only">(current)</span></a></li><li class="nav-item active"><a class="nav-link" href="/device.htm">Device</a></li><li class="nav-item"><a class="nav-link" href="/config.htm">Configuration</a></li><li class="nav-item"><a class="nav-link" href="/calibration.htm">Calibration</a></li><li class="nav-item"><a class="nav-link" href="/about.htm">About</a></li></ul></div><div class="spinner-border text-light" id="spinner" role="status"></div></nav><!-- START MAIN INDEX --><div class="container"><hr class="my-4"><div class="alert alert-success alert-dismissible fade hide show d-none" role="alert" id="alert"><div id="alert-msg">...</div><button type="button" id="alert-btn" class="close" aria-label="Close"><span aria-hidden="true">×</span></button></div><script type="text/javascript">function showError(s){$(".alert").removeClass("alert-success").addClass("alert-danger").removeClass("d-none").addClass("show"),$("#alert-msg").text(s)}function showSuccess(s){$(".alert").addClass("alert-success").removeClass("alert-danger").removeClass("d-none").addClass("show"),$("#alert-msg").text(s)}$("#alert-btn").click(function(s){$(".alert").addClass("d-none").removeClass("show")})</script><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Current version:</div><div class="col-md-4 themed-grid-col bg-light" id="app-ver">Loading...</div></div><div class="row mb-3" id="h-app-ver-new" hidden><div class="col-md-8 themed-grid-col bg-light">New version:</div><div class="col-md-4 themed-grid-col bg-light" id="app-ver-new">Loading...</div></div><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Host name:</div><div class="col-md-4 themed-grid-col bg-light" id="mdns">Loading...</div></div><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Device ID:</div><div class="col-md-4 themed-grid-col bg-light" id="id">Loading...</div></div><div class="row mb-3"><a class="badge badge-primary" data-toggle="collapse" href="#collapseLog" role="button" aria-expanded="false" aria-controls="collapseLog" id="log-btn">View error log</a></div><script>function loadLog(){$("#logContent").load("/log")}$("#log-btn").click(function(o){loadLog()}),setInterval(function(){loadLog()},3e3)</script><div class="collapse" id="collapseLog"><div class="card card-body"><pre><code id="logContent"></code></pre></div></div><hr class="my-4"></div><script type="text/javascript">function getConfig(){var n="/api/device";$("#spinner").show(),$.getJSON(n,function(n){console.log(n),$("#app-ver").text(n["app-ver"]+" (html 0.7.0)"),$("#mdns").text(n.mdns),$("#id").text(n.id)}).fail(function(){showError("Unable to get data from the device.")}).always(function(){$("#spinner").hide()})}window.onload=getConfig</script><!-- START FOOTER --><div class="container-fluid themed-container bg-primary text-light">(C) Copyright 2021-22 Magnus Persson</div></body></html>
|
||||
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta name="description" content=""><title>Beer Gravity Monitor</title><link href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous"><script src="https://code.jquery.com/jquery-3.6.0.min.js" integrity="sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" crossorigin="anonymous"></script><script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js" crossorigin="anonymous"></script></head><body class="py-4"><!-- START MENU --><nav class="navbar navbar-expand-sm navbar-dark bg-primary"><a class="navbar-brand" href="/index.htm">Beer Gravity Monitor</a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation"><span class="navbar-toggler-icon"></span></button><div class="collapse navbar-collapse" id="navbar"><ul class="navbar-nav mr-auto"><li class="nav-item"><a class="nav-link" href="/index.htm">Home <span class="sr-only">(current)</span></a></li><li class="nav-item active"><a class="nav-link" href="/device.htm">Device</a></li><li class="nav-item"><a class="nav-link" href="/config.htm">Configuration</a></li><li class="nav-item"><a class="nav-link" href="/calibration.htm">Calibration</a></li><li class="nav-item"><a class="nav-link" href="/about.htm">About</a></li></ul></div><div class="spinner-border text-light" id="spinner" role="status"></div></nav><!-- START MAIN INDEX --><div class="container"><hr class="my-4"><div class="alert alert-success alert-dismissible fade hide show d-none" role="alert" id="alert"><div id="alert-msg">...</div><button type="button" id="alert-btn" class="close" aria-label="Close"><span aria-hidden="true">×</span></button></div><script type="text/javascript">function showError(s){$(".alert").removeClass("alert-success").addClass("alert-danger").removeClass("d-none").addClass("show"),$("#alert-msg").text(s)}function showSuccess(s){$(".alert").addClass("alert-success").removeClass("alert-danger").removeClass("d-none").addClass("show"),$("#alert-msg").text(s)}$("#alert-btn").click(function(s){$(".alert").addClass("d-none").removeClass("show")})</script><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Current version:</div><div class="col-md-4 themed-grid-col bg-light" id="app-ver">Loading...</div></div><div class="row mb-3" id="h-app-ver-new" hidden><div class="col-md-8 themed-grid-col bg-light">New version:</div><div class="col-md-4 themed-grid-col bg-light" id="app-ver-new">Loading...</div></div><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Host name:</div><div class="col-md-4 themed-grid-col bg-light" id="mdns">Loading...</div></div><div class="row mb-3"><div class="col-md-8 themed-grid-col bg-light">Device ID:</div><div class="col-md-4 themed-grid-col bg-light" id="id">Loading...</div></div><div class="row mb-3"><a class="badge badge-primary" data-toggle="collapse" href="#collapseLog" role="button" aria-expanded="false" aria-controls="collapseLog" id="log-btn">View error log</a></div><script>function loadLog(){$("#logContent").load("/log")}$("#log-btn").click(function(o){loadLog()}),setInterval(function(){loadLog()},3e3)</script><div class="collapse" id="collapseLog"><div class="card card-body"><pre><code id="logContent"></code></pre></div></div><hr class="my-4"></div><script type="text/javascript">function getConfig(){var n="/api/device";$("#spinner").show(),$.getJSON(n,function(n){console.log(n),$("#app-ver").text(n["app-ver"]+" (html 0.7.9)"),$("#mdns").text(n.mdns),$("#id").text(n.id)}).fail(function(){showError("Unable to get data from the device.")}).always(function(){$("#spinner").hide()})}window.onload=getConfig</script><!-- START FOOTER --><div class="container-fluid themed-container bg-primary text-light">(C) Copyright 2021-22 Magnus Persson</div></body></html>
|
||||
@ -34,7 +34,7 @@ build_flags =
|
||||
-D EMBED_HTML # If this is not used the html files needs to be on the file system (can be uploaded)
|
||||
-D USER_SSID=\""\"" # =\""myssid\""
|
||||
-D USER_SSID_PWD=\""\"" # =\""mypwd\""
|
||||
-D CFG_APPVER="\"0.7.0\""
|
||||
-D CFG_APPVER="\"0.7.9\""
|
||||
lib_deps = # Switched to forks for better version control.
|
||||
# Using local copy of these libraries
|
||||
#https://github.com/jrowberg/i2cdevlib.git#<document>
|
||||
|
||||
@ -29,7 +29,7 @@ SOFTWARE.
|
||||
|
||||
#define CFG_JSON_BUFSIZE 3192
|
||||
|
||||
#define CFG_APPNAME "GravityMon " // Name of firmware
|
||||
#define CFG_APPNAME "GravityMon" // Name of firmware
|
||||
#define CFG_FILENAME "/gravitymon.json" // Name of config file
|
||||
#define CFG_HW_FILENAME "/hardware.json" // Name of config file for hw
|
||||
|
||||
|
||||
92
src_docs/source/advanced.rst
Normal file
92
src_docs/source/advanced.rst
Normal file
@ -0,0 +1,92 @@
|
||||
Advanced Configuration
|
||||
######################
|
||||
|
||||
.. _format-editor:
|
||||
|
||||
Format editor
|
||||
+++++++++++++
|
||||
|
||||
To reduce the need for adding custom endpoints for various services there is an built in format editor that allows the user to customize the format being sent to the push target.
|
||||
|
||||
.. warning::
|
||||
|
||||
Since the format templates can be big this function can be quite slow on a small device such as the esp8266.
|
||||
|
||||
.. image:: images/format.png
|
||||
:width: 800
|
||||
:alt: Format editor
|
||||
|
||||
You enter the format data in the text field and the test button will show an example on what the output would look like. If the data cannot be formatted in json it will just be displayed as a long string.
|
||||
The save button will save the current formla and reload the data from the device.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you save a blank string the default template will be loaded.
|
||||
|
||||
These are the format keys available for use in the format.
|
||||
|
||||
.. list-table:: Directory structure
|
||||
:widths: 30 50 20
|
||||
:header-rows: 1
|
||||
|
||||
* - key
|
||||
- description
|
||||
- example
|
||||
* - ${mdns}
|
||||
- Name of the device
|
||||
- gravmon2
|
||||
* - ${id}
|
||||
- Unique id of the device
|
||||
- e422a3
|
||||
* - ${sleep-interval}
|
||||
- Seconds between data is pushed
|
||||
- 900
|
||||
* - ${temp}
|
||||
- Temperature in format configured on device, one decimal
|
||||
- 21.2
|
||||
* - ${temp-c}
|
||||
- Temperature in C, one decimal
|
||||
- 21.2
|
||||
* - ${temp-f}
|
||||
- Temperature in F, one decimal
|
||||
- 58.0
|
||||
* - ${temp-unit}
|
||||
- Temperature format `C` or `F`
|
||||
- C
|
||||
* - ${battery}
|
||||
- Battery voltage, two decimals
|
||||
- 3.89
|
||||
* - ${rssi}
|
||||
- Wifi signal strength
|
||||
- -75
|
||||
* - ${run-time}
|
||||
- How long the last measurement took, two decimals
|
||||
- 3.87
|
||||
* - ${angle}
|
||||
- Angle of the gyro, two decimals
|
||||
- 28.67
|
||||
* - ${tilt}
|
||||
- Same as angle.
|
||||
- 28.67
|
||||
* - ${gravity}
|
||||
- Calculated gravity, 4 decimals for SG and 1 for Plato.
|
||||
- 1.0456
|
||||
* - ${gravity-sg}
|
||||
- Calculated gravity in SG, 4 decimals
|
||||
- 1.0456
|
||||
* - ${gravity-plato}
|
||||
- Calculated gravity in Plato, 1 decimal
|
||||
- 8.5
|
||||
* - ${corr-gravity}
|
||||
- Temperature corrected gravity, 4 decimals for SG and 1 for Plato.
|
||||
- 1.0456
|
||||
* - ${corr-gravity-sg}
|
||||
- Temperature corrected gravity in SG, 4 decimals
|
||||
- 1.0456
|
||||
* - ${corr-gravity-plato}
|
||||
- Temperature corrected gravity in Plato, 1 decimal
|
||||
- 8.5
|
||||
* - ${gravity-unit}
|
||||
- Gravity format, `G` or `P`
|
||||
- G
|
||||
|
||||
320
src_docs/source/api.rst
Normal file
320
src_docs/source/api.rst
Normal file
@ -0,0 +1,320 @@
|
||||
.. _rest-api:
|
||||
|
||||
REST API
|
||||
########
|
||||
|
||||
All the API's use a key called ``ID`` which is the unique device id (chip id). This is used as an API key when sending requests to the device.
|
||||
|
||||
GET: /api/config
|
||||
================
|
||||
|
||||
Retrive the current configuation of the device via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` or ``F``
|
||||
* ``gravity-format`` is always ``G`` (plato is not yet supported)
|
||||
|
||||
Other parameters are the same as in the configuration guide.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"mdns": "gravmon",
|
||||
"id": "ee1bfc",
|
||||
"ota-url": "http://192.168.1.50:80/firmware/gravmon/",
|
||||
"temp-format": "C",
|
||||
"brewfather-push": "http://log.brewfather.net/stream?id=Qwerty",
|
||||
"http-push": "http://192.168.1.50:9090/api/v1/Qwerty/telemetry",
|
||||
"http-push-h1": "header: value",
|
||||
"http-push-h2": "header: value",
|
||||
"http-push2": "http://192.168.1.50/ispindel",
|
||||
"http-push2-h1": "header: value",
|
||||
"http-push2-h2": "header: value",
|
||||
"influxdb2-push": "http://192.168.1.50:8086",
|
||||
"influxdb2-org": "org",
|
||||
"influxdb2-bucket": "bucket_id",
|
||||
"influxdb2-auth": "token",
|
||||
"mqtt-push": "192.168.1.50",
|
||||
"mqtt-port": 1883,
|
||||
"mqtt-user": "user",
|
||||
"mqtt-pass": "pass",
|
||||
"sleep-interval": 30,
|
||||
"voltage-factor": 1.59,
|
||||
"gravity-formula": "0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436",
|
||||
"gravity-format": "G",
|
||||
"temp-adjustment-value": 0,
|
||||
"gravity-temp-adjustment": false,
|
||||
"gyro-temp": true,
|
||||
"gyro-calibration-data": {
|
||||
"ax": -330,
|
||||
"ay": -2249,
|
||||
"az": 1170,
|
||||
"gx": 99,
|
||||
"gy": -6,
|
||||
"gz": 4
|
||||
},
|
||||
"angle": 90.93,
|
||||
"gravity": 1.105,
|
||||
"battery": 0.04
|
||||
}
|
||||
|
||||
|
||||
GET: /api/device
|
||||
================
|
||||
|
||||
Retrive the current device settings via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"app-name": "GravityMon",
|
||||
"app-ver": "0.0.0",
|
||||
"id": "ee1bfc",
|
||||
"mdns": "gravmon"
|
||||
}
|
||||
|
||||
|
||||
GET: /api/status
|
||||
================
|
||||
|
||||
Retrive the current device status via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` or ``F``
|
||||
|
||||
Other parameters are the same as in the configuration guide.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"id": "ee1bfc",
|
||||
"angle": 89.86,
|
||||
"gravity": 1.1052,
|
||||
"gravity-tempcorr": 1.1031,
|
||||
"temp-c": 0,
|
||||
"temp-f": 32,
|
||||
"battery": 0,
|
||||
"temp-format": "C",
|
||||
"sleep-mode": false,
|
||||
"rssi": -56
|
||||
}
|
||||
|
||||
|
||||
GET: /api/config/formula
|
||||
========================
|
||||
|
||||
Retrive the data used for formula calculation data via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``a1``-``a4`` are the angles/tilt readings (up to 5 are currently supported)
|
||||
* ``g1``-``g4`` are the corresponding gravity reaadings in SG or Plato depending on the device-format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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,
|
||||
"gravity-format": "G",
|
||||
"gravity-formula": "0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436"
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/device
|
||||
========================
|
||||
|
||||
Used to update device settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` (Celcius) or ``F`` (Farenheight)
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"id": "ee1bfc",
|
||||
"mdns": "gravmon",
|
||||
"temp-format": "C",
|
||||
"sleep-interval": 30
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/push
|
||||
======================
|
||||
|
||||
Used to update push settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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",
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/gravity
|
||||
=========================
|
||||
|
||||
Used to update gravity settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``gravity-formula`` keywords ``temp`` and ``tilt`` are supported.
|
||||
* ``gravity-format`` can be either ``G`` (SG) or ``P`` (PLATO)
|
||||
|
||||
.. note::
|
||||
``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
|
||||
|
||||
{
|
||||
"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
|
||||
==========================
|
||||
|
||||
Used to update hardware settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
.. note::
|
||||
``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
|
||||
|
||||
{
|
||||
"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
|
||||
=========================
|
||||
|
||||
Used to update formula calculation data via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``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
|
||||
|
||||
{
|
||||
"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
|
||||
=============================
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import requests
|
||||
import json
|
||||
|
||||
host = "192.168.1.1" # IP adress (or name) of the device to send these settings to
|
||||
id = "ee1bfc" # Device ID (shown in serial console during startup or in UI)
|
||||
|
||||
def set_config( url, json ):
|
||||
headers = { "ContentType": "application/json" }
|
||||
print( url )
|
||||
resp = requests.post( url, headers=headers, data=json )
|
||||
if resp.status_code != 200 :
|
||||
print ( "Failed " )
|
||||
else :
|
||||
print ( "Success " )
|
||||
|
||||
url = "http://" + host + "/api/config/device"
|
||||
json = { "id": id,
|
||||
"mdns": "gravmon", # Name of the device
|
||||
"temp-format": "C", # Temperature format C or F
|
||||
"sleep-interval": 30 # Sleep interval in seconds
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/push"
|
||||
json = { "id": id,
|
||||
"http-push": "http://192.168.1.1/ispindel",
|
||||
"http-push2": "",
|
||||
"http-push-h1": "",
|
||||
"http-push-h2": "",
|
||||
"http-push2-h1": "",
|
||||
"http-push2-h2": "",
|
||||
"brewfather-push": "",
|
||||
"influxdb2-push": "",
|
||||
"influxdb2-org": "",
|
||||
"influxdb2-bucket": "",
|
||||
"influxdb2-auth": "",
|
||||
"mqtt-push": "192.168.1.50",
|
||||
"mqtt-port": 1883,
|
||||
"mqtt-user": "Qwerty",
|
||||
"mqtt-pass": "Qwerty"
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/gravity"
|
||||
json = { "id": id,
|
||||
"gravity-formula": "",
|
||||
"gravity-format": "P",
|
||||
"gravity-temp-adjustment": "off" # Adjust gravity (on/off)
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/hardware"
|
||||
json = { "id": id,
|
||||
"voltage-factor": 1.59, # Default value for voltage calculation
|
||||
"temp-adjustment": 0, # If temp sensor needs to be corrected
|
||||
"gyro-temp": "on", # Use the temp sensor in the gyro instead (on/off)
|
||||
"ota-url": "" # if the device should seach for a new update when active
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/formula"
|
||||
json = { "id": id,
|
||||
"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
|
||||
}
|
||||
set_config( url, json )
|
||||
@ -1,20 +0,0 @@
|
||||
Backlog of changes
|
||||
##################
|
||||
|
||||
This is a list of potential ideas to implemnt in the software.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
- Write contribution instructions
|
||||
- Example project for creating integrations and instructions
|
||||
- Add instructions for other services
|
||||
|
||||
Code
|
||||
----
|
||||
|
||||
- Support for plato
|
||||
- Use pre-commit for validating check-in
|
||||
- Show indicated battery life based on interval (check if its feasable)
|
||||
- Add possibility to add one certificate for proper SSL authentication.
|
||||
- Add configurable Authentication/Token header to http/https requests
|
||||
@ -22,7 +22,7 @@ copyright = '2021-2022, Magnus Persson'
|
||||
author = 'Magnus Persson'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '0.7.0'
|
||||
release = '0.8.0'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
.. _setting-up-device:
|
||||
|
||||
Setting up device
|
||||
#################
|
||||
Configuration
|
||||
#############
|
||||
|
||||
The device can operate in two modes and must be in ``configuration mode`` in order for the web server to be active.
|
||||
|
||||
@ -41,8 +41,10 @@ URL: (http://gravmon.local/device)
|
||||
:width: 800
|
||||
:alt: Device Settings
|
||||
|
||||
The button `view error log` will show the last 15 errors on the device. This can be useful for checking errors without
|
||||
the need to connect to the serial port.
|
||||
.. tip::
|
||||
|
||||
The button `view error log` will show the last 15 errors on the device. This can be useful for checking errors without
|
||||
the need to connect to the serial port or to check what errors has occured while in `gravity mode`.
|
||||
|
||||
* **Version:**
|
||||
|
||||
@ -50,11 +52,12 @@ the need to connect to the serial port.
|
||||
|
||||
* **Device name:**
|
||||
|
||||
This is unique name of the device.
|
||||
This is unique name of the device which is set in the configuration, also known as MDNS name.
|
||||
|
||||
* **Device ID:**
|
||||
|
||||
This is unique identifier for the device (ESP8266 id), this is required when using the API as an API Key to safeguard against faulty requests.
|
||||
This is unique identifier for the device (ESP8266 id), this is required when using the API as an API Key to safeguard
|
||||
against faulty requests. This is the ESP8266 chip ID, so it should be unique.
|
||||
|
||||
|
||||
Configuration
|
||||
@ -75,15 +78,19 @@ Device Setting
|
||||
|
||||
* **Temperature format:**
|
||||
|
||||
Choose between Celsius and Farenheight
|
||||
Choose between Celsius and Farenheight when displaying temperature.
|
||||
|
||||
* **Interval:**
|
||||
|
||||
This defines how long the device should be sleeping between the readings when in `gravity monitoring` mode. You will also see the values in minutes/seconds to easier set the interval. 900s is a recommended interval.
|
||||
This defines how long the device should be sleeping between the readings when in `gravity monitoring` mode. You will also see
|
||||
the values in minutes/seconds to easier set the interval. 900s is a recommended interval. The sleep interval can
|
||||
be set between 10 - 3600 seconds (60 minutes).
|
||||
|
||||
.. note::
|
||||
|
||||
The sleep interval can be set between 10 - 3600 seconds (60 minutes).
|
||||
A low value such as 30s will give a lifespan of 1-2 weeks and 300s (5 min) would last for 3+ weeks. This assumes that
|
||||
there is good wifi connection that takes less than 1s to reconnect. Poor wifi connection is the main reason for battery drain.
|
||||
|
||||
|
||||
* **Calibration values:**
|
||||
|
||||
@ -164,13 +171,21 @@ Push Settings
|
||||
:width: 300
|
||||
:alt: HTTP Headers
|
||||
|
||||
Its now possible to define 2 http headers per push target. This is avaialble via a pop-up window but dont forget
|
||||
to press the save buttons on the post section to save the values.
|
||||
You can define 2 http headers per push target. This is available via a pop-up window but dont forget
|
||||
to press the save buttons on the post section to save the values. One common header is content type which is the
|
||||
default setting for http targets.
|
||||
|
||||
Mozilla has a good guide on what options exist; `HTTP Headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers>`_
|
||||
Refer to the documentation on what headers would be needed for a specific service target.
|
||||
The input must have the format **'<header>: <value>'** for it to work. The UI will accept any value so errors
|
||||
will not show until the device tries to push data.
|
||||
|
||||
|
||||
::
|
||||
|
||||
Content-Type: application/json
|
||||
X-Auth-Token: <api-token>
|
||||
|
||||
|
||||
Mozilla has a good guide on what headers are valid; `HTTP Headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers>`_
|
||||
|
||||
|
||||
Gravity Settings
|
||||
@ -182,16 +197,20 @@ Gravity Settings
|
||||
|
||||
* **Gravity format:**
|
||||
|
||||
Gravity format can be eihter `SG` or `Plato`. The device will use SG Internally and convert to Plato when displaying data.
|
||||
Gravity format can be eihter `SG` or `Plato`. The device will use SG Internally and convert to Plato when displaying or sending data.
|
||||
|
||||
* **Gravity formula:**
|
||||
|
||||
Gravity formula is compatible with standard iSpindle formulas so any existing calculation option can be used. You can also use
|
||||
the feature to create the formula by supplying the raw data. See :ref:`create-formula`
|
||||
|
||||
The gravity formula accepts to paramaters, **tilt** for the angle or **temp** for temperature (temperature inserted into the formula
|
||||
will be in celsius). I would recommend to use the formula calculation feature instead since this is much easier.
|
||||
|
||||
* **Temperature correct gravity:**
|
||||
|
||||
Will apply a temperature calibration formula to the gravity as a second step.
|
||||
Will apply a temperature calibration formula to the gravity as a second step after gravity has been calculated. It's also possible to
|
||||
build this into the gravity formula.
|
||||
|
||||
.. warning::
|
||||
This formula assumes that the calibration has been done at 20°C / 68°F.
|
||||
@ -229,7 +248,7 @@ Hardware Settings
|
||||
|
||||
* **OTA URL:**
|
||||
|
||||
Should point to a URL where the .bin file + version.json file is located.
|
||||
Should point to a URL where the firmware.bin file + version.json file are located.
|
||||
|
||||
For the OTA to work, place the following files (version.json + firmware.bin) at the location that you pointed out in OTA URL. If the version number in the json file is newer than in the
|
||||
code the update will be done during startup.
|
||||
@ -243,588 +262,3 @@ Hardware Settings
|
||||
http://192.168.1.1/firmware/gravmon/
|
||||
|
||||
|
||||
.. _format-editor:
|
||||
|
||||
Format editor
|
||||
#############
|
||||
|
||||
To reduce the need for adding custom endpoints for various services there is an built in format editor that allows the user to customize the format being sent to the push target.
|
||||
|
||||
.. warning::
|
||||
|
||||
Since the format templates can be big this function can be quite slow on a small device such as the esp8266.
|
||||
|
||||
.. image:: images/format.png
|
||||
:width: 800
|
||||
:alt: Format editor
|
||||
|
||||
You enter the format data in the text field and the test button will show an example on what the output would look like. If the data cannot be formatted in json it will just be displayed as a long string.
|
||||
The save button will save the current formla and reload the data from the device.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you save a blank string the default template will be loaded.
|
||||
|
||||
These are the format keys available for use in the format.
|
||||
|
||||
.. list-table:: Directory structure
|
||||
:widths: 30 50 20
|
||||
:header-rows: 1
|
||||
|
||||
* - key
|
||||
- description
|
||||
- example
|
||||
* - ${mdns}
|
||||
- Name of the device
|
||||
- gravmon2
|
||||
* - ${id}
|
||||
- Unique id of the device
|
||||
- e422a3
|
||||
* - ${sleep-interval}
|
||||
- Seconds between data is pushed
|
||||
- 900
|
||||
* - ${temp}
|
||||
- Temperature in format configured on device, one decimal
|
||||
- 21.2
|
||||
* - ${temp-c}
|
||||
- Temperature in C, one decimal
|
||||
- 21.2
|
||||
* - ${temp-f}
|
||||
- Temperature in F, one decimal
|
||||
- 58.0
|
||||
* - ${temp-unit}
|
||||
- Temperature format `C` or `F`
|
||||
- C
|
||||
* - ${battery}
|
||||
- Battery voltage, two decimals
|
||||
- 3.89
|
||||
* - ${rssi}
|
||||
- Wifi signal strength
|
||||
- -75
|
||||
* - ${run-time}
|
||||
- How long the last measurement took, two decimals
|
||||
- 3.87
|
||||
* - ${angle}
|
||||
- Angle of the gyro, two decimals
|
||||
- 28.67
|
||||
* - ${tilt}
|
||||
- Same as angle.
|
||||
- 28.67
|
||||
* - ${gravity}
|
||||
- Calculated gravity, 4 decimals for SG and 1 for Plato.
|
||||
- 1.0456
|
||||
* - ${gravity-sg}
|
||||
- Calculated gravity in SG, 4 decimals
|
||||
- 1.0456
|
||||
* - ${gravity-plato}
|
||||
- Calculated gravity in Plato, 1 decimal
|
||||
- 8.5
|
||||
* - ${corr-gravity}
|
||||
- Temperature corrected gravity, 4 decimals for SG and 1 for Plato.
|
||||
- 1.0456
|
||||
* - ${corr-gravity-sg}
|
||||
- Temperature corrected gravity in SG, 4 decimals
|
||||
- 1.0456
|
||||
* - ${corr-gravity-plato}
|
||||
- Temperature corrected gravity in Plato, 1 decimal
|
||||
- 8.5
|
||||
* - ${gravity-unit}
|
||||
- Gravity format, `G` or `P`
|
||||
- G
|
||||
|
||||
|
||||
.. _create-formula:
|
||||
|
||||
Create formula
|
||||
##############
|
||||
|
||||
.. image:: images/formula1.png
|
||||
:width: 800
|
||||
:alt: Formula data
|
||||
|
||||
Here you can enter up to 5 values (angles + gravity) that is then used to create the formula. Angles equal to zero will be regarded as empty even if there is a gravity reading.
|
||||
|
||||
.. image:: images/formula2.png
|
||||
:width: 800
|
||||
:alt: Formula graph
|
||||
|
||||
Once the formula is created a graph over the entered values and a simulation of the formula will give you a nice overview on how the formula will work.
|
||||
|
||||
.. _rest-api:
|
||||
|
||||
REST API
|
||||
########
|
||||
|
||||
All the API's use a key called ``ID`` which is the unique device id (chip id). This is used as an API key when sending requests to the device.
|
||||
|
||||
GET: /api/config
|
||||
================
|
||||
|
||||
Retrive the current configuation of the device via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` or ``F``
|
||||
* ``gravity-format`` is always ``G`` (plato is not yet supported)
|
||||
|
||||
Other parameters are the same as in the configuration guide.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"mdns": "gravmon",
|
||||
"id": "ee1bfc",
|
||||
"ota-url": "http://192.168.1.50:80/firmware/gravmon/",
|
||||
"temp-format": "C",
|
||||
"brewfather-push": "http://log.brewfather.net/stream?id=Qwerty",
|
||||
"http-push": "http://192.168.1.50:9090/api/v1/Qwerty/telemetry",
|
||||
"http-push-h1": "",
|
||||
"http-push-h2": "",
|
||||
"http-push2": "http://192.168.1.50/ispindel",
|
||||
"http-push2-h1": "",
|
||||
"http-push2-h2": "",
|
||||
"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",
|
||||
"sleep-interval": 30,
|
||||
"voltage-factor": 1.59,
|
||||
"gravity-formula": "0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436",
|
||||
"gravity-format": "G",
|
||||
"temp-adjustment-value": 0,
|
||||
"gravity-temp-adjustment": false,
|
||||
"gyro-temp": true,
|
||||
"gyro-calibration-data": {
|
||||
"ax": -330,
|
||||
"ay": -2249,
|
||||
"az": 1170,
|
||||
"gx": 99,
|
||||
"gy": -6,
|
||||
"gz": 4
|
||||
},
|
||||
"angle": 90.93,
|
||||
"gravity": 1.105,
|
||||
"battery": 0.04
|
||||
}
|
||||
|
||||
|
||||
GET: /api/device
|
||||
================
|
||||
|
||||
Retrive the current device settings via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"app-name": "GravityMon ",
|
||||
"app-ver": "0.0.0",
|
||||
"id": "ee1bfc",
|
||||
"mdns": "gravmon"
|
||||
}
|
||||
|
||||
|
||||
GET: /api/status
|
||||
================
|
||||
|
||||
Retrive the current device status via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` or ``F``
|
||||
|
||||
Other parameters are the same as in the configuration guide.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"id": "ee1bfc",
|
||||
"angle": 89.86,
|
||||
"gravity": 1.1052,
|
||||
"gravity-tempcorr": 1.1031,
|
||||
"temp-c": 0,
|
||||
"temp-f": 32,
|
||||
"battery": 0,
|
||||
"temp-format": "C",
|
||||
"sleep-mode": false,
|
||||
"rssi": -56
|
||||
}
|
||||
|
||||
|
||||
GET: /api/config/formula
|
||||
========================
|
||||
|
||||
Retrive the data used for formula calculation data via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
* ``a1``-``a4`` are the angles/tilt readings (up to 5 are currently supported)
|
||||
* ``g1``-``g4`` are the corresponding gravity reaadings in SG or Plato depending on the device-format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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,
|
||||
"gravity-format": "G",
|
||||
"gravity-formula": "0.0*tilt^3+0.0*tilt^2+0.0017978*tilt+0.9436"
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/device
|
||||
========================
|
||||
|
||||
Used to update device settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``temp-format`` can be either ``C`` (Celcius) or ``F`` (Farenheight)
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"id": "ee1bfc",
|
||||
"mdns": "gravmon",
|
||||
"temp-format": "C",
|
||||
"sleep-interval": 30
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/push
|
||||
======================
|
||||
|
||||
Used to update push settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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",
|
||||
}
|
||||
|
||||
|
||||
POST: /api/config/gravity
|
||||
=========================
|
||||
|
||||
Used to update gravity settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``gravity-formula`` keywords ``temp`` and ``tilt`` are supported.
|
||||
* ``gravity-format`` can be either ``G`` (SG) or ``P`` (PLATO)
|
||||
|
||||
.. note::
|
||||
``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
|
||||
|
||||
{
|
||||
"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
|
||||
==========================
|
||||
|
||||
Used to update hardware settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
.. note::
|
||||
``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
|
||||
|
||||
{
|
||||
"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
|
||||
=========================
|
||||
|
||||
Used to update formula calculation data via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
* ``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
|
||||
|
||||
{
|
||||
"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
|
||||
=============================
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import requests
|
||||
import json
|
||||
|
||||
host = "192.168.1.1" # IP adress (or name) of the device to send these settings to
|
||||
id = "ee1bfc" # Device ID (shown in serial console during startup or in UI)
|
||||
|
||||
def set_config( url, json ):
|
||||
headers = { "ContentType": "application/json" }
|
||||
print( url )
|
||||
resp = requests.post( url, headers=headers, data=json )
|
||||
if resp.status_code != 200 :
|
||||
print ( "Failed " )
|
||||
else :
|
||||
print ( "Success " )
|
||||
|
||||
url = "http://" + host + "/api/config/device"
|
||||
json = { "id": id,
|
||||
"mdns": "gravmon", # Name of the device
|
||||
"temp-format": "C", # Temperature format C or F
|
||||
"sleep-interval": 30 # Sleep interval in seconds
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/push"
|
||||
json = { "id": id,
|
||||
"http-push": "http://192.168.1.1/ispindel",
|
||||
"http-push2": "",
|
||||
"http-push-h1": "",
|
||||
"http-push-h2": "",
|
||||
"http-push2-h1": "",
|
||||
"http-push2-h2": "",
|
||||
"brewfather-push": "",
|
||||
"influxdb2-push": "",
|
||||
"influxdb2-org": "",
|
||||
"influxdb2-bucket": "",
|
||||
"influxdb2-auth": "",
|
||||
"mqtt-push": "192.168.1.50",
|
||||
"mqtt-port": 1883,
|
||||
"mqtt-user": "Qwerty",
|
||||
"mqtt-pass": "Qwerty"
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/gravity"
|
||||
json = { "id": id,
|
||||
"gravity-formula": "",
|
||||
"gravity-format": "P",
|
||||
"gravity-temp-adjustment": "off" # Adjust gravity (on/off)
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/hardware"
|
||||
json = { "id": id,
|
||||
"voltage-factor": 1.59, # Default value for voltage calculation
|
||||
"temp-adjustment": 0, # If temp sensor needs to be corrected
|
||||
"gyro-temp": "on", # Use the temp sensor in the gyro instead (on/off)
|
||||
"ota-url": "" # if the device should seach for a new update when active
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/formula"
|
||||
json = { "id": id,
|
||||
"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
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
|
||||
.. _data-formats:
|
||||
|
||||
Data Formats
|
||||
############
|
||||
|
||||
.. _data-formats-ispindle:
|
||||
|
||||
iSpindle format
|
||||
===============
|
||||
|
||||
This is the format used for standard http posts.
|
||||
|
||||
* ``corr-gravity`` is an extended parameter containing a temperature corrected gravity reading.
|
||||
* ``gravity-format`` is an extended parameter containing the gravity format (G or P).
|
||||
* ``run-time`` is an extended parameter containing the number of seconds the execution took.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"ID": "2E6753",
|
||||
"token" : "gravmon",
|
||||
"interval": 900,
|
||||
"temperature": 20.5,
|
||||
"temp-units": "C",
|
||||
"gravity": 1.0050,
|
||||
"angle": 45.34,
|
||||
"battery": 3.67,
|
||||
"rssi": -12,
|
||||
|
||||
"corr-gravity": 1.0050,
|
||||
"gravity-unit": "G",
|
||||
"run-time": 6
|
||||
}
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. code-block::
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"ID": "${id}",
|
||||
"token" : "gravmon",
|
||||
"interval": ${sleep-interval},
|
||||
"temperature": ${temp},
|
||||
"temp-units": "${temp-unit}",
|
||||
"gravity": ${gravity},
|
||||
"angle": ${angle},
|
||||
"battery": ${battery},
|
||||
"rssi": ${rssi},
|
||||
"corr-gravity": ${corr-gravity},
|
||||
"gravity-unit": "${gravity-unit}",
|
||||
"run-time": ${run-time}
|
||||
}
|
||||
|
||||
|
||||
.. _data-formats-brewfather:
|
||||
|
||||
Brewfather format
|
||||
=================
|
||||
|
||||
This is the format for Brewfather. See: `Brewfather API docs <https://docs.brewfather.app/integrations/custom-stream>`_
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"temp": 20.5,
|
||||
"temp_unit": "C",
|
||||
"battery": 3.67,
|
||||
"gravity": 1.0050,
|
||||
"gravity_unit": "G",
|
||||
}
|
||||
|
||||
|
||||
.. _data-formats-influxdb2:
|
||||
|
||||
Influx DB v2
|
||||
============
|
||||
|
||||
This is the format for InfluxDB v2
|
||||
|
||||
.. code-block::
|
||||
|
||||
measurement,host=<mdns>,device=<id>,temp-format=<C|F>,gravity-format=SG,gravity=1.0004,corr-gravity=1.0004,angle=45.45,temp=20.1,battery=3.96,rssi=-18
|
||||
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. code-block::
|
||||
|
||||
measurement,host=${mdns},device=${id},temp-format=${temp-unit},gravity-format=${gravity-unit} gravity=${gravity},corr-gravity=${corr-gravity},angle=${angle},temp=${temp},battery=${battery},rssi=${rssi}
|
||||
|
||||
|
||||
.. _data-formats-mqtt:
|
||||
|
||||
MQTT
|
||||
====
|
||||
|
||||
This is the format used to send data to MQTT. Each of the lines are specific topics
|
||||
|
||||
.. code-block::
|
||||
|
||||
ispindel/device_name/tilt 89.96796
|
||||
ispindel/device_name/temperature 21.375
|
||||
ispindel/device_name/temp_units C
|
||||
ispindel/device_name/battery 0.04171
|
||||
ispindel/device_name/gravity 33.54894
|
||||
ispindel/device_name/interval 1
|
||||
ispindel/device_name/RSSI -58
|
||||
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. tip::
|
||||
|
||||
Each line in the format is treated as one topic. The `|` is used as separator between lines and the first `:` is used as separator between topic and value. Each line is formatted as `<topic>:<value>`
|
||||
|
||||
.. code-block::
|
||||
|
||||
ispindel/${mdns}/tilt:${angle}|
|
||||
ispindel/${mdns}/temperature:${temp}|
|
||||
ispindel/${mdns}/temp_units:${temp-unit}|
|
||||
ispindel/${mdns}/battery:${battery}|
|
||||
ispindel/${mdns}/gravity:${gravity}|
|
||||
ispindel/${mdns}/interval:${sleep-interval}|
|
||||
ispindel/${mdns}/RSSI:${rssi}|
|
||||
|
||||
This is a format template that is compatible with v0.6. Just replace the `topic` with the topic you want to post data to.
|
||||
|
||||
.. code-block::
|
||||
|
||||
topic:{"name":"gravmon","ID":"${id}","token":"gravmon","interval": ${sleep-interval},"temperature": ${temp},"temp-units": "${temp-unit}","gravity":${gravity},"angle": ${angle},"battery":${battery},"rssi": ${rssi},"corr-gravity":${corr-gravity},"gravity-unit": "${gravity-unit}","run-time": ${run-time}}|
|
||||
|
||||
|
||||
version.json
|
||||
============
|
||||
|
||||
Contents version.json. The version is used by the device to check if the this version is newer. The html files will also be downloaded if the are present on the server. This way it's easy to
|
||||
upgrade to a version that serve the html files from the file system. If they dont exist nothing will happen, the OTA flashing will still work. If the html files are missing from the file system
|
||||
they can be uploaded manually afterwards.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"project":"gravmon",
|
||||
"version":"0.7.0",
|
||||
"html": [
|
||||
"index.min.htm",
|
||||
"device.min.htm",
|
||||
"config.min.htm",
|
||||
"format.min.htm",
|
||||
"calibration.min.htm",
|
||||
"about.min.htm"
|
||||
]
|
||||
}
|
||||
|
||||
156
src_docs/source/data.rst
Normal file
156
src_docs/source/data.rst
Normal file
@ -0,0 +1,156 @@
|
||||
.. _data-formats:
|
||||
|
||||
Data Formats
|
||||
############
|
||||
|
||||
.. _data-formats-ispindle:
|
||||
|
||||
iSpindle format
|
||||
===============
|
||||
|
||||
This is the format used for standard http posts.
|
||||
|
||||
* ``corr-gravity`` is an extended parameter containing a temperature corrected gravity reading.
|
||||
* ``gravity-format`` is an extended parameter containing the gravity format (G or P).
|
||||
* ``run-time`` is an extended parameter containing the number of seconds the execution took.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"ID": "2E6753",
|
||||
"token" : "gravmon",
|
||||
"interval": 900,
|
||||
"temperature": 20.5,
|
||||
"temp-units": "C",
|
||||
"gravity": 1.0050,
|
||||
"angle": 45.34,
|
||||
"battery": 3.67,
|
||||
"rssi": -12,
|
||||
|
||||
"corr-gravity": 1.0050,
|
||||
"gravity-unit": "G",
|
||||
"run-time": 6
|
||||
}
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. code-block::
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"ID": "${id}",
|
||||
"token" : "gravmon",
|
||||
"interval": ${sleep-interval},
|
||||
"temperature": ${temp},
|
||||
"temp-units": "${temp-unit}",
|
||||
"gravity": ${gravity},
|
||||
"angle": ${angle},
|
||||
"battery": ${battery},
|
||||
"rssi": ${rssi},
|
||||
"corr-gravity": ${corr-gravity},
|
||||
"gravity-unit": "${gravity-unit}",
|
||||
"run-time": ${run-time}
|
||||
}
|
||||
|
||||
|
||||
.. _data-formats-brewfather:
|
||||
|
||||
Brewfather format
|
||||
=================
|
||||
|
||||
This is the format for Brewfather. See: `Brewfather API docs <https://docs.brewfather.app/integrations/custom-stream>`_
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"name" : "gravmon",
|
||||
"temp": 20.5,
|
||||
"temp_unit": "C",
|
||||
"battery": 3.67,
|
||||
"gravity": 1.0050,
|
||||
"gravity_unit": "G",
|
||||
}
|
||||
|
||||
|
||||
.. _data-formats-influxdb2:
|
||||
|
||||
Influx DB v2
|
||||
============
|
||||
|
||||
This is the format for InfluxDB v2
|
||||
|
||||
.. code-block::
|
||||
|
||||
measurement,host=<mdns>,device=<id>,temp-format=<C|F>,gravity-format=SG,gravity=1.0004,corr-gravity=1.0004,angle=45.45,temp=20.1,battery=3.96,rssi=-18
|
||||
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. code-block::
|
||||
|
||||
measurement,host=${mdns},device=${id},temp-format=${temp-unit},gravity-format=${gravity-unit} gravity=${gravity},corr-gravity=${corr-gravity},angle=${angle},temp=${temp},battery=${battery},rssi=${rssi}
|
||||
|
||||
|
||||
.. _data-formats-mqtt:
|
||||
|
||||
MQTT
|
||||
====
|
||||
|
||||
This is the format used to send data to MQTT. Each of the lines are specific topics
|
||||
|
||||
.. code-block::
|
||||
|
||||
ispindel/device_name/tilt 89.96796
|
||||
ispindel/device_name/temperature 21.375
|
||||
ispindel/device_name/temp_units C
|
||||
ispindel/device_name/battery 0.04171
|
||||
ispindel/device_name/gravity 33.54894
|
||||
ispindel/device_name/interval 1
|
||||
ispindel/device_name/RSSI -58
|
||||
|
||||
|
||||
This is the format template used to create the json above.
|
||||
|
||||
.. tip::
|
||||
|
||||
Each line in the format is treated as one topic. The `|` is used as separator between lines and the first `:` is used as separator between topic and value. Each line is formatted as `<topic>:<value>`
|
||||
|
||||
.. code-block::
|
||||
|
||||
ispindel/${mdns}/tilt:${angle}|
|
||||
ispindel/${mdns}/temperature:${temp}|
|
||||
ispindel/${mdns}/temp_units:${temp-unit}|
|
||||
ispindel/${mdns}/battery:${battery}|
|
||||
ispindel/${mdns}/gravity:${gravity}|
|
||||
ispindel/${mdns}/interval:${sleep-interval}|
|
||||
ispindel/${mdns}/RSSI:${rssi}|
|
||||
|
||||
This is a format template that is compatible with v0.6. Just replace the `topic` with the topic you want to post data to.
|
||||
|
||||
.. code-block::
|
||||
|
||||
topic:{"name":"gravmon","ID":"${id}","token":"gravmon","interval": ${sleep-interval},"temperature": ${temp},"temp-units": "${temp-unit}","gravity":${gravity},"angle": ${angle},"battery":${battery},"rssi": ${rssi},"corr-gravity":${corr-gravity},"gravity-unit": "${gravity-unit}","run-time": ${run-time}}|
|
||||
|
||||
|
||||
version.json
|
||||
============
|
||||
|
||||
Contents version.json. The version is used by the device to check if the this version is newer. The html files will also be downloaded if the are present on the server. This way it's easy to
|
||||
upgrade to a version that serve the html files from the file system. If they dont exist nothing will happen, the OTA flashing will still work. If the html files are missing from the file system
|
||||
they can be uploaded manually afterwards.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"project":"gravmon",
|
||||
"version":"0.7.0",
|
||||
"html": [
|
||||
"index.min.htm",
|
||||
"device.min.htm",
|
||||
"config.min.htm",
|
||||
"format.min.htm",
|
||||
"calibration.min.htm",
|
||||
"about.min.htm"
|
||||
]
|
||||
}
|
||||
16
src_docs/source/formula.rst
Normal file
16
src_docs/source/formula.rst
Normal file
@ -0,0 +1,16 @@
|
||||
.. _create-formula:
|
||||
|
||||
Create formula
|
||||
##############
|
||||
|
||||
.. image:: images/formula1.png
|
||||
:width: 800
|
||||
:alt: Formula data
|
||||
|
||||
Here you can enter up to 5 values (angles + gravity) that is then used to create the formula. Angles equal to zero will be regarded as empty even if there is a gravity reading.
|
||||
|
||||
.. image:: images/formula2.png
|
||||
:width: 800
|
||||
:alt: Formula graph
|
||||
|
||||
Once the formula is created a graph over the entered values and a simulation of the formula will give you a nice overview on how the formula will work.
|
||||
@ -125,10 +125,14 @@ the following libraries and without these this would have been much more difficu
|
||||
functionallity
|
||||
installation
|
||||
configuration
|
||||
formula
|
||||
services
|
||||
advanced
|
||||
api
|
||||
data
|
||||
compiling
|
||||
contributing
|
||||
q_and_a
|
||||
backlog
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
81
src_docs/source/services.rst
Normal file
81
src_docs/source/services.rst
Normal file
@ -0,0 +1,81 @@
|
||||
.. _services:
|
||||
|
||||
Service Integration
|
||||
###################
|
||||
|
||||
This chapter contains a list of targets and what configuration is needed to interact with them.
|
||||
|
||||
Brewfather
|
||||
++++++++++
|
||||
|
||||
Just enter the http adress found on brewfather, not other settings are needed. The endpoint has the following format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
http://log.brewfather.net/http://log.brewfather.net/stream?id=<yourid>
|
||||
|
||||
|
||||
The URL is found under settings.
|
||||
|
||||
Fermentrack
|
||||
+++++++++++
|
||||
|
||||
`Fermentrack <https://www.fermentrack.com>`_ is a open source brewing software to monitor and control fermentation.
|
||||
|
||||
GravityMon can be installed and used as an iSpindle. Just register the device as an iSpindle and use the defined endpoint which normally is:
|
||||
|
||||
.. code-block::
|
||||
|
||||
http://myservername/ispindel
|
||||
|
||||
UBIdots
|
||||
+++++++
|
||||
|
||||
`UBIdots <https://www.ubidots.com>`_ is a IoT service that display data collected various sources.
|
||||
|
||||
For this service there are two options to configure the integration. First you will need your default token which is found under `API Credentials` (<api-tokem> in the example below).
|
||||
Swap the text <devicename> with the name you want to show in ubidots.
|
||||
|
||||
**Option 1** - token as an URL parameter
|
||||
|
||||
Enter the following as URL:
|
||||
|
||||
.. code-block::
|
||||
|
||||
http://industrial.api.ubidots.com/api/v1.6/devices/<devicename>/?token=<api-token>
|
||||
|
||||
|
||||
This is the less secure option.
|
||||
|
||||
**Option 2** - token as the http header
|
||||
|
||||
Enter the following as URL, use either standard or ssl.
|
||||
|
||||
.. code-block::
|
||||
|
||||
http://industrial.api.ubidots.com/api/v1.6/devices/<devicename>
|
||||
https://industrial.api.ubidots.com/api/v1.6/devices/<devicename>
|
||||
|
||||
|
||||
Under `Headers` (button after the http url in the UI) enter the following string:
|
||||
|
||||
.. code-block::
|
||||
|
||||
X-Auth-Token: <api-token>
|
||||
|
||||
|
||||
This is the more secure option.
|
||||
|
||||
Even though ubidots can handle the default ispindle format it probably better to just post the data you want. This is an example of a
|
||||
format template that can be used. For information on customizing the format see :ref:`format-editor`.
|
||||
|
||||
.. code-block::
|
||||
|
||||
{
|
||||
"temperature": ${temp},
|
||||
"gravity": ${gravity},
|
||||
"angle": ${angle},
|
||||
"battery": ${battery},
|
||||
"rssi": ${rssi}
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user