Implement review notes control chains doc

[steersbob]

Commit: c485bf2
Tested on laptop with kubuntu 20.04 LTS on March 26 and March 30 2021.

l5: "The downside of this flexibility is that it takes some time to get to know all the components and understand how they work together."

l7: Consider revision: "This page describes how control chains are constructed in Brewblox at the hand of common brew setup examples. Wizards that generate these examples are implemented in the Brewblox UI. Design choices are discussed with the examples."

l12: Weird to start a basic example with an image. Maybe shift the image behind the first block of text at l36. Also: in the text first is spoken about the minimal building blocks of a control system. Maybe this is best served with its own image. Then continue to the Brewblox implementation with its own image. Possibly side-by side. Cool the image is HTML generated. What are those icons in the top right of every component? Can they be used to indicate the block type?

General remark: an image of the local network topology, protocols, software and naming is useful too; Like: server / Pi (Brewblox UI, block manipulation / readout) <-> controller / Spark (Blox) <-> sensors / actuators. Then you can explain what runs where, and what it is used for. Later you can add other services to the network like the Tilt service for instance. Maybe a separate introductory chapter "Brewblox at a glance..."

l39: "keeps a history of to..." lose of.

l47: turn -> be

l53: add: The elements of these diagrams represent the control blocks that run on the Spark controller. The control blocks can be shown and manipulated on the Spark service page of the Brewblox UI (Brewblox UI -> side panel -> Sevices -> Spark). Switch between the list and diagram view of the control blocks with the toggle in the top-right corner of the screen.

l58: "The example below shows the block diagram on a service..."

l60: confusing to talk about nodes, better use the word blocks

Spark service page - diagram form:

• What is the use case for the 'view fullscreen toggle' in the bottom-right corner? Weird that it starts 'fullscreen' with all the scrollbars
• Maybe add a 'add new block' button in the bottom-right corner too? Double click for add new block depends on knowledge... I expect it will be the most-used menu option

l67: I still find pictures before the explaining text surprising. It is different on paper due size limitations and placement, but on a webpage I prefer text first. There are no page breaks, and the space is there anyhow.

l106: They can both use the same sensor / setpoint pair as input (but this is not how it is implemented now in the ferment fridge wizard, revise?). It IS implemented like that, I was confused with Beer / Fridge mode which are implemented in a different way.

l108: why don't they overlap? Maybe dumb it down... Becomes clearer in the next lines. Suggestion: "The fridge temperature is either too low or too high, so in general the heating and cooling PIDs will not be active at the same time." Why can the output of the Cooling PID be negative? Is it coded that way? I assumed PIDs had an output representing 0 - 100%

l114: lose one: "simultaneous simultaneous"

Wait, why is a mutex needed? You ended the previous section by saying heating and cooling generally do not overlap?

l115: "When one of the actuators holds the mutex, the other is prevented from turning on."

l116: "only one actuator..."

l117: "This prevents quickly alternating between heating and cooling." Why is this needed?

l119: You started out by saying we will learn about control chains at the hand of some common examples. Now you give me all these details about this specific configuration. Interesting and important maybe, but not really what you said the goal of this chapter was.

l127: picture before text.

l172: What is this advanced setup useful for?

l182: adjusted

l192: why no block diagram of the glycol-cooled fermenter control chain? What do we learn here?

l222: the pin connectors look different on the expansion board compared to the Spark. Add a photo maybe? Also, an output pin actually is an output pin pair. Potentially confusing.

l225: What is 100Hz PWM mode? When do you need it? What PWM mode does it support? What is that sufficient for?

l250: "...changes the setting of the Setpoint block..."

l252: "For instance, the Setpoint Profile is very useful to slowly change your temperature setting while fermenting. This ensures the yeast has time to adapt." Not all control block names are in Capital Case, I suggest naming them uniformly.

l262: "sensor setpoint pair" - I presume you mean the setpoint block, you already mentioned the temperature sensor

l264: add a diagram of a HERMS setup? I am not fully aware of all the brew setups yet.

l271: text before figure, YaY!

l273: add distance between HLT / MT control chain and BK control chain in diagram? They are so close they seem connected before close inspection

l324: lose "more than should eventually be transferred to your mash tun" because sentence too long, confusing

l325: "and fill the HLT to the level that just submerges the coil."

l327: what is the use of this example? How do I realize that? How do I set the higher HLT temperature? You said it was automatic.

l328: "This will give you a much more..."

l334: Setpoint Driver? Setpoint Profile?

l338: why do you want to boil with constant power? To prevent...

l343: 1 - lose "for", 2 - spelling "praCtical", 3 - why is it not practical? can you be more specific?

l345: descriptions on diargram arrows missing

l378: "..it will block the other from turning on too."

l385: can you be more specific? Why do we want equal sharing? I imagine it is faster, less erratic, more controlled, but I don't know...

l387: is client the best word? It is not introduced or named Can more than two blocks be balanced? "..limit the power to each connected block"?

l388: Examples:

l399: why is this here? details about how to create the balancer block better described in the previous section called balancer

General remark: control_chains.md suffers from a mixed goal / message. You introduce the chapter by saying Brewblox can be overwhelming due to its modularity and complexity. We will learn about Brewblox by discussing control chains in practical brewing situations and we end up learning about sophisticated control chain options and design decisions.