Updates to docs
This commit is contained in:
Magnus Persson
parent
2662f38bf7
commit
e234d6f908
3
.github/workflows/pio-build.yaml
vendored
3
.github/workflows/pio-build.yaml
vendored
@ -36,7 +36,8 @@ jobs:
|
||||
git config --global advice.detachedHead false
|
||||
|
||||
- name: Run PlatformIO
|
||||
run: pio run -e gravity-release -e gravity-perf -e gravity-debug
|
||||
#run: pio run -e gravity-release -e gravity-perf -e gravity-debug
|
||||
run: pio run -e gravity-release -e gravity-perf
|
||||
|
||||
- uses: EndBug/add-and-commit@v7 # You can change this to use a specific version. https://github.com/marketplace/actions/add-commit
|
||||
with:
|
||||
|
||||
Binary file not shown.
@ -1,5 +1,7 @@
|
||||
.. _compiling-the-software:
|
||||
|
||||
Compiling the software
|
||||
-----------------------
|
||||
######################
|
||||
|
||||
Tools
|
||||
=====
|
||||
@ -14,7 +16,7 @@ Code Formatting
|
||||
===============
|
||||
I use pre-commit and their cpp style checks to validate the code. Plugin defintions are found in **.pre-commit-config.yaml**
|
||||
|
||||
https://www.pre-commit.com
|
||||
`Pre-Commit <https://www.pre-commit.com>`_
|
||||
|
||||
.. note::
|
||||
|
||||
@ -23,12 +25,19 @@ https://www.pre-commit.com
|
||||
|
||||
Targets
|
||||
=======
|
||||
In the repository there are 3 targets defined
|
||||
In the platformio config there are 3 targets defined
|
||||
|
||||
* gravity-debug; Maximum logging for trouble shooting, deep sleep is disabled.
|
||||
* gravity-release; Standard release
|
||||
* gravity-perf; Standard release but contains code for measuring performance
|
||||
|
||||
.. warning::
|
||||
The debug target can be unsable and crash the device under certain circumstanses.
|
||||
Excessive logging to the serial port can cause corruption and crashes. I'm still
|
||||
trying to figure out what causes these issues in the debug target. Other targets are
|
||||
stable and works fine.
|
||||
|
||||
|
||||
Source structure
|
||||
================
|
||||
.. list-table:: Directory structure
|
||||
|
||||
@ -1,8 +1,11 @@
|
||||
Configuration
|
||||
-----------------------
|
||||
The device can operate in two modes and must be in `configuration mode` in order for the web server to be active.
|
||||
.. _setting-up-device:
|
||||
|
||||
One of the following conditions will place the device in `configuration mode`:
|
||||
Setting up device
|
||||
#################
|
||||
|
||||
The device can operate in two modes and must be in ``configuration mode`` in order for the web server to be active.
|
||||
|
||||
One of the following conditions will place the device in ``configuration mode``:
|
||||
|
||||
- Gyro has not been calibrated
|
||||
- Sleep mode has been disabled in the web interface
|
||||
@ -23,7 +26,7 @@ Configuration is accessed by entering the URL for the device, this will be the m
|
||||
The main page shows the device readings; gravity, angle, temperature and battery charge. If the checkbox is active then the device will never go into sleep mode. This is useful if
|
||||
you are collecting angle/tilt for calibration. If this is unchecked the device will change mode as explained before.
|
||||
|
||||
.. note::
|
||||
.. tip::
|
||||
|
||||
If you are connected to the device via a serial console (speed: 115200) you can see the connection sequence and get the Unique ID and IP adress from there.
|
||||
|
||||
@ -57,7 +60,7 @@ Configuration
|
||||
URL: (http://gravmon.local/config)
|
||||
|
||||
Device Setting
|
||||
**************
|
||||
++++++++++++++
|
||||
|
||||
.. image:: images/config1.png
|
||||
:width: 800
|
||||
@ -83,12 +86,12 @@ Device Setting
|
||||
|
||||
These are calibration data for the gyro. Place the device flat on a table and press the button to save the default orientation values. Without this calibration we cannot calculate the correct angle/tilt.
|
||||
|
||||
.. note::
|
||||
.. warning::
|
||||
|
||||
The device will **not** go into `gravity monitoring` mode unless calibrated
|
||||
|
||||
Push Settings
|
||||
*************
|
||||
+++++++++++++
|
||||
|
||||
.. image:: images/config2.png
|
||||
:width: 800
|
||||
@ -124,7 +127,7 @@ Push Settings
|
||||
|
||||
|
||||
Gravity Settings
|
||||
****************
|
||||
++++++++++++++++
|
||||
|
||||
.. image:: images/config3.png
|
||||
:width: 800
|
||||
@ -138,15 +141,19 @@ Gravity Settings
|
||||
|
||||
Will apply a temperature calibration formula to the gravity as a second step.
|
||||
|
||||
This is the formula used for temperature calibration (temp is in F). Cal = 20C.
|
||||
.. warning::
|
||||
This formula assumes that the calibration has been done at 20C.
|
||||
|
||||
.. code-block::
|
||||
Formula used in temperature correction:
|
||||
|
||||
gravity*((1.00130346-0.000134722124*temp+0.00000204052596*temp^2-0.00000000232820948*temp^3)/(1.00130346-0.000134722124*cal+0.00000204052596*cal^2-0.00000000232820948*cal^3))
|
||||
::
|
||||
|
||||
gravity*((1.00130346-0.000134722124*temp+0.00000204052596*temp^2-0.00000000232820948*temp^3)/
|
||||
(1.00130346-0.000134722124*cal+0.00000204052596*cal^2-0.00000000232820948*cal^3))
|
||||
|
||||
|
||||
Hardware Settings
|
||||
*****************
|
||||
+++++++++++++++++
|
||||
|
||||
.. image:: images/config4.png
|
||||
:width: 800
|
||||
@ -174,9 +181,10 @@ Hardware Settings
|
||||
http://192.168.1.1/firmware/gravmon/
|
||||
|
||||
|
||||
.. _create-formula:
|
||||
|
||||
Create formula
|
||||
=============================
|
||||
##############
|
||||
|
||||
.. image:: images/formula1.png
|
||||
:width: 800
|
||||
@ -190,14 +198,15 @@ Here you can enter up to 5 values (angles + gravity) that is then used to create
|
||||
|
||||
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.
|
||||
|
||||
@ -241,7 +250,7 @@ Other parameters are the same as in the configuration guide.
|
||||
|
||||
|
||||
GET: /api/device
|
||||
****************
|
||||
================
|
||||
|
||||
Retrive the current device settings via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
@ -256,7 +265,7 @@ Retrive the current device settings via an HTTP GET command. Payload is in JSON
|
||||
|
||||
|
||||
GET: /api/status
|
||||
****************
|
||||
================
|
||||
|
||||
Retrive the current device status via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
@ -281,7 +290,7 @@ Other parameters are the same as in the configuration guide.
|
||||
|
||||
|
||||
GET: /api/config/formula
|
||||
************************
|
||||
========================
|
||||
|
||||
Retrive the data used for formula calculation data via an HTTP GET command. Payload is in JSON format.
|
||||
|
||||
@ -307,7 +316,7 @@ 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.
|
||||
|
||||
@ -324,7 +333,7 @@ Used to update device settings via an HTTP POST command. Payload is in JSON form
|
||||
|
||||
|
||||
POST: /api/config/push
|
||||
**********************
|
||||
======================
|
||||
|
||||
Used to update push settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
@ -343,7 +352,7 @@ Used to update push settings via an HTTP POST command. Payload is in JSON format
|
||||
|
||||
|
||||
POST: /api/config/gravity
|
||||
*************************
|
||||
=========================
|
||||
|
||||
Used to update gravity settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
@ -359,7 +368,7 @@ Used to update gravity settings via an HTTP POST command. Payload is in JSON for
|
||||
|
||||
|
||||
POST: /api/config/gravity
|
||||
*************************
|
||||
=========================
|
||||
|
||||
Used to update hardware settings via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
@ -374,7 +383,7 @@ Used to update hardware settings via an HTTP POST command. Payload is in JSON fo
|
||||
|
||||
|
||||
POST: /api/config/formula
|
||||
*************************
|
||||
=========================
|
||||
|
||||
Used to update formula calculation data via an HTTP POST command. Payload is in JSON format.
|
||||
|
||||
@ -398,11 +407,87 @@ Used to update formula calculation data via an HTTP POST command. Payload is in
|
||||
}
|
||||
|
||||
|
||||
Data Formats
|
||||
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 endpoint
|
||||
"http-push2": "", # HTTP endpoint2
|
||||
"brewfather-push": "", # Brewfather URL
|
||||
"influxdb2-push": "", # InfluxDB2 settings
|
||||
"influxdb2-org": "",
|
||||
"influxdb2-bucket": "",
|
||||
"influxdb2-auth": ""
|
||||
}
|
||||
set_config( url, json )
|
||||
|
||||
url = "http://" + host + "/api/config/gravity"
|
||||
json = { "id": id,
|
||||
"gravity-formula": "", # If you want to set the gravity formula
|
||||
"gravity-temp-adjustment": "off" # on or 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
|
||||
"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
|
||||
############
|
||||
|
||||
iSpindle format
|
||||
***************
|
||||
===============
|
||||
|
||||
This is the format used for standard http posts.
|
||||
|
||||
@ -428,11 +513,10 @@ This is the format used for standard http posts.
|
||||
|
||||
|
||||
Brewfather format
|
||||
******************
|
||||
=================
|
||||
|
||||
This is the format for Brewfather
|
||||
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
@ -446,7 +530,7 @@ This is the format for Brewfather
|
||||
|
||||
|
||||
Influx DB v2
|
||||
************
|
||||
============
|
||||
|
||||
This is the format for InfluxDB v2
|
||||
|
||||
@ -456,7 +540,7 @@ This is the format for InfluxDB v2
|
||||
|
||||
|
||||
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
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
.. _functionallity:
|
||||
|
||||
Functionallity
|
||||
==============
|
||||
|
||||
@ -6,21 +8,21 @@ The main differences
|
||||
|
||||
* **Operates in two modes gravity monitoring and configuration mode**
|
||||
|
||||
In ``gravity monitoring`` mode it behaves just like the iSpindle, it wakes up at regular intervals, measure angle/tile, temperature, calculates gravity and pushes the data to defined endpoints.
|
||||
In ``gravity monitoring`` mode it behaves just like the iSpindle, it wakes up at regular intervals, measures angle/tile, temperature, calculates gravity and pushes the data to defined endpoints.
|
||||
|
||||
In ``configuration mode`` the device is always active and the webserver is active. Here you can view the angle/tilt values, change configuration options and more. When in this mode you can also interact with the device
|
||||
via an REST API so data can be pushed to the device via scripts (see API section for more information)
|
||||
via an REST API so data can be pushed to the device via scripts (see API section for more information).
|
||||
|
||||
You can force the device into ``configuration mode`` while measuring gravity. This is useful when calibrating the device so you dont needs to wait for the device to wake up and push the data. The entire calibration
|
||||
You can force the device into ``configuration mode`` while measuring gravity. This is useful when calibrating the device so you don't needs to wait for the device to wake up and push the data. The entire calibration
|
||||
sequence can be handled via the web interface without need for additional software tools.
|
||||
|
||||
*See the configuration section for more information on how to trigger the configuration mode.*
|
||||
See the :ref:`setting-up-device` section for more information on how to trigger the configuration mode.
|
||||
|
||||
* **Can send data to multiple endpoints at once**
|
||||
|
||||
The original iSpindle can only have one destination, this software will push data to all defined endpoints so in theory you can use them all. However this will consume a lot of battery power so use only as many as needed.
|
||||
|
||||
Currently the device supports the following endpoints: http (2 differnt), influxdb2 and Brewfather
|
||||
Currently the device supports the following endpoints: http (2 different), influxdb2 and Brewfather
|
||||
|
||||
If you want additional targets please raise a feature request in the github repo.
|
||||
|
||||
@ -60,21 +62,20 @@ Other features
|
||||
Experimental features
|
||||
---------------------
|
||||
|
||||
.. tip::
|
||||
These are not enabled by default. To enable them you need to recompile the code and enable the correct defines.
|
||||
|
||||
* Use the temperature sensor in the gyro instead of DS18B20
|
||||
|
||||
This works fine when the device has time to cool down between measurements and it saves a few milliseconds (reduced battery consumption). My testing shows that this is quite accurate.
|
||||
There is lots of battery power to save, reading the temp sensor takes almost as long as the gyro. This could reduce the run time by 40-50% and probly extend battery life with the same.
|
||||
However more testing is required. Might add this as an option in the UI.
|
||||
|
||||
.. note::
|
||||
|
||||
This is not enabled by default.
|
||||
|
||||
* Performance measurements
|
||||
|
||||
I've also create a small library to measure execution code in some areas of the code that i know is time consuming. This way I can find a good balance between performace and quality.
|
||||
|
||||
*See the compile section for more information.*
|
||||
See the :ref:`compiling-the-software` for more information.
|
||||
|
||||
|
||||
Battery life
|
||||
|
||||
@ -7,14 +7,13 @@ Welcome to GravityMon's documentation!
|
||||
######################################
|
||||
|
||||
.. note::
|
||||
|
||||
Preliminary documentation. This is work in progress. This documentation reflects **v0.5**
|
||||
This documentation reflects **v0.5**. Last updated 2022-01-09
|
||||
|
||||
|
||||
GravityMon is a replacement firmare for the iSpindle firmware, it uses the same hardware configuration so
|
||||
you can easily switch between them. It's used to measure gravity in beer and show the progress of fermentation.
|
||||
|
||||
For more information on this topic and function please visit https://www.ispindel.de.
|
||||
For more information on this topic and function please visit `iSpindel Homepage <https://www.ispindel.de>`_ .
|
||||
|
||||
I started GravityMon because i like to create software and wanted to do some low level programming. I had done a few
|
||||
projects based on esp8266 and also started to brew beer so this combination was quite natural.
|
||||
@ -22,10 +21,9 @@ projects based on esp8266 and also started to brew beer so this combination was
|
||||
The hardware design comes from the fantastic iSpindle project so that is not covered in this documentation.
|
||||
|
||||
My approach to this software is a little different from that the original ispindle firmware. The github repository can
|
||||
be found here; https://github.com/mp-se/gravitymon
|
||||
be found here; `GravityMon on Github <https://github.com/mp-se/gravitymon>`_
|
||||
|
||||
.. note::
|
||||
|
||||
This software is in the early stages even though its more than one year old so if you find issues, please
|
||||
open a ticket on github.
|
||||
|
||||
@ -39,18 +37,19 @@ The main differences:
|
||||
* Send data to multiple endpoints when pushing data.
|
||||
* Automatic temperature adjustment of gravity reading
|
||||
* OTA support from local webserver
|
||||
* Build in function to create gravity formulas (*New in v0.5*)
|
||||
* Build in function to create gravity formulas
|
||||
|
||||
There are also a experimental features such as:
|
||||
|
||||
* Using the temperature sensor in gyro instead of DS18B20 (faster)
|
||||
* Performance measurements (used to optimise code)
|
||||
|
||||
**For a complete breakdown see the functionallity section.**
|
||||
For a complete breakdown see the :ref:`functionallity`
|
||||
|
||||
Credits to
|
||||
----------
|
||||
This software uses the following libraries and without these this would have been much more difficult to acheive:
|
||||
Ideas to some of these functions have been picked up from disucssions in the iSpindle forums. This software uses
|
||||
the following libraries and without these this would have been much more difficult to acheive:
|
||||
|
||||
* https://github.com/jrowberg/i2cdevlib.git
|
||||
|
||||
@ -105,6 +104,7 @@ This software uses the following libraries and without these this would have bee
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
license
|
||||
releases
|
||||
functionallity
|
||||
installation
|
||||
|
||||
@ -5,7 +5,7 @@ Official esptool
|
||||
================
|
||||
|
||||
The prefered option for flashing esp8266 device is via the official esptool. Documentation can be found
|
||||
here; https://docs.espressif.com/projects/esptool/en/latest/esp32/
|
||||
here; `esptool home page <https://docs.espressif.com/projects/esptool/en/latest/esp32/>`_
|
||||
|
||||
Windows 10 should install a driver for the USB -> Serial automatically when you connect a esp8266.
|
||||
|
||||
@ -34,7 +34,7 @@ Just select a baud rate of 115200, 8N1.
|
||||
Binaries
|
||||
********
|
||||
|
||||
In the /bin directory you will find 3 different firmware builds;
|
||||
In the /bin directory you will find 2 different firmware builds;
|
||||
|
||||
* **firmware.bin**
|
||||
|
||||
@ -44,9 +44,6 @@ In the /bin directory you will find 3 different firmware builds;
|
||||
|
||||
This version also submits performance data to an influx database with detailed execution times.
|
||||
|
||||
* **firmware-debug.bin**
|
||||
|
||||
Development build. Not recommended for normal use.
|
||||
|
||||
In these versions all the html files are embedded in the binaries. The file system is currently only used for storing
|
||||
the configuration file.
|
||||
|
||||
26
src_docs/source/license.rst
Normal file
26
src_docs/source/license.rst
Normal file
@ -0,0 +1,26 @@
|
||||
.. _licence:
|
||||
|
||||
Licence
|
||||
#######
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2021-22 Magnus
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@ -1,5 +1,7 @@
|
||||
.. _releases:
|
||||
|
||||
Releases
|
||||
========
|
||||
########
|
||||
|
||||
v0.5.0 (beta)
|
||||
-------------
|
||||
@ -18,5 +20,5 @@ v0.4.0
|
||||
|
||||
Latest stable development version is: **v0.4.0**
|
||||
|
||||
https://github.com/mp-se/gravitymon/releases/tag/v0.4.0
|
||||
`Release v0.4 on Github <https://github.com/mp-se/gravitymon/releases/tag/v0.4.0>`_
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user