Design Workflow: Part II - Laying Sidewalk

In the second installment of this diagram-drawing, picture-viewing blog post, we will discuss behavioural diagrams. In contrast to structural diagrams, the behavioural variety models what the program does during runtime. In other words, the diagrams shown today will demonstrate how the program does what it is meant to do.

The first type of diagram is called an activity diagram. These show various processes in a flowchart-like format and are normally used when only one class or function is involved. They start with a large dot, which represents the beginning of the activity. It progresses by following the arrows through the diagram. Ellipses tell you what occurs at a certain stage. When some type of decision-making is required, a diamond with arrows pointing away from it is used. The arrows list the conditions that must be true in order to follow that path. Finally, the activity terminates at a dot similar to the starting one, but it has an extra ring around it. If you're still confused, you can check out Fig.1.

Fig.1 - An activity diagram outlining how the light is turned on

The diagram in Fig.1 shows what would occur in the TurnOn() method in the Light class. The state of the light is first checked and, if it is off, it is turned on. However, if the light is already on, the exit status is set to 1 and nothing else occurs. As stated by the comment box, this will be quite similar to the TurnOff() method as well as the respective functions in the Pump class.

Fig.2 is also an activity diagram, but it outlines how the Scheduler decides when to run tasks.

Fig.2 - An activity diagram explaining how the Scheduler will do tasks

The key to this function is that each task time is compared to the current time and the time when the function was last called. If the task time occurred between these two times, the task will be started. Although this method seems a little unorthodox, it is actually more stable than constantly pegging the CPU to check the time. You may think it would be easier to check every second and to run a task if the its scheduled time and the current time matches. However, my understanding of the sleep() function in C++ is that it is not all that accurate and, therefore, it may rest too long. One could imagine the detriment if the program delayed turning on the light for a whole day because of under-redundant coding.

If you read the comment box, you will see that this function cycles through a list of tasks. There is a little bit of a disclaimer here as the task times can not be grouped together, as in an array, because the object that each corresponds to must be preserved. Therefore, this part will consist of adjacent if statements rather than something like a for loop.


The next type of diagram is called a sequence diagram. These show processes that occur between multiple objects. Objects are created from classes and they are the parts that do the work of the program. A sequence diagram shows interactions in relation to time, from top to bottom. On the left side, there is the familiar Actor which has a long rectangle under it to show that it is active. To the right of the Actor, there are boxes that represent each of the objects involved. They have a line under them that shows when the object exist. It is aptly called a lifeline. Lines drawn horizontally from any of the aforementioned entities represent actions in the sequence. They are called messages. If this description still leaves something to be desired, you can take a look at Fig.3.

Fig.3 - A sequence diagram showing the automatic refreshment of the pH level

This diagram shows how the pH level is refreshed and documented in daemon mode. It starts with the Scheduler messaging the MyInterface object to do a health check. As mentioned by the comment box, other things are included in the health check, but we will simply look at the pH monitor for the sake of simplicity. MyInterface then messages MyWater, telling it to get the pH level. MyWater tells the pHCircuit instance to turn itself on and it returns h. This variable contains the pH value of the water. h continues to be passed up to MyInterface where it is given to MyReporter to add the new information in its log.


Fig. 4 shows what happens as soon as the program starts;

Fig.4 - A sequence diagram outlining what occurs on start-up

With this set-up, objects create the other objects; therefore, there is little need to manually create them. This simplifies the start-up greatly. The only object other than the Scheduler or the Commander that is created this way is the Reporter.

You might be wondering why  MyReporter is not created by MyInterface, which is the object that would use it. The reason is that the Reporter class requires a parameter (bool RunMode) in order to be created. This means that it would need to be given to MyScheduler and then to MyInterface, and finally to MyReporter in a cascading fashion. Because the parameter is not used in the former two objects, using this style does not make sense. If one extends this logic to the various Circuit classes, parameters would be handed-off four times without being used. Therefore, the constructor of Scheduler may look something like this:

Scheduler(HydrogardenInterface* MyInterface, Light* MyLight, Water* MyWater, Pump* MyPump, Reporter* MyReporter, Circuit* pH, Circuit* Nutrient, Circuit* Level, int pHIn, int pHOut, int NutrientIn, int NutrientOut, int LevelIn, int LevelOut, bool RunMode)

I think this goes without saying, but this function prototype is extremely long.

This is also why various members are assigned using external variables (they also make maintenance easier as the values are together rather than being scattered throughout the program).

 

That is all for the design workflow, meaning that next time we will actually be building the hydrogarden.

Design Workflow: Part I - Creating Abstracts

In the last blog post, I talked about how the design workflow should only require one blog post. After planning how I was going to write it, I discovered there was a lot of explanation to do. Therefore, I will be splitting it into two parts: one about the structural diagrams and one about the behavioural diagrams; today we will just worry about the structural ones.

By structural, I mean how the program for DotSlashGarden will be written. This being said, the design workflow is more about the software than the hardware.

In object-oriented programming (OOP), one thing that a programmer writes are the classes. These classes describe the parts of the program, or, as one might say, its structure. Classes are represented in UML using class diagrams (surprising, no?). These diagrams have the name at the top, the variables in the middle, and the functions in the bottom. The stuff in the middle, the member variables, describe the information about the class. The member functions describe what the class can do. They are called members because they belong to the class. After each member, there is a colon and a word which declares what type it is. A class diagram for the parts of the hydrogarden are shown in Fig.1.

Fig.1 - A class diagram for the HydrogardenObjects

You may notice a symbol prepended to each member. The (-) symbol means the member is private and only the class it belongs to can access it. The (#) symbol means it is protected and only its class or its friends can access it (seriously, friend is a keyword in C++). The (+) symbol is public, therefore anyone can access it.

Programmers restrict access to certain members because it makes the program more stable and less likely to do something weird. Besides, if a program did not have to abide by rules, we would get the singularity, which is a different conversation entirely. If you want to know more about restricting members, you can do so here.


If we focus our attention back to Fig.1, one may notice that the member functions fulfill the use cases established in the elaboration phase. There are a couple of things to note in this diagram:

• Lack of a webcam class and separation of the pump class

I determined that because the webcam will be using different software than the one I will be creating, there is no need to model it in this diagram.

As for the pump class, I decided that it was its own entity and things would be simpler if it became its own class.

• Arrows and lines with the circuit class

The three circuit classes at the bottom (CircuitpH, CircuitNutrient, and CircuitLevel) have an arrow pointing to the Circuit class because they are derived from it. Although each type of circuit is different, they have many things in common, such as they have input and output pins. The Circuit class, which is called the base class, contains these members. By deriving classes from the base class, I can reuse code because the information in the base class will be present in the derived classes. The Circuit class is called an abstract class because one would not be able to make an instance (or object, as it is called) because it is not actually a real thing. This is much like the fact that a colour, such as green, is not a thing, but you can have something that is the colour, such as a leaf. An abstract class is illustrated with italics.

There is also a dashed line with a corner-folded box. This is a comment box and it says that the pin of the various circuits will be declared as external, or global, variables. This is used to simplify the configuration of the objects made from these classes. The rationale behind this will became more clear in the next blog post.

• ExitStatus: bool

In the Pump and Light classes, there something in brackets with the name ExitStatus and is of type boolean. First of all, a boolean is a type of variable that is either true or false (1 or 0). This variable is used to tell the Reporter what to report. For example, if the Light.TurnOn(bool *ExitStatus) member is called, but the light is already on, ExitStatus would equal 1. When the Reporter sees this, it will recognize that an error has occurred and write about it in its log file. If the light was off, ExitStatus would be 0 and nothing major would happen. You can read more about exit status here.

The next diagram is also a class diagram, and it is about the HydrogardenInterface. You can see it in Fig.2.

Fig.2 - A class diagram for the HydrogardenInterface

This class uses a pattern called the façade pattern, which means that it acts like an interface for the HydrogardenObjects (just as an aside, after typing these long-winded, over-explaining names a few times, I realize I will need to change them later). If you look at its member functions, you will see that it contains all of the use-case-satisfying, member functions from what it manages. This means that, instead of using the various hydrogarden parts individually, other classes must use the HydrogardenInterface to change the hydrogarden's state.



The next diagram, still a class diagram, shows what the Scheduler and Commander classes will look like. They are shown in Fig.3 and Fig.4.

Fig.3 - A class diagram for the Scheduler

Both of the previously mentioned classes are responsible for enforcing the automation of this project. They are created based on what mode the program is running in, manual or daemon. Because of this, only one of them will be present at any given time.


Scheduler is used when the program is in daemon, or automatic, mode. Therefore, it understands when and how to turn things on and off. As said by the comment boxes, the times are assigned by the so-called external variables and Scheduler will retrieve the current time from an outside function.

Fig.3 - A class diagram for the Commander

Commander is much like Scheduler, except it does not fret about time, which is a feature I am sure all of us would want. Anyways, it provides a menu that the user can use to control the hydrogarden manually.






The last class diagram is of the Reporter, which is Fig.4. This class has functions that log the activities of DotSlashGarden. These functions outline predefined events that may occur during its operation. Although there is the chance that something may happen that was not allocated for, this would be a bug, which are difficult to predict except in their existence.

Fig.4 - A class diagram for the Reporter

The sole member variable of this class, RunMode, contains the mode of the program, manual or daemon. This information is used to determine whether to post notifications to stdin (standard input, which would probably be a console window) or the log file. Imagine if you were trying to use DotSlashGarden manually and, in order to see output from it, you had to look in a log file, and, in order to see future output, you needed to refresh it every so-often. This would be an absolute pain and, therefore, sending notifications to stdin would be easier. Simultaneously, if the program was running by itself, you would not want it to be outputting to the console, with no one ever to read it. This is why the RunMode variable exists.




The other type diagram that I drew for the structural diagrams is a deployment diagram. It shows what hardware will be used, the components of the hardware, and the interaction between the individual parts. This diagram is embodied in Fig.5.

Fig.5 - A deployment diagram for DotSlashGarden

The top half of the diagram shows the devices I decided upon in the inception phase as abstract nodes, except for the hydrogarden of course. The bottom half shows the actual devices that have more familiar names, such as laptop and Internet. Inside these nodes, there are other, smaller boxes; these are called components. The lines between components and devices show how the work gets done in DotSlashGarden. For example, if I wanted to access the hydrogarden through my laptop, I would use SSH and the Internet to connect with the Raspberry Pi. From there, I would start an instance of garden and that would allow me to control the hydrogarden.

Supposedly, pictures are worth a thousand words, but, with my pictures, a thousand words accompany them. In the next blog post, I will talk about behavioural diagrams, explain more diagrams, and reveal how the software works.

Construction Phase: A Pseudo-Staff Meeting

As you may remember from the inception phase, the construction phase was split into its 3 workflows. Therefore, this post will act as an overview of the entire phase and hopefully allow you to know what to expect in the coming weeks. In a large company, they would call this a staff meeting, but, seeing as I am the only one, that name is not really appropriate.

The entirety of the construction phase was planned to last 5 weeks. However, due to my early completion of the last two phases, I now have about 7 weeks. The time will be distributed like this:

• Design Workflow - 1 week
• Implementation Workflow - 5 weeks
• Testing Workflow - 1 week

I understand that these workflows are just names and they may mean nothing to you, so I shall explain them individually:

• Design Workflow

In this workflow, one does all the planning of the project. In my case, I will create all the UML diagrams I will need. Although some thought about programming will be done, no coding is written in this stage.

The cool part of this workflow is that, once completed, the implementation workflow is extremely simple because I only need to translate UML into C++ without any thought of the program's flow as it would have already been figured out.

As for blog posts, there should only be one, and it will display the various UML diagrams and provide explanations.

• Implementation Workflow

This is where the exciting stuff happens: the actual building! This includes writing the software and constructing the physical device. As this is the proverbial meat-and-potatoes of the project, there will be a lot of emphasis, and therefore, blog posts, on this workflow.

The posts will be split between the programming and the device. The programming should only have one post, but this may increase if I discover it is more difficult than first thought. The device posts will be split into the various systems (light system, water system, etc.) with one or two posts for each.

• Testing Workflow

If all goes well, this should only take a day. However, I am not naive enough to think it will work the first time. In fact, I am anticipating failure, therefore I allocated an entire week to fix unforeseen issues.

Unless things start to go really wrong, this workflow should only comprise of one post.

As I have been working on the design workflow since I finished the elaboration phase, it should be finished fairly soon. After that comes the actual building and, after that, the first trial run.

The Elaboration Phase: Recursive Ad Nauseam

The elaboration phase is the second phase of the Unified Process. Much like its name suggests, the ideas from the inception phase are elaborated upon during this phase. It encompasses the analysis and the design workflows, but, unlike in the inception phase, I will not be doing each workflow individually. Instead, I will be combining the two so the analysis will simply be supplemented by diagrams.

In this phase, The main idea is about use cases. Use cases are basically anything that a user can do with a program. For example, in a web browser, one can load web pages. Use cases are very general and they solidify the functionality of the project.

Use cases can be represented in UML as a use case diagram. The use cases for DotSlashGarden are shown in Fig.1.

Fig.1 - The use case diagram for DotSlashGarden.

Although these use cases are somewhat self-explanatory, there is a formal way to do them. However, this takes a lot of space, so I shall exclude it from this post. If you wish to see them, you may do so here. The only thing you may need to know about that document is, at the end of each use case, a type of notification is made announcing what occurred. This notification will become a log file that I can view in order to monitor the hydrogarden.



You probably noticed the stick figure with the name "Actor" below it. The actor represents what is interfacing with the program. Because the hydrogarden can be operated either by automatic or manual commands, the actor must represent both. Fig.2 is a visual depiction of this idea. This is perhaps a bit over-the-top, but I want to be crystal clear with my reasoning.

Fig.2 - A sequence diagram explaining Actor.

The idea of use cases is to satisfy all requirements made in the inception phase. In order to do this easily, the requirements and use cases must be given unique identifiers, which are shown below. Fig.3 matches the requirements with the use cases.

Fig.3 - A chart matching requirements with use cases.

REQ1: Turn on light
REQ2: Turn off light
REQ3: Monitor pH
REQ4: Monitor nutrients
REQ5: Monitor water level
REQ6: Aerate water
REQ7: Take photo

UC1: Check water level
UC2: Check pH level
UC3: Check nutrient level
UC4: Turn pump on
UC5: Turn pump off
UC6: Turn light on
UC7: Turn light off
UC8: Turn webcam on
UC9: Turn webcam off

As you can see, all requirements are matched with a use case, so we can now move on.

The last part of the elaboration phase is to create analysis classes. In object-oriented programming (OOP), classes are used to describe the various parts of the program. From these classes, one can propagate objects, which do the work of the program; however, this story is for another post. Analysis classes are the basic framework of the program and contain no code. They simply give a rough outline of the program, or, in this case, the program and the device.

Analysis classes are made with Class Responsibility Collaboration (CRC) cards. These cards consist of a class name, a description of its purpose, and lines showing how they work together. Fig.4 shows CRC cards in action.

Fig.4 - Analysis classes for DotSlashGarden

Note: When I mention the Mediator pattern, I of course mean the Façade pattern. Sorry about that.
 
In this diagram, one would see the typical classes one would expect, such as Light and Webcam, but there are also classes that are unfamiliar, such as the Mediator and Scheduler. These classes will be used to control the interactions in the program.

• Mediator - provides an interface for the physical hydrogarden parts. In other words, if you wanted to turn on the light, you would use the mediator to do that ( i.e. MyMediator.LightTurnOn() ) instead of accessing the light directly ( i.e. MyLight.TurnOn() would be protected ). This pattern decreases coupling and makes for uniform access.
• Scheduler - processes automated operations. This allows the hydrogarden to operate automatically
• Commander - processes manual commands. This allows the hydrogarden to handle user-defined, on-demand commands, which gives the user control.
• Reporter - creates notifications. The log file it creates can be used to see what the hydrogarden is doing.

That is all for the elaboration phase. In the next post, I will be starting the construction phase, where I actually start to build the hydrogarden.

Inception Phase: The Dream is Real

The inception phase is the first phase of the Unified Process and its goal is to gather ideas and organize them into a logical format. This phase includes the requirements and analysis workflows and perhaps even a little bit of the design workflow. What this means is that I will decide on what my hydrogarden will do, whether or not I can create it, how the project will be scheduled, and the amount of money I can spend. As for the design workflow, it consists of some pretty pictures.

Edit: Any text seen in italics is an addition from the second iteration.

Requirements

In this workflow, one lists the requirements, or the things one wants to do, as a noun/verb pair. This style includes an object, such as 'radio', and one or multiple actions, such as 'turn on' or 'increase volume'. The list for my hydrogarden is as follows:

• Light - Turn on, Turn off
• Water - Monitor level, Monitor pH, Monitor nutrients, Aerate
• Webcam - Take picture
• Thermometer - Measure temperature

 Each noun corresponds to a physical part of the hydrogarden and each verb is an action that can be done.

The next part is to determine the feasibility of each of the previously listed requirements. The only component I believe to not be feasible is the thermometer. With all of the others, I roughly understand how I can set them up, but, with the thermometer, I have no clue. Granted, I have not really looked into it, but I see little benefit by including one anyway as my hydrogarden should be in a suitable environment at all times.

Analysis

The first point of conversation in this workflow is scheduling. In my previous blog post, I said that I wanted to complete DotSlashGarden by the end of August, which gives me about 9 weeks. I have planned it like this:

• Inception Phase: 1 week
• Elaboration Phase: 1 week
• Construction Phase: 5 weeks
• Design Workflow: 1 week
• Implementation Workflow: 3 weeks
• Testing Workflow: 1 week
•  Transition Phase: 2 weeks

This outline is very rough and will likely change in the future. For example, I may complete the elaboration phase sometime this week. While this plan is not exactly what I intend on doing, but it should give me some motivation to get stuff done.

Now, I want to talk about budgeting. I have compiled a rough list of things that I think I will need in order to create the hydrogarden. However, I am not going to discuss it in depth because that is not the purpose of this phase. What is important is that the upper bound cost of this project will be about $400. It is worth repeating that what I calculated is the upper bound cost. I listed everything that I may need, even if it seemed redundant (for example, a Raspberry Pi and an Arduino board, even though I probably won't use both). If one looked at the commercially available hydrogardens, one would see I could pick one up for about $100. In my opinion, complete control and general awesomeness is worth at least a couple hundred dollars.

As for the structure of the hydrogarden, I have identified three main components: the Front End, the Independent Device, and the Hydrogarden Objects. If you don't want to do more reading, you can simply look at Fig.1 in the next section. It probably does a better job at explaining it.

• The Front End provides a means of manual control or monitoring. This component could be my laptop or, in the instance of the Raspberry Pi, a TV and keyboard. 

• The Independent Device would carry out manual or automated commands. This device could be a Raspberry Pi or an Arduino board.

• The last component, the Hydrogarden Objects, would be responsible for completing the requirements in the last section. It consists of three systems: the Light System, the Water System, and the External Monitoring System. What is included in these systems is fairly self-explanatory.

Design

The design workflow is used to outline how the project will look and function when it is built. Diagrams are used to express this work. I will be using the Unified Modelling Language (UML) to create these diagrams. A diagram showing the components of the hydrogarden and how they are related is shown in Fig.1 (I promised pictures, did I not?).

Fig.1 - The component configuration for the hydrogarden, which was modified during the second iteration.

 
This setup would create the type of communication seen in Fig.2.

Fig.2 - Input/Output movement in the hydrogarden.

The reason I enjoy the design workflow is that I get to make cool diagrams and they explain themselves.

Conclusion

I want to express a concern here. It is about the Raspberry Pi. I have talked about it a few times and I think it will be the best device to do what I want. Unfortunately, these small computers are hard to come by and it may be months before I get one. Nevertheless, I am on the waiting list.

You may also notice that I did not do any planning for the programming portion of this project. Or did I? Because I will be using object-oriented programming, any design I make for the physical hydrogarden can be used for the program that will run it.

Even though this is the end of the inception phase, I can always do it again, or start another iteration as it is called, if I would like. This would occur if I found that parts were missing from this phase. I have already completed the second iteration.

Although not the most interesting phase, it is certainly required to have a solid foundation. The next phase will be the elaboration phase, where I create use cases and go deeper into UML.