Brewery/gravitymon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' into dev

Browse Source
This commit is contained in:
Magnus Persson 2022-10-18 19:00:28 +02:00
commit 3b7be30363
16 changed files with 124 additions and 116 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/pio-build-patch.yaml vendored
View File

@ -36,9 +36,7 @@ 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
#run: pio run -e gravity-release
run: pio run -e gravity-release
- uses: EndBug/add-and-commit@v7 # You can change this to use a specific version. https://github.com/marketplace/actions/add-commit
with:

2
src_docs/source/advanced.rst
View File

@ -17,7 +17,7 @@ To reduce the need for adding custom endpoints for various services there is an
: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.
The save button will save the current formula and reload the data from the device.
You can also select a template from the list and copy that to the current endpoint.

16
src_docs/source/api.rst
View File

@ -8,7 +8,7 @@ All the API's use a key called ``ID`` which is the unique device id (chip id). T
GET: /api/config
================
Retrive the current configuation of the device via an HTTP GET command. Payload is in JSON format.
Retrieve the current configuration 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)
@ -81,7 +81,7 @@ This API has been removed from 0.9 and merged with /api/status
GET: /api/status
================
Retrive the current device status via an HTTP GET command. Payload is in JSON format.
Retrieve the current device status via an HTTP GET command. Payload is in JSON format.
* ``temp-format`` can be either ``C`` or ``F``
* ``platform`` can be either ``esp8266``, ``esp32c3``, ``esp32s2`` or ``esp32``
@ -117,10 +117,10 @@ 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.
Retrieve the data used for formula calculation data via an HTTP GET command. Payload is in JSON format.
* ``a1``-``a10`` are the angles/tilt readings (up to 10 are currently supported)
* ``g1``-``g10`` are the corresponding gravity reaadings in SG or Plato depending on the device-format.
* ``g1``-``g10`` are the corresponding gravity readings in SG or Plato depending on the device-format.
.. code-block:: json
@ -239,7 +239,7 @@ 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)
* ``temp-format`` can be either ``C`` (Celsius) or ``F`` (Fahrenheit)
.. code-block::
@ -327,7 +327,7 @@ POST: /api/config/formula
Used to update formula calculation data via an HTTP POST command. Payload is in JSON format.
* ``a1``-``a10`` are the angles/tilt readings (up to 10 are currently supported)
* ``g1``-``g10`` are the corresponding gravity reaadings (in SG)
* ``g1``-``g10`` are the corresponding gravity readings (in SG)
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.
@ -369,7 +369,7 @@ The requests package converts the json to standard form post format.
import requests
import json
host = "192.168.1.1" # IP adress (or name) of the device to send these settings to
host = "192.168.1.1" # IP address (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 ):
@ -425,7 +425,7 @@ The requests package converts the json to standard form post format.
"temp-adjustment": 0, # If temp sensor needs to be corrected
"gyro-temp": "on", # Use the temp sensor in the gyro instead (on/off)
"ble": "red", # Enable ble on esp32
"ota-url": "" # if the device should seach for a new update when active
"ota-url": "" # if the device should search for a new update when active
}
set_config( url, json )

42
src_docs/source/configuration.rst
View File

@ -23,22 +23,22 @@ URL: (http://gravmon.local)
:alt: Index page
Configuration is accessed by entering the URL for the device, this will be the mDNS name *device.local* or the IP adress. The following chapter assumes the device name is *gravmon*.
Configuration is accessed by entering the URL for the device, this will be the mDNS name *device.local* or the IP address. The following chapter assumes the device name is *gravmon*.
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.
You can also view the average time a gravity measurement takes. Under optimal setting this should be around 1.5 - 2.0 seconds. If this is higher than 2 seconds this is most likley connected to slow wifi
You can also view the average time a gravity measurement takes. Under optimal setting this should be around 1.5 - 2.0 seconds. If this is higher than 2 seconds this is most likely connected to slow wifi
connection. It will show 0 if data has not been collected yet.
.. 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.
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 address from there.
.. tip::
The button `view error log` will show the last error messages 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`. From v1.1 it will also detect
the need to connect to the serial port or to check what errors has occurred while in `gravity mode`. From v1.1 it will also detect
any abnormal restarts or crashes and record these in the logfile.
@ -61,7 +61,7 @@ The limitation is 63 chars but using long names might break endpoints that data
* **Temperature format:**
Choose between Celsius and Farenheight when displaying temperature.
Choose between Celsius and Fahrenheit when displaying temperature.
* **Interval:**
@ -94,7 +94,7 @@ Push Settings
.. note::
When enabling SSL this will not validate the root CA of the remote service, this is a design decision based on two aspects. Enabling CA validation will take 3-4s extra on each connection which means way less
battery life, so the decision is to prioritize battery life over security. The data transmitted is not really that sensitive anyway so I belive this is a good balance.
battery life, so the decision is to prioritize battery life over security. The data transmitted is not really that sensitive anyway so I believe this is a good balance.
* **HTTP 1 (POST):**
@ -129,7 +129,7 @@ The token is included in the default format for the HTTP GET url but can be used
:width: 300
:alt: HTTP Headers
You can define 2 http headers per push target. This is available via a pop-up window but dont forget
You can define 2 http headers per push target. This is available via a pop-up window but don't 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.
@ -197,14 +197,14 @@ Gravity Settings
* **Gravity format:**
Gravity format can be eihter `SG` or `Plato`. The device will use SG Internally and convert to Plato when displaying or sending data.
Gravity format can be either `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
The gravity formula accepts to parameters, **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:**
@ -233,12 +233,12 @@ Hardware Settings
* **Voltage factor:**
Factor used to calcualate the battery voltage. If you get a too low/high voltage you can adjust this value.
Factor used to calculate the battery voltage. If you get a too low/high voltage you can adjust this value.
* **Config voltage:**
Defines the level of voltage when the device should enter config mode due to charging. This might vary between different battery manufacturers.
If you dont what the device to go into configuration mode when charging, set this to 6V. This was added since differnt batteries have different
If you don't what the device to go into configuration mode when charging, set this to 6V. This was added since different batteries have different
voltages when fully charged.
* **Temperature correction:**
@ -250,15 +250,15 @@ when the device starts. So changing this will not take affect until the device i
Enable this feature will use the temp sensor i the gyro instead of the DS18B20, the benefit is shorter run time and
longer battery life (this is an experimental feature). The value used is the first temperature reading from when the
device is activated, since the gyro should be cool this is reflecting the surronding temperature. After it has
device is activated, since the gyro should be cool this is reflecting the surrounding temperature. After it has
been running the value would be totally off.
* **Enable storage mode when placed on cap**
When place on the cap (<5 degres tilt) the device will go into deep sleep forever (until reset). In order to wake it
When place on the cap (<5 degree tilt) the device will go into deep sleep forever (until reset). In order to wake it
up you need to do a reset. One option is to attach a magnetic reed switch (default open) to the reset pin and use a
magnet to force a reset without opening the tube. The reed switch is typically an electronic component of 14 mm
long incapsulated in a small glass tube. See hardware section for more information, :ref:`hardware`.
long encapsulated in a small glass tube. See hardware section for more information, :ref:`hardware`.
* **Bluetooth: (Only ESP32)**
@ -290,7 +290,7 @@ This option gives you the possibility to install an new version of the firmware
:alt: Update firmware
Advanded Settings
Advanced Settings
+++++++++++++++++
.. image:: images/config5.png
@ -299,21 +299,21 @@ Advanded Settings
.. warning::
Changeing these parameters with caution. The wrong values might cause the device to become unresponsive.
Change these parameters with caution. The wrong values might cause the device to become unresponsive.
* **Gyro reads:**
This defines how many gyro reads will be done before an angle is calculated. More reads will give better accuracy and also allow detection of
movement. Too many reads will take time and affecte batterylife. 50 takes about 800 ms to execute.
movement. Too many reads will take time and affect battery life. 50 takes about 800 ms to execute.
* **Gyro moving threashold:**
* **Gyro moving threshold:**
This is the max amount of deviation allowed for a stable reading.
* **Formula deviation:**
This is the maximum devation on the formlula allowed for it to be accepted. Once the formula has been derived it will be validated against the supplied
This is the maximum deviation on the formula allowed for it to be accepted. Once the formula has been derived it will be validated against the supplied
data and of the deviation on any point is bigger the formula will be rejected.
* **Ignore angles below water:**
@ -335,11 +335,11 @@ This is the amount of time allowed for a wifi connect.
* **Wifi portal timeout:**
If the wifi portal is triggered (can be triggerd by reset) then this is the amount of time allowed before it exists again.
If the wifi portal is triggered (can be triggered by reset) then this is the amount of time allowed before it exists again.
* **Skip Interval (...):**
These options allow the user to have variable push intervals for the diffrent endpoints. 0 means that every wakeup will send data to that endpoint. If you enter another number then that defines how many sleep cycles will be skipped.
These options allow the user to have variable push intervals for the different endpoints. 0 means that every wakeup will send data to that endpoint. If you enter another number then that defines how many sleep cycles will be skipped.
If the sleep interval is 300s and MQTT is set to 0 and HTTP1 is set to 2 then MQTT will be sent every 300s while HTTP1 would be sent 900s. This is great if you want to send data to a local mqtt server often but brewfather will only
accept data every 15 min.

4
src_docs/source/contributing.rst
View File

@ -7,11 +7,11 @@ In order to keep the source code in good condition I use `pre-commit <https://pr
.. note::
If you are using Windows as a base platform I would suggest that you install pre-commit under wsl (Windows Subssytem for Windows) and run it from there, I have found
If you are using Windows as a base platform I would suggest that you install pre-commit under wsl (Windows Subsystem for Windows) and run it from there, I have found
that this approach works fine.
The following command will run pre-commit on all the source files. Assuming you are inte project directory.
The following command will run pre-commit on all the source files. Assuming you are in the project directory.
.. code-block::

2
src_docs/source/data.rst
View File

@ -134,7 +134,7 @@ 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
upgrade to a version that serve the html files from the file system. If they don't 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

6
src_docs/source/formula.rst
View File

@ -9,7 +9,7 @@ Create formula
Here you can enter up to 10 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.
When you submit the values the device will try create a forumla with increasing level of complexity. It will start
When you submit the values the device will try create a formula with increasing level of complexity. It will start
with a order 2 formula and then try 3 and 4.
Once the formula has been created it will validate the formula against the supplied angles/gravity and if there is a too
@ -21,14 +21,14 @@ Under the Error Log you will also find hints to what problem the formula creator
`CALC: Validation failed on angle 33.430000, deviation too large 3.14, formula order 2`
This means that the angle 33.43 had a deviation of 5.8 SG and since the default threashold is 3, it will fail. You
This means that the angle 33.43 had a deviation of 5.8 SG and since the default threshold is 3, it will fail. You
can also see that it has failed on that point in both a order 2 and 4 formula.
.. image:: images/qa_1.png
:width: 400
:alt: Example of deviating value
So in this case you can either increase the threashold or remove the angle that has an issue. You can also
So in this case you can either increase the threshold or remove the angle that has an issue. You can also
use the graph on the calibration page to identify angles that is probably not correct.
.. image:: images/formula2.png

24
src_docs/source/functionallity.rst → src_docs/source/functionality.rst
View File

@ -1,6 +1,6 @@
.. _functionallity:
.. _functionality:
Functionallity
Functionality
==============
The main features
@ -68,7 +68,7 @@ The main features
Currently the device can handle 10 data points which should be enough to get a accurate formula. At least 3 data points
is needed to get an accurate formula.
* **Customize the data format beeing sent to push targets**
* **Customize the data format being sent to push targets**
In order to make it easier to support more targets there is a built in format editor that can be used to
customize the data that is to be sent. This way you can easily adapt the software to new targets without coding.
@ -79,7 +79,7 @@ The main features
* **Automatic temperature adjustment of gravity reading**
If you want to correct gravity based on beer temperature you can do this in the formula but here is a nice
feature that can correct the gravity as a second step making this independant of the formula.
feature that can correct the gravity as a second step making this independent of the formula.
* **OTA support from webserver**
@ -99,8 +99,8 @@ The main features
* **WIFI connection issues**
The software will not wait indefiently for a wifi connection. If it takes longer than 20 seconds to connect then
the device will try the seconday wifi configuration, and that also failes it will go into deep sleep for 60 seconds and then
The software will not wait indefinitely for a wifi connection. If it takes longer than 20 seconds to connect then
the device will try the secondary wifi configuration, and that also fails it will go into deep sleep for 60 seconds and then
retry later. This to conserve batter as much as possible.
* **Use gyro temperature sensor**
@ -119,7 +119,7 @@ The main features
:width: 800
:alt: Gyro temp vs DS18B20
* **Celsius or Farenheigt**
* **Celsius or Fahrenheit**
You can switch between different temperature formats. GravityMon will always use C for it's internal calculations and
convert to F when displayed.
@ -131,15 +131,15 @@ The main features
* **Stable gyro data**
The device will read the gyro 50 times to get an accurate reading. If the standad deviation is to high it will not
use the data since this is inacurate and the device is probably moving, probably do to active fermentation or movement of
The device will read the gyro 50 times to get an accurate reading. If the standard deviation is to high it will not
use the data since this is inaccurate and the device is probably moving, probably do to active fermentation or movement of
fermentation vessel. This sequence takes 900 ms seconds to execute and besides wifi connection this is what consumes the most
battery. With more testing this might be changes to either speed up or provide more stable readings.
* **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. This is a lot of help trying to figure out where bottlenecks
way I can find a good balance between performance and quality. This is a lot of help trying to figure out where bottlenecks
are in the code and where to put optimization efforts. Examples of real measurements:
* Reading the gyro: 885 ms
@ -160,7 +160,7 @@ The main features
Battery life
------------
The long term battery test has now been completed. Using a 2200 mA battery and sending data every 5 minutes to a local server on my network. The battery lasted 47 days which is excellet battery life.
The long term battery test has now been completed. Using a 2200 mA battery and sending data every 5 minutes to a local server on my network. The battery lasted 47 days which is excellent battery life.
In another test I had a device running with an sleep interval of only 30s with ok wifi connection. The device lasted 12 days which i think is excellent considering the short sleep interval.
@ -173,7 +173,7 @@ Performance
Since I have the possibility to measure the performance of different function in the code this is what I have been able to gather.
The typical runtime in a measurement cycle is approx 2 seconds and in some cases it can take up to 6-8 seconds but this is mainly related to establishing the WIFI connection. So stable wifi is
essential for long batterylife. Out of the 2 seconds of run-time the major time is spent on gyro readings (1.3s) and temperature measurements of (0.6s) so using the gyro sensor for measureing
essential for long battery life. Out of the 2 seconds of run-time the major time is spent on gyro readings (1.3s) and temperature measurements of (0.6s) so using the gyro sensor for measuring
temperature would reduce the total runtime with 25%. Sending data over http takes less than 100ms (on my local network) so this is not drawing much power.
The image below shows how the run-time varies over time. The pink line is the wifi connection time and this is why the time varies. The orange is the total runtime for the awake period.

4
src_docs/source/hardware.rst
View File

@ -3,8 +3,12 @@
Hardware
########
<<<<<<< HEAD
iSpindle based on esp8266
=========================
=======
There are lots of resources out there on how to build the hardware for an iSpindle so I will not go into details on that part. Here are two of my builds using the iSpindle PCB v4.
>>>>>>> master
There are lots of resouces out there on how to build the hardware for an iSpindle so I will not go into details on that part. I typically use one of the
excellent pcb boards that, for example the iSpindel PCB v4.0 from Cherry Philip. Here is one of my standard builds using an esp8266.

26
src_docs/source/index.rst
View File

@ -25,13 +25,13 @@ Main features
* Support either an ESP8266-d1-mini, ESP32-mini or ESP32C3-mini board (see :ref:`hardware`)
* Operates in two modes gravity monitoring and configuration mode
* Gravity mode is comparable to how the iSpindle works when collectintg data
* Gravity mode is comparable to how the iSpindle works when collecting data
* Configuration mode has a modern HTML5 based web UI. No need to start the access point to change settings
* Offloading some of the functionallity to run in the web browser, this allows for more advanced features.
* Offloading some of the functionality to run in the web browser, this allows for more advanced features.
* REST API to enable scripted configuration
* Send data to multiple endpoints and services at once (2xHTTP POST, HTTP GET, MQTT, INFLUXDB2)
* Directly test all endpoints from user interface with feedback to simplify troubleshooting
* Complete format customization for all endpoints using templates (dont really need to change the software to support new services)
* Complete format customization for all endpoints using templates (don't really need to change the software to support new services)
* Setup guides for how to send data to many popular services. Currently 10+ are documented
* Automatic temperature adjustment of gravity (just tick a checkbox)
* OTA support from webserver
@ -40,11 +40,11 @@ Main features
* Visual graph showing how formula will be interpreted based on entered values
* Using the temperature sensor in gyro instead of DS18B20 (faster)
* SSL support in all endpoints (no certificate validation due to limitations on esp8266).
* Built in performance measurements (used to optimise code)
* Built in performance measurements (used to optimize code)
* Storage mode when placed on cap (indefinite sleep)
* Customize various hardware parameters to opimize device functionallity.
* Customize various hardware parameters to optimize device functionality.
For a complete breakdown see the :ref:`functionallity`
For a complete breakdown see the :ref:`functionality`
.. note::
If you are missing some feature, please reach out on `Github <https://github.com/mp-se/gravitymon/discussions>`_ or `homebrewtalk.com <https://www.homebrewtalk.com/threads/replacement-firmware-for-ispindel-gravitymon.698058/>`_
@ -60,7 +60,7 @@ an example on how the fermentation process can be tracked. The graph has been re
:alt: Example fermentation
GravityMon is a replacement firmware for the iSpindle and uses the same hardware configuration and is 100% compatible. It
implements a lot of the features that has been requested in the orginal iSpindle project but never implemented for
implements a lot of the features that has been requested in the original iSpindle project but never implemented for
various reasons. Here is a list of :ref:`main_features`.
From v0.9 the firmware also supports a iSpindle built using an ESP32 d1 mini (pin compatible with esp8266). Currently this is an experimental
@ -77,7 +77,7 @@ My approach to this software is a little different from that the original iSpind
The github repository can be found here; `GravityMon on Github <https://github.com/mp-se/gravitymon>`_
.. note::
I dont take responsibility for any errors or issues caused by the software. The software is provided as-is. I will however
I don't take responsibility for any errors or issues caused by the software. The software is provided as-is. I will however
try my best to fix issues that might occur.
I have tested this software on 40+ brews with good results.
@ -103,8 +103,8 @@ order to save battery.
Credits to
----------
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:
Ideas to some of these functions have been picked up from discussions in the iSpindle forums. This software uses
the following libraries and without these this would have been much more difficult to achieve:
* https://github.com/jrowberg/i2cdevlib
@ -112,7 +112,7 @@ the following libraries and without these this would have been much more difficu
* https://github.com/codeplea/tinyexpr
Proccess the gravity formula and calculate the gravity and various corrections.
Process the gravity formula and calculate the gravity and various corrections.
* https://github.com/graphitemaster/incbin
@ -148,7 +148,7 @@ the following libraries and without these this would have been much more difficu
* https://github.com/256dpi/arduino-mqtt
Library for sending data to mqtt based on lightweight mqtt implemenentation.
Library for sending data to mqtt based on lightweight mqtt implementation.
* https://graphjs.com/
@ -176,7 +176,7 @@ the following libraries and without these this would have been much more difficu
intro
releases
functionallity
functionality
installation
configuration
troubleshooting

18
src_docs/source/installation.rst
View File

@ -12,7 +12,7 @@ You have these 3 options for flashing this firmware.
Brewflasher
===========
The prefered option for flashing GravityMon is using BrewFlasher, its a tools that support many brewing related firmwares for ESP8266 and ESP32. This works
The preferred option for flashing GravityMon is using BrewFlasher, its a tools that support many brewing related firmwares for ESP8266 and ESP32. This works
on both Windows and Mac. You can download the latest version from here: `Brewflasher <https://www.brewflasher.com/>`_ there is also a web based version
available here `Brewflasher WEB <https://web.brewflasher.com/>`_.
@ -27,7 +27,7 @@ In the /bin directory you will find 4 different firmware builds;
* **firmware.bin**
This is the standard release build (prefered version)
This is the standard release build (preferred version)
* **firmware32.bin**
@ -65,7 +65,7 @@ iSpindel (esp8266)
==================
If you already have the device flashed with iSpindel firmware you can go into the configuration mode where you will find
an option for updating firmware. The option is under the maintence meny.
an option for updating firmware. The option is under the maintenance menu.
Select the esp8266 version of the firmware called firmware.bin and press upload.
@ -125,19 +125,19 @@ Configuring WIFI
When the device is flashed it will need to have WIFI configuration in order to work. If you have used other software on
the device its possible that wifi settings already exist.
If this is not configured in the device it will create an wirless access point called `GravMon`. The default password is `password`.
If this is not configured in the device it will create an wireless access point called `GravMon`. The default password is `password`.
Connect to this AP and enter the SSID and password you want to use. If the web page dont open automatically you can enter the following adress
Connect to this AP and enter the SSID and password you want to use. If the web page don't open automatically you can enter the following address
in the browser: **http://192.168.4.1**
Before pressing save on the network infomration, make a note of the devicename that is shown on the screen, this will be the name that is used
Before pressing save on the network information, make a note of the devicename that is shown on the screen, this will be the name that is used
in the next step to access the configuration pages. The link would look like this: **http://gravitymon56EA34.local**
.. note::
When selecting a SSID in the list this will be populated in both wifi fields. This is the behaviour of the wifi manager library that I'm using,
in the future this is planned to be moved to the normal UI.
Under wifi settings you can define a primary and seconday wifi SSID. The seconday will be used in case the primary fails. If the seconday is
Under wifi settings you can define a primary and secondary wifi SSID. The secondary will be used in case the primary fails. If the secondary is
successful then it will be used as primary. *The second wifi setting is optional and not needed.*
@ -153,10 +153,10 @@ Finding the device adress
Once the wifi network settings have been added then the device will reboot and connect to your network. If the blue led is flashing then it's up and running and is ready to be configured.
If your computer supports mDNS the adress you saw before can be used in your web browser to connect to the device. Windows does not have the best support for mDNS so if you are having issues
If your computer supports mDNS the address you saw before can be used in your web browser to connect to the device. Windows does not have the best support for mDNS so if you are having issues
with finding the network name you can try the following:
* Check your wireless router for the IP adress and use that to connect instead, for example; http://192.168.1.56
* Check your wireless router for the IP address and use that to connect instead, for example; http://192.168.1.56
* Download an IP scanner / Port Scanner on your Windows computer or mobile device and use that to find what devices are listening on port 80.
Once you can access the user interface then proceed to the next step.

8
src_docs/source/intro.rst
View File

@ -3,7 +3,7 @@
Getting started
===============
First you need a completed iSpindle hardware, there are several resouces around that topic so it
First you need a completed iSpindle hardware, there are several resources around that topic so it
will not be covered in this documentation. Please visit `iSpindel Homepage <https://www.ispindel.de>`_ for
more information.
@ -29,7 +29,7 @@ Step 3 - Configuration
----------------------
Once the device can connect to WIFI it will go into `configuration mode` and start a web server for
doing the initial configuration. In order to access the device you will need to find its name or ip adress.
doing the initial configuration. In order to access the device you will need to find its name or ip address.
It will broadcast a name like gravitymonXXXXXX.local over mDNS. Where the XXXXXX is the unique device id. You can
find the name via an mDNS browser, check your router or connect the device to a serial monitor. On windows mDNS
@ -50,7 +50,7 @@ Configuration - Device Settings - Gyro Calibration
++++++++++++++++++++++++++++++++++++++++++++++++++
You need to place the device on a flat surface and then press the
calibrate button. It will take a few seconds for this to complete and the angle should be close to 90 degress. Without
calibrate button. It will take a few seconds for this to complete and the angle should be close to 90 degrees. Without
calibration the device will not go into gravity mode.
Configuration - Push Settings
@ -65,7 +65,7 @@ previous calibration then you can add them here, if not follow the calibration g
There are several guides for how to calibrate the device (`iSpindle Calibration <https://www.ispindel.de/docs/Calibration_en.html>`_)
This will get the data points needed to create the formula, and the datapoints will be stored on the device so you can
This will get the data points needed to create the formula, and the data points will be stored on the device so you can
adjust them when needed.
Step 4 - Completed

12
src_docs/source/q_and_a.rst
View File

@ -4,14 +4,14 @@ Q & A
My device is no going in to sleep after fully charged
-----------------------------------------------------
- Calibrate the device in the web interface
- Check the angle/tilt. If the device is reporting 90 degress then its not going into sleep. Tilt the device and check if sleep works.
- Check in reported voltage of the battery in the web interface. If this is higher than 4.15V the device belives its beeing charged. In that case adjust the voltage factor under hardware so the voltage drops below 4.15V.
- Check the angle/tilt. If the device is reporting 90 degrees then its not going into sleep. Tilt the device and check if sleep works.
- Check in reported voltage of the battery in the web interface. If this is higher than 4.15V the device believes its being charged. In that case adjust the voltage factor under hardware so the voltage drops below 4.15V.
- Check if the `always on` option is activated in the web interface.
My device reports a temperature of -273C or -491F
-------------------------------------------------
- The DS18B20 temperature sensor cannot be found and this is the default value reported in this case.
- Check the orienation of the sensor and soldering.
- Check the orientation of the sensor and soldering.
Calibration error (unable to find a valid formula)
--------------------------------------------------
@ -28,16 +28,16 @@ To fix these this you can;
- remove the value from the list (setting the angle to zero will do that)
- change the advanced setting (Formula max deviation) to a higher value and save the values again.
In the case above this paramater was changed from 1.6 SG to 4 SG and the formula was accepted. The deviation on this point was just above 3 SG.
In the case above this parameter was changed from 1.6 SG to 4 SG and the formula was accepted. The deviation on this point was just above 3 SG.
User interface does not render correctly
----------------------------------------
Since the user interface is built using bootstrap v5 the device requires access to the internet
to download required javascripts and css files. Due to size it would not be possible to store these
to download required javascript and css files. Due to size it would not be possible to store these
on the device. Make sure the device can access: https://cdn.jsdelivr.net/npm/bootstrap
Data is not popoulated in the fields
Data is not populated in the fields
------------------------------------
The user interface uses JQuery to fetch data from the device. This javascript library needs to be downloaded

38
src_docs/source/releases.rst
View File

@ -3,6 +3,7 @@
Releases
########
<<<<<<< HEAD
v1.2.0 - beta1
==============
@ -20,6 +21,11 @@ Documentation
* Updated hardware section with options for ESP32 boards
* Updated installation instructions.
=======
v1.1.1
======
* BUG: The text before the first variable was missed in the conversion of a format template.
>>>>>>> master
v1.1.0
======
@ -31,16 +37,16 @@ Features
* Updated sensor types in home assistant for auto registration of device
* Added ${app-ver} and ${app-build} to format template as new variables
* Improved error messages when creating formula so the troublesome measurement points can be identified
* Changed defaule validation threashold from 1.6 SG to 3.0 SG, this should allow for some more variance when creating formula
* Changed default validation threshold from 1.6 SG to 3.0 SG, this should allow for some more variance when creating formula
* Updated format template for Home Assistant, aligned with new mqtt configuration format
* Added format template for Home Assistant with automatic device registration
* Added storage mode which is activated under hardware setting. When place on the cap (<5 degres tilt) the device will go into storage mode and deep sleep.
* Added storage mode which is activated under hardware setting. When place on the cap (<5 degree tilt) the device will go into storage mode and deep sleep.
Known issues, not yet fixed
+++++++++++++++++++++++++++
* When updating firmware and the feature `deep sleep` is active the device will activate deep sleep if the gyro is not responding. FIX: Reboot device
Issues adressed
Issues addressed
++++++++++++++++
* Refactored error logging function to reduce memory usage and crashes. Max size of error log is 2 x 4 kb
* Refactored format template engine to reduce memory usage and crashes, can how handle slightly larger payloads than before. Increase from around 1100 chars to 1600 chars
@ -62,7 +68,7 @@ User interface
* Added Assistant Device registration, this is only done when format template is saved, during normal operation only data values are posted on MQTT. If HA is restarted then the device will disappear
* Calibration temperature (for temp adjustment) can now be set under advanced settings, default is 20C
* Changed length of device name from 12 to 63 chars. 63 is the max limit according to mdns.
* Under format options its now possible to select brewfather ispindle format to avoid errors connected to using the wrong format template with the various brewfather endpoints
* Under format options its now possible to select brewfather iSpindle format to avoid errors connected to using the wrong format template with the various brewfather endpoints
* Added brewblox as format under format options
* Added home assistant (with device registration) as format under format options
* User can now edit the voltage level that forces the device into config mode (device detects charging)
@ -93,14 +99,14 @@ Documentation
+++++++++++++
* Update documentation to match v1.0
* Installation instructions updated on how to find the device after wifi has been configured.
* Documentation on brewfather has been updated to adress SG/Plato conversion
* Documentation on brewfather has been updated to address SG/Plato conversion
* Added circuit diagram for esp8266 and esp32
* Added additional http error codes to troubleshooting documentation
User interface
++++++++++++++
* Upgraded to bootstrap v5.1 for web pages.
* Added button on indexpage to direct to github issues.
* Added button on index page to direct to github issues.
* Added button to extract important information for support requests.
* First point in gravity formula is now reserved for water gravity, this to allow detection of angles below water that can be filtered out.
* Changed layout on index page with measured data on top.
@ -111,19 +117,19 @@ Features
++++++++
* Added advanced setting to ignore angles that are lower than water. This is disabled by default.
* Added support for MPU6500 (standard is MPU6050).
* Removed brewfather option (can use standard HTTP options), the old apporach can still be used via changing format template.
* Removed brewfather option (can use standard HTTP options), the old approach can still be used via changing format template.
* Added 5 more points for formula creation, so a total of 10 angles/gravity values can be stored.
* Added https support for Influxdb v2
* Added possibility to set 2 wifi ssid where the second acts as a fallback in case it fails to connect. If succesful the seconday becomes the new primary.
* Added possibility to set 2 wifi ssid where the second acts as a fallback in case it fails to connect. If successful the secondary becomes the new primary.
* SSL connections are skipped on ESP8266 when in config mode since there is a high probability it will crash due to low memory.
* Advanced settings: Added possibility to have variable push intervals for different endpoints so that different frequency can be used, for example; 5min mqtt, 15min brewfather.
* Advanced settings: Changes how many times the gyro is read (less reads, quicker but less accurate)
* Advanced settings: Set amount of gyro movement is allowed for a accurate read.
* Advanced settings: What deviation is acceptable for creating formula deviation
* Advanced settings: Various timeouts, wifi connect, wifi portal, http connects.
* Advanced settings: Adjust resolution of temp sensor (9 bits to 12 bits), higher resolution takes longer thus reducing batterylife
* Advanced settings: Adjust resolution of temp sensor (9 bits to 12 bits), higher resolution takes longer thus reducing battery life
Issues adressed
Issues addressed
++++++++++++++++
* BUG: Fixed issue in formula calculation in case there were a gap in the data series
* BUG: Field name for wifi strength changed from "rssi" to "RSSI"
@ -134,7 +140,7 @@ v0.9.0
======
* Added one http push target that uses HTTP GET. This can be used with ubidots or blynk api's.
* Added function to test push targets from configuration page. It will send data and show the return code as a first step.
* Added documetation on how to integrate with Blynk.io using http get.
* Added documentation on how to integrate with Blynk.io using http get.
* Config page now shows the estimated runtime for the device (based on a full battery and previous average runtime)
* Experimental release of firmware using an esp32 instead of esp8266
* Merged index and device pages into one so that all the needed information is available on the index page.
@ -151,9 +157,9 @@ v0.9.0
* BUG: Corrected PIN for voltage read on ESP32
* BUG: If using plato and not gravity formula was defined the value was set to null.
* BUG: Temp format name was incorrect in iSpindle format causing receiver to incorrectly read temperature.
* BUG: Temperature sensor adjusmemnt value was not handled properly when using Farenheight.
* BUG: Temperature sensor adjustment value was not handled properly when using Fahrenheit.
* BUG: If the ID was to low the device id could end up with a leading space causing errors in data post. Added leading zero to ID.
* BUG: Entering wifi setup and a timeout occured the wifi settings could be deleted.
* BUG: Entering wifi setup and a timeout occurred the wifi settings could be deleted.
v0.8.0
======
@ -173,7 +179,7 @@ v0.8.0
from 16k to 2k. This can make a huge difference on a device with only 40k RAM. Not all
servers might support this feature.
* Updated documentation pages.
* Tested batterylife, 47 days using an update frequency of 5 min
* Tested battery life, 47 days using an update frequency of 5 min
v0.7.1
======
@ -195,7 +201,7 @@ Latest stable version. `Release v0.7 on Github <https://github.com/mp-se/gravity
* Added support for Plato
* Added error handling for calibration page.
* Added experimental target ESP32 (using an ESP32 D1 Mini which is pin compatible with ESP8266). Not
really usable since wifi connection is extreamly slow with current Arduino releases (3-8 seconds).
really usable since wifi connection is extremely slow with current Arduino releases (3-8 seconds).
* Added experimental format editor so users can customize their data format used for pushing data.
This will reduce the need for custom push targets. As long as the service is supporting http
or https then the data format can be customized.
@ -226,7 +232,7 @@ v0.6.0
v0.5.0
======
* Added feature to calcuate formula on device
* Added feature to calculate formula on device
* Total rewrite of documentation
* WIFI settings are now stored in config file
* Defined version numbers for all dependant libraries to avoid updates breaking build.

24
src_docs/source/services.rst
View File

@ -8,11 +8,11 @@ This chapter contains a list of targets and what configuration is needed to inte
Brewfather
++++++++++
Brewfather is an all in one service that allows you to manage you recepies and brews.
Brewfather is an all in one service that allows you to manage you recipes and brews.
**Option 1** - iSpindle Endpoint
This opion makes use of the standard http (1 or 2) endpoints in the push section. If you are using SG then the device name needs to end with [SG] or brewfather will assume
This option makes use of the standard http (1 or 2) endpoints in the push section. If you are using SG then the device name needs to end with [SG] or brewfather will assume
that the data is in plato. You can also modify the format template using the following options:
Update the following part `"gravity": ${gravity-plato},` or `"name" : "${mdns}[SG]",``
@ -29,7 +29,7 @@ Documentation on this can be found under `Brewfather iSpindle Endpoint <https://
**Option 2** - Custom Stream
This option makes use of the http push endpoint with a custom format template. Just enter the http stream adress found
This option makes use of the http push endpoint with a custom format template. Just enter the http stream address found
on brewfather, not other settings are needed. The stream endpoint URL has the following format:
.. code-block::
@ -79,7 +79,7 @@ UBIdots
you might need to reduce the number of values sent to the service. It will also treat every parameter as a number unless you create a custom device type and explicit define the string values
as text. This will require a paid subscription (as I interpret the documentation). The example format below will only send numbers so that should work fine with the paid subscription.
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).
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-token> in the example below).
Swap the text <devicename> with the name you want to show in ubidots.
**Option 1** - token as an URL parameter
@ -112,7 +112,7 @@ Under `Headers` (button after the http url in the UI) enter the following string
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
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::
@ -163,9 +163,9 @@ username / password to be able to publish messages on a topic.
gravmon/${mdns}/battery:${battery}|
It's also possible to allow home assistant to do autodisovery and automatically create the sensor. This format
It's also possible to allow home assistant to do auto discovery and automatically create the sensor. This format
template will create two sensors and update the values for them. The registration will occur when you save the format template. If Home Assistant
is restarted then the device will dissapear. The first method is the most persistant one.
is restarted then the device will disappear. The first method is the most persistent one.
.. warning::
This will only work on 1.1+ since the the memory allocation on previous versions are not enough to handle this large payload.
@ -189,10 +189,10 @@ is restarted then the device will dissapear. The first method is the most persis
Brewer's Friend
+++++++++++++++
Brewer's friend is an all in one service that allows you to manage you recepies and brews.
Brewer's friend is an all in one service that allows you to manage you recipes and brews.
.. warning::
I dont have an account for brewers friend so I have not been able to verfy this completely. Its based on
I don't have an account for brewers friend so I have not been able to verify this completely. Its based on
the available documentation. If this works please let
You can find you API key when logged in to the service. Follow these `instructions <https://docs.brewersfriend.com/devices/ispindel>`_
@ -293,7 +293,7 @@ Brewpiless
If you connect the device to the brewpiless access point there is not way to access the user interface for configuration so it's recommended to connect the device to your normal network.
The device need to have a name starting with iSpindle, for example `iSpindel000`. Set the URL for one of the http POST targets to `http://ip/gravity` where ip is the ip adress of Brewpiless.
The device need to have a name starting with iSpindle, for example `iSpindel000`. Set the URL for one of the http POST targets to `http://ip/gravity` where ip is the ip address of Brewpiless.
BrewBlox
@ -302,8 +302,8 @@ BrewBlox
To send iSpindel data to brewblox over mqtt you need to modify the format template to match the expected format. Once you have configured the mqtt information you also need to update the format template
for this target.
This format template will post the expected json document on the topic, dont forget the `|` character at the end of the line which is needed to parse the payload. The first to words are the topic
name and after the first `:` this is the json playload. Text within the brackets will be used as the unit for the value and degC is displayed as °C. You can add other parameters under the data section
This format template will post the expected json document on the topic, don't forget the `|` character at the end of the line which is needed to parse the payload. The first to words are the topic
name and after the first `:` this is the json payload. Text within the brackets will be used as the unit for the value and degC is displayed as °C. You can add other parameters under the data section
in the json document if you need other values as well.
.. code-block::

10
src_docs/source/troubleshooting.rst
View File

@ -13,12 +13,12 @@ Log errors
* Error validating created formula. Deviation to large, formula rejected
The device will try to create formulas with different complexities. It will try to
validate the formula using the supplied values. If the differnce is more than 1.6 SG on any point
the formula will be rejected. Check the entered values if they seams to be resonable.
validate the formula using the supplied values. If the difference is more than 1.6 SG on any point
the formula will be rejected. Check the entered values if they seams to be reasonable.
* No valid calibration values, please calibrate the device.
The gyro needs to be calibrated at 90 degress (flat). This is done on the configration page.
The gyro needs to be calibrated at 90 degrees (flat). This is done on the configuration page.
* Low on memory, skipping push
@ -33,10 +33,10 @@ Log errors
* Influxdb push failed response
* HTTP push failed response
All these errors are standard http error codes. This are the commone ones;
All these errors are standard http error codes. This are the common ones;
* 400 - Bad request. Probably an issue with the post format. Check format in the format editor.
* 401 - Unathorized. The service needs an token or other means to authenticate the device.
* 401 - Unauthorized. The service needs an token or other means to authenticate the device.
* 403 - Forbidden. Could be an issue with token or URL.
* 404 - Not found. Probably a wrong URL.