Prototype Deployment Software Requirements

[TerryJC]

As agreed at the meeting this morning, (viewtopic.php?f=13&t=48#p525), here are the draft Requirements for the software currently being developed for the Prototype Deployment. Eventually, these Requirements will be incorporated into a formal Requirements Specification or into the overall Phased Requirements (viewtopic.php?f=4&t=49#p527). For the moment, the following should provide a good starting point.

Prototype Hardware Configuration
Reference should be made to the attached diagram, which shows what we installed during August and ran with the Resistance Probe connected to sumppi and (unsuccessfully so far), the float switch connected to buttspi.

During operation of the prototype system a continual circulation of the water in the in the Butts and Sump will be maintained by allowing a small quantity of water to flow (by gravity) from the Butts to the Sump.

Software Environment
The Raspbian version is Stretch.

Communications
Communications between sumppi and buttspi shall be via the Ethernet link.

Software Requirements for sumppi
For the current deployment, sumppi has only got one probe connected, a resistance probe based on conductivity. As the water covers various contacts at 100 mm intervals, a small current is detected and turned into a logic voltage. The probe contacts are Active-Low, so the input to the Interfacing Board is 0 V when the probe contact is covered and 5 V when it is dry.

The sumppi shall:

1. Monitor the level of the water in the sump frequently by reading the outputs of the Resistance Probe.
2. Write the results of the sump level measurements to a local file for future analysis and diagnostic purposes.
3. Establish communications between itself and buttspi by sending packets to it and listening for a response.
4. Interrogate buttspi frequently to monitor the level of water in the Butts.
5. Using the results obtained from the level measurements, operate the butts pump to maintain the level of the water in the sump between <Low Level> mm and <High Level> mm.
6. Suspend pumping of water to the Butts if the Float Switch is actuated, signalling that the Butts are full.

Notes:

1. <Low Level> mm and <High Level> mm will be determined during development, but are assumed to be between 300 mm and 700 mm initially.
2. If possible, a background pumping level should be maintained, so that under stable conditions the Butts Pump is enabled at regular intervals to keep the sump water level close to <High Level>, but without exceeding it. In other words the average rate of flow of water from the Sump to the Butts should equal the rate of flow from the Butts to the Sump. It is recognised that the flow into the sump will reduce as the level of water in the Butts decreases, so the final algorithm should take this into account.
3. When the Butts are full, then no more water will be pumped out of the sump, so the excess will be lost through the overflow into the soakaway.

Software Requirements for buttspi
For the current deployment, buttspi has only got one probe connected, a float switch. As the water reaches the top of the Butts a microswitch is made. The probe is Active-Low, so the input to the Interfacing Board is 0 V when the float switch is closed and 5 V when it is open.

The buttspi shall:

1. Monitor the state of the float switch frequently.
2. Write the results of the float switch state to a local file for future analysis and diagnostic purposes.
3. Establish communications between itself and sumppi by responding on the network to packets from it.
4. Send the current state of the float switch to sumppi when requested.

[hamishmb]

This is very clear, but there are problems with this at the moment, because it doesn't follow how the software already runs, and makes it more complicated; instead of having to be interrogated, buttspi broadcasts the data at a set time interval. Soon, the interval will be able to be changed by the software. This is beneficial because we don't put extra load on the Pis by querying.

Also, that's not really how connecting works, but it doesn't really matter.

Thanks for doing this Terry, but we hadn't decided that we needed to yet, and because of things like the above, it might slow us down because implementation details change over time as we figure out what's best: querying might turn out to be better, or it might be good as a fallback later. At the moment though, we don't know what works and what doesn't so putting it in a requirements document doesn't make much sense to me.

Hamish

[hamishmb]

^ The interval will be able to change based on a request from Sumppi

[hamishmb]

Oh, note also that I'll stick with 600 and 400 until we are sure that the other sensors are working; they weren't when I last checked properly.

[TerryJC]

OK, OK and OK.

Referring to your point about interrogation as opposed to broadcast, I didn't know how you had done it and made an assumption. Once all the comments are in, I'll update the spec and repost.

Referring to your point about the interval, I purposely didn't talk about that, because that is to do with your implementation; not the requirement. I made no attempt to say how you should achieve the requirement, only what you should achieve.

I think that we do need this now. The whole point of Requirements is to give all stakeholders a chance to say what they want and need. Comments are then collated and the implementation then follows the Requirements, rather than the other way round. This prevents comments like 'I didn't think it was going to do that' or 'I thought it was going to' when the system is completed. Far from slowing us down, having agreed requirements mean that everyone is on the same page and shooting at the same target. A lack of understanding of the requirements (or a lack of agreement of the requirements) has scuppered many projects over the years. The engineering industry isn't noted for wasting time (time is money), but successful engineering projects usually start off with agreed requirements that are adhered to. (As opposed to Government software projects which invariably fail because civil servants do not understand the Requirements and / or try to change them near the end when they realise what they are getting.)

We should do our best to get this right and with hindsight, we should have done this several months ago, since it is likely that what you thought you are doing may not be what Penri and I thought you are doing.

[hamishmb]

Okay then, sounds like a good idea. I'm working on the software now, but a bit later I'll amend the requirements document

[TerryJC]

You only need to make comments; I'll update the requirements.

[hamishmb]

Okay. Was I supposed to be doing design requirements? I can't remember.

Notes:

As above with the broadcast Comms instead of queries.
To connect, a socket is created (at both ends) and both ends will wait until there's a connection.

For design requirements I'm roughly outlining design and noting eg interface classes and similar, rather than implementation? Sorry, because I really seem to have a mental block with this!

Hamish

[TerryJC]

Okay. Was I supposed to be doing design requirements? I can't remember.

When we first discussed this; about 10 days or so ago, I suggested that I would write the software requirements and you would write the design documentation (note; not design requirements).

The idea of the requirements is, as mentioned in my original post, to detail what the stakeholders want the software to do.

The design documentation is written in response to the requirements and the idea is to:

1. Identify the programming language to be used and any tools required to complete development. (In this case the language has been pre-ordained in the System Design Spec, but you would normally list the IDE used and the compiler where relevant, etc.)
2. Describe the design philosophy behind the solution. (in this case your approach to the various elements of the requirements.
3. Specify what the component parts of the solution will be. (In this case this would be objects and functions that will make up your solution.)
4. Describe, at a high level, what each component does and detail any information needed to use the component. (In this case this would include the arguments to the object or function and the expected result.)

In old-school engineering, this document would be produced before any software was written, to give the team leaders a chance to comment on the approach etc. More modern 'agile' development systems tend to have the developers write the design documentation and the code in parallel, usually completing all of the work required to realise one particular component, before moving on to the next. When I say completing, I mean write the design, write the code, debug the code, unit test the code, integrate the code into previously completed parts and discuss the whole thing at a weekly meeting to effectively 'sign-off' the work done. I don't think we need that much oversight, but a nod to the approach could prevent all sorts of issues later.

I appreciate that the approach that you have taken so far has been to write the code and then think about documentation afterwards, but generations of projects that tried that either failed or learnt the lesson the hard way. The pit-falls are many and various, but include developers who can't remember what they did, or why they did the code in 'that' particular way. The end result is patchy or rushed documentaion, or none at all because the original developer has moved on.

Notes:

As above with the broadcast Comms instead of queries.
To connect, a socket is created (at both ends) and both ends will wait until there's a connection.

Here I was guilty of specifying how and not what, so I will rein that part back a bit, to simply say that communications shall be established between the (master) sumppi and the (remote) buttspi.

For design requirements I'm roughly outlining design and noting eg interface classes and similar, rather than implementation? Sorry, because I really seem to have a mental block with this!

See above.

[hamishmb]

Okay, fair enough, I can see you've seen this happen before, so thank you for helping

Before I get started on that, I will change variable and function names to obey Python's style guide, but that won't take long; I'll make a start on the requirements today.

I can't promise I'll get it right, but I'll certainly give it my best shot