diff --git a/TODO.md b/TODO.md index fa9c59b..901aafc 100644 --- a/TODO.md +++ b/TODO.md @@ -1,7 +1,8 @@ # TODO List ## Open -- Update documentation + +- Figure out if we switch from PCBs.io ### Completed This Sprint - ~~Look into NaN on Bubbles after flash~~ @@ -11,6 +12,7 @@ - ~~Auto-reload the About page information~~ - ~~Detect first run after flash~~ - ~~Normalize DRD with KC~~ +- ~~Update documentation~~ ### Completed this version - ~~Fix 'nan' error in Bubbles after SPIFFS upload~~ diff --git a/docs/assembly/index.rst b/docs/assembly/index.rst index 0a474d6..021b1b9 100644 --- a/docs/assembly/index.rst +++ b/docs/assembly/index.rst @@ -3,7 +3,7 @@ Device Assembly ======================================== -Brew Bubbles runs on an ESP8266 controller. To detect the information to be logged, you need to connect specific devices to the controller. I have provided a circuit board design, sometimes called a "shield" to make this easier. +Brew Bubbles runs on an ESP8266 controller. To detect the information to be logged, you need to connect specific devices to the controller. I have provided a circuit board design, sometimes called a "shield," to make this easier. Assembly is not difficult, but it does require some basic soldering. @@ -19,13 +19,13 @@ Controller The ESP8266 controller is paired with many different "developer boards" to make connections easier. Do yourself a favor and do not buy a bare ESP8266 chip. I can't help you if you do. -The developer board used in this project is the **Wemos D1 Mini**. Wherever you purchase it, make sure it is an ESP-12F (if that information is listed) and that it says 4MB (or sometimes shown as 32Mb which is 4 megaBYTES converted to megaBITS.) Also, be sure it comes with the 8-pin male and female headers, or else you will need to get them elsewhere. You can find the Wemos D1 Mini in many places, here are a few: +The developer board used in this project is the **Wemos D1 Mini**. Wherever you purchase it, make sure it is an ESP-12F (if that information is listed) and that it says 4MB (or sometimes shown as 32Mb, which is 4 megaBYTES converted to megaBITS.) Also, be sure it comes with the 8-pin male and female headers, or else you will need to get them elsewhere. You can find the Wemos D1 Mini in many places; here are a few: -#. **The "Legitimate" Way**: The Wemos D1 Mini has been knocked off mercilessly. This situation is ironic since Espressif makes the ESP8266 controller, and they are a Chinese company. In the past, wemos.cc_ was the way to buy the "original" Wemos D1 Mini. However, they no longer appear to sell them, and instead, the website is a wiki-type information source. +#. **The "Legitimate" Way**: The Chinese have knocked the Wemos D1 Mini has mercilessly. This situation is ironic since Espressif makes the ESP8266 controller, and they are a Chinese company. In the past, wemos.cc_ was the way to buy the "original" Wemos D1 Mini. However, they no longer appear to sell directly, and instead, the website is a wiki-type information source. #. **The Quick Way**: Why Amazon, of course. You can search for "Wemos D1 Mini" (it has to be "mini" and not "pro") and find a large number of different ways to buy. My preference is to get a handful at a time since they are cheaper that way. This_ link gives you five for $17.99 in a couple of days with free Prime shipping ($3.60/ea.) -#. **The Cheap Way**: AliExpress_ has everything anyone would ever need, so long as that person can wait a month or more for delivery. For $1.99 each this way is as cheap as it gets. Be aware that there are different sellers on there, and each ship independently. Sometimes you save by paying less on shipping if you are buying multiple things from one seller. +#. **The Cheap Way**: AliExpress_ has everything anyone would ever need, so long as that person can wait a month or more for delivery. For $1.99 each, this way is as cheap as it gets. Be aware that there are different sellers on there, and each ship independently. Sometimes you save by paying less on shipping if you are buying multiple things from one seller. Printed Circuit Board ````````````````````` @@ -53,7 +53,7 @@ General Parts These are the parts which you can get pretty much anywhere. -The items marked with an \*asterisk below are optional. They are in the design to provide a means to monitor and trend the ambient temperature where you place the fermenter, and the fermenting liquid's temperature via a thermowell or insulated in contact with the fermenter. If you choose not to use these, the firmware automatically skips reporting these readings. +The items marked with an \*asterisk below are optional. They are in the design to provide a means to monitor and trend the ambient temperature where you place the fermenter and the fermenting liquid's temperature via a thermowell or insulated in contact with the fermenter. If you choose not to use these, the firmware automatically skips reporting these readings. ===== ====================================== ============ Quan Description Placement @@ -66,32 +66,32 @@ Quan Description Placement 2* DS18B20 Temperature sensor and lead VESSEL, ROOM ===== ====================================== ============ -This BOM is available on Mouser_. You can find these parts just about any of the usual places. Make sure they are the proper rating and form factor. +This BOM is available on Mouser_. You can find these parts in just about any of the usual places. Please make sure they are the proper rating and form factor. -If you choose to use the temperature sensors, you need to obtain two (2) Waterproof DS18B20_ Temperature Sensor with leads. These are the same as used with the various fermenter temperature control projects such as BrewPi Remix. You also need to crimp on a three-terminal female plug. You can get a kit_ on Amazon with more terminals than you ever need including the crimping tool for about $25 or save by doing some careful AliExpress shopping. +If you choose to use the temperature sensors, you need to obtain two (2) Waterproof DS18B20_ Temperature Sensor with leads. These are the same as used with the various fermenter temperature control projects such as BrewPi Remix. You also need to crimp on a three-terminal female plug. You can get a kit_ on Amazon with more terminals than you ever need, including the crimping tool, for about $25 or save by doing some careful AliExpress shopping. Component Installation ---------------------- -You are going to have to solder. If you have legitimately never soldered anything before, I recommend you spend a few minutes on YouTube and watch a few videos. Sparkfun_ also has a very nice tutorial_. It is not hard at all once you get the hang of it. And, while the shield is comparatively small, the components chosen are simple through-hole parts, which may be easily soldered by a beginner with a little patience. +You are going to have to solder. If you have legitimately never soldered anything before, I recommend you spend a few minutes on YouTube and watch a few videos. Sparkfun_ also has a very nice tutorial_. It is not hard at all once you get the hang of it. While the shield is comparatively small, the components chosen are simple through-hole parts, which may be easily soldered by a beginner with a little patience. I do not intend to provide a step-by-step on how to solder here. Still, I recommend the following part installation order for ease of assembly: -1. Resistors - As the shortest mounted components, soldering the three resistors to the board first is the least challenging. They are also some of the most tolerant components, so these grant you some experience to get you going. +1. Resistors - As the shortest mounted components, soldering the three resistors to the board first is the least challenging. They are also some of the most tolerant parts, so these grant you some experience to get you going. -2. 3-Pin headers - These components are not sensitive to the heat at all except for the plastic. +2. 3-Pin headers - These components are not sensitive to the heat except for the plastic. 3. Capacitors - These are mounted next. Be sure to get them as close to the board as possible since having them stick up changes their intended impact on the circuit. -4. 8-pin female headers - These are the tallest items on the front side of the board and are the last pieces to go on this side. Lightly tack on one pin and make sure the header is straight. When you have it positioned correctly, start from the other end, and solder the pins correctly. If you have a D1 laying around with the pin headers soldered on it already, using that to steady the parts helps. This process is a chicken or the egg choice with the next item. The first part to be soldered, either the controller or shield, is the most difficult. After that, you can use the other to steady the headers of the first. If you have a breadboard, you may also employ that to steady the parts. +4. 8-pin female headers - These are the tallest items on the front side of the board and are the last pieces to go on this side. Lightly tack on one pin and make sure the header is straight. When you have it positioned correctly, start from the other end, and solder the pins correctly. If you have a D1 laying around with the pin headers soldered on it already, using that to steady the parts helps. This process is a chicken or the egg choice with the next item. The first part to be soldered, either the controller or shield is the most difficult. After that, you can use the other to steady the headers of the first. If you have a breadboard, you may also employ that to steady the parts. 5. 8-pin male headers - These need to be soldered on the controller board. See note on #4 above. -6. GP1A57HR photo-interrupter - If the controller is still attached, take it off temporarily. The photo-interrupter goes on the *back* side of the circuit board in the outline provided. Therefore you solder it from the top side. If you put it on the wrong side, you can remove the solder (more YouTube work), but I'm not going to lie: it is frustrating. Be careful to di it right the first time. +6. GP1A57HR photo-interrupter - If the controller is still attached, take it off temporarily. The photo-interrupter goes on the *back* side of the circuit board in the outline provided. Therefore you solder it from the top side. If you put it on the wrong side, you can remove the solder (more YouTube work), but I'm not going to lie: it is frustrating. Be careful to do it right the first time. Once you have finished soldering the shield, make sure to clean off the flux. You can use cheap vodka or Everclear, or a commercially available flux solvent. -It should be apparent by now that the Wemos should plug into the shield. There is a notch in the shield which corresponds to the notch in the Wemos, and the controller should be on the same side as the components as shown: +It should be apparent by now that the Wemos should plug into the shield. There is a notch in the shield, which corresponds to the notch in the Wemos. The controller should be on the same side as the components as shown: .. figure:: complete.jpg :scale: 100 % @@ -101,7 +101,7 @@ It should be apparent by now that the Wemos should plug into the shield. There Sensors ------- -Obtain some Dupont headers and a crimper from any of the usual places. Crimp a 3-pin female header on your sensors and plug them in. +Obtain some Dupont headers and a crimper from any of the usual places. Crimp a 3-pin female header on your sensors and plug them in. Some have asked about the pin order and the potential to change it to facilitate soldering a DS18B20 sensor directly to the PCB. That configuration was how I did my early prototypes, and it was a nicer form factor. However, I quickly found out that the ESP8266 would heat the surrounding parts, and the sensor read about 10°F higher than it should. Other projects get away with this, I believe, because they use sleep mode on the controller. As a web-delivered application, that was not an option for me. Bracket and Mounting -------------------- @@ -113,9 +113,9 @@ Position the photo-receptor such that the U-gap surrounds the bottom of a fermen :align: center :alt: Position of sensor around airlock -You should certainly feel free to use duct tape or a rubber-band or whatever suits you to affix Brew Bubbles to the airlock. For those who desire a more finished approach, I have included a 3-D printable bracket_ design in the project. The finished controller & shield combo is slid into the top so that the temperature sensor connectors point up. The airlock is then passed through the hole in the bracket and into the carboy stopper. The hole may need to be adjusted larger or drilled out depending on the size of your airlock. If it is too loose around the airlock, a drill stop or even tape may be used on the tube under the bracket to hold it in place. +You should certainly feel free to use duct tape or a rubber-band or whatever suits you to affix Brew Bubbles to the airlock. I have included a 3-D printable bracket_ design in the project for those who desire a more finished approach. The completed controller & shield combo is slid into the top to allow the temperature sensor connectors to point up. The airlock is then passed through the hole in the bracket and into the carboy stopper. The hole may need to be adjusted larger or drilled out depending on the size of your airlock. If it is too loose around the airlock, a drill stop or even tape may be used on the tube under the bracket to hold it in place. -There is a hole in the side of the bracket intended to allow using a pop-rivet or small screw to secure the temperature sensor cable(s) with an R-type cable clamp_. I recommend this to avoid strain on the small wires. +There is a hole in the bracket side intended to allow using a pop-rivet or small screw to secure the temperature sensor cable(s) with an R-type cable clamp_. I recommend this to avoid strain on the small wires. .. figure:: mounted.jpg :scale: 45 % diff --git a/docs/configuration/7_brf_settings.jpg b/docs/configuration/7_brf_settings.jpg new file mode 100644 index 0000000..9b99c11 Binary files /dev/null and b/docs/configuration/7_brf_settings.jpg differ diff --git a/docs/configuration/8_ts_settings.jpg b/docs/configuration/8_ts_settings.jpg new file mode 100644 index 0000000..5fb3974 Binary files /dev/null and b/docs/configuration/8_ts_settings.jpg differ diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index 04da69d..15b64c6 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -6,7 +6,7 @@ Brew Bubbles is presented to the user for monitoring and configuration as a set mDNS Support for Client OS -------------------------- -The Brew Bubbles device leverages a multicast Domain Naming System (mDNS) to make it easier to connect to your device. You may also have heard of zeroconf, which includes mDNS, or Avahi, which is a different implementation of mDNS. For our purposes, all of them work together. +The Brew Bubbles device leverages a multicast Domain Naming System (mDNS) to make it easier to connect to your device. You may also have heard of zeroconf, which includes mDNS; or Avahi, which is a different implementation of mDNS. For our purposes, all of them work together. Since I designed Brew Bubbles to be accessed and configured via a web page, you need to know its address. Your local WiFi automatically assigns an IP address if you did not enter a static address in the WiFi configuration. You can always type in something like `192.168.4.100`, but that's not as easy to remember as `brewbubbles.local.` @@ -33,7 +33,7 @@ Menu Across the top of every page, a menu displays. The standard desktop page looks like the below: -.. figure:: desktop_header.JPG +.. figure:: desktop_header.jpg :scale: 100 % :align: center :alt: Desktop menu view @@ -86,7 +86,7 @@ Vessel Name Vessel Name is a label that you may assign to help you keep track of multiple devices. It defaults to "Fermenter 1," but you may change it in the settings. Bubbles per Minute - Brew Bubbles internally polls the device for approximately one minute. It then reports the bubbles per minute in exact terms, meaning the number may be a decimal. Brew Bubbles also uses a sliding window to average the readings to help filter noise. The sliding window is set at 15, meaning as the device is in operation, it reports Bubbles per Minute as an average of up to the last 15 readings. In effect, this is a 15-minute average. This window is not configurable via the interface. + Brew Bubbles internally polls the device for approximately one minute. It then reports the bubbles per minute in exact terms, meaning the number may be a decimal. Brew Bubbles also uses a sliding window to average the readings to help filter noise. The sliding window is set at 15, meaning as the device is in operation, it reports Bubbles per Minute as an average of up to the last 15 readings. In effect, this is a 15-minute moving average. This window is not configurable via the interface. Ambient Temp If you have an ambient (room) temperature sensor installed, this reports the temperature in the configured temperature format (default is Fahrenheit.) This temperature reports in a 5-minute sliding window. This window is not configurable via the interface. @@ -95,7 +95,7 @@ Vessel Temp If you have a vessel temperature sensor installed, this reports the temperature in the configured temperature format (default is Fahrenheit.) This temperature reports in a 5-minute sliding window. This window is not configurable via the interface. Last Reading - The date and time of the most recently calculated reading set within the controller. Internally the device refreshes its values every 60 seconds (approximately.) + The date and time of the most recently calculated reading set within the controller. Internally the device refreshes its values approximately every 60 seconds.) Refresh In The web page refreshes its displayed values every 60 seconds. This field shows the time remaining until that refresh. @@ -109,7 +109,7 @@ Settings Page The settings page contains all configurable items for configuration and control of Brew Bubbles. Note: - Each setting has an "Update" button to save that individual setting. Make sure you save each setting as you go. If you change two settings and click "Update," you will be saving only the setting corresponding to the update button alongside. + Each setting page as an "Update" button. Be sure to save any updates before leaving a page. There will be no reminder if you selct another link without saving. Controller Settings ``````````````````` @@ -129,7 +129,7 @@ mDNS ID: The name should be 3 to 24 characters in length, begin with a letter, and contain only ASCII letters 'a' through 'z' (case-insensitive), the digits '0' through '9', and the hyphen-minus character ('-'). Do not include the `.local` portion of the mDNS name. Bubble ID: - Bubble ID is an additional field that can distinguish between different Brew Bubbles devices reporting to a shared system. + Bubble ID is an additional field that can help distinguish between different Brew Bubbles devices reporting to a shared system. Temperature Settings ```````````````````` @@ -142,13 +142,13 @@ Configure temperature format and calibration in this section: :alt: Temperature Settings Temperature Format: - Select either Fahrenheit or Celsius with the radio button and click "Update." Conversion happens internally to the controller and displays in the proper format. + Select either Fahrenheit or Celsius with the radio button. Conversion happens internal to the controller and reports in the proper format. Temperature Calibration: - In this section, you may enter calibration offsets to either sensor independently. Enter any decimal-based number from -25.0 to 25.0 and click "Update." The offset applies internally, and the corrected temperatures are displayed. + In this section, you may enter calibration offsets to either sensor independently. Enter any decimal-based number from -25.0 to 25.0 and click "Update." The compensation applies internally, and the corrected temperatures are displayed. -Target Settings -``````````````` +URL Target Settings +```````````````````` Target settings control how Brew Bubbles reports to HTML endpoints such as BrewPi Remix or Fermentrack. BrewPi Remix automatically begins to report on Brew Bubbles' data once received at its endpoint. .. figure:: 5_target_settings.jpg @@ -157,7 +157,7 @@ Target settings control how Brew Bubbles reports to HTML endpoints such as BrewP :alt: Target Settings Target: - The target may be any DNS or mDNS name. If you are using mDNS, be sure to include the ".local" portion. The address should be a complete URI, including the target page and port if needed. For BrewPi Remix, the name will be `http://{hostname}.local/brewpi-api.php`. Remember to click "Update" after entering the target URL. + The target may be any DNS or mDNS name. If you are using mDNS, be sure to include the ".local" portion. The address should be a complete URI, including the target page and port if needed. For BrewPi Remix, the name will be `\http://{hostname}.local/brewpi-api.php`. If you are unable to access Brew Bubbles using the \*.local name, you are not able to use a target with a .local name either. In this case, use the IP address of your target. @@ -175,9 +175,9 @@ Authority is made up of: authority = [userinfo@]host[:port] -For more information, please review the Wiki_ article. +For more information, please review the Wikipedia_ article. -.. _Wiki: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier +.. _Wikipedia: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier Push Frequency: Enter the push frequency in minutes. Be sure to check your target system's requirements and restrictions so that you do not flood the target. For BrewPi Remix, I recommend setting it at 2 minutes, which matches the default charting granularity. Valid settings for this field are 1 to 60 minutes. @@ -198,7 +198,52 @@ Brewer's Friend Key: Push Frequency: Enter the push frequency in minutes. Brewer's Friend requires that you push readings no more than once every 15 minutes. Valid settings for this field are 15 to 120 minutes. -Other -````` +Brewfather Settings +```````````````````` + +Brewfather integration is also supported. Adding Brew Bubbles to your Fermentation Chart is done in Settings where you will enable "Custom Stream." The device must have reported to Brewer's Friend at least once to be listed. + +.. figure:: 7_brf_settings.jpg + :scale: 110 % + :align: center + :alt: Brewfather Settings + +Brewfather Key: + Log into your Brewfather account and go to Settings > Custom Stream. Your API key will be a 10 to 64-character string of letters and numbers on the line following "URL \http://log.brewfather.net/stream?id=" (do not include the the URL.) e.g. you may see: \http://log.brewfather.net/stream?id=q4F3wPfooBa3X3, from which you will enter `q4F3wPfooBa3X3` as your key. + +Push Frequency: + Enter the push frequency in minutes. Brewfather requires that you push readings no more than once every 15 minutes. Valid settings for this field are 15 to 120 minutes. + +ThingSpeak Settings +```````````````````` + +ThingSpeak allows posting custom data streams in order to collect and report upon it. To enable this functionality, you must create a channel with the following: + +- **Name (optional):** Any you prefer, such as "Brew Bubbles | Fermenter 1" +- **Description (optional):** How you would like to present this, such as "Brew Bubbles data channel for Fermenter 1." +- **Field 1:** "BPM" and check enabled +- **Field 2:** "Ambient °F" (or "Ambient °C") and check the box to enable +- **Field 3:** "Vessel °F" (or "Vessel °C") and check the box to enable +- **Link to External Site (optional):** \https://www.brewbubbles.com +- **Link to GitHub (optional):** \https://github.com/lbussy/brew-bubbles/ + +After you create your channel, you may optionally go into "Sharing" and allow people to view your channel. The public URL may be discovered by selecting the "Public View" tab. + +.. figure:: 8_ts_settings.jpg + :scale: 110 % + :align: center + :alt: ThingSpeak Settings + +Channel ID: + Go to 'My Channels.' Select the 'API Keys' tab for your channel. The channel ID and write API key will be displayed. The Channel ID is a number towards the top in bolded characters. + +Channel Write Key: + Go to 'My Channels.' Select the 'API Keys' tab for your channel. The channel ID and write API key will be displayed. You must use the "Write" key, the "Read" key will not allow posting data. If you ever wish to generate a new write API key, you must re-enter it into Brew Bubbles or else posting will fail. + +Push Frequency: + Enter the push frequency in minutes. Users of a free account are limited to sending no more than 3 million messages each year to the ThingSpeak service. This works out to approximately 5 posts per minute. Users of the free license will also be limited to 4 channels. Since Brew Bubbles only allows you to send once per minute, and ThingSpeak limits you to four free channels, you are unlikely to find a way to exceed your quota. + +Advanced +`````````` I will cover Firmware Update and WiFi reset in subsequent sections. diff --git a/docs/firmwareupdate/1_update_firmware.jpg b/docs/firmwareupdate/1_update_firmware.jpg deleted file mode 100644 index 841c2c4..0000000 Binary files a/docs/firmwareupdate/1_update_firmware.jpg and /dev/null differ diff --git a/docs/firmwareupdate/2_update_firmware.jpg b/docs/firmwareupdate/2_update_firmware.jpg index 2a0f438..cde34d9 100644 Binary files a/docs/firmwareupdate/2_update_firmware.jpg and b/docs/firmwareupdate/2_update_firmware.jpg differ diff --git a/docs/firmwareupdate/index.rst b/docs/firmwareupdate/index.rst index 8de6e6e..0696aa4 100644 --- a/docs/firmwareupdate/index.rst +++ b/docs/firmwareupdate/index.rst @@ -1,21 +1,14 @@ Firmware Update =============== -After you initially flash the controller, you may update Brew Bubbles via the web page when new versions are released. You may do this without erasing any of the Brew Bubbles' settings. If you instead choose to flash new firmware and LittleFS manually, your application configuration is lost. Click the "Update Firmware" button to continue. - -.. figure:: 1_update_firmware.jpg - :scale: 45 % - :align: center - :alt: Update Firmware - -The next page displays your controller's current version, as well as the latest version available. +After you initially flash the controller, you may update Brew Bubbles via the web page when new versions are released. You may do this without erasing any of the Brew Bubbles' settings. If you instead choose to flash new firmware and LittleFS manually, your application configuration is lost. This page displays your controller's current version, as well as the latest version available. .. figure:: 2_update_firmware.jpg - :scale: 45 % + :scale: 100 % :align: center :alt: Version comparison -If you wish to proceed, clicking "Update Firmware" one more time begins the process. +If you wish to proceed, clicking "Update Firmware" button begins the process. .. figure:: 3_update_firmware.jpg :scale: 45 % diff --git a/docs/home.png b/docs/home.png new file mode 100644 index 0000000..8832c2d Binary files /dev/null and b/docs/home.png differ diff --git a/docs/index.rst b/docs/index.rst index 369ee6b..efbe540 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,14 +8,19 @@ Brew Bubbles Documentation One of the very first things a homebrewer does in the morning after a brew day is rush to the fermenter and look to see if the airlock is bubbling. Just in case you are not quite at the point you take a day off afterward, or even remember to brew on Saturday, this project is for you. -Brew Bubbles is a combination hardware/software solution for homebrewers. Brew Bubbles intends to allow monitoring of the fermentation process by counting and reporting bubbles in an S-type airlock as “Bubbles per Minute” (BPM.) Also, since not everyone has a fancy fermentation chamber and temperature control, Brew Bubbles optionally reports the temperature of your fermenter and the room in which the fermenter rests. All of these reports in a compact mobile-responsive web page served by the device itself. +Brew Bubbles is a combination hardware/software solution for homebrewers. Brew Bubbles intends to monitor the fermentation process by counting and reporting bubbles in an S-type airlock as “Bubbles per Minute” (BPM.) Also, since not everyone has a fancy fermentation chamber and temperature control, Brew Bubbles optionally reports your fermenter’s temperature as well as that of which the room in which the fermenter rests. All of these reports in a compact mobile-responsive web page served by Brew Bubbles. -If you use temperature control already, such as BrewPi Remix or Fermentrack, Brew Bubbles reports that data to display in that solution. If you use a cloud dashboard for your brews such as Brewer’s Friend, the data may be displayed there as well. +If you use temperature control already, such as BrewPi Remix or Fermentrack, Brew Bubbles reports that data to display in that solution. If you use a cloud dashboard for your brews, such as Brewer’s Friend, you can display the data there as well. + +.. figure:: home.png + :scale: 75 % + :align: center + :alt: Main Window Contributions ------------- -This documentation is absolutely a work in progress, in that I depend on *you* to help me make sure it is relevant and easy to read. *I* know how to work with Brew Bubbles. My goal is to make you an expert too. Anything that is confusing is a bug and I want to know about it, please. +Documentation should always be considered a work in progress; in that, I depend on *you* to help me make sure it is relevant and easy to read. *I* know how to work with Brew Bubbles. My goal is to make you an expert too. Anything that is confusing is a bug, and I want to know about it, please. For spelling/grammatical errors, or if you would like to improve the documentation, please feel free to issue a pull request with the update. For technical issues with the documentation, please `open an issue on GitHub`_. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index ede18c5..91e61bd 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -7,10 +7,10 @@ There are two critical files in this project: File Description Address ============= ====================================== ========== firmware.bin_ The Brew Bubbles application layer 0x00000 -littlefs.bin_ The Brew Bubbles web file system 0x300000 +littlefs.bin_ The Brew Bubbles web file system 0x300000 ============= ====================================== ========== -These files represent the program that you upload to your controller. The `firmware.bin` file is the C-based program that handles serving web pages, processing configurations, detecting pulses (bubbles), scheduling, and monitoring the temperature. The LittleFS file system is delivered within the `littlefs.bin` file. LittleFS is analogous to a directory on your computer. It contains web pages and images served via the web interface. +These files represent the program that you upload to your controller. The `firmware.bin` file is the C-based program that handles serving web pages, processing configurations, detecting pulses (bubbles), scheduling, and monitoring the temperature. The `littlefs.bin` file is how the controller's web file system is delivered. It is analogous to a directory on your computer. It contains web pages and images served via the web interface. Flashing Firmware - Initial --------------------------- @@ -128,7 +128,7 @@ When setup is complete, click on the "*START*" button underneath the green box. :align: center :alt: Completion screen for the Flash Download tool -At this point, you may close the tool and the selection screen, and proceed with setup. +At this point, you may close the tool and the selection screen and proceed with setup. Erase Flash ----------- diff --git a/docs/prerequisites/index.rst b/docs/prerequisites/index.rst index 14360f7..344c9bb 100644 --- a/docs/prerequisites/index.rst +++ b/docs/prerequisites/index.rst @@ -1,12 +1,12 @@ Project Prerequisites ===================== -To use Brew Bubbles, you need to use an S-lock type fermentation lock. These locks are inexpensive and readily available. There are always discussions about the ability to clean these locks. It’s my experience that a warm soap and water soak followed by a good rinse handles the nasties. If you use a liquid such as Everclear or cheap Vodka in it, there are no worries about sucking germs back into your brew. For the price, you could replace them every few batches. +To use Brew Bubbles, you need to use an S-lock type fermentation lock. These locks are inexpensive and readily available. There are always discussions about the ability to clean these locks. It’s my experience that a warm soap and water soak followed by a good rinse handles the nasties. For the price of the airlocks, you could replace them every few batches if you were worried. -These are not perfect airlocks. I would have preferred to devise a way to use the three-piece airlocks; however, in testing, these proved to be exceedingly dependant upon the airlock fill level to work reliably. +These are not perfect airlocks. I would have preferred to devise a way to use the three-piece airlocks; however, in testing, these proved to be exceedingly dependant upon the airlock fill level to work reliably. Still, Brew Bubbles should take its signal from any input. The future may hold additional options. -If you use a blow-off-tube, you would remove that and replace it with the S-lock when blowoff danger has subsided. I have also had excellent results using FermCap-S and not using a blowoff tube despite vigorous fermentation. FermCap-S works well in the boil too. +If you use a blow-off-tube, you would remove that and replace it with the S-lock when blowoff danger has subsided. I have also had excellent results using FermCap-S and not using a blowoff tube despite vigorous fermentation. -On top of the S-lock, you need an ESP8266 controller and some other parts detailed in the Device Assembly page. +You need an ESP8266 controller and some other parts detailed on the Device Assembly page in addition to the S-lock. The :ref:`Assembly` page has a complete BOM for Brew Bubbles. -Add a tiny bit of time and some skill which you can pick up making a couple of these devices, and you have yourself an easy to make, low-cost, and rewarding DIY homebrew project. +Add a tiny bit of time and some skill you can pick up making a couple of these devices, and you have yourself an easy to make, low-cost, and rewarding DIY homebrew project. diff --git a/docs/setup/4_captive_portal.jpg b/docs/setup/4_captive_portal.jpg deleted file mode 100644 index 272bf97..0000000 Binary files a/docs/setup/4_captive_portal.jpg and /dev/null differ diff --git a/docs/setup/4_captive_portal.png b/docs/setup/4_captive_portal.png new file mode 100644 index 0000000..5efad0e Binary files /dev/null and b/docs/setup/4_captive_portal.png differ diff --git a/docs/setup/5_select_ap.jpg b/docs/setup/5_select_ap.jpg deleted file mode 100644 index c3a2b17..0000000 Binary files a/docs/setup/5_select_ap.jpg and /dev/null differ diff --git a/docs/setup/5_select_ap.png b/docs/setup/5_select_ap.png new file mode 100644 index 0000000..7852293 Binary files /dev/null and b/docs/setup/5_select_ap.png differ diff --git a/docs/setup/6_save_ap.jpg b/docs/setup/6_save_ap.jpg deleted file mode 100644 index a446434..0000000 Binary files a/docs/setup/6_save_ap.jpg and /dev/null differ diff --git a/docs/setup/6_save_ap.png b/docs/setup/6_save_ap.png new file mode 100644 index 0000000..f73a7e5 Binary files /dev/null and b/docs/setup/6_save_ap.png differ diff --git a/docs/setup/7_done.png b/docs/setup/7_done.png new file mode 100644 index 0000000..2b04d8b Binary files /dev/null and b/docs/setup/7_done.png differ diff --git a/docs/setup/index.rst b/docs/setup/index.rst index d2eaf6a..8b268b8 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -3,7 +3,7 @@ Set Up Networking Once you have flashed the firmware and littlefs files to your controller, it starts in Access Point mode with a captive portal. A captive portal is similar to what you get when you connect to free WiFi with a login web page. Any network communication will be redirected to the portal page, allowing you to log in. This captive portal is how you initially configure Brew Bubbles, allowing it to connect to your local WiFi. -This process works best through a phone in most cases. There are some peculiarities in the ESP8266 libraries, which sometimes cause the process to act a little flakey. It may not open the portal page, or not issue an IP address to your client. In testing, these problems did not come up using a phone. If you don't have a phone handy, it is possible to do this work with your computer. However, I point out some caveats below. +This process works best through a phone in most cases. There are some peculiarities in the ESP8266 libraries, which sometimes cause the process to act a little flakey. It may not open the portal page or not issue an IP address to your client. In testing, these problems did not come up using a phone. If you don't have a phone handy, it is possible to do this work with your computer. However, I point out some caveats below. Blink Mode: The LED on the ESP8266 is an indicator of various modes during operation. When in AP mode, the LED blinks on and off at 0.5Hz. That is, it is on for a second and off for a second. When in this mode, the access point shows up in the list of available access points on your client. @@ -49,7 +49,7 @@ Captive Portal Page does not Open Connection Timed Out or Similar Errors `````````````````````````````````````` -If you cannot open the captive portal web page by following the above instructions, it is possible your connection may not have been issued an IP address. Follow instructions for your particular platform to set the following parameters: +If you cannot open the captive portal web page by following the above instructions, the controller may not have issued your device an IP address. Follow instructions for your particular platform to set the following parameters: IP Configuration: IP Address: 192.168.4.2 @@ -72,19 +72,19 @@ When you access the captive portal, you have six choices: #. Restart #. Exit -.. figure:: 4_captive_portal.jpg - :scale: 90 % +.. figure:: 4_captive_portal.png + :scale: 25 % :align: center :alt: Captive portal choices Select option 1, "Configure WiFi." You see the following configuration screen: -.. figure:: 5_ select_ap.jpg - :scale: 90 % +.. figure:: 5_select_ap.png + :scale: 25 % :align: center :alt: Captive portal choices -Your access point should be visible in the list on top. Selecting it populates the name in the SSID field below. If your access point does not show up, you can re-scan or simply enter the AP name manually. Note this name is case-sensitive. Next, enter your access point password in the "Password" field. +Your access point should be visible in the list on top. Selecting it populates the name in the SSID field below. If your access point does not show up, you can re-scan or enter the AP name manually. Note this name is case-sensitive. Next, enter your access point password in the "Password" field. If you need to use a static IP address, you must fill out the following fields: @@ -93,13 +93,20 @@ If you need to use a static IP address, you must fill out the following fields: #. Subnet #. Static DNS -If you have questions about these fields, consult the documentation for your access point. You need not fill out these fields to use an automatically assigned IP address, since you may access the device by its name once connected to WiFi. +If you have questions about these fields, consult the documentation for your access point. You need not fill out these fields to use an automatically assigned IP address since you may access the device by its name once connected to WiFi. + +You may also change the device name, which is required if you have more than one device on the network. No two devices should have the same name. Once you have filled out at least the SSID and Password, click on the "Save" button. -.. figure:: 6_save_ap.jpg - :scale: 90 % +.. figure:: 6_save_ap.png + :scale: 25 % :align: center :alt: Save WiFi configuration -The controller restarts at this point and connects to the wireless access point you have configured. +The controller will now connect to the wireless access point you have configured. On most phones, the configuration page will close automatically. + +.. figure:: 7_done.png + :scale: 25 % + :align: center + :alt: Save WiFi configuration diff --git a/docs/troubleshooting/about_diags.jpg b/docs/troubleshooting/about_diags.jpg new file mode 100644 index 0000000..ab39f81 Binary files /dev/null and b/docs/troubleshooting/about_diags.jpg differ diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst index 36ff860..28c2b75 100644 --- a/docs/troubleshooting/index.rst +++ b/docs/troubleshooting/index.rst @@ -6,7 +6,7 @@ The easiest way to get help with the project is to join the `Brew Bubbles discus .. _Brew Bubbles discussion on Homebrewtalk.com: https://support.brewbubbles.com .. _Github: https://github.com/lbussy/brew-bubbles/issues -As a means to help you determine what is going wrong with your setup, this page includes various bits and pieces which do not fit elsewhere. +This page includes various bits and pieces that do not fit elsewhere, which may help you if things are not going as expected. LED Flashing ------------ @@ -16,30 +16,62 @@ In typical operation, the blue LED on the controller indicates the photo-recepto During non-operating mode, the LED flashes at different frequencies as an indicator of the process underway. 0.5Hz: - The LED blinks at 0.5Hz or 1 second on, one second off, when in Access Point mode + The LED blinks at 0.5Hz or 1 second on, one second off when in Access Point mode 0.66Hz: - The LED blinks at 1.5Hz (33 seconds on, .33 seconds off) while the controller is attempting to connect to your WiFi. After trying for 30 seconds, the connection attempt fails, and the controller enters AP mode. AP mode times out after 120 seconds and resets the controller. + The LED blinks at 1.5Hz (33 seconds on, .33 seconds off) while the controller attempts to connect to your WiFi. After trying for 30 seconds, the connection attempt fails, and the controller enters AP mode. AP mode times out after 120 seconds and resets the controller. 10Hz: - The controller needs to access an Internet Network Time Protocol (NTP) server to get the correct time. While attempting to get the time, the LED flashes at 10Hz or .05 seconds on, .05 seconds off. Occasionally, the controller cannot get network time, in which case it remains in that loop indefinitely since the controller cannot operate without the correct time. If you see this, you can reset the controller with the reset button located within the cutout, and try again. + The controller needs to access an Internet Network Time Protocol (NTP) server to set the correct time. While attempting to get the time, the LED flashes at 10Hz or .05 seconds on, .05 seconds off. Occasionally, the controller cannot get network time, in which case it remains in that loop indefinitely since the controller cannot operate without the correct time. If you see this, you can reset the controller with the reset button located within the cutout and try again. Double-Reset Detect ------------------- -If you need to access the AP configuration portal without resetting the WiFi settings via the web page, press the reset button twice within 2 seconds. The controller resets and starts AP mode where the LED flashes at 0.5Hz. +If you need to access the AP configuration portal without resetting the WiFi settings via the web page, press the reset button twice within 10 seconds. The controller resets and starts AP mode, where the LED flashes at 0.5Hz. If the LED does not start flashing at the 0.5Hz rate, repeat the double reset until it does. You need not treat the resets like a double-mouse click; once per second is usually sufficient. Emergency AP mode ----------------- -If you are unable to access the AP by any other means, you may do so by jumpering D5 to GND on the controller and resetting it via the reset button or with a power cycle. The controller starts in AP mode, where the LED flashes at 0.5Hz. +If you cannot access the AP by any other means, you may do so by grounding D5 on the controller and resetting it via the reset button or with a power cycle. The controller then starts in AP mode, where the LED flashes at 0.5Hz. Serial Debug ------------ -Serial debug has been left enabled in the firmware. You may connect the device to your computer and use a terminal program set at a baud rate of 74880 to review the debug messages. +Serial debug has been left enabled in the firmware. You may connect the device to your computer and use a terminal program set at a baud rate of 74880 to review the debug messages. Rudimentary commands are allowed: + +.. code-block:: + + Available serial commands: + p: 'Ping, e.g. {}' (null json) + r: Restart controller + ?: Help (this menu) + +Telnet Debug +------------- + +A simple Telnet server is available to connect with PuTTY or another terminal emulator over port 23. There is no security to this connection; the connection will only emulate the serial connection display as if it was directly connected to your computer. The same serial commands are available as described above. + +Controller Reset +----------------- + +You may perform a reset on the controller by navigating to Settings > Advanced > Reset. The controller will reset as if you had pressed the reset button on the controller itself. + +About page +----------- + +The "About" page shows some diagnostic information which may be helpful in certain circumstances: + +.. figure:: about_diags.jpg + :scale: 100 % + :align: center + :alt: About Page Diagnostics + +- **Header:** The header displays the firmware's tagged version, followed by the branch, followed by the commit. This information may be helpful where confusion exists about which version is installed. +- **Uptime:** Uptime shows how long the controller has been running without a restart. The controller may reset itself for several reasons, including a 42-day reboot cycle. +- **Reset Reason:** The reason for the last reboot according to the core libs. +- **Heap Information:** Memory information for the controller. Low memory conditions may cause crashes or occasionally self-reboots to attempt to heal the issue. FAQ --- -No FAQ yet, I'll capture that as time goes on. +No FAQ yet; I'll capture that as time goes on.