# Welcome
This is the official documentation for BierBot Bricks. As you can tell, it's currently work in progress - but you may find the already completed ones interesting.
### What's this all about
The BierBot Bricks brewing software aims to help you to brew great beer. You can add different devices (a.k.a. "Bricks")
* to control your equipment (the BierBot Brick),
* to track your temperatures and
* to track your gravity (TILT, iSpindel)
... over time. You can import and create **recipes** using our recipe editor, you can view a **detailled brewing batch log** after your brewday and you can **invite fellow brewers to your brewery** to share all of the aforementioned stuff.
### Getting started
Let's say you simply want to "start brewing" and end up with a screen similar to the following. You might ask: "How do I get there?". Here's the answer:
1. [Register / Login](https://bricks.bierbot.com/#/register).
2. [Build or buy a Brick ](/hardware/hardware/brick-101)(Easy option: Sonoff TH16 based, flexible option: Raspberry Pi).
3. [Connect the Brick to your brewery](/getting-started/adding-your-first-brick).
4. [Assign the relay and temperature sensor of your Brick to a device](/getting-started/setting-up-your-first-mashtun), i.e. mashtun.
5. [Create or import a recipe](/getting-started/importing-recipes).
6. [Start the recipe to launch to automatic mode.](/using-bricks/automatic-mode)
### Get involved / contribute to this documentation
If you want to help building this documentation: Please shoot us a message at hello \[ad) bierbot \[döt ] com. A free BierBot waits for you ;) Thanks!
### Cool links that might be interesting
* YouTube Video: How to build your own [Brick for just 25€ in 15 minutes](https://www.youtube.com/watch?v=ZJEo5KyGwx4).
* Our Instagram page: New [features will be announced here](https://www.instagram.com/bierbotbrewing/).
* The official support forums: If you have a question worth sharing or a feature request you'd like to discuss in public, please reach out using [our support forums](https://github.com/BernhardSchlegel/BierBot-Bricks).
Last but not least: Our [privacy statement](https://bricks.bierbot.com/#/privacy) and [terms](https://bricks.bierbot.com/#/terms).
# Terminology
This page will briefly touch some of the most important terms (or concepts) used throughout our application.
"**Bricks**" are all physical devices at your site, no matter if a Sonoff TH with one relay and one temperature sensor, an Raspberry PI with several relays and temperature sensors or TILT, iSpindel, Hydrom, Float ... all are "Bricks" offering interfaces/capabilities. An overview over all Bricks is given [here](/hardware/hardware).
In the BierBot interface you then create "**Equipment**" - to which you then assign the interfaces/ capabilities of your Bricks via drag and drop. So for example a relay from the Raspberry Pi then becomes the heater of your mash tun. A relay of a Sonoff TH the stirrer. Another Sonoff TH can then control the cooling of your fermenter and your TILT contributes the value for the original gravity. The "equipment" has different types (mash tun, fermenter, BIAB) each with different capabilities. A mash tun, for example, has no field for original gravity and only the BIAB device allows you to configure initialization cycles for the pump. You can read more about the various equipment types support [here](/using-bricks/equipment).
# Adding your first BierBot Brick
1. To connect your Brick to your brewery, head over to 'Bricks' on the left menu, and click the blue on the top right corner.
2. Copy the API-key into your clipboard, you'll need it later.
3. Connect your BierBot Brick to power. It will create an WiFi starting 'BierBot Brick'. Connect to it using the same device.
4. After connection you're redirected to the configuration page. Select 'Configure WiFi' at the top.
5. Wait for the scan to finish, select your home (or brewery ;) ) WiFi, set the password and paste the API-key from your clipboard into the respective fields.
6. Your Brick should show up automatically. If not, refresh the page after 10s.
7. Hit 'Activate' (mandatory). Optional: change the Bricks name by clicking on it.
This process is the same (at least from 1-3) for other devices you might want to add to your brewery.
# Setting up your first mashtun
You've connected your first Brick to your brewery? Great! Next step is to assign its interfaces - most likely a relay and a temperature to a device.
### Prerequisites
To able to setup a mashtun, you need a Brick connected to your brewery. If you did not already do that, head over [here](/getting-started/adding-your-first-brick).
### Creating a mashtun (fermenter, etc.)
The process is the same for pretty much every device. We'll use the mashtun as an example.
1. Select "Equipment" in the side navigation.
2. Click the "Create device" button the respective card.
3. A dialog will apear, asking which type of device you want to create. Select "Mashtun / BIAB". If you want to know what's the logic behind it, check out [this page](/using-bricks/equipment).
4. A empty Mashtun / BIAB device will appear. Let's discuss what you see:
* A title saying "Mashtun / BIAB". You can rename your device by simply clicking on it. This is handy if you have multiple mashtuns.
* A outlined button saying "Control" (with an slider icon). You can change the PDI-controller settings here - or let the [automated calibration feature](/using-bricks/equipment/calibration) do the job for you (which is recommended).
* A "Heating" section, displaying a "dropzone" denoted by something that looks like a open switch.
* A "Circulation" section, displaying the same dropzone. We also need a relay to control our pump (BIAB) / stirrer (else) after all.
* A "Temperature sensors" section, displaying a dropzone denoted by a thermoemeter icon.
5. We now want to assign the
1. the **relay** of our Brick to the **"heating" of our mashtun**
2. the **temperature sensor** of our Brick to **our mashtun**
6. We do this - and that is the catch - by drag and dropping! This is shown in the image below.
7. After your done, dont forget to hit the **SAVE** button!
8. Aaand: you're done.
You can proceed by putting your mashtun to work, e.g. by [creating / importing a recipe](/getting-started/importing-recipes) and [starting a recipe](/getting-started/creating-a-new-recipe) or controlling the temperature in [manual mode](/using-bricks/the-manual-mode).
TODO
# Creating / importing recipes
Creating and importing recipes is super easy with BierBot Bricks.
## Creating recipes
Select "Recipes" on the left and click the "Create"-Button
You'll be presented with a vanilla recipe. You now have the following options
1. Change the recipes' name (by clicking on it).
2. Change the final wort volume (by clicking on it).
3. Add a comment using the textarea.
4. Add a mashing rest by clicking the big button.
5. Changing the boiling time (by clicking on it).
6. The primary fermentation duration will be calculated based on the fermentation steps you configured (no rocket science...)
7. Adding a fermentation step.
8. When you're done, you can save. (You you can undo mashing / fermentation step edits.)
### Adding a mashing rest
After hitting the "Rest add" button the popup dialog showing up enables you (from top to bottom):
* set a rest name ("mash-in", "alpha-rest", etc.)
* Next step on
* **Time passed**: Set a number of minutes the targettemperature should be held before moving on to the next step
* **Manually**: The next step will never be automatically triggered. You need to manually click on the "next-step" button in the automatic mode.
* Circulate: If you configured a circulation relay / pwm on your mashtun / BIAB you can control if the pump or stirring device will be turned on during this step.
* Targettemperature: Set the targettemp in your configured unit.
* Rest duration: Set the number of minutes to be waited after reaching the target temperature. This will only be shown if "next step on" is set to "time passed".
### Adding a fermentation step
After hitting the "Fermentation step add" button the popup dialog showing up is pretty similiar to the mashing dialog. Key differences are:
* If time passed is selected, the duration is specified in days (rather than minutes as when in mashing mode).
* You can select whether this step is for primary "fermentation" or "secondary fermentation" - which will ultimately determined the "time to bottle" (which will be used in future versions of the software).
## Importing recipes
You can import your recipes from other brewing recipe websites using BeerXML. To do so, simply hit the BeerXML button in the recipes section from the menu on the left
And then either click on the file-input zone or simply drag & drop your BeerXML file:
Hit "next". Since a BeerXML can contain multiple recipes, the second page will ask you, which recipes you want to import. In this case, there was only one. Let's select it and hit "Finish":
There you go: The recipe is imported:
You can go ahead and edit / tweak it like any other recipe in your recipe-book.
# Starting your first brew
Starting your first brew is easy:
1. [Create or import a recipe](/getting-started/importing-recipes).
2. [Start it in automatic mode](/using-bricks/automatic-mode).
# FAQ
This section answers or links the most commonly asked questions.
## My temperature reads -127°C
The original Tutorial was published when the TH Origin was shipped with a DS18B20 sensor. The sensor that is included today is, however, is the WTS01. The WTS01 has a black box as part of its cable:
WTS01 sensor with black box
To fix this, you need to remove the black box from the cable and solder the cables back together. Or (even better): File a [Pull-Request](https://github.com/BernhardSchlegel/Brick-32/issues/13#issuecomment-2450070187) to support the WTS01 it software-wise.
## I have problems flashing the ESP32!
You're not alone. Check the following points:
1. ESP32 not in boot mode: Press button on TH before powering up.
2. Cable connections: The data is transferred by switching between 3.3V and 0V multiple million times per Sekond. Image a cable not sitting tight. No way signal gets through. Really make sure, cables are snug1
3. RX-RX: RX on flasher needs to be connected to TX on Sonoff TH and vice versa. DO NOT connect RX-RX and TX-TX (on side transmits, other side receives)
4. Power: Make sure Sonoff TH has sufficient power. Worst case you need to connect AC while flashing, consult an expert ⚠️⚠️⚠️, be safe and don't kill yourself ☠️.
5. Make sure the jumper is set to 3.3V and not 5V on your COM-Port flasher. Note: If you've used it in the 5V configuration previously, your TH might be unrecoverably fried now ⚡.
6. Check that the soldering of the pinheader is solid on your TH.
7. COM-Port driver: Go to device manager and check for COM-Ports. If there's only one, your COM port flasher might not be recognized. Try to unplug and plug in your COM port flasher again. If there's no COM port appearing / disappearing the "virtual COM port" driver is missing. Which driver you need depends on the flasher you bought. Chances are high you're using a FTDI, drivers for this chip can be found here:
8. USB-Cable: Another reason you might not be seing your virtual COM port is that you're using a USB-cable which only has power but no data. These are often bundled along with battery driven LED lights or other battery driven devices.
## My temperature is always zero / 0?
That's likely a problem with your hardware. You can try the following:
1. Make sure, the temperature sensor is really plugged in. Plug it in. All the way. You hear a "click" when you "kind of" plug in it. Plug it in deeper.
2. If you're using a 5m extension cable: try it without the extension. We have 2m and 3m available. Just reach out to us!
## How can I update my BierBot Brick?
If you're using a Sonoff TH16 with a PCB reading version "2.1" or you bought your BierBot Brick, the **update requires access to the COM-Headers** on the PCB. In theory, the BierBot Bricks firmware runnning on your device would allow an update using the WiFi configuration portal. This, however, does not work, since the storage of the Sonoff TH 16 is too small to store both, the old software and the new software at the same time.
Good news: If we figure out a way to reduce the firmware size drastically, this becomes an option in the future without you having to change anything. If you know `C` and have an idea how to do that, please feel free to contribute, the [code is open source](https://github.com/BernhardSchlegel/BierBot-Bricks).
## Which devices are supported?
Any device, that goes "full-on" after being powered up will work. Full-on means that the device is not "on and waiting for orders" but that it's turning on the heating / cooling / pump right after being connected to a socket. To give you some examples of devices that will work:
* A induction plate with a physical control knob, such as the [Hendi 3.5kW heating](https://amzn.to/3B7z8oD). Just turn the know to 3.5kW (yep, unlike the Inkbird, the BierBot supports 3.5kW).
* Any fridge - just set it to maximum cooling.
* Any valve/pump for glycol chillers - just keep in mind that the BierBot Brick only outputs AC.
## What happens, if the BierBot Brick looses WiFi connection?
When the BierBot Brick looses it's connection, it will enter a **fail-safe** state. This means, that the relay is turned off. This is to avoid, that your beer is frozen down to eisbock temperature our your mashtun killing your enzymes.
The BierBot Brick will retry to connect automatically. After successfull re-connection the process will automatically pick up where it was left.
# Overview - available Bricks
BierBot Bricks aims to be an open hub for all your brewery equipment - we call every them Bricks.
### Available Bricks
We're permanently working on expanding the list. Here are your current options:
| Name | Sensors | Actors | How to get it |
| ---------------------------------------------- | -------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------- |
| [Brick 101](/hardware/hardware/brick-101) | 1 Temperature Sensor | 1 Relay | [buy](https://bricks.bierbot.com/#/buy) / [built](https://www.youtube.com/watch?v=ZJEo5KyGwx4) |
| [Brick 32](/hardware/hardware/brick-32) | 1 Temperature Sensor | 1 Relay | [built](https://youtu.be/5TI9fxsTRmM) |
| [TILT](/hardware/hardware/tilt) | 1 Temperature Sensor, 1 Gravity sensor | | [buy](https://tilthydrometer.com/) |
| [iSpindel](/hardware/hardware/ispindel) | 1 Temperature Sensor, 1 Gravity sensor | | [built](https://github.com/universam1/iSpindel/blob/master/docs/README_en.md) |
| [RaspberryPi](/hardware/hardware/raspberry-pi) | multiple Temperate Sensors | multiple relays | [built](https://www.youtube.com/watch?v=gghbpVjFMLI) |
| [HYDROM](/hardware/hardware/hydrom) | 1 Temperature Sensor, 1 Gravity sensor | | [buy](https://hydrom.io/) |
| [RaptPill](/hardware/hardware/raptpill) | 1 Temperature Sensor, 1 Gravity sensor | | [buy](https://www.kegland.com.au/products/yellow-rapt-pill-hydrometer-thermometer-wifi-bluetooth) |
### Community Bricks
Extensions of our software or completely new developments by our awesome community will be linked here:
Are you missing something: Let us know!
# BierBot Brick
The "Brick" has a temperature sensor and a relay that allows you to control the mash tun, refrigerator or fermenter.
## How to get one?
* you can either [buy one](https://docs.google.com/forms/d/e/1FAIpQLSdufvcrD5-fHKjQn-D_Tyt6hMuHTNFTUUF2EIjy8WuuVZbeRQ/viewform)
* or build one yourself (see below).
## How to build you own BierBot Brick
### What you'll need
You don't need much to build your Brick, most of the tools are optional (and just make your life easier).
#### Materials
* [Sonoff TH16 incl. a temperature sensor](https://amzn.to/3xE4RvL) - this is the main component.
* [AC-Extension-Cord](https://amzn.to/3vDH7q2)
* [DIP-Pin header (you'll only need1x4)](https://amzn.to/3rXGrJT)
* [Rainbow cable (Female to female)](https://amzn.to/3udmdh2)
#### **Tools**
* [USB Serial converter](https://amzn.to/3ujiT3w) (Virtual COM-Port) - to flash the PCB.
* [mini USB cable](https://amzn.to/337DtIB) (if you don't already have one) - to connect your serial converter to your PC.
* [Soldering-iron.](https://amzn.to/3nE6sNu)
* Something to strip the wires (pliers, scissors, knife, etc.).
* Two screwdrivers (philips and longitudinal slot).
* *Optional: wire end ferrules and a wire end ferrule pliers.*
### Steps
#### **Step 1: Expose the contacts**
First we have to expose the contacts of the board, via which we will then flash the software.
To do this, first loosen the Phillips screw and lift off the front cover (Figure 1.1). Then insert a teaspoon between the upper and lower part of the housing at the U-hole. By turning the spoon, the housing can now be pried open (Fig. 1.2). Now you only have to loosen the 4 screws that secure the circuit board in the housing (Figure 1.3).
#### Step 2: Soldering the DIP pin header
There are 5 DIP holes on the board with which we have to make "contact" for flashing. For this we simply solder the 4x1 pin header. Important here: We only need the pins from "**GND**" to "**VCC**" ("EXP-LOG" is **not** needed). Insert the pin header from the top, turn the board around and solder it from the bottom with 4 solder pads. Soldering tip: Rather heat the contact surfaces on the board, and then dab the solder to it.
Now screw the board back into the lower part of the housing using the 4 screws.
#### Step 3: Connecting the power cable
Now you need the extension cable. Cut it (Figure 3.1) (the center is not necessarily the best place for your purpose), and carefully remove the insulation (Figure 3.2 and 3.3). When removing the outer insulation (black in our case), be careful not to damage the inner insulation (brown, blue, yellow-green). Repeat the process for both ends of the cable.
Now thread the cable through the opening of the upper housing part (Fig. 3.4) from "outside" to "inside" (in quotation marks, because the housing is currently open). Twist the strands together. If available, you can also crimp a wire end sleeve (ideally with a 4-jaw pliers to maximize the contact area).
Now connect the wires to the terminal of the board (Figure 3.5 and 3.6). For this purpose, it is best to press on the top of the button with a longitudinal slot and insert the cable. **The board must be completely de-energized during this step! In no case connect the plugs with the socket!**
The mapping is as follows:
| Label on PCB | Plug/Socket | Cable Color (Germany, EU) | US |
| ------------ | -------------- | ------------------------- | ------------ |
| L IN | Plug | Brown | Black |
| L OUT | Socket | Brown | Black |
| N | doesn't matter | Blue | White |
| Epsilon / E | doesn't matter | Yellow-Green | Green-Yellow |
On the **Figure 4.3** you can see a **clear representation for EU color coding**.
#### Step 4: Connect the data cable for flashing
Now it's time for the "Rainbow" cable. We use it to connect our pin header (Figure 4.1) to the serial interface (Figure 4.2). Connect the Rainbow cable "as is" to the pin header of the board. Make sure that the jumper on the serial interface is set to 3.3V when it is "right" (when the USB port is up).
The other side must be connected to our USB board. Pay attention to the labels! Start with GND, that belongs on the outside. Now leave one pin free. Now comes "VCC" (in our case white, the cable that is maximum away from GND on the board), followed by E-RX (black) and E-TX (brown) - so in the same order of the pin header.
For your reference: Here again the complete cabling (power and data cable)
#### **Step 5: Flashing the Software**
Now we still have to play the software on our board. For this we need two things:
1. The Brick software itself ([available for free on Github](https://github.com/BernhardSchlegel/BierBot-Bricks/releases)). Download the "firmware.bin" of the "Latest Release".
2. The tool to flash the chip (ESP8266) ([also available for free on Github](https://github.com/nodemcu/nodemcu-flasher)). Most likely you need the ESP8266Flasher.exe file from the "[Win64/Release](https://github.com/nodemcu/nodemcu-flasher/tree/master/Win64/Release)" directory.
Save both files (Flasher and firmware.bin) on your PC. Now connect the USB board with the mini USB cable to your PC. To check if the board is recognized correctly do the following: Press the Windows key (on your keyboard), type "Hardware", click on the Hardware Manager. Under "Ports (COM & LPT) you should now see a COM3 (or any other number).
{% hint style="info" %}
**If not**, you may be able to fix the problem by downloading the driver for your USB board [HERE ](https://ftdichip.com/drivers/vcp-drivers/)(current is 2.12.36.1) and unpacking it to Downloads\CDM+v2.12.36.1+WHQL+Certified. Then, in Hardware Manager, right-click the device that was not detected correctly (at the top, probably with a question mark), and click "Update Driver". Then select "search on my computer" or the **root** directory you just created (CDM+v2.12.36.1+WHQL+Certified).
{% endhint %}
Now start the "ESP8266Flasher.exe". Go to the tab "Config" ( (1) in the picture), and click on the gear wheel ( (2) in the picture). Select the "firmware.bin" in the dialog that pops up.
Go back to the "Operation" tab, select your COM port (in my case "COM3").
Now we have to put the board into flash mode. For this we start with a powerless board (unplug the mini USB from your PC). Then hold down the button on the board 1), and then connect 2) (while holding down the button) the mini USB cable to the PC again.
Hit **Flash!** The Flashing tool will now install the PCB with the software - time to get some homebrew to celebrate this victory!
#### **Step 6: Closing the case**
As soon as the flashing tool signals the successful completion of the flashing process with a green checkmark, we now only have to reassemble the case. To facilitate future updates, it is recommended to route the Rainbow cable with "outside" and leave it plugged on the DIP header (but take a photo or label of the GND cable for future reference). Please note that you should protect the case from water, as it does not meet IP68 in this state.
Click the case back together & plug in the DS18B20 temperature sensor - **Done!**
### **Final words**
You can now head over to [bricks.bierbot.com](https://bricks.bierbot.com/#/setup) and setup your Brick and at it to a device. And explanation how to do so can be found [here](/getting-started/setting-up-your-first-mashtun).
This howto will be also available on German on the [awesome brau!magazin](https://braumagazin.de/).
⚠️ **DISCLAIMER:** **DANGER OF ELECTROCUTION** ⚠️
If your device connects to mains electricity (AC power) there is danger of electrocution if not installed properly. If you don't know how to install it, please call an electrician (***Beware:*** certain countries prohibit installation without a licensed electrician present). Remember: ***SAFETY FIRST***. It is not worth the risk to yourself, your family and your home if you don't know exactly what you are doing. Never tinker or try to flash a device using the serial programming interface while it is connected to MAINS ELECTRICITY (AC power).
We don't take any responsibility nor liability for using this software nor for the installation or any tips, advice, videos, etc. given by any member of this site or any related site. [source](https://github.com/arendst/Tasmota/edit/development/README.md)
# TILT™
### How to add your TILT™
We will setup a "custom API" that will enable your TILT™ to log into your Bricks account. Since the TILT™ offers a Bluetooth connection only, a **bluetooth** enabled device with **access to the internet** (WiFi, mobile 4G) has to be **always** in range of your TILT™. If you have a de-comissioned smartphone running iOS or Android - this should not be an issue.
You will need
* A device in bluetooth range of your TILT™.
* The "TILT 2" installed on your device, you can [get it for free here](https://tilthydrometer.com/pages/app).
* Your API-Key as shown by the "Add Brick" Dialog. (copy this into your clipboard).
* The target endpoint URL, which is `https://brewbricks.com/api/tilt/v1`
Check? Let's go:
1. Put your tilt into a glass of water to turn it on.
2. Open your "TILT 2" app - your TILT™ should appear.
3. Hit the gear icon in the top left corner (see image "gear icon").
4. Select your TILT from the List (e.g. TILT YELLOW, TILT RED, etc.).
5. Hit "Clear" under "beer name".
6. Paste the API from above, e.g. `Ii420unaFaXKQrMfCI8T`.
7. Hit the "Save"-button right underneath.
8. Set the "logging interval" to "15min" (the app will incorrectly show your TILT as offline otherwise).
9. Optional: Disable "device logging" by flipping the switch.
10. Disable "Use default cloud URL".
11. Hit "3RD PARTY CLOUD LOGGING".
12. **Enable** "Use custom cloud URL 1".
13. Paste the URL `https://brewbricks.com/api/tilt/v1`
14. Hit save underneath.
You can now head over to the "Bricks" Section (Menu on the left on [bricks.bierbot.com](https://bricks.bierbot.com)) - your TILT™ should appear. Head over to the "Equipment" Section, and assign the temperature and gravity interfaces to your fermenter by drag & dropping. If you do not have a fermenter yet, create one by clicking "Create Device".
Done!
### Where to buy your TILT
* Offical Website / buy it straight from the creators:
* [On Amazon](https://amzn.to/3vYVHZK)
* Regional Suppliers:
* Germany, [hobbybrauerversand.de](https://www.hobbybrauerversand.de/Tilt-Hydrometer-Thermometer)
# iSpindel / iSpindle
This page will show you how to integrate your iSpindel into Bricks!
### Prerequisites
Create a free BierBot Bricks account [here](https://bricks.bierbot.com/#/register).
### How to add your iSpindel / iSpindle
The setup with BierBot Bricks is easy and for free. You will need the iSpindle Firmware `7.1.0` or later, for details regarding firmware and their compatibility please refer the following table.
| Version | Certified / Works | Binary |
| ------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [7.1.0](https://github.com/universam1/iSpindel/releases/tag/7.1.0) | check ( :white\_check\_mark: ) | [Download](https://firebasestorage.googleapis.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-Mb-yazhyh6RzCW1gcvw%2F-MfdAT4fS3NjiVzLA-qR%2F-MfdAzOXWl9RC_TwTm4k%2Ffirmware_7.1.0.bin?alt=media\&token=077212b0-ae08-4eee-9e35-b62ce9261ae4) |
| [7.1.1](https://github.com/universam1/iSpindel/releases/tag/7.1.1) | tbd ( :question: ) | [Download](https://firebasestorage.googleapis.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-Mb-yazhyh6RzCW1gcvw%2F-MfdAT4fS3NjiVzLA-qR%2F-MfdB3B-No2VtDPit1rQ%2Ffirmware_7.1.1.bin?alt=media\&token=ddac8f6e-a629-4bd6-b068-2913f26dafaa) |
| [7.1.2](https://github.com/universam1/iSpindel/releases/tag/7.1.2) | tbd ( :question: ) | [Download](https://firebasestorage.googleapis.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-Mb-yazhyh6RzCW1gcvw%2F-MfdAT4fS3NjiVzLA-qR%2F-MfdB80bXLAQiwiOsI02%2Ffirmware_7.1.2.bin?alt=media\&token=6ad2a610-a553-4942-ac85-4d631c242447) |
| later | tbd | |
1. After Registration, select "Bricks" in the menu on the left (see 1 in the picture).
2. Hit the blue "Add Brick" button in the top right corner.
3. Select "iSpindel" in the popup and copy the displayed API key into your clipboard.
4. Now open the configuration portal of your iSpindel (by pressing reset multiple times, see portal for more info).
5. Select "Bricks (free & easy)" as service (see 2 in the image).
6. Paste the api key from your clipboard into the "Token/ API key" field and hit the blue save bottom at the bottom.
7. Now go back to [bricks.bierbot.com](https://bricks.bierbot.com/#/) and select "Bricks" in the menu on the left - your iSpindel should appear momentarily. Note: If you have a PRO account you can re-configure the transmit interval using the iSpindel-Bricks settings. **Per default, the interval is controlled by our backend.**
8. Now, open the menu and hit "Equipment" (see 3 in the image).
9. Create a new device (blue button, top right corner), select "**Fermenter**" in the popup.
10. Now assign the gravity sensor from the iSpindle to the respective field of your fermeter by **drag & dropping** - the respective target dropzone on your fermenter will be highlighted green to guide you. You can do the same for your temperature sensor, but this is optional.
11. Hite "Save".
12. To start recording, we will also need a recipe. Go to "Recipes" on the left and create a recipe. You only need to setup one (dummy) fermentation step. Save the recipe and go back to the list of recipes. Start your recipe by clicking the orange play button. Read more about how to start a brew here: [Automatic mode](/using-bricks/automatic-mode#starting-a-brew).
### Settings of the iSpindel
The iSpindel offers a lot of custom settings. Some of them require a PRO membership:
* Gravity: Set the unit of the gravity reading as transmitted by the iSpindel.
* Overwrite polynom: If activate, the gravity reading from your iSpindel will be ignored. Our backend will calculate the gravity for you based on the tilt reading of your iSpindel - which is transmitted by default.
* Polynoms: Allows you to set the polynoms in case you enabled overwrite. This has the advantages that you don't need to have physical access to your iSpindel or login into the firmware to change it. Be careful: Wrong polynoms can yield high gravity readings which will be automatically filtered out. For your reference, here are the values we're using:
* Quad (tilt^2): 0,007136580659515083
* Linear (tilt): -0,16104368844888492
* Constant: -0,1784570194026703
* Set custom logging interval (requires PRO): Overwrite the default logging interval of your iSpindel. This is effective after the next request without the need for phyiscal access to the iSpindel.
* Calibration: You can calibrate your temperature reading by setting constant offsets.
### Firmware Binaries
Binary downloads only are here for backup purposes. Always check the offical [releases on the iSpindel-Repository](https://github.com/universam1/iSpindel/releases) or compile them yourself.
{% file src="/files/-MfdAzOXWl9RC\_TwTm4k" %}
iSpindel firmware (7.1.0)
{% endfile %}
{% file src="/files/-MfdB3B-No2VtDPit1rQ" %}
iSpindel firmware (7.1.1)
{% endfile %}
{% file src="/files/-MfdB80bXLAQiwiOsI02" %}
iSpindel firmware (7.1.2)
{% endfile %}
# Raspberry Pi
If you have a Raspberry Pi, you can try out the BierBot Bricks integration. Code is available for [free on Github](https://github.com/BernhardSchlegel/BierBot-Bricks-RaspberryPi). If you want to build one yourself, checkout the following ressources:
* [YouTube step by step guide.](https://www.youtube.com/watch?v=gghbpVjFMLI)
* [Extensive Blog-Post.](https://bierbot.com/blog/howto/howto-build-a-raspberry-pi-based-brewing-control/)
### How to add your Raspberry Pi to bricks.bierbot.com
Please refer the ["Getting Started"](https://github.com/BernhardSchlegel/BierBot-Bricks-RaspberryPi#getting-started) section of the repository where the free code is located.
# Brick 32
The Brick 32 is the official successor for self-builders for the BierBot Brick. While the BierBot Brick was based on the - no longer available - Sonoff TH 16, the Brick 32 is based on the Sonoff TH Origin. The Sonoff TH Origin was released June 2022.
To build one yourself:
* Get the free Code [from the Github-Repo](https://github.com/BernhardSchlegel/Brick-ESP32)
* Watch the YouTube build guide:
* Read the [Blog article](https://bierbot.com/blog/tutorial-easy-brewing-control-build/) how to build one.
### How to add your Brick ESP32
1. Go to [bricks.bierbot.com](https://bricks.bierbot.com/#) and head over to "Brewery" > "Bricks".
2. Click "Add Brick" and follow the instructions on the screen. Copy the API key into your clipboard.
3. Connect the Brick ESP32 to power.
4. Search for WiFi starting with "Brick-32-" (i.e. Brick-32-0042123) and connect to using a device of your choice (iPhone, Android, Windows, Mac). If the captive portal does not show automatically, nor a prompt to "connect", open your browser and head to "neverssl.com" - you'll be redirected.
5. Provide your Wifi credentials and paste the API key from your clipboard in the respective field.
Done! Your Brick 32 should show up momentarily.
# HYDROM
This page will show you how to integrate your Hydrom into Bricks!
Prerequesites:
* Your HYDROM needs at least to be running the Hydrom-Software version 1.4.0. A guide how to update is available on [Englisch](https://instruction.hydrom.io/readme/firmware-update) and [German](https://anleitung.hydrom.io/allgemeine-einstellungen/firmware-update).
Steps
1. Head to your [breweries Bricks](https://bricks.bierbot.com/#/brewery/bricks) page, hit Add Brick in the upper-right corner, select Hydrom and copy the API key into your clipboard - you'll need it later.
2. Start your Hydrom by moving the Switch to the middle and pressing the buttom.
3. Connect to the "Hydrom\_\[...]" WiFi.
4. Connect to your network by providing the credetials:\
5. Now head to the "Services"-Page by using the menu on the left, enable the "BierBot Bricks" service and paste the API key from your clipboard that you've copied in Step 1:\
6. Scroll to the bottom and hit "Deep Sleep". To send a message, turn your Hydrom off and on or wait for the specified sleep duration.
7. Your Hydrom will apear on the Bricks page of your brewery:\
8. One last step is to activate it by hitting "Activate".
9. Now head over to "Equipment"-Page and create a new "Fermenter"-device. Assign the interfaces of your Hydrom temperature and specific gravity to your fermenter.
10. Hit the blue save button & you're ready to go!
# RaptPill
This page will show you how to integrate your RaptPill into Bricks!
### Requirements:
* Your RaptPill is registered on .
* The setup guide for the RAPTPill is available in [English.](https://mashcamp.shop/wp-content/uploads/2023/05/KL20596_-_RAPT_Pill_Hydrometer_and_Thermometer_Quick_Start_Guide.pdf)
### Steps
1. Log in to the portal .
2. Select "Custom Webhook"\
3. Set a "name" and a "description" as you'd like. Other parameters: are:
1. URL:
2. Method: POST
4. Payload: Copy and Paste the following, change `YOUR_API_KEY`to match your API key:
```
{
"apikey": "YOUR_API_KEY",
"type": "raptpill",
"brand": "rapt",
"version": "0.0.1",
"chipid": "@device_name",
"s_number_wort_0": @gravity,
"s_number_temp_0": @temperature,
"s_number_batterypercent_0": @battery,
"s_number_wifi_0": @rssi
}
```
5. Devices: Select "RaptPill"\
6. Your RaptPill will apear on the Bricks page of your brewery:
7. The last step is to activate your RaptPill by hitting "Activate".
8. Head over to the [Equipment](https://bricks.bierbot.com/#/brewery/equipment)-Section, and assign the temperature and gravity interfaces to your fermenter by drag & dropping. If you do not have a fermenter yet, create one by clicking "Create Device".
Congrats! You're done.
### Where to buy your RaptPill?
* Offical Website / buy it straight from the creators: [https://www.kegland.com](https://www.kegland.com.au/products/yellow-rapt-pill-hydrometer-thermometer-wifi-bluetooth)
* [MashCamp](https://mashcamp.shop/shop/brauanlagen/gaerbehaelter/kontrollierte-gaerfuehrung/kegland-rapt-pill-digitaler-hydrometer-und-thermometer/)
# Setup your Bricks account
After registration everything is automatically setup for you
1. A new brewery: This will hold everything "brewing" related (recipes, hardware, etc.). You can also add others to the brewery. Read more here: [Managing your brewery](/using-bricks/managing-your-brewery).
2. Your profile for profile picture, username (to make it easy for others to add you to their brewery).
3. **Most importantly**: Your settings. These allow you to customize, e.g. all units used in the UI to your needs. Read more here: [Your settings](/using-bricks/your-settings).
# Managing your brewery
The brewery holds all things brewing. This includes (but is not limited to):
* Recipes
* Bricks (BierBot Brick, electric hydrometers)
* Equipment such as Mashtuns and Fermenters, as well as their calibration information.
* Running brewing and fermentation processes.
* Recipes.
If you head over to "Brewery" > "Administration" in the menu on the left, you have a couple of options:
* At the top, you can switch between breweries - if you're a member of more than one brewery.
* You can add a brewery logo to your brewery. Currently, that's just for yourself.
* You can give your brewery a name.
* You can change the last brewnumber. In case your brewnumber is purely numerical (only consisting of 0-9), BierBot Bricks will automatically increment this number for your next brew by 1.
* The members. You can add new members by typing their name in the "Search member" input. Registered users can change their name on the profile page. **Attention**: All members have full access.
# Equipment
This Section explains some advanced mechanisms offered. If you want to know which equipment types exist, head over [here](/using-bricks/equipment-types).
# Calibration
Nailing temperatures especially during mashing is crucial. By default, temperature controllers turn off the relais (the heating) when the target temperature is reached. This inevitably leads to temperature overshoots. Our software is already a little bit smarter by default and turns off the heating **before** the target temperature is reached. 👌
It get's even better: By hitting the button, the BierBot Bricks software **automatically** learns how your system behaves to **minimize** future overshoots. 👌👌👌
To calibrate your device, set it up like you would for a normal brew. This means, e.g.
* Fill it up with water (just skip the fermentables).
* Install your stirring equipment (pump in BIAB systems).
It'll take about 60 minutes to finish the calibration. After that, your PDI and other device settings are automatically calculated for you. If you want, you can still adjust the automatically inferred PDI settings afterwards (read about it here [PDI control settings](/using-bricks/equipment/pdi-control-settings)).
# PDI control settings
Every brewing system - be it a mashtun, BIAB device or fermeter - is different. To perfectly hit the set target temperature it is therefore possibly and necessary to adjust the temperature controller settings to your device.
Usually, a automatic calibration will do this for you. Read how it works here: [Calibration](/using-bricks/equipment/calibration).
In some rarer cases, you might want to change the parameters yourself. You can do this for Relais and PWM capable switches separately. This section will explain the reasoning behind it.
### Switch Relay
The following parameters are available:
* $$k\_p$$: If 1, the relais will turned of when the target temperature is reached. If $$k\_p > 1$$the relais will be turned of earlier.
* $$k\_d$$: Controls the influence of the temperature change rate. The higher the bigger.
* $$k\_i$$: Controls the influence of the integrated temperature change. The higher the bigger.
* $$hysteresis$$: The hystersis is a dead zone around the target temperature, in which the relais will not be turned on again. It is symmetrical and covers both positive an negative deviations. This means, that if the hystersis is set to 0.2°C and the target temperature is 60°C (140°F) the deadzone will span from 59.9°C to 60.1°C.
# Equipment types
BierBot Bricks offers different device categories. Depending on the category, different interfaces, tailored settings (i.e. how to initialize the pumps), and visualizations (i.e. separate HLT and MLT temperatures for HERMS) are supported.
Currently, the following equipment types and profiles are supported:
| Type | When to use | Min Bricks required |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [Mashtun](/using-bricks/equipment-types/mashtun) | Automate your mashing with a single, heated vessel and optional stirring. | 1 |
| [BIAB / MLT / HLT](/using-bricks/equipment-types/biab) | Automate your mashing with a single, heated vessel and optional advanced settings for controlling pumps. | 1 |
| [HERMS (advanced)](/using-bricks/equipment-types/herms) | Automate your mashing with two (MLT, HLT) vessels. Advanced settings for HERMS and pumps available. | 2 |
| [Fermenter](/using-bricks/equipment-types/fermenter) | Automate your fermentation by heating / cooling. You can also monitor your gravity over time using i.e. TILTs or iSpindels. | 1 if you want to control your temperatues. If you just want to monitor a electric hydrometer is sufficient. |
Here's a visualization how multiple Bricks can be grouped to support various scenarios. Despite each Brick offers one temperature probe, this is not displayed.
# Mashtun
The "Mashtun" is the right type for mashing if you stirr your mash.
This device type also supports automatic **calibration**. Read [Calibration](/using-bricks/equipment/calibration) to find out, what the huge benefits of calibrating your device are.
### Interfaces
It offers three different interface types:
* Electrical switches for heating (required)
* Electrical switches for circulation, i.e., to control a pump or stirring using the software (optional)
* Temperature sensors for wort temperature (required)
### Settings of a mashtun
You can change the following settings:
* "When to turn the circulation on":
* "Always on": The stirring will be always on. Only requirement: The recipe step (in Automatic) or toggle (manual) must have circulation to be set to "turned on".
* "Only during and after heating": This will only turn the circulation on when the heating is turned on and a configurable amount of time (in minutes) after heating was turned off.
* "Only when heating": Like the last option, only that circulation will be turned off immediately after heating is stopped without any delay.
# BIAB / MLT / HLT
The "BIAB / MLT / HLT" is the right type for mashing if you have a BIAB setup or want to start the easy way with automating parts of your HERMS setup. Upsides of a "BIAB / MLT / HLT" device over a regular "Mashtun" device include:
1. Being able to initialize your pumps
This device type also supports automatic **calibration**. Read [Calibration](/using-bricks/equipment/calibration) to find out, what the huge benefits of calibrating your device are.
### Interfaces
Much like the "Mashtun", it offers three different interfaces:
* Electrical switches for heating (required)
* Electrical switches for circulation pumps, i.e., to init pumps.
* Temperature sensors for wort temperature (required)
### Settings of "BIAB / MLT / HLT"
You can change the following settings
* "When to turn the circulation on" (pump from MLT through Coil of HLT):
* "Always on": The stirring will be always on. Only requirement: The recipe step (in Automatic) or toggle (manual) must have circulation to be set to "turned on".
* "Only during and after heating": This will only turn the circulation on when the heating is turned on and a configurable amount of time (in minutes) after heating was turned off.
* "Only when heating": Like the last option, only that circulation will be turned off immediately after heating is stopped without any delay.
* Pump init cycles: Set a number of pump inits to get the air out of your tubes. This will turn on and off your pump a couple of times
* Duration of ON in a init cycle (requires "Pump init cycles" to be larger than 0): Set the on duration of the init cycle.
* Duration of OFF in a init cycle (requires "Pump init cycles" to be larger than 0): Set the off duration of the init cycle.
# HERMS (advanced)
The "HERMS (advanced)" is the right type for mashing if you have a HERMS setup with two kettles (MLT and HLT) and two BierBot Bricks automating them. Upsides of a "HERMS (advanced)" device include:
1. During brewing, both the MLT and HLT temperatures are visualized in one plot.
2. Process relevant information such as "when the target temperature was reached" is inferred from the MLT. Yet, the HLT is controlled accordingly.
3. You are able to set a offset between MLT and HLT.
4. Your able to set init intervals for your pump.
This device type also supports automatic **calibration**. Read [Calibration](/using-bricks/equipment/calibration) to find out, what the huge benefits of calibrating your device are.
### Interfaces
The following interfaces are offered
* Electrical switches for heating the HLT (required)
* Electrical switches for advanced control over the circulation between MLT and HLT through the coil (optional)
* Temperature sensor for HLT temperature (required)
* Temeprature sensor for MLT temperature (required)
### Settings of a "HERMS (advanced)"
You can change the following settings:
* "When to turn the circulation on" (pump from MLT through Coil of HLT):
* "Always on": The stirring will be always on. Only requirement: The recipe step (in Automatic) or toggle (manual) must have circulation to be set to "turned on".
* "Only during and after heating": This will only turn the circulation on when the heating is turned on and a configurable amount of time (in minutes) after heating was turned off.
* "Only when heating": Like the last option, only that circulation will be turned off immediately after heating is stopped without any delay.
* Pump init cycles: Set a number of pump inits to get the air out of your tubes. This will turn on and off your pump a couple of times
* Duration of ON in a init cycle (requires "Pump init cycles" to be larger than 0): Set the on duration of the init cycle.
* Duration of OFF in a init cycle (requires "Pump init cycles" to be larger than 0): Set the off duration of the init cycle.
* HLT target temperature set by: Defines how the HLT target temperature is set.
* Delta to target temperature: The target HLT temperature is set by adding an offset to the current target mash temperature.
* MLT-HLT Delta: Like "Delta to target temperature" and allowing to limit the offset between MLT and HLT during heating phases explicitly. This is handy, if your MLT is overpowered to go easy on enzymes (avoiding being heated up too much when traveling through the coil).
* Aggressive approach (soon): Like "Delta to target temperature" only that you can specify a seperate (larger) offset during heating phases between HLT and target temperature.
* Target difference between HLT and target temperature (requires "HLT target temperature set by" to be set to "Delta to target temperature"): Set the target delta. Example: Mashing target temperature is 60°C, delta is 2°C. This results into an target HLT temperature of 62°C.
* Target difference between MLT and HLT (requires "HLT target temperature set by" to be set to "MLT-HLT Delta"): Limit the maximum delta between HLT and MLT during heating.
* Target difference between HLT and target temperature during heating (requires "HLT target temperature set by" to be set to "Aggressive approach"): Allows you to set a higher difference for heating to speed up getting the MLT to target temperature.
# Fermenter
The "Fermenter" is the right type of Device if you want to control (using BierBot Bricks) or monitor (i.e. using TILT, iSpindel, etc.) your fermentation. It supports both actively cooling and heating your fermentation vessel.
### Interfaces
* Electrical switches for cooling (optional). You might wonder why this is optional? Some user only track their fermentation using, i.e. an iSpindel, and do not want to actively control their fermentation.
* Electrical switches for heating (optional). In case you use a fridge for cooling, this can be used to control [heating mats](https://amzn.to/3FBDkOH) that are place inside your fridge.
* Temperature sensors (required): to monitor the temperature of your green beer / wort in fermentation. You can also add mutliple sensor values. In this case, they will be averaged. An example for this would be to have a iSpindel floating on top and a DS18B20 installed at the bottom of your fermentation tank.
* Gravity sensors (optional): Assign gravity sensors (i.e. using a TILT ([TILT™](/hardware/hardware/tilt)) or iSpindle ([iSpindel / iSpindle](/hardware/hardware/ispindel)) to track the progress of your fermentation. If you want to track this long term (over a week or so), be sure to launch a recipe for fermentation in the [Automatik Mode](/using-bricks/automatic-mode) as the [Manual mode](/using-bricks/the-manual-mode) will only display the last couple of minutes.
### Good to know
If you want to reduce the wear and tear on the compressor of your fridge, you can increase the "hysteresis" value in the "CONTROL"-Settings. Settings this to a larger value will reduce the number of times the compressor will be turned on and off significantly.
Also, if you you both heating and cooling, be sure to set the hysteresis of one of both larger than the other. Otherwise, they will work "against each other". Good values are:
* cooling hysteresis: 0.4°C
* heating hysteresis: 1°C
# Manual mode
When historic recordings and comments are not needed, the manual mode is the weapon of choice. E.g. for controlling a sparge tun to reach and hold 78°C / 172,4°F or a fridge/fermenter holding 5°C / 41°F for multiple weeks / years.
# Automatic mode
The automatic mode runs your recipe consisting of multiple temperature seteps "automatically" and saves all temperatures, comments and other logs (volume, gravity) permanently.
### Prerequisites
Before you can start the Automatic mode, you need to create a recipe. If you have already done that: Great! If not and you want to know how: Head over to the creating a [recipe tutorial](/getting-started/importing-recipes).
### Starting a brew
To start a brew, head over to your recipes. Click the "Start brew" button in the list of recipes. Wait a few seconds while the software prepares your brew. You'll be automatically redirected to the brewing / "Automatic" screen.
### Brew preparation
Before the brew actually starts, we need to set some **generic settings**:
* The target amout of final wort (this is only used as part of the logging for now).
* The brewnumber: Based on your breweries next brew - automatically incremented by 1 if that's a number only.
We also need to select the **used hardware** for every brewing step defined by the recipe. This may vary, since not every recipe may i.e. include fermentation steps.
You can only select hardware that is ready for use. A mashtun without any heating relais configured will not work / show up here.
After you've selected devices for all brewing steps (or skipped them), you can start the brew. If you want to start the brew right away hit "Let's go!". If you want to schedule the brew, to start at a later point of time, use the "schedule start" button. This makes sense, if you want to start the brew in the morning without having to leave the bed until mash-in.
### The brew
Finally - the brew starts. The brewing screen gives you every information about your process at a glance. From top to bottom:
* At the top, the **control card** is located. It consists of
* The current temperature reading (you can configure the unit in [Your settings](/using-bricks/your-settings)).
* A Stop button - if you want to abort the brew.
* A next button - that will trigger the next recipe step without checking any conditions.
* A card showing the current state of your device (is the heating/cooling on or off)
* A "add log" button. By default, this button will log comments. Using the arrow down, you can also add other logs such as gravity-readings, volumes, etc.
* On the left you'll find all recipe steps for mashing and fermentation. Also, if a process step is completed (e.g. mashing, meaning all mashing step), a wrapup card will be displayed. This is a **gentle** reminder 😉 that is now the perfect time to add some logs such as the current gravity.
* On the top-right all diagrams will be displayed. Different diagrams will appear as soon as the values arrive. In most cases this will be the temperature. You can zoom to a predefined range using the dropdown at the top right, or by interacting the the plot directly.
* On the bottom-right you'll find the **comments card**. This card will simply display all comments you've logged using the button on the **control card**.
# Gravity history
If you run a automatic to track the progress of your fermentation, a gravity graph will show up. Here's how to read it.
First off: different people use different units. You can set all units used in this graph in your interface settings . This includes the unit for the gravity itself °Plato, SG (as as the temperature in °C or °F for the neighbouring graphs).
By default, the graph will display two lines: The gravity (in the unit of your choice) and the fermentation percentage:
While the gravity is straight-forward (well, that's the reading from your Brick) the "% Fermentation" needs a little bit more explanation.
"% Fermentation" is calculated like follows: Suppose you started fermentation with a green beer at SG=1.05 or 12°Plato and are now at SG=1.025 or 6°P. The "fermentation percentage" would be 50% as 50% of the available sugars were already fermented.
If you set the starting sugar after completing your mashing, this value will be used as the maximum. If you didn't set this or started the automatic brew right with the fermentation process, the maximum value of all available gravity readings will be used as a fallback.
Also: You can **disable lines** in the graph by clicking on the respective item ("Gravity" or "% Fermentation") in the legend below the graph.
# Brewlogs
Every brew that was completed using the automatic mode will be permanently stored as a brewing log so you can look up your temperature profiles, brewing duration, recipes steps and comments afterwards
The brewing logs overview screen shows you all of your past brews. You can search for past brews using the search field on the top-right corner of the table.
Currently that is
* Name of the brew
* Two action buttons ( ):
* To delete this log
* To open the detailled report
* A rating, each member of your brewery has one vote
* The brewnumber
* when the brew was brewed
* It's duration
* Wort volume boiling
* The amount of green beer
* The gravity after boiling
* and the gravity after fermentation (this will be used to calculated the ABV).
Any info that can be changed inline is denoted by a . Just click on it, to edit it.
# Your settings
Bricks is tailored towards customization and gives you full control over every unit used in the UI.
Your settings consist of three major areas. Your account, the interface settings, and your notification settings.
### Account-Settings
You can change your password and delete your account here. Please don't do the latter ❤.
### Interface-Settings
The interface settings allow you to change pretty much any unit displayed in the UI. Missing something? Please let us know! Settings currently include (but are not limited to):
* Gravity Unit: °Plato and original gravity.
* Gravity unit for own measurements: If you add a gravity during a brew there is a chance you'll want to do it using Brix since because that's how your refractometer works.
* Time units
* For mashing (boiling duration, rest time)
* For fermentation (how long to hold a temperature)
* For the heating gradient
* Unit System: You can set this to metric (most parts of the world), imperial (mostly US), or custom. If custom is selected, you can specify each unit manually:
* Temperature: °Celsius or °Fahrenheit
* Volume: Liters, fluid ounces or gallons.
* Lengh: Meter or inches.
* Weight (malts): Kilogram, gram, milligram, pounds.
* Weight (hops): Kilogram, gram, milligram, pounds.
* Pressure: Bar, PSI, kPa.
### Notification-Settings
You can control when to be notified.
# Bricks API
The Bricks API is fully documented and open to everyone. If you are a software dev, this section will help you to turn your hardware into a "Brick" and interact with our software.
## IOT endpoint
`GET` `https://brewbricks.comapi/iot/v1?apikey=apikey&type=:type&brand=:brand&version=:version&chipid=:chipid[sakey=:savalue]`
This method is the main endpoint for connecting various IOT devices to BierBot Bricks.
#### Query Parameters
| Name | Type | Description |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apikey | string | The \`apikey\` of your brewery. |
| type | string | A hardware descriptor, e.g. `sonoff_th16`, `wemos_d1`, `rapsberry_3b` (logic: `manufacturer_board`). |
| brand | string | Who produced your device. For own / opensource projects please use `oss`. |
| version | string | Firmware version of your hardware. E.g. `0.4.2`. |
| chipid | string | The chipid / similar of your device. This has to be **unique** among all devices of one brewery. |
| sakey | string |
For how `sakey` has to be shaped, please see below. `savalue` can be anything of the following: - 0/1: indicating the current state of an relay. - 0-1023 indicating the current state of an PWM signal. - 0-105 indicating a temperature reading in degree celsius. - 0-20 indicating the specific graviy (SG) in degree plato (°P).
|
{% tabs %}
{% tab title="200 Important OBEY the next\_request\_ms defining when the IOT should call the backend the next time. Repeated violation will cause your device to be blocked and in extreme cases your account to be locked. The first request will not hold and target values for actors (see the epower\_0\_state: 0). After your Brick has been activated, the backend returns the new target state for each actor of your request." %}
```
{
"error": 0,
"error_text": "",
"warning": 0,
"warning_text": "",
"next_request_ms": 15000,
"epower_0_state": 0
}
```
{% endtab %}
{% endtabs %}
The sensor / actory key ( `sakey` ) has follow the following schema (`$x_$y_$z_$i`):
* `$x` all fields are prefixed with `a` (actor) or `s` (sensor)
* `$y` datatype of the sensor / actor. currently supported are `bool` and `number`
* `$z` the physical meaning, e.g. `temp`, `wort` for sensors. or `epower`, `pressure` for actors.
* `$i` index on the device, starts with 0. This allows enumeration if multiple interfaces are of the same type. The index needs to be incremented for all groups of `$x` and `$z` (the datatype is not relevant).
Return value is a JSON map
```
{
"error": 0,
"error_text": "",
"warning": 0,
"warning_text": "",
"next_request_ms": 15000
}
```
Attention: Pay respect to the `next_request_ms` field. Especially if you contact the backend repetitively too early your Brick might get banned permanently.
Examples:
* Device 1:
* `s_number_temp_0`: first sensor sending a temperature number.
* `s_number_temp_1`: second sensor sending a temperature number.
* `s_number_temp_id_0`: ID of the first temperature sensor, i.e. `0x00003ffc3664`.
* `a_number_epower_0`: This a PWM actor.
* `a_bool_epower_1`: note, how index is incremented, despite the change of `$z`.
### Sample request and implementations
Example request by the BierBot Brick would look like
```
https://brewbricks.com/api/iot/v1?type=sonoff_th16&brand=bierbot&version=0.9.4&s_number_temp_0=42&a_bool_epower_0=0&chipid=142424242_5C:CF:FF:20:CC:A5&apikey=YOUR_API_KEY
```
Sample implementations are available in
* [C/C++](https://github.com/BernhardSchlegel/BierBot-Bricks/blob/main/ESP8266/src/main.cpp#L479) for a Brick, [C/C++](https://github.com/universam1/iSpindel/blob/master/pio/src/iSpindel.cpp#L792) for a Hydrometer
* [Python](https://github.com/BernhardSchlegel/BierBot-Bricks-RaspberryPi/blob/main/main.py#L75)
# Connecting displays
BierBot Bricks exposes an API to query information about your currently ongoing brews. You will get the brew name, current and target temperatures, and (if the next step is due after a set amount of time and the temperature was reached) the time until the the next action.
## Endpoint for getting statistics about currently running brews.
`GET` `https://brewbricks.com/api/iot/v1`
#### Request Body
| Name | Type | Description |
| ----------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| apikey\* | String | your API key as for all other Bricks |
| type\* | String | always has to be `display` |
| brand\* | String | always has to be `oss` |
| version\* | String | version of the display software running |
| chipid\* | String | A uniquie identifier for this Brick. Can be the chip ID or also any other unique and always permanent value |
| d\_object\_information\_0\* | String | Specifies the shape of your display. I.e. `4x20` for a typical 4 by 20 display. |
{% tabs %}
{% tab title="200: OK If everything was OK. Sample response body can be found below." %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
A sample response looks like this:
```
{
"result": "success",
"error": 0,
"error_text": "",
"warning": 0,
"warning_text": "",
"settings": {
"temperatureUnit": "celsius",
"displayBrewEveryS": 5,
"showLocalIP": false
},
"brews": [
{
"currentTemperatureC": {
"na": -273,
"primary": 10,
"secondary": -273,
"hlt": -273,
"mlt": -273
},
"id": "T1muylAbPsxkZ389ha1z",
"name": "Pils (TILT)",
"targetTemperatureC": 10,
"nextEvents": [
{
"timeRemainingS": 85587.428,
"type": "step"
}
]
},
{
"currentTemperatureC": {
"na": -273,
"primary": 11.06,
"secondary": -273,
"hlt": -273,
"mlt": -273
},
"id": "DcfimLZm4PFMaTErounA",
"name": "Pils (iSpindel + Steuerung)",
"targetTemperatureC": 14,
"nextEvents": []
}
],
"next_request_ms": 15000
}
```
# Pro API
The Pro API lets you interact with your brewerys' data, i.e. to enable custom build dashboards.
### Setup
To enable the Pro API: Got to your brewerys admin page (), locate the "Pro-API" section and toggle the enable toggle to on. The Pro-API key and API key become available. The latter is the normal API key you've used for setting up all your Brick. The first one is an additional API key we need for communicating with the API.
Pro-API config menu
### Usage
Note: This requires at least a PRO membership.
If you're missing an endpoint, please reach out using the blue feedback button, the [contact form](https://bierbot.com/contact/) or the [forum](https://forum.bierbot.com).
{% openapi src="/files/FfGzYLLZ4DmuZUGP50CY" path="/api/devices" method="get" %}
[My Project.openapi.json](https://972345729-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mb-yazhyh6RzCW1gcvw%2Fuploads%2Ft4H4asf7ILS2fpktQWy0%2FMy%20Project.openapi.json?alt=media\&token=5914dead-4226-4d38-bc7c-59b3b3f729ee)
{% endopenapi %}
{% openapi src="/files/FfGzYLLZ4DmuZUGP50CY" path="/api/device" method="get" %}
[My Project.openapi.json](https://972345729-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mb-yazhyh6RzCW1gcvw%2Fuploads%2Ft4H4asf7ILS2fpktQWy0%2FMy%20Project.openapi.json?alt=media\&token=5914dead-4226-4d38-bc7c-59b3b3f729ee)
{% endopenapi %}
# Changelog
Note: If a release only includes "minor bugfixes" it's not displayed in the chanelog.
* 10/01/2025
* Reworking payments - now with PayPal support.
* 01/28/2024
* Enable "Free rise" during fermentation steps (heating will not be turned on until target temperature was reached).
* Show gravity alongside temperature during fermentation on Automatic and Status page.
* Fix bug for beerXML import if boiling size is missing.
* 12/13/2023
* Varios bugfixes and stability increases: Deletion of gravities in the log, filtering out unvalid temperature values (only -20°C-150°C), display endpoint properly formatted device array
* Display of gravity in the top bar when fermentation is ongoing in automatic mode
* Return of calibration offset for Sonoff TH Elite devices for display
* 12/03/2023
* Introduction of Pro API to query additional information for brewing devices, see detailled documentation [here](/developer-section/pro-api).
* 10/22/2023
* Outliers in plots can now be removed from chart by clicking the trash icon and then the respective point in the chart\
* Preparation for new Brick type
* Inventory management released for PRO members
* Several bug fixes
* 11/01/2023
* minor updates (i.e. "last seen" of a Brick is now the delta to the current time, interaces from Bricks now display and indexnumber if the Brick has more than one interface of the same type)
* bugfixes
* Support of adding ingredients in recipes.
* 10/08/2022
* Change of "temperature reached" reached logic. Old way: Current temperature lower than set temperature. New way: Current temperature has to be within +-0.25°K of the target temperature.
* minor bugfixes
* 08/31/2022
* Android app release
* minor bugfixes
* 06/21/2022
* custom polynom for iSpindel calibration in UI
* 05/23/2022
* optimized stability and performance for brews in automatic mode
* 05/09/2022
* [Display endpoint](/developer-section/bricks-api/connecting-displays) for connecting LCD displays.
* 02/06/2022
* Recipe editing while brew is active.
* Usability improvements (i.e. brewname is displayed as column in brewing logs)
* minor bugfixes
* 12/23/2021
* Supporting multiple brews at a time for PRO members.
* 11/21/2021
* HERMS support
* minor bugfixes
* 11/07/2021
* BIAB mashing device support.
* 10/30/2021
* Temperature Sensor calibration
* Initialization cycles for pumps
* 08/17/2021
* new language: Portugese