Update Documentation

.gitignore

@@ -9,7 +9,6 @@ CMakeCache.txt
 CMakeFiles
 CMakeScripts
 Testing
-Makefile
 cmake_install.cmake
 install_manifest.txt
 compile_commands.json
@@ -29,3 +28,8 @@ apidocs/
 *.sw?
 
 src/Version.h
+
+# Virtualenv / Sphinx
+/venv
+/docs/venv
+/docs/_build

README.md

@@ -1,14 +1,15 @@
-# brewpi-esp
+# BrewPi-ESP
 An implementation of the BrewPi firmware on the ESP8266, ESP32, and ESP32-S2 with additional, added features
 
 ## Introduction
-This project ports the BrewPi firmware to the ESP8266, ESP32, and ESP32-S2 controllers. It is compatible with [Fermentrack](http://www.fermentrack.com/) and [BrewPi-Remix](https://www.brewpiremix.com/).
+BrewPi provides a temperature controller which uses PID algorithms to tightly control a fermenting beer's temperature -- meaning that you can in many cases control the temperature of your fermenting beer to within _one tenth of a degree_. It was originally designed by Elco Jacobs, and used an Arduino running the BrewPi firmware to measure temperatures and toggle heating/cooling, paired with a Raspberry Pi to receive & graph temperature changes over time.
+
+This project ports the BrewPi firmware to the ESP8266, ESP32, and ESP32-S2 controllers, eliminating the need for an Arduino. It is compatible with [Fermentrack](http://www.fermentrack.com/) and [BrewPi-Remix](https://www.brewpiremix.com/) - both of which can be installed on a Raspbery Pi to capture/graph temperatures similar to the original project.
 
 ### Documentation:
-* [Selecting your Hardware](docs/Selecting%20an%20ESP%20Board.md) 
-* [Building a "Solder Free" BrewPi](docs/Solder%20Free%20BrewPi.md) 
-* [Installing the Firmware](docs/Installing%20the%20Firmware.md)
-* [Developing/Contributing](docs/DEVELOP.md)
+* [Selecting your Hardware](docs/source/Selecting%20an%20ESP%20Board.md) 
+* [Building a "Solder Free" BrewPi](docs/source/Solder%20Free%20BrewPi.md) 
+* [Installing the Firmware](docs/source/Installing%20the%20Firmware.md)
 * [Hardware Information](https://github.com/thorrak/thorrak_hardware/blob/master/BrewPi-ESP8266.md) - PCB files, ordering and BOMs
 
 ## Expected Pinout

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = source
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+myst-parser==0.19.1
+sphinx==6.1.3
+sphinx_rtd_theme==1.2.0

docs/source/BrewPi Algorithm.md

@@ -0,0 +1,10 @@
+# BrewPi Algorithm
+
+BrewPi uses a (PID algorithm)[https://en.wikipedia.org/wiki/PID_controller] to control the fermentation temperature of beer very precisely. The algorithm works by adjusting the temperature setting of the fridge a fermenter is in based on the desired temperature of the beer. This is done by an automated process, similar to stationing a robot next to your fridge's thermostat and telling it to adjust the thermostat up or down based on where you think it needs to be in order to get the beer temperature correct.
+
+Just as when typically adjusting the thermostat on a refrigerator, whether or not the fridge turns on takes into account factors such as how far the current temperature is from the setpoint and how long it has been since the last cooling cycle took place (compressor protection). Heating or cooling will take place until the fridge temperature meets or surpasses the setpoint (though similar to the built in thermostat, there may be a "minimum run time" so as to protect the compressor). When using a heater the algorithm continues to simply change the fridge temperature setpoint - toggling cooling or heating depending on whether the fridge temperature is above or below the desired fridge setpoint.
+
+The BrewPi algorithm determines the optimal fridge setpoint based on the beer temperature and how historically changing the fridge thermostat has affected the beer temperature. The PID algorithm measures error in the 
+
+However, the algorithm has limits, as it uses a single algorithm to control both heating and cooling. This assumption assumes that both heating and cooling will be impacted by the same degree of error which means that you will generally want to match your heating and cooling power, as well as the degree to which the heating/cooling can be picked up by the fridge sensor.
+

docs/source/Controller Configuration Options.md

@@ -0,0 +1,34 @@
+# Controller Configuration Options
+
+
+## User Guide to Configuration
+
+The majority of the configuration of your BrewPi happens behind-the-scenes, either handled automatically by the controller itself or managed by Fermentrack or BrewPi Remix.
+
+
+### "Low Delay" Mode
+
+BrewPi implements a number of protections designed to prevent damage to compressor-based cooling systems such as refrigerators, kegerators, or keezers. These include requiring cooling to run for a minimum period of time before being turned off, requiring a minimum amount of time to pass with the cooling off before allowing it to come back on, and requiring a minimum amount of time to pass before switching between heat & cooling. Low Delay mode reduces the delays associated with cooling
+
+| | **Normal** | **"Low Delay"** |
+|------------------------------------------------|------------|-----------------|
+| Minimum Cooling "Off" Time | 300s | 60s |
+| Minimum Heat "Off" Time | 300s | 300s |
+| Minimum Cooling "On" Time | 180s | 20s |
+| Minimum Heat "On" Time | 180s | 180s |
+| Min Cool "Off" Time (Fridge Constant Mode) | 600s | 60s |
+| Min time between switching between heat & cool | 600s | 600s |
+
+
+:::{Warning}
+Low Delay mode should never be used with compressor-based cooling as it may damage your equipment. Low Delay mode is intended for other types of cooling, such as glycol, chilled water pumps, fans/ice, or peltier coolers.
+:::
+
+
+### Rotate TFT
+
+TFT-based builds (ESP32) can have the display rotated if it is inserted in the case upside down (or the manufacturer has changed the default orientation). If your screen is upside-down, toggle this on. 
+
+
+
+

docs/source/Supported Sensors & Actuators.md

@@ -0,0 +1,49 @@
+# Supported Temperature Sensors & Switches/Actuators
+
+
+## Actuators (Switches/Relays)
+
+Two types of actuators are currently supported: Pin-based and Kasa WiFi Switches:
+
+### Pin-based Actuators
+
+Pin-based actuators are the traditional type used with BrewPi where an output pin on the controller turns on/off based on whether the controller is calling for heating or cooling. This pin is typically then connected to a relay which then switches the load of the heater/cooler. The "sainsmart" style relay boards are slightly unintuitive in that the pin being "high" (on) actually results in the load being turned _off_. To resolve this, there is an "Invert Pin" option that can be set to ensure that these style of boards are properly toggled on/off. 
+
+:::{important}
+When setting up a pin, make sure that the device is off when you expect it to be off, and is on when you expect it to be on. Setting the "invert" flag incorrectly can reverse these, resulting in frozen beer (or worse, if your heater runs indefinitely!)
+:::
+
+### TPLink Kasa WiFi Smart Switches
+
+Kasa WiFi Switches are "smart" plugs which allow for your cooling/heating source to be plugged into a WiFi-enabled device that can then be toggled over your network. BrewPi-ESP detects these devices when connected to the same WiFi network, and can control them without using TP Link's cloud. Initial connection of these devices to the internet (along with initial setup) is completed in the Kasa smart phone app -- once complete, these devices should be detected by BrewPi-ESP.
+
+
+## Temperature Sensors
+
+There are three types of temperature sensors supported by BrewPi-ESP: OneWire (DS18b20) temperature sensors, Inkbird bluetooth temperature sensors, and Tilt Pro hydrometers. All three types of temperature sensors allow for a calibration offset to be defined: An amount - specified in 1/16 degree C - that will be added to/subtracted from each reading.
+
+
+### OneWire Sensors (DS18b20)
+
+OneWire (DS18b20) temperature sensors are the type traditionally used with BrewPi, and are hard-wired to the controller. They can often be purchased in stainless, waterproof housing, connected to several meter long cables, ready for insertion into a thermowell. Most of these sensors are powered via discrete power, but parasite power versions exist -- BrewPi-ESP will not function with parasitic sensors.
+
+
+### Inkbird Bluetooth Temperature Sensors
+
+Inkbird manufactures a number of wireless bluetooth temperature sensors, several of which have been tested and work with BrewPi-ESP:
+
+* Inkbird IBS-TH1 Plus
+* Inkbird IBS-TH2 (both temperature only and temperature + humidity)
+* Inkbird IBS-TH2 Plus
+
+The "plus" versions of these sensors typically come with an extendable temperature probe that can be inserted into a thermowell, and oftentimes also include a display.
+
+
+### Tilt Hydrometers
+
+Tilt hydrometers are bluetooth devices that measure both the specific gravity and temperature of your fermenting beer. There are two versions available - the Tilt and the Tilt Pro. The Tilt Pro offers temperature resolution of 0.1 F whereas the regular Tilt offers temperature resolution of whole degrees fahrenheit. The Tilt is an ideal solution for setups that lack a thermowell (or instances where the Tilt would be utilized regardless). 
+
+:::{note}
+Due to their higher thermal mass and finer resolution, temperature control using a Tilt is only recommended with the Tilt Pro. Use of a non-Pro tilt is possible, but will result in less accurate temperature control. 
+:::
+

docs/source/Web Interface.md

@@ -0,0 +1,41 @@
+# Using the BrewPi-ESP Web Interface
+
+
+## Dashboard
+
+The dashboard contains a "virtual" LCD showing the state of the controller, as well as dashboard panels breaking out the various control points. From this panel you can also change the control mode the controller is using to manage temperatures by clicking the "Change" link on the Control Mode panel.
+
+
+### Changing Control Mode
+
+After clicking the "Change" link a window will pop up allowing you to select the new control mode. There are three selectable modes from the web interface, and one mode that may appear if the controller is connected to BrewPi Remix or Fermentrack:
+
+* **Off** - Temperature control is disabled, and cooling/heating will be turned off
+* **Fridge Constant** - The controller will control the fridge/chamber temperature to match a setpoint
+* **Beer Constant** - The controller will control the beer temperature, using the fridge temperature as an input to the algorithm
+* **Beer Profile** - _Not selectable from the web interface_ - If the controller is connected to BrewPi Remix or Fermentrack and is currently applying a fermentation temperature profile, the controller will be placed in Beer Profile mode. Beer Profile mode is not selectable from the web interface as management of the profile is handled by Fermentrack/BrewPi Remix.
+
+When selecting Fridge Constant or Beer Constant mode you will be asked to provide a temperature setpoint to control to in the temperature units selected on the controller.
+
+
+## Set up Sensors/Actuators
+
+BrewPi-ESP is designed to read temperatures from a number of different types of temperature data sources and use that to control temperature by actuating several types of switches. In order for this to work, BrewPi-ESP must be told which temperature sensors correspond with each data type (beer temp, fridge temp, or room temp) and which actuators correspond to heating/cooling. The Set Up Sensors/Actuators page allows you to see all sensors/actuators known to the controller and assign each device the relevant function. 
+
+More information on supported sensors and actuators can be found in [](Supported Sensors & Actuators.md).
+
+
+## Controller Settings
+
+The Controller Settings page allows you to toggle certain settings associated with the controller. A discussion of these settings can be found in [](Controller Configuration Options.md).
+
+
+## About Controller
+
+The About Controller page allows you to see the controller's firmware version, the time since last reboot, some debugging information around what caused the last reboot, and the amount of free memory available on the controller. 
+
+
+## Technical Notes
+
+The BrewPi-ESP front end is written in JavaScript + Vue. The source files for the interface are saved to a [separate repository on GitHub](https://github.com/thorrak/brewpi_esp_ui) and are governed by a different license from BrewPi-ESP. The front end primarily speaks to the controller via a number of JSON api endpoints that were designed specifically for this purpose. Please be aware that these endpoints are not expected to remain static between firmware versions, and _will_ change without notice.
+s

docs/source/conf.py

@@ -0,0 +1,29 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'BrewPi-ESP'
+copyright = '2023, John Beeler'
+author = 'John Beeler'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['myst_parser']
+
+myst_enable_extensions = ["colon_fence"]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/source/index.md

@@ -0,0 +1,28 @@
+.. BrewPi-ESP documentation master file, created by
+ sphinx-quickstart on Thu Mar 2 08:43:24 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to BrewPi-ESP's documentation!
+======================================
+
+
+:::{toctree}
+:maxdepth: 1
+Installing the Firmware.md
+Controller Configuration Options.md
+Selecting an ESP Board.md
+Solder Free BrewPi.md
+Web Interface.md
+Supported Sensors & Actuators.md
+:::
+
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`