-
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.
As of Arduino 1.6 and BrewTroller v2.7 Build 11 a customized Arduino is no longer required.
-
Download Arduino official package.
-
Add third-party Board Manager URL in Arduino Preferences:
-
https://github.com/OSCSYS/boards/raw/master/package_OSCSYS_Boards_index.json
-
Select BrewTroller/OpenTroller from Boards menu.
-
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 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
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.
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: Used in the Chill step to cool the boiled wort
-
Wort Out: Used to transfer wort from boil kettle to fermentation vessel
-
Whirlpool: Used to recirculate wort in boil kettle during Boil and Chill steps
-
Drain: Available on the Main menu and used to drain the system after clean
-
User 1: Available on the Main menu and used for user defined functions
-
User 2: Available on the Main menu and used for user defined functions
-
User 3: Available on the Main menu and used for user defined functions
The Output Profile menu for each profile shows the outputs assigned to the profile by name in addition to the [Add Output] and [Test Profile] options. If you click on a menu item for an assigned output it is removed from the profile. Changes made to the profile are not recorded until you exit the Output Profile menu. You will be prompted if you want to save changes. If you choose not to save the changes, changes are lost.
This menu allows you to add RS485 devices using the MODBUS RTU protocol on systems with an RS485 port. Up to four boards can be added however the total output count including on-board outputs provided by the controller itself is limited to 32 outputs. This logic uses MODBUS RTU function code 15: 'Force Multiple Coils'.
Each RS485 output board has the following menu options:
-
Address: The MODBUS slave address of the output board
-
Register: The register of the first coil on the MODBUS slave device
-
Count: The number of outputs or coils to be added on the MODBUS slave device
-
Auto-Assign: The RS485 relay board developed by OSCSYS includes support for dynamically changing the devices slave address. A non-configured or reset device boots with a default address. This menu option will look for a device on that address and automatically assign it a new address while configuring the board on the BrewTroller. This option is only available when the board address is not configured. Use the following process to auto-assign:
-
Click and hold the RS485 Board Reset button until the status LED turns off
-
The RS485 Board status LED will triple flash indicating the board is offline. Click the reset button to bring the RS485 Board online using the default address. (This logic is required to prevent multiple boards from using the default address simultaneously during initial system setup.)
-
Select the Auto-Address option on the board menu
-
An address will be suggested for the board. Click OK to accept.
-
-
ID Mode: The OSCSYS developed RS485 relay board includes support to ID mode causing the status LED to flash and physically identify the board configured on a specific address. This menu option toggles the ID mode On or Off.
-
Delete: Removes the board configuration
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
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
This allows you to enable or disable the E-Stop logic (if an E-Stop port is included on the target device).
The Trigger menu also provides access to ten user-defined triggers that will force specific outputs to be disabled. This logic was added to replace compile-time logic used to protect heating elements from dry-firing and mash tuns from overflowing during sparge. The trigger support however is not specific to any brew step allowing flexibility for users to configure output disable logic as needed.
Triggers are displayed as follows:
-
Not Configured: The trigger has not been configured and is available for assignment
-
Input <Number>: A trigger is configured based on digital input <Number>
-
<Vessel> Volume: A trigger is configured based on <Vessel> volume
-
<Vessel> Delay: A trigger is configured based on <Vessel> setpoint transition from inactive to active
The following options are available when configuring a trigger:
-
Type: Disabled, Digital Input, Volume or Setpoint Delay
-
Vessel/Input: The vessel (volume or setpoint delay) or index (digital input) the trigger should monitor
-
Threshold: For volume trigger, the volume above or below which the trigger is active
-
Active: Low if the trigger is active when the input is inactive or the volume is below the threshold. High if the trigger is active when the input is active or volume is greater than threshold. For Setpoint delay, High will cause the trigger to be active only when the setpoint has become active. A value of Low for Setpoint delay causes the trigger to be active except when the setpoint has changed.
-
Profile Filter: Allows you to filter the trigger so it is only active when the specified profiles are active. If no profiles are in the filter this setting is ignored. This is useful if an output should cutoff in one profile but other logic using the same output in another profile should ignore the trigger.
-
Disabled Outputs: Allows you to select what outputs this trigger should disable
-
Release Hysteresis: Keeps the trigger active for a specified number of seconds after the trigger condition has cleared. This is useful to prevent a float switch from "bouncing" an output on/off repeatedly or to enforce a specific time delay after a setpoint has become active.
This menu supports the use of RGBIO boards for manual control and display of output status. Each board supports 8 channels. Each channel includes an RGB LED supporting a full color palette representing the assigned output’s state. Each channel also includes two switches used to force a channel’s assigned output On or Off.
Up to four boards can be added to a system. Each board supports 8 channels that are assigned to specific outputs. The following options are available on the RGBIO board menu:
-
Address: The I2C Slave address of the RGBIO board
-
Auto Assign: Displayed only if an address is not configured. This allows a board to be reset to it’s default non-configured address, detected and manually added to the BrewTroller configuration. Use the following process to auto-assign:
-
Click and hold the RGBIO Board Reset button until the status LED turns off
-
The RGBIO Board status LED will triple flash indicating the board is offline. Click the reset button to bring the RGBIO Board online using the default address. (This logic is required to prevent multiple boards from using the default address simultaneously during initial system setup.)
-
Select the Auto-Address option on the board menu
-
An address will be suggested for the board. Click OK to accept.
-
-
ID Mode: Causes the RGBIO board on the configured address to blink identifying itself
-
Assignments: Opens a menu showing the boards channels. Each channel assignment provides the following submenu items:
-
<Output>: The output name associated with this channel or 'No Assignment'
-
Recipe: The color recipe to be used for this channel
-
Delete: Deletes the channel assignment
-
-
Delete: Deletes the RGBIO board configuration
Up to four color recipes can be created and associated with a channel. The color recipe is made up of four color values used to display one of four possible output states:
-
Off: The output is forced off as both the Auto and Manual channel switches are off
-
Auto Off: The output is off because the Auto channel switch is on but no nothing is currently activating the output in the system logic
-
Auto On: The output is on because the Auto channel switch is on and the output is active due to system logic
-
On: The output is on because the Manual channel switch is on
Colors are defined as 12-bit HEX values in the form 0x000 where the first digit after the x represents red, the second green and the third the blue value of the LED. Each digit supports 16 values between 0-9 and A-F where 0 is fully off and F is fully on.
Color Recipe 1 has the following default values designed to represent heat outputs:
-
Off: 0xF00 (Red)
-
Auto Off: 0xFFF (White)
-
Auto On: 0xF40 (Orange)
-
On: 0x0F0 (Green)
Color Recipe 2 has the following default values designed to represent pump and valve outputs:
-
Off: 0xF00 (Red)
-
Auto Off: 0xFFF (White)
-
Auto On: 0x00F (Blue)
-
On: 0x0F0 (Green)
Color Recipes 3 and 4 have no default values.