Software Design Documentation To-Do (March 2022 onwards)

[hamishmb]

I thought it would be good to start a new thread to track the progress of the design documents I'm going to be be creating for the software. These are all created with the aim of making future system maintenance easier, both for us and whoever may replace us. I do not have any particular timescale for completing these in mind.

Please note that the software needs to be updated and refactored first in order for this to not be immediately out of date - I will do that first.

This post will be continually updated with the current status and list.

• Make a glossary of terms used in the software (Not Started)
• Make some fairly basic, selective, class diagrams to show how the different classes in the system interact (Not Started).
• Make some fairly basic object diagrams to show how the software runs in some example configurations (Not Started).
• Extra (and up to date) flow diagrams to show how the different threads work in more detail (Not Started).
• Update the existing flow charts for individual pis' control logic (Not Started).
• Some process model diagrams to show how the different threads interact to get work done, on a high level (Not Started)
• Some deployment diagrams to show what software runs on which computer and how the different parts of the system interact at a high level (Not Started).

Current Status: Waiting for software changes before most tasks can be started.

Last updated 26 August 2022.

[hamishmb]

Note that this is currently waiting on other software development tasks to complete.

Terry,

Would you like to take on some of the work, for example updating the existing flow charts for the control logic? That's one of the tasks here that doesn't have to wait.

[TerryJC]

Can do

[TerryJC]

Would you like to take on some of the work, for example updating the existing flow charts for the control logic? That's one of the tasks here that doesn't have to wait.

Hamish,

Just to ensure we are talking about the same thing; are you referring to the flowcharts that appeared in Annexes C and D of the WMT River System Software Design Specification.

If so, I envisage that apart from updating the existing diagrams we would also need new ones for the Stage Butts and the Lady Hanham Butts, plus the Water Backup Logic.

[hamishmb]

Terry,

Yes, just checked and those are what I'm referring to, and yes we will also need new diagrams, but we may need to finish and test that code first, in case we have to change the design (at least for Patrick's code).

I think the new diagrams should just include the control logic, and ignore the rest of the setup and management. All of that stuff is common to all devices running the river system software, so it should go in a diagram by itself.

[TerryJC]

I think the new diagrams should just include the control logic, and ignore the rest of the setup and management. All of that stuff is common to all devices running the river system software, so it should go in a diagram by itself.

For completeness; I was thinking of doing a diagram for 'main', which shows the setup and management of the program flow. From there there would be cross-references to the various control diagrams.

When do you think it would be OK for me to get on with the others? I'm assuming that the current diagrams for SumpPi and Wendy ButtsPI are unlikely to change much, but what about the Stage ButtsPi? I thought that was basically working.

[hamishmb]

That sounds sensible.

Yes, that would be fine, but I wouldn't do the hanham pi, as we only have the temporary top up logic for that so far, and it isn't tested. I don't think the stage pi logic was tested or deployed either. It looks like it might be deployed, but stage pi doesn't seem to be online right now, so I can't log in to check. I think stage pi's logic may have been deployed while I was away from volunteering, does anyone remember?

EDIT: Missed the question. As for when, pretty soon, I just need to test the logic. You can do your sumppi and wendy pi diagrams whenever you like though, as you know exactly what your intentions were.

[TerryJC]

OK.

[hamishmb]

Note: I am actively committing changes to the code at the moment - make sure you have the latest version from the repo if you need to look at the code or its documentation.

I am also working on the documentation - cd to /docs and run make html to view the docs.

[TerryJC]

Okay.