FIRMWARE & SOFTWARE PROCESSES & BEST PRACTICES —> Part 2: Software Architecture | Creating the Map

Introduction to Software Architecture

After you’ve described the landscape and destination, you can draw the map (aka software architecture). How do the features of the landscape fit together? Do they influence each other? How do you get from one location to another? Ideally, we reveal these answers in the software architecture.

Some developers think that it is cost-effective to skip the design phase and plunge straight into development. However, architecture that results from development on the fly often results in unnecessary or incompatible code. Writing unnecessary code increases the overall cost of the project and the deliverable (if there is one) seldom runs efficiently. Additionally, potentially higher refactoring costs can occur after release.

The SIGMADESIGN firmware/software development team follows Software Architecture Best Practices to create the architecture for a deliverable:

  • The specific diagrams needed in the design phase depend on the project and development.
  • This diagram approach can help to to kick-start the creation of more traditional design diagrams (for example, UML object models, sequence diagrams, or state machine diagrams).
  • Finally, we dissect the project requirements and begin to turn those client requests into actual software.

How We Create the Map

In this example, we use a hypothetical scenario of updating the software for the steering system of a space cruiser with an improved asteroid avoidance system that runs on Windows 10.

We are going to use the hypothetical example of updating the software for the steering system of a space cruiser with an improved asteroid avoidance system that runs on Windows 10. We start with a review of the customer requirements and specifications. For example, we might build a software-controlled test machine to validate a customer’s system. During the review of requirements and specifications, we might consider such things as optimization for 24/7 operation, and the type of operating system (OS) and user interface (UI) such as Windows 10. Additional considerations could include user inputs, functions while under test, and test conclusions (provision of a report/analysis of the test log).

The next step is to analyze the requirements and specifications. On design day 1, we identify the key phrases in the requirements. For example, it’s helpful to first determine whether or not the hardware platforms provide any flexibility, such as a requirement that the software must run in a Windows UI.

Now let’s take a deeper dive into the critical requirements…

This improved asteroid avoidance system implies closed-loop positional control, which means that, for each control time delta, we must ensure that the steering wheel is at a specified angular position. We are going to build a software-controlled test machine to validate this new steering system. There are six high-level testing requirements:

  • Wheel rotation must be automated.
  • User inputs must be available prior to testing.
  • High-speed logging under test must be possible.
  • The UI must be Windows 10.
  • The system must be optimized to operate 24/7.

If it is necessary for the system to run all day and night, a desktop environment for handling motion and logging is not ideal. A separate high-speed controller that runs independently of Windows is preferable for reliable, long duration motion. Executing a UI in Windows is quite common, but because of the second durability requirement, it is necessary for this system to exist on at least two hardware layers (including a PC).

It will be necessary for users to create a wheel position profile up to one minute in length that is repeatable. Profile creation is easy to complete in Windows, but continuous execution of such a profile is problematic. The resulting force must be measured. Pre-test inputs include a one minute rotation profile and the number of cycles in which the profile repeats. A relatively high logging rate while testing is not suitable for Windows, especially over long durations. While under test, we must log the wheel rotation, torque, and cycle count at 1 kHz. Post-test reporting can execute in Windows. Because the UI scope says to run in Windows, this creates an opportunity to develop an offline reporting tool. It must be possible to run a test report that analyzes the logged data.

Now that we have made an initial analysis of the requirements, we can turn to a whiteboard or launch a diagraming tool such as Visio. We will assume that main features become individual software module nodes. For example, the data logging requirement will be an independent, fully testable module or actor. For the purpose of architecture brainstorming, the software nodes can take any shape.

Rapid Diagramming

Rapid diagramming is a tool that we use to identify how the code must be developed in order to satisfy requirements. Remember that requirements are independent when they are defined. The architecture is what integrates these requirements. We like to use a whiteboard or a favorite rapid-diagraming tool to:

  • Sketch out firmware/software modules as nodes
  • Show arrows as messages that pass between modules.

This is the initial pass. We have a windows system to satisfy the UI requirement and non-Windows hardware for better reliability in control applications. The modular layout is intentionally a tree structure. The top-level parent modules are responsible for the lives of the child modules. Arrows represent the message pathways between the modules. These messages are typically requests (i.e. they ask another module to do something) or broadcasts, which are notifications to another module that something has occurred. To promote module re-use and minimize dependencies, we assume that messages only pass up or down the module tree.

For the hardware Controller OS, the top-level main parent module has a motion_control module. Motion control governs test execution. There is also a dedicated module that reads sensor data, and a logging module that saves data to file. On the Windows side, there is a profile_editor module that builds wheel rotation profiles and a module for post-test analysis reports.

This first diagram has at least a couple of potential issues:

First, the motioncontrol module will likely need the latest sensor data faster than it can be received if it follows the path through main. Second, this diagram does not include a communication mechanism between the Windows PC and the Controller OS.

On the second pass, we promoted motion_control to be the parent of reading_sensors. Likewise, the log module is now a child of motion_control to have access to the faster data. We created two new modules on the Windows side and two on the controller OS side. One set of modules passes messages from the Windows PC to the Controller OS, while the other handles Controller OS to Windows PC communication.

Now we have our software architecture. We addressed the requirements and the Windows 10 side and Controller OS side are integrated. It is possible to proceed with code development and testing.

What Typically Happens Now?

In a project for a real customer, with actual, more detailed requirements, we would likely begin to construct a sequence diagram. Among other things, a sequence diagram maps out the order of messages that flow to or from a given module after a user pushes the start button. After that, we may decide to build a state machine diagram in the top-level module of the controller. These diagrams help to determine exactly what kind of messages each module needs. The further creation of diagrams serves to complete the architecture and help make the development phase go more smoothly.


The defined requirements and specifications must be analyzed and diagrammed, which results in the architecture. The way tasks are often differentiated in firmware/software estimates and the ways in which we analyze requirements are all related to the approach that we take to designing an architecture. The integration of the requirements and specifications creates the road map that includes the starting point, the milestones along the journey, and the destination. The code development process can now start. We can write, review, and test code with confidence that we are on the right track and will not take costly detours or wind up on dead-end streets.

Return to the Introduction to Firmware and Software Best Practices

Read Part 1: Requirements of the Firmware & Software Best Practices