Implement review notes spark connection settings

[steersbob]

File: connect_settings.md
Commit: 5be4c2c
Review date: April 13 2021
Tech: Tested on laptop with kubuntu 20.04 LTS and Spark (service: spark-one) with Fermentation Fridge wizard blocks (standard). Spark is powered & connected over USB. Spark simulation (spark-sim) was added as extra service.

General remark: sections 'Connecting multiple devices', 'Adding a Spark service', 'Adding a Spark simulation' and 'Spark connection settings' are best merged into one guide imho.

l18 I understand --device-id is a setting, but I don't know how to use it. Personally I could use an example; I understand the add-spark command can be followed by --device-id=400058000551353432383931. In the YAML file I don't fully understand the syntax. It seems to be command: --device-id=400058000551353432383931. Another possibility is you don't show an example and use it as a filter to select tech-savvy users -

l32 "The Spark service running on the server..." I am still not fully aware of the Brewblox system. I have to think every time how it works and make frequent mistakes

l34 Note: brewblox-ctl discover-spark only works in your Brewblox directory

l41 works!

l54 Ah! Examples are here. Maybe add "Examples will follow later this section" to l15

l64 In your docker YAML configuration file; docker-compose.yml

l71 What does '>-' mean? Is this how it is implemented by the add-spark command too? In my configuration file the command-entry is one line: command: --name=spark-one --discovery=all --device-id=400058000551353432383931 I re-added it yesterday with the add-spark command

l80 You just told me in the 'Finding the device ID' section that the Spark has an IP and a port number. Don't I need to specify the port? Maybe add a remark. -Personally curious too-

l104 Knit picking: what means default in the two cases? With the add-spark command I assume --discovery=all is default, even if not specified explicitly. Am I obliged to specify the command in the YAML file if I write it myself?

l129 I could use some more context here. You just told me how to configure how the Spark service should find the Spark. I presume this section will be about the procedures how the Spark service actually achieves that once it is running

l131 what is the device serial and how is it different from the Device ID? I just read in l32 every Spark has an unique serial number that can be used as an ID. Aren't they the same then...?

l148 I know the protocol is called TCP/IP, but I only ever talk about an IP address... What is a TCP address?

l160 what does this stop mean? Questions:

• This means the procedure stops if the --discovery setting is not specified? Can we mark --discovery=all as default in the flow chart?
• what is the difference between this stop and the one in l167?
• what happens after a stop? 'If discovery fails, the service reboots' suggests a reboot. Curiously 'Ready to connect' of l177 suggests a successful finish of the chart, but points to a stop sign too... Success may be better

General remark: when does a branch of the flow chart get labeled 'no'?

• stop of l160 is NOT labeled
• stop l167 IS labeled
• stop l171 IS labeled
• 'no' branch of --device-id arg? l164 is not labeled but could use one in my opinion. Curiously it is not specified in the code either
• stop l179 is NOT labeled

l183 the --device-serial command is not formally introduced.

l184 How, where, why?

l186 What are these examples for? You already gave me examples... It reads like a first draft of examples that did not get deleted. Some of it belongs to the settings descriptions discussed previously, some of these are useful.

Later after reading the rest: Useful part starts from l207. Maybe delete the rest and label with ## Examples. Maybe add an example with the --device-serial because I still don't know how that works or why you want to use that as a selector.

l200 This you already told me...

l201 what does this mean? USB devices more specific? I understand they will be checked first, I can see that in the flow chart and I can think of some rationale of it being more reliable / stable and the better option for a connection if it is there

l203 "..all discovered devices are valid and connection is made with the first in the list."