Merge pull request #4 from lbussy/devel

New BrewPi Remix Docs
brewpi-remix · Jun 9, 2019 · c49918d · c49918d
2 parents eaa0af4 + 2e7f7db
commit c49918d
Show file tree

Hide file tree

Showing 166 changed files with 5,817 additions and 5,448 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+brewpi-userdocs-remix.code-workspace
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "restructuredtext.confPath": "${workspaceFolder}"
+}
diff --git a/docs/Makefile → Makefile b/docs/Makefile → Makefile
diff --git a/README.md b/README.md
@@ -0,0 +1,14 @@
+# ![BrewPi Legacy Remix Logo](https://raw.githubusercontent.com/lbussy/brewpi-www-rmx/master/images/brewpi_logo.png)
+BrewPi Remix Documentation
+==========================
+
+This repository contains documentation created for users of [BrewPi Remix](https://www.brewpiremix.com).
+
+License
+-------
+BrewPi-UserDocs-RMX is licensed under the [GNU General Public License v3.0](https://github.com/lbussy/brewpi-userdocs-rmx/blob/master/LICENSE).
+
+Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.
+
+[![Documentation 
+Status](https://readthedocs.org/projects/brewpi-userdocs-rmx/badge/?version=legacy)](https://brewpi-userdocs-rmx.readthedocs.io/en/devel/?badge=devel)
diff --git a/_build/doctrees/README.doctree b/_build/doctrees/README.doctree
diff --git a/_build/doctrees/automated/index.doctree b/_build/doctrees/automated/index.doctree
diff --git a/_build/doctrees/automated/security.doctree b/_build/doctrees/automated/security.doctree
diff --git a/_build/doctrees/devices/index.doctree b/_build/doctrees/devices/index.doctree
diff --git a/_build/doctrees/environment.pickle b/_build/doctrees/environment.pickle
diff --git a/_build/doctrees/index.doctree b/_build/doctrees/index.doctree
diff --git a/_build/doctrees/manual/arduino.doctree b/_build/doctrees/manual/arduino.doctree
diff --git a/_build/doctrees/manual/index.doctree b/_build/doctrees/manual/index.doctree
diff --git a/_build/doctrees/multi/index.doctree b/_build/doctrees/multi/index.doctree
diff --git a/_build/doctrees/rpi/index.doctree b/_build/doctrees/rpi/index.doctree
diff --git a/_build/doctrees/update/index.doctree b/_build/doctrees/update/index.doctree
diff --git a/docs/_build/html/.buildinfo → _build/html/.buildinfo b/docs/_build/html/.buildinfo → _build/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: e0e68f116bd817e608c669ff62d5885c
+config: a75ca169af2dc74d3f105575de72b1ef
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/_build/html/.doctrees/README.doctree b/_build/html/.doctrees/README.doctree
diff --git a/_build/html/.doctrees/automated/index.doctree b/_build/html/.doctrees/automated/index.doctree
diff --git a/_build/html/.doctrees/automated/security.doctree b/_build/html/.doctrees/automated/security.doctree
diff --git a/_build/html/.doctrees/devices/index.doctree b/_build/html/.doctrees/devices/index.doctree
diff --git a/_build/html/.doctrees/environment.pickle b/_build/html/.doctrees/environment.pickle
diff --git a/_build/html/.doctrees/index.doctree b/_build/html/.doctrees/index.doctree
diff --git a/_build/html/.doctrees/manual/arduino.doctree b/_build/html/.doctrees/manual/arduino.doctree
diff --git a/_build/html/.doctrees/manual/index.doctree b/_build/html/.doctrees/manual/index.doctree
diff --git a/_build/html/.doctrees/multi/index.doctree b/_build/html/.doctrees/multi/index.doctree
diff --git a/_build/html/.doctrees/rpi-install/index.doctree b/_build/html/.doctrees/rpi-install/index.doctree
diff --git a/_build/html/.doctrees/rpi/index.doctree b/_build/html/.doctrees/rpi/index.doctree
diff --git a/_build/html/.doctrees/update/index.doctree b/_build/html/.doctrees/update/index.doctree
diff --git a/_build/html/README.html b/_build/html/README.html
@@ -0,0 +1,106 @@
+
+
+<!doctype html>
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title> &#8212; BrewPi Remix 0.0.1 documentation</title>
+    <link rel="stylesheet" href="_static/bizstyle.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="_static/language_data.js"></script>
+    <script type="text/javascript" src="_static/bizstyle.js"></script>
+    <link rel="index" title="Index" href="genindex.html" />
+    <link rel="search" title="Search" href="search.html" />
+    <meta name="viewport" content="width=device-width,initial-scale=1.0">
+    <!--[if lt IE 9]>
+    <script type="text/javascript" src="_static/css3-mediaqueries.js"></script>
+    <![endif]-->
+  </head><body>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">BrewPi Remix 0.0.1 documentation</a> &#187;</li> 
+      </ul>
+    </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#"></a></li>
+<li><a class="reference internal" href="#brewpi-remix-documentation">BrewPi Remix Documentation</a><ul>
+<li><a class="reference internal" href="#license">License</a></li>
+</ul>
+</li>
+</ul>
+
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/README.md.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="search.html" method="get">
+      <input type="text" name="q" />
+      <input type="submit" value="Go" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+
+  <div class="section" id="id1">
+<h1><img alt="https://raw.githubusercontent.com/lbussy/brewpi-www-rmx/master/images/brewpi_logo.png" src="https://raw.githubusercontent.com/lbussy/brewpi-www-rmx/master/images/brewpi_logo.png" />BrewPi Legacy Remix Logo<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h1>
+</div>
+<div class="section" id="brewpi-remix-documentation">
+<h1>BrewPi Remix Documentation<a class="headerlink" href="#brewpi-remix-documentation" title="Permalink to this headline">¶</a></h1>
+<p>This repository contains documentation created for users of <a class="reference external" href="https://www.brewpiremix.com">BrewPi Remix</a>.</p>
+<div class="section" id="license">
+<h2>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
+<p>BrewPi-UserDocs-RMX is licensed under the <a class="reference external" href="https://github.com/lbussy/brewpi-userdocs-rmx/blob/master/LICENSE">GNU General Public License v3.0</a>.</p>
+<p>Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.</p>
+</div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">BrewPi Remix 0.0.1 documentation</a> &#187;</li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2019, Lee C. Bussy.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
+    </div>
+  </body>
+</html>
diff --git a/...uild/html/_images/device-list-example.png → _build/html/_images/device-list-example.png b/...uild/html/_images/device-list-example.png → _build/html/_images/device-list-example.png
diff --git a/_build/html/_sources/README.md.txt b/_build/html/_sources/README.md.txt
@@ -0,0 +1,11 @@
+# ![BrewPi Legacy Remix Logo](https://raw.githubusercontent.com/lbussy/brewpi-www-rmx/master/images/brewpi_logo.png)
+BrewPi Remix Documentation
+==========================
+
+This repository contains documentation created for users of [BrewPi Remix](https://www.brewpiremix.com).
+
+License
+-------
+BrewPi-UserDocs-RMX is licensed under the [GNU General Public License v3.0](https://github.com/lbussy/brewpi-userdocs-rmx/blob/master/LICENSE).
+
+Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.
diff --git a/_build/html/_sources/automated/index.rst.txt b/_build/html/_sources/automated/index.rst.txt
@@ -0,0 +1,24 @@
+Automated Installation of BrewPi
+================================
+Part of the "remix" in the BrewPi Remix project was to create all new scripts and methods to install and update BrewPi. These scripts are part of the `brewpi-tools-rmx repository on GitHub <https://github.com/lbussy/brewpi-tools-rmx>`_.
+The install script will install all dependencies, set up users and permissions, download the latest code base and setup a few system daemons to keep things running well.
+
+Behind the scenes there are actually four GitHub repositories required to run BrewPi.  None of that will be visible to most users.  Most people will only need to follow the instructions they are presented to get a perfectly running system.
+
+Running the Install Script
+--------------------------------------
+The initial install is handled by a bootstrap script, which will execute, provide for dependencies, and call the rest of the scripts needed.  Behind the scenes; GitHub repositories will be cloned to your RPi, apt packages will be downloaded and installed, and configuration items created.
+
+If you are security conscious, naturally inquisitive, or would just like to know what's going on, have a look at this :doc:`note about security <./security>`.
+
+Use the following command to begin the installation, no other preparation or commands are necessary.  The script is automatically downloaded for you:
+
+.. code-block:: console
+
+    curl -L install.brewpiremix.com | sudo bash
+
+Now just follow the instructions on the screen.
+
+After the Install
+------------------------------
+If the installation was successful, your last step will be to :doc:`to set up your devices in the device manager <../devices/index>`.
diff --git a/_build/html/_sources/automated/security.rst.txt b/_build/html/_sources/automated/security.rst.txt
@@ -0,0 +1,28 @@
+About Security
+==============
+My instructions will tell you to copy and paste a command into your terminal window.  Despite me telling you to do that, I am now going to tell you how *unsafe* that is.  Many people browse the Internet, find the command they need, and blindly paste it into their terminal window.  This one is (potentially) **dangerous** from a non-trusted source:
+
+.. code-block:: console
+
+    curl -L install.brewpiremix.com | sudo bash
+
+Here's how to decode it:  In this case I've provided an easy to remember Internet address `install.brewpiremix.com <install.brewpiremix.com>`_ on my website.  That's not actually where it goes however because on that website I have it redirecting to the `real script <https://raw.githubusercontent.com/lbussy/brewpi-tools-rmx/master/bootstrap.sh>`_ on GitHub. That script is then piped (via the `|` character) through the command `sudo bash`.  When you use `sudo` it will run the command which *follows* with `root` privileges.  So, you basically found someone on the Internet telling you to run their code as root, without even knowing what it all does.  Seems scary now, doesn't it?
+
+Despite the inherent risk, installing an application as root is often necessary since many applications have to make global changes to your system.  In this case I am helping you by installing various helper packages for BrewPi, setting up system services like the Apache web server which allows you to connect to BrewPi, creates the actual user `brewpi` under which the scripts run, and some other necessary housekeeping.
+
+**This is how bad things happen.**
+
+Even if you think you *completely* understand the command you are reading and copying, there is still an opportunity for a specially crafted web page to make the command look like one thing, but be a completely different command when you paste it.  That would be **A Bad Thing™.**  For an example, see `this page which describes this copy/paste vulnerability <https://www.brewpiremix.com/copy-paste-and-you/>`_.
+
+The lesson to be learned from this is if you are going to copy/paste a command from *any* source, always use an interim paste into a text editor like Notepad or type it in manually to make sure **A Bad Thing™** doesn't happen to you.
+
+Wait.
+
+Now you don't know if you should trust the setup command I provided?  I'm shedding a happy tear.  Security and the Internet is a rabbit hole filled with (justifiable) paranoia and bad actors.  Your choices here however are:
+
+1. Trust me and run it, or;
+2. Examine `that script <https://github.com/lbussy/brewpi-tools-rmx/blob/master/bootstrap.sh>`_ carefully and make sure it does nothing bad.  Then, since the first one executes as root you need to follow that to the `next one <https://github.com/lbussy/brewpi-tools-rmx/blob/master/install.sh>`_ because it inherits that security construct from the first.
+
+Ultimately you can drive yourself crazy when you realize the implications, or just accept that whenever you install free code from the Internet you take your chances.  This is the case with any software, not just BrewPi.
+
+Now, newly armed with facts, you can head back to :doc:`the automated install instructions <./index>` to get back on track.
diff --git a/_build/html/_sources/devices/index.rst.txt b/_build/html/_sources/devices/index.rst.txt
@@ -0,0 +1,62 @@
+Configuring your Devices
+========================
+Since BrewPi 0.2, the hardware setup is dynamic and flexible: you can install and uninstall hardware from the web interface. This is all done from the `Device Configuration` tab in the web interface. From the device manager you can assign hardware (temp sensors, SSRs, etc.) to functions.
+
+Your Devices After Programming
+-----------------------------------
+If you have just uploaded a HEX file to your Arduino and the EEPROM was reset, no devices are installed by default.
+
+Receiving the Device List
+-------------------------
+Even with no devices configured, you must first click `Refresh device list` to receive an updated list of installed and detected devices an slots from the Arduino. To be able to receive the device list, the BrewPi script has to be running.
+
+Detected Devices
+^^^^^^^^^^^^^^^^
+The detected devices list shows all devices that are automatically discovered by BrewPi, these include:
+ * All OneWire devices (temperature sensors and DS2413 OneWire switches)
+ * All pins for which there is an assigned terminal on your shield
+
+Installed Devices
+^^^^^^^^^^^^^^^^^
+All devices that are assigned to a function are found under `Installed devices`.
+
+Device Properties
+^^^^^^^^^^^^^^^^^
+Each device has the following properties:
+
+==========================  =====
+Device setting/property     What it does
+==========================  =====
+**Device slot**             A device is installed into a device slot. This is a unique number used to identify the device. When configuring your devices, make sure there are no 2 devices with the same slot.
+**Assigned to (chamber)**   Each device is assigned to a Chamber. Currently there is only Chamber 1, but we are preparing for future multi-chamber support. Select `Chamber 1` for all your devices.
+**Assigned to (beer)**      In each chamber, each device is either a `Chamber device` or assigned to a beer. Currently all supported devices are chamber devices, except for the beer temperature sensor which should be assigned to `Beer 1`.
+**Function**                This is the most important setting for your device. Here you can set what the device should do. The function list is automatically limited to functions that fit with the hardware type. Currently supported functions:
+                              - **Chamber temp**: the sensor in the fridge (chamber device).
+                              - **Beer temp**: the sensor in your beer (beer device).
+                              - **Room temp**: measures any temperature you want, but is not used in the algorithm, just for logging (chamber device).
+                              - **Chamber cooler**: The output that controls your fridge compressor (chamber device).
+                              - **Chamber heater**: The output that controls your heater (chamber device).
+                              - **Chamber light**: This output is activated when the door is opened (see chamber door) and can also be used as heater by enabling `light as heater` in advanced settings.
+                              - **Chamber door**: an input that detects when the fridge door is opened.
+**Device type**             Not user configurable, set automatically based on assigned function.
+**Hardware type**           Not user configurable, set automatically (`Temp Sensor`, `Digital pin` or `OneWire actuator`).
+**Device type**             Not user configurable, set automatically based on assigned function.
+**Pin type**                Here you can set whether the output/input should be inverted. Because the shields have a transistor that inverts the signal behind each output with a terminal, you should set this to `inverted`. For devices you add yourself, without a transistor, do not invert the signal. For the door switch, it depends on the type of switch you have.
+**Arduino Pin**             The pin the device is configured for. You can only set this yourself when defining a new device. The OneWire pins are hardcoded, you can not add your own OneWire pins. Just connect your sensors to an existing OneWire pin and refresh the device list to detect it.
+==========================  =====
+
+Installing new devices and assigning them to a function
+-------------------------------------------------------
+You can install a device by changing the properties to a correct configuration and hitting `Apply`. If the values are accepted by the Arduino, your device will show up under `Installed Devices` after refreshing the list.
+
+Please refer to the screenshot below for a reference configuration with all devices installed currently supported by BrewPi. Just leave out any devices you don't have.
+
+.. image:: device-list-example.png
+
+Uninstalling a device
+---------------------
+To uninstall a device, just set it's function to `None`, hit `Apply` and refresh your device list.
+
+Work Complete
+^^^^^^^^^^^^^
+That was the last step of 'Getting started with BrewPi Remix' Enjoy using your BrewPi and don't forget to come and say hi on the `Mega Thread <https://www.homebrewtalk.com/forum/threads/howto-make-a-brewpi-fermentation-controller-for-cheap.466106/>`_.
diff --git a/_build/html/_sources/index.rst.txt b/_build/html/_sources/index.rst.txt
@@ -0,0 +1,26 @@
+.. image:: https://raw.githubusercontent.com/lbussy/brewpi-www-rmx/master/images/brewpi_logo.png
+
+BrewPi Remix Documentation
+========================================
+This documentation is written in reStructured text format and is part of the `BrewPi Remix Project
+<https://www.brewpiremix.com/>`_.  If you see something that could use some updating, please let me know. Even better: Fix it yourself and send me a pull request on GitHub.
+
+This documentation is intended for the beginner, who has to find a teenager just to change his or her wallpaper.  It should also contain ample "just the facts" information for more experienced users.  A deficiency in the documentation (i.e. if you get lost) is considered a bug, and you should bring it to my attention.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    ./rpi/index.rst
+    ./automated/index.rst
+    ./devices/index.rst
+    ./manual/index.rst
+    ./manual/arduino.rst
+    ./multi/index.rst
+    ./update/index.rst
+
+.. Indices and tables
+.. ==================
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`