Specifications¶
Introduction¶
BrewBox tries to answer the question of monitoring and controling a micro brewery which comes to the brewer’s wishing for :
- being able to ensure a constant quality of the beer produced.
- improving brew process efficiency as quantities produced increase.
Monitoring enables following the brewing process characteristics like mashing temperatre or boiling time. This is usually achived by fitting the micro brewery with sensors, like temperature probes.
Controling means acting on equipments fitted in the brewery to run the brewing steps like powering heating element to boil the mash or pumps for transferring liquids between kettles. Controling also requires components and knowledges to build control panel with displays, switches or PID controller.
Finally automation matches together monitoring and controling and enables automatic actuators control based on sensors data and programmable actions. It usually requires professional equipments like programmable logic controller and good knowledge in electronic and electricity.
The goal of BrewBox is to help home brewers to achieve these three goals by providing a system :
- flexible enough to fit any configuration of brewery with a wide range of sensors type.
- offering a large set of features for monitoring, controling and automate the brewery activity.
Use cases¶
Collect data from sensors¶
This documentation describes how BrewBox collects signals from sensors fitted in a micro brewery and converts them into data usable for monitoring and control.
Use case description¶
Collecting data from sensors is a process based on sampling sensors signal at regular interval and converting these samples into information representing some physical quantity. Some special cases may require sampling interruption in order to convert and process some signal as a priority. In both cases data generated during this process are stored and available for further use.
Note
The way signals are physically sampled depends on sensors types and electronic circuitry configuration. This problematic is addressed in the non functionnal requirements section.
Sensors sampling¶
BrewBox maintains a list of sensors fitted in equipements composing the brewery. Each sensor is associated with a sampling configuration describing how and when sampling may occur :
At startup, BrewBox reads the sampling configuration for all active sensors (ie. sensor instances with Status==ACTIVE).
Signal conversion¶
Interruptions management¶
Preconditions¶
Data collection starts once the sensors fitted in the brewery are on and connected to BrewBox system.
Postconditions¶
Data collections runs in background throughout the brewing process, until sensors are switched off.
Home brewer activities¶
[Brewer]-(Setup batch) [Brewer]-(Monitor brewing process) [Brewer]-(Configure brewery equipements) (Monitor brewing process)>(Collect data from sensors{bg:beige}) (Monitor brewing process)>(Control actuators{bg:beige})Home brewer uses BrewBox for :
- configuring BrewBox system in order to operate sensor and actuators fitted in its home brewery;
- setting up batch steps and characteristics in order to build a batch program;
- monitoring brewing process in order to compare actual and planned characteristics. This activity which includes:
- collecting data from sensors for monitoring purposes;
- controling actuators for follow batch program.
Brewery activities¶
[Brewery]-(Run batch) (Run batch)>(Collect data from sensors{bg:beige}) (Run batch)>(Control actuators{bg:beige})Brewery is used by BrewBox in activites which involve brewery sensors or actuators. This happen when running a batch program setup by the Home brewer which includes:
- collecting data from sensors for monitoring purposes;
- controling actuators for follow batch program.
Brewbox specifications are divided into several documents :
- an introduction describing the context in which BrewBox can help.
- a description of use-cases and other `functional requirements`_ achieved by BrewBox.
- a reference class model.
- a description of non functional requirements which must be satisfied by BrewBox to meet any hobbyist knowledge and capacity.
Note
BrewBox requirements are not set in stone and specification documentation is not exhaustive. Any comments or improvement proposals are welcome.
Class model¶
Here is a list of class used in the specification model :
Object model¶
Brewer¶
Brewer is used for storing personal information concerning the brewer, user of the brewery.
Attributes¶
| Field | Description |
|---|---|
| first_name | Brewer first name (mandatory) |
| last_name* | Brewer last name (mandatory) |
| Brewer email (mandatory), which can be used to send automatic email notifications | |
| phone_number | Brewer phone number, which can be used to send automatic SMS notifications (if available) |
| language | Brewer prefered language |
| country | Brewer country location |
Brewery¶
Brewery class is the representation of a brewery in BrewBox. This is the central object for accessing equipments, sensors, actuators and data.
Attributes¶
| Field | Description |
|---|---|
| name | Short descriptive name for the brewery |
| description | Longer description for the brewery (optional) |
| start_date | Date when the brewery has been used for the first time |
| status | Brewery status. Can be something like idle, running batch, running fermentation, ... |
Relations¶
- Equipments : a list of equipments describing the brewery composition.
- Brewer : link to the home brewer using the brewery.
Rules¶
BrewBox can monitor and control only one brewery. There can only exist one instance of Brewery class.
Sensor¶
Sensor class is used for storing characteristics of sensors used in breweries.
Attributes¶
| Field | Description |
|---|---|
| name | Short descriptive name for the sensor |
| description | Longer description for the sensor (optional) |
| status | Current status of the sensor in the brewery. Can be one of :
|
Relations¶
- SamplingConfiguration : link to the sampling configuration used for this sensor.
- ConversionConfiguration : link to the conversion configuration used for this sensor.
Rules¶
All status can be set manually by the user. Some status can also be set automatically by BrewBox :
- UNREACHABLE is set by BrewBox when some problem occurs when collecting data
- DISABLED is set by BrewBox when to many errors occurs when collecting data. Some user action is necessary to reset sensor status.
DISABLED sensors are not processed by BrewBox during sampling process.
SamplingConfiguration¶
SamplingConfiguration class holds configuration attributes used by BrewBox to compute sensors scheduling. Sampling configuration can be basic, interval based or cron-style.
SamplingConfiguration¶
SamplingConfiguration is an abstract class holding configuration attributes common to all sampling methods.
Attributes¶
| Field | Description |
|---|---|
| start | Sensor sampling lifetime. Value can be :
|
IntervalSamplingConfiguration¶
IntervalSamplingConfiguration holds configuration attributes for interval sampling. Interval sampling is a basic sampling method where samples are taken on repeated intervals.
Attributes¶
| Field | Description |
|---|---|
| interval | Sampling interval value |
| unit | Interval value unit. Value can be:
|
Rules¶
Example : An IntervalSamplingConfiguration instance with Interval=5 and Unit=MINUTE will setup a sensor sampling every 5 minutes.
CronStyleSamplingConfiguration¶
CronStyleSamplingConfiguration allows to setup sampling configuration based on cron-style expressions.
Attributes¶
| Field | Description |
|---|---|
| year | 4-digit year number |
| month | month number (1-12) |
| day | day of the month (1-31) |
| week | ISO week number (1-53) |
| day_of_week | number or name of weekday (0-6 or mon,tue,wed,thu,fri,sat,sun) |
| hour | hour (0-23) |
| minute | minute (0-59) |
| second | second (0-59) |
Rules¶
Sampling will occur every time the time and date match the cron expression given by the attributes values.
Non functional requirements¶
User guide¶
Todo
To be done
Welcome¶
Brewbox consists of software and hardware components which provide solutions to monitor, control and automate a home brewery.
BrewBox is part of projects developped by Beerfactory.
This documentation contains all the project’s knowledge, from its specifications to user guide.