Supplementary Module 2

Detailed Design Diagrams

Author: Geoffrey Messier
Schematics
Schematic Software Tools
A schematic is an essential part of any electrical detailed design document that involves
a new hardware design.
A schematic is a circuit drawing that shows how the components in your design are
connected.
Schematics can be created using a standard drawing program but theyre typically
done using some kind of computer aided design (CAD) tool.
These tools provide the following important functions:
They will provide a library of the huge number of electrical components that can
be used in your design.
They will perform some basic electrical rule checking to make sure your schematic
is connected correctly.
They will generate a layout of a printed circuit board for your design.
The package we will be using in ENEL 300 is called Eagle. We will only be using it
to draw schematics and not electrical checks or board generation. However, it will still
give you the feel of working with a real CAD schematic tool and the information is
certainly out there if you want to go further with it to create your own board.
The detailed design lab handout will point you to the tutorial material you need to
work through in order to use Eagle for your project.

Software Architecture Diagrams

How to Write Your Code
The software detailed design exercise involves translating your high level software diagrams into code and then documenting that code.

ENEL 300 Supplementary Module 2: Detailed Design Diagrams

c Geoffrey Messier, 2012

Page 1/5

 Lets start with writing the software first. First, recall the very simple state diagram
I drew in the last video module.
Youll remember that your Arduino code always consists of two functions:
setup(): Called once after power-up or reset.
loop(): Called over and over again.
This is where well put implementing our FSM.
A hint about coding style: Try to use functions as much as possible. Try to avoid
cluttering up setup() and loop() with a lot of lines of code that would be better put
in a function.
Driving

ObstacleDetected

Entry/start driving forward

Exit/stop driving
Do: look for obstacle

ObstacleGone

Waiting
Entry/start timer
Exit/stop timer
Do: look for obstacle
Do: check timer

TimerExpired

How to Write Your Code - setup()

For this class, you will be designing the code for a FSM. That means youll need to
define a global variable, called State, that contains your current state.
In your setup() function, you basically take care of everything you need to get ready
before your state diagram makes that first transition from the start point.
One job you must do is to intialize State to the state that you transition into from
the start point. You also need to execute any entry actions for that state.
setup(){
State = DRIVING;
StartDriving();
}
How to Write Your Code - Do Operations
The loop() function is where youre going to be doing most of your work. There is a
very specific way to map your state machine into your code.
Remember you have Do activites in some of your states. These are implemented by
starting the loop() function with a case statement where you have one case for each
of the states in your diagram.
Within each case, put a call to each of the functions that perform your Do command.
Note that weve added a state called TERMINATE to represent the state diagram exit
point. No actions are done while in this state.

ENEL 300 Supplementary Module 2: Detailed Design Diagrams

c Geoffrey Messier, 2012

Page 2/5

loop(){
switch(State){
case DRIVING:
ObstaclePresent = CheckForObstacle();
break;
case WAITING:
ObstaclePresent = CheckForObstacle();
TimerExpired = CheckTimer();
break;
case TERMINATE:
break;
}

How to Write Your Code - Entry/Exit Ops & State Transitions

Finally, you need to implement the code necessary to make the state transitions and
to perform entry/exit actions.
This is implemented with a second case statement in the loop() function that follows
the one used for the do commands.
Note that each case statement has the same flow:
Check to see if the transition conditions are satisfied. If so:
Perform the exit actions for the current state.
Change the state variable to the next state.
Perform the entry actions for the next state.
loop(){
// Do action case statement goes here.
switch(State){
case DRIVING:
if(ObstaclePresent){
StopDriving();
State = WAITING;
StartTimer();
}
break;
case WAITING:
if(ObstacleGone){
StopTimer();
State = DRIVING;
ENEL 300 Supplementary Module 2: Detailed Design Diagrams
c Geoffrey Messier, 2012

Page 3/5

StartDriving();
}
if(TimerExpired){
StopTimer();
State = TERMINATE;
}
break;
case TERMINATE:
break;
}
Tools for Describing Software
Once your code is complete, you need to provide documentation that will allow others
to use, modify and build on your software.
This documentation comes in a variety of sources:
Diagrams and tools for describing your software modules. The UML system that
we used for our state diagrams have a number of other systems for describing
software structure. These are quite focused on OO software design, though.
Automatic tools that parse the comments of the code itself to produce documentation. The doxygen system is an example of this.
Simply producing readable code. Good comments, variable names and function
names.
We will be using the final system in this class.
Readable Code
Follow these guidelines:
Use descriptive variable names.
Always give a variable a name that describes the data it stores or the function it
performs.
If you have an integer that is 0 if there is no obstacle or 1 if there is an obstacle,
call it ObstacleDetected instead of A or x1.
Note how this makes the code itself start to read more like a sentence: if(ObstacleDetected){
..} instead of if(A){..}
Use descriptive function names.
Always give a function a name that describes what it does.
If the function checks for an obstacle, call it CheckForObstacle() rather than
f1().
ENEL 300 Supplementary Module 2: Detailed Design Diagrams
c Geoffrey Messier, 2012

Page 4/5

 Use a mix of upper and lower case.

This is a simple rule but really makes your code more mature and easier to read.
So, instead of writing OBSTACLEDETECTED or obstacledetected, you would write
ObstacleDetected.
Dont be afraid of long names.
Youll notice that in many of my examples above, I use fairly long names (ie.
ObstacleDetected, CheckForObstacle()).
This is important to make your code readable. While it takes longer to type, this
extra time is saved many times over when someone else comes along to figure out
what your code does.
Dont comment things that are obvious from the code.
When I say comment your code, use comments to explain or outline things that
are not obvious from reading the code itself.
The following is an example of a wasted comment:
// Setting ObstacleDetected to 1
ObstacleDetected = 1;
At a minimum, comments should always be provided at the start of a function
declaration to explain what the function does. After that, its a judgement call.

ENEL 300 Supplementary Module 2: Detailed Design Diagrams

c Geoffrey Messier, 2012

Page 5/5