-
Notifications
You must be signed in to change notification settings - Fork 15
BrewTroller v2.7 Manual (develop)
This is intended to be the BrewTroller manual for the most recent develop branch of the github.com/oscsys/brewtroller repo. This is a living document that updates as features are added.
The latest develop branch of this repository is available here: https://github.com/OSCSYS/brewtroller/archive/develop.zip
This section covers changes that must be made before the firmware source is compiled and uploaded to a target device.
The BrewTroller firmware supports several different target device types. Each target device supported has a unique HWProfile.h file that configures BrewTroller for target device. These HWProfile.h files are stored in a HWProfiles folder structure within the source code. Currently, the source code is configured for use with the OpenTroller DX1. To configure BrewTroller for another device type simply locate the HWProfile.h file for your target device in the HWProfiles folder and replace the HWProfile.h file in the root folder of the BrewTroller firmware.
The long-term goal for this project is to eliminate the need to configure and compile source code entirely. There are however a few options that are currently only available if enabled in the source prior to uploading. These options are configured in the Config.h file of the source code.
BrewTroller defaults to Imperial units (F/Gallons/Pounds). If you wish to use with Metric units you must uncomment the //#define USEMETRIC line by removing the proceeding '//':
#define USEMETRIC
This option dynamically alters the HLT setpoint based on the mash setpoint and error. Error refers to the difference between the actual temperature and setpoint.
By default, an alarm condition will cause the configured alarm output to be activated constantly. This option causes the alarm output to be modulated or pulsed instead.
This branch of BrewTroller is designed to be used with a customized version of the Arduino 1.0.5-R2 development environment. The official Arduino IDE has been customized to support the ATMEGA1284P microcontroller used by BrewTroller/OpenTroller devices and also includes libraries not included with Arduino that BrewTroller requires.
The custom IDE is available for both Windows and Mac systems:
-
Make sure the target device is connected via USB to the system being used to upload the firmware.
-
Launch the customized Arduino IDE.
-
Select ATMEGA1284P Board from the Tools-Board menu
-
Select the appropriate serial port for your target device from the Tools-Serial Port menu
-
Click the upload button → or select Upload from the File menu
BrewTroller boots to the Home Screen displaying the firmware version. An unlock icon in the upper right corner of the screen indicates that the user interface (UI) is unlocked and the encoder can be used to switch between logical screens. Clicking the encoder will lock the user interface on the active screen causing the encoder input to be sent to the screen. A click held for one second or longer will unlock the user interface.
The BrewTroller firmware must be configured for your specific brewing system once it has been loaded to the target device.
Navigate to and lock the Home Screen. Click the encoder to launch the Main Menu. Select System Setup.
When the Boil Kettle output uses PWM this setting defines the temperature at which the Auto Boil logic should switch from full power to Boil Power.
When the Boil Kettle output uses PWM this setting defines the power level needed to hold the boil once the boil temperature has been reached if Auto Boil logic is used.
This setting exposes the calculation factor used to determine the amount of liquor lost to evaporation during the boil. This is used to calculate recipe volumes.
This setting exposes the calculation factor used to determine the amount of volume grain will consume in the mash tun. This is used by the user interface to detect capacity issues with recipes.
This setting exposes the calculation factor used to determine the amount of liquor lost to grain absorption. This is used to calculate recipe volumes.
This value is added to the strike volume in recipe logic to account for strike liquor that is left in the strike heat vessel and plumbing after strike transfer. If Strike is heated directly in the mash this should be 0.
This value is added to the sparge volume in recipe logic to account for sparge liquor that is left in the sparge heat vessel and plumbing after sparging.
This value is added to the total liquor volume in recipe logic to account for wort left in the mash tun after sparge. Since strike volume is subtracted from the total liquor to obtain sparge volume this essentially is added to sparge liquor. This value will affect mash efficiency but typically not by much as the wort is diluted during sparge.
This value is added to the preboil volume in recipe logic to account for wort that is left in the boil vessel and plumbing after transfer to fermentation vessel. This value will affect both mash efficiency and hop utilization as additional water will be added to liquor to compensate for this loss. As an alternative you can leave this value 0 and instead adjust your batch volume to compensate and scale your recipe for the larger batch volume. The quantity of hops used in a recipe is also likely to affect this value as the hop debris will displace some of this volume.
This menu is used to assign specific temperature sensors to vessels/functions. Use the encoder to navigate between the available sensor functions:
-
HLT: Hot Liquor Tank
-
Mash: Mash Tun
-
Kettle: Boil Kettle
-
H2O In: Water input temperature displayed on Chill screen
-
H2O Out: Water output temperature displayed on Chill screen
-
Wort Out: Wort output temperature displayed on Chill screen (typically used with counterflow chiller)
-
AUX 1: User-defined sensor displayed on AUX screen
-
AUX 2: User-defined sensor displayed on AUX screen
-
AUX 3: User-defined sensor displayed on AUX screen
Click the encoder for access to the following menu options:
-
Scan Bus: Scan the 1-Wire bus for an attached sensor that has not been previously assigned to a function
-
Delete Address: Clear the assigned sensor address
-
Clone Address: Copy the address from another vessel/function allowing a single sensor to be used for multiple functions
-
Cancel: Return to vessel/function selection
-
Exit: Exit Temperature Sensor menu
Note: It is recommended to attach a single sensor to the bus and assign its function. Then add a second sensor and assign it’s function. Repeat until all sensors have been detected and assigned. If multiple unassigned sensors are connected to the bus it will be more difficult to determine which sensor was found during a scan.
This menu provides access to vessel specific settings including heat output and volume/capacity settings. In addition, this menu exposes a Bubbler sub-menu that provides configuration for the intermittent bubbler system.
The optional output to be used for Pulse Width Modulation (PWM) heat output. PWM is used to pulse an output for a percentage of time. This is typically used with electric heating elements and provide variable output power from 0-100% instead of simply on or off.
When a PWM output has been configured this controls the length of time that represents the entire PWM period including the percentage of time the output is active and the remaining inactive time.
This is used to control the number of increments available within the PWM period. For example, with the a PWM period of 1.0s and a PWM resolution of 120 the output time will increase in increments of 8.3ms. This is helpful to align the PWM output with the source AC power frequency. When using a resolution of 120 with 60Hz power each increment represents half of an AC cycle. For manual control of the boil kettle it may be helpful to use a smaller resolution of 60 or 30 so that fewer increments are required to adjust power output.
The PWM output level is controlled by the PID algorithm. PID combines three different calculations to determine the output level: Proportional (P) represents current error, Integral (I) represents past error and Derivative (D) represents predicted error. The Gain settings allow these three calculations to be weighted.
This sets the output percentage resulting from the PID algorithm. The default value of 100 does not impose a limit.
This setting is used to control when the Vessel Heat output profile is enabled. This heat control is completely independent of the optional PWM logic controlled in the previously described settings. Hysteresis is used to avoid rapid switching between Vessel Heat and Vessel Idle output profiles. A value of 1.0 degree caused the Heat profile to be enabled if the current temperature is 1.0 degrees or more below the setpoint. The Heat profile will remain on until the setpoint is reached.
This indicates the maximum capacity of the vessel and is used to validate program recipe settings.
This represents the amount of liquid trapped in the volume and is included in the various recipe volume calculations.
This sub-menu allows creation of mappings between analog sensor values and specific volumes. BrewTroller will use the two closest calibration points to estimate volume in a vessel. When selecting an OPEN slot you will be prompted to input the volume currently in the vessel. After a series of readings the following options are presented:
-
Update (Old Value) to (New Value): This will update the calibration with the newly read analog value
-
Manual Entry: This will allow you to manually enter an analog value to map to the volume.
-
Delete: Deletes the calibration volume and value.
Tip: Due to the location of your pressure port on your vessel you may not be able to read values below a certain volume. You can manually create a calibration at 0.0 Gal/l using a manual entry of one less than your lowest actual calibration. For example, if your lowest possible reading is 1.00 Gal with a value of 40, create a calibration of 0.00 Gal with a value of 39. This will result in any read value under 1.0 Gal to be shown as 0.0 Gal.
This option will copy all vessel settings from another vessel. This is useful if you are using a vessel for multiple purposes (HLT as Kettle, or Mash as Kettle, etc.)
The intermittent bubbler system will periodically activate an output to run one or more air pumps connected to your pressure sensor plumbing. While the pump is active and for a configurable delay period thereafter volume readings will not be taken.
-
Output: The output the air pump(s) is connected to.
-
Interval: How often the output is activated.
-
Duration: How long the output is active.
-
Delay: How long to continue delaying volume reads after the pump is deactivated.
Output Profiles provide an abstraction layer between BrewTroller logic and users brewing systems. BrewTroller activates output profiles to perform specific operations. The user configures the output profile to activate whatever outputs are required to complete that operation. The following output profiles are supported:
-
Alarm: This will be replaced with a single output configuration in the near future
-
Fill HLT: Used to fill the HLT vessel with water
-
Fill Mash: used to fill the mash vessel with water
-
<Vessel> Heat: Used to heat the <Vessel> with Vessel Hysteresis setting
-
<Vessel> Idle: Used when a setpoint is active on the <Vessel> but <Vessel> Heat is not active. Useful for stirrers and recirculation.
-
<Vessel> PWM Active: Active if the <Vessel> PWM output percent is not zero.
-
Add Grain: Used during the Add Grain/Grain In step to add grain into the mash tun.
-
Strike Transfer: Not yet implemented… coming soon.
-
Sparge In: Transfers sparge liquor into the mash
-
Sparge Out: Transfers wort out of the mash and into the kettle
-
Boil Additions: Used when boil addition alarms are activated for use with automatically performing additions
-
Chill:
-
Wort Out
-
Whirlpool
-
Drain
-
User 1
-
User 2
-
User 3
This menu includes options to automate actions in specific steps during program recipe execution. Settings used during the execution of specific steps are also configured here.
Determines if sparge volume is filled at the start of a program (Start) or after preheat (Refill). This default is now Refill which is a departure from previous logic.
Determines if Auto Fill logic should be activated on the start of Fill step. Default = Off.
Determines if Fill Step should automatically exit once target volume has been reached. Default = Off
Determines if Preheat Step should automatically exit once target strike temperature has been reached. Default = Off.
Determines if strike is transferred automatically at the start of Add Grain step. Default = Off
Determines if Add Grain step should automatically exit after a period of 1-255 minutes. This assumes you have something activated with the Add Grain output profile that is feeding grain into the mash tun. Default = Off
Determines if the Mash Hold step should be skipped and program execution move directly to sparge. Default = Off
Limits sparge input volume based on sparge output volume (0.1 - 25.5 l/Gal). This replaces the old SPARGE_IN_PUMP_CONTROL compile option. Default = Off
This replaces the HLT_MIN_REFILL option. It is useful for HERMS users who need extra HLT volume than a recipe might call for to cover the HERMS coil. (0.0 - 6553.6 l/Gal) Default = 0.0
Determines if Sparge should exit and boil start once kettle volume is reached. Default = Off
Determines if Whirlpool (formerly BoilRecirc) profile should be activated during the specified last minutes of boil. This is useful to sanitize a chiller or pump used during chill/transfer. Default = Off
Determines how many seconds the Boil Additions profile is active with each hop alarm. Default = 0
Determines the temperature for the preboil alarm if enabled in the recipe. Default = 205F/96C
Defines the specific heat capacity of the mash tun to be used when calculating strike temperature if the strike is not heated directly in the mash. For example, a keggle might use a value of 3.564 based on the specific heat capacity of 304 stainless (0.120) times the empty weight of 29.7 lbs. This option was added because I wanted to remove the static "STRIKE_TEMP_OFFSET" compile option and thought we could step up the logic a notch. Strike temperature calculation at the start of preheat uses real-time temperature of the mash sensor along with this setting to determine how much the strike temperature needs to be offset. Setting this to 0 will not include this additional specific heat in strike calculations.