User Manual/Documentation

[wiltdavi]

I hesitate in creating an item with this title because I know it can be taken the wrong way. This is at no way a negative on this project as I am amazed at everything that has gone into this to help keep these systems working.

I am wondering if there is some documentation or other site that I am missing that explains some items that I have questions about. There has been some mention in some issues about an existing or future blog. Am I missing something that I should be following that will help me with understanding some of the questions I have?

Here are some examples of questions I have that I have not been able to find the answer to when reviewing the information in this project.

1. I have seen reference in other issues to the config.yaml and in reviewing the code I see that it can be used to alias a system for easier identification but what I don't know is if it is required to add your devices to this file. If I don't add it will I not see the system when navigating to http://raspberrypi/?

2. I have been monitoring this project for a while but I only just started using it and I am finding that I don't know what to expect when working with this software. I only have 1 Zseries and a PicoStill and I am not really sure what I should expect to be able to see when navigating to http://raspberrypi/. For example, I have not run a brew session with the Z but I did run a session with the PicoStill. Am I supposed to be able to see something from the Z from this session or since it is not a brew session will I not see anything as I believe the PicoStill interaction is still under development?

I am not asking for my specific questions I have provided here to be answered but more in general if there is a gathering of this information that I am missing. If some central location for this information does not exist I would like to offer my support to create the User Manual/Documentation for this project. I can take the lead on this effort but I will need guidance from the main developers and assistance from people with other equipment to fill in the gaps for the resources I personally don't have. I appreciate everything that has gone into this project and would like to contribute to making it even better.

[tmack8001]

There has been some mention in some issues about an existing or future blog. Am I missing something that I should be following that will help me with understanding some of the questions I have?

Nope seems you are following the right things if you know a blog is coming out (once I get time to author and finish it... you may not know, but entertaining kids on vacation while working full time doesn't work well with "side projects").

I have seen reference in other issues to the config.yaml and in reviewing the code I see that it can be used to alias a system for easier identification but what I don't know is if it is required to add your devices to this file. If I don't add it will I not see the system when navigating to http://raspberrypi/?

Yup, you got it... The config file is simply for naming your devices, most if you only have 1 or 2 this is purely cosmetic and not needed at all. The other thing we are using the config.yaml for is to add various "optional" features like forcing a specific firmware or allowing new custom firmwares to be loaded to devices.

I only have 1 Zseries and a PicoStill and I am not really sure what I should expect to be able to see when navigating to http://raspberrypi/.

For any and all sessions the Z reports temperature values for the various sensors. Even when using picobrew.com you had these graphs in BrewHouse that is the same here as well...the raspberrypi essentially is "BrewHouse" (not to be confused with the addition features in "BrewCrafter" aka the recipe crafter). The Still doesn't communicate over the internet except to register and get firmware... So no T monitoring, but that said members of the community including myself are working on adding that functionality to get T monitoring on a graph you can monitor / babysit remotely.

If some central location for this information does not exist I would like to offer my support to create the User Manual/Documentation for this project. I can take the lead on this effort but I will need guidance from the main developers and assistance from people with other equipment to fill in the gaps for the resources I personally don't have. I appreciate everything that has gone into this project and would like to contribute to making it even better.

Thanks for being willing to take up some contributions here. There are likely a couple ways I see this working and mentioning below to get that conversation started:

1. we add a set of "support" screens and additional "help text" to the web interface so everything is a one stop shop. This would include bundling the product manuals in with the server under some "support" screen.

2. though no. 1 only works for those that have online servers that are up to date (probably a safe assumption this can happen) it would be good to have more general documentation and examples on a personal blog/forum/GitHub page (readme.md has some of these details you are mentioning, but is more developer focused than user focused... Users have had it hard enough to find GitHub's "assets" expand on the releases... So you know anything in GitHub to me is effectively lost and visible only to technically savvy users that have experience and exposure to GitHub already).

3. no. 1 and no. 2 (likely somewhere in the middle of these?)

A bunch of the random "how do I do manual brewing with Pico?" Shouldn't IMO be the purpose of this project, but rather just source or reference already gathered documentation from around. Facebook Group, FB Files section, other GitHub repositories, Picobrewers.org, etc.

Thanks again for your want to get involved. If more "realtime" is needed here feel free to hit me up on FB messenger, but GitHub issues works for me as well (there is some forum system in GH too, but I haven't used it or explored that yet myself).

[tmack8001]

Also feel free to check out the demo server, http://ec2-3-136-112-93.us-east-2.compute.amazonaws.com/, which has example machines configured through the config.yaml (see they are "waiting to brew" and are named and not just the random characters of the "product id"). If the devices were connected (via performing a brew session) and not in the config.yaml they would show up like this image just as the UID / Product ID.

Below shows an "active brew session"

Followed by an "inactive non aliased device"

[wiltdavi]

@tmack8001 trust me I completely understand the lack of time and priority of side projects while juggling everything else in life. I myself have that issue also so while I want to contribute to this project it may be delayed at time.

Thank you for the direct comment to some of my questions I asked here but continuing I will try and keep this to the general discussions about how to address documentation.

I agree that navigating GitHub to find the information is not the most intuitive options for what I assume will be the majority of the users for this project and therefore have help built into the app or some other more useful friendly location is probably the best solution for the majority of the documentation. Though, GitHub is the initial landing page so I think the Read.md should have the initial start setup information and link to or explain where to find additional information, for example the online server support screens.

With this in mind I am going to start a couple other items to gather the information I would like to include in the Read.md and then I will create a pull request with my suggested updates and we can go from there.

[tmack8001]

Sounds great @wiltdavi appreciate any and all help.

Given this project is specifically built to be multi platform (though majority of users will likely be going RaspberryPi route due to simplicity) we should keep that in mind with any documents added.

What definitely is needed is some screenshots of the experiences and features available with this with maybe a few platform specific instructions to expand what I ready added there.

[tmack8001]

@wiltdavi here is my quick take to make sure devices are eagerly "registered" upon receipt of the first request from the machine. #173

Obviously there are edge cases that don't work here... power cycles, etc could potentially disrupt this, but in most cases the device will force a reinitialization when that happens (like the Z) if a request fails while interacting with the system menus.