# Quick Start Part 1¶

Welcome to the CertSAFE Quick Start. This guide will introduce you to some of the concepts of the CertSAFE language and how to accomplish common tasks in the CertSAFE environment. Many useful topics will only be touched on briefly in this document, however links will be provided throughout to more detailed articles on these topics. You are encouraged to read through these more detailed articles if you want to know more about, or are having trouble understanding any of the topics covered.

As you follow along with this guide, you will build a CertSAFE project that describes a simple control system and allows you to simulate the system’s execution. You can download a completed version of this example project to help you follow along with the tutorial.

## The scenario¶

Suppose you receive requirements from a customer as part of a contract for developing a temperature display system. Your goal is to design the low-level details of the software for this system before implementing it. The requirements are the following:

Note

Temperature Display Requirements:

1. The Temperature Display shall have two temperature sensors, one outside sensor and one inside sensor, which read temperatures in Celsius as 32-bit floating point values.
2. The display shall sample the sensor data and update every 100 milliseconds.
3. The temperature °F shall be calculated from the temperature °C with the following equation: °F = °C × 9/5 + 32
4. For each sensor the display shall indicate Sensor Broken if the temperature is greater than 150°F or less than -150°F.

There are a few things to notice about these requirements. Requirement #2 tells you that this will be a discrete-time system that will run at 10 Hz. Requirement #1 defines the input value as being read in Celsius, but requirement #4 uses the value in Fahrenheit, with requirement #3 specifying the conversion. Since this is a discrete-time system with multiple interacting requirements, CertSAFE seems like a good fit.

## Creating a project¶

In CertSAFE a model is built by the software based on definitions created by the user. These definitions are all housed in a project. So in order to build the definitions necessary to model the system described in the requirements, we need to create a project.

When a new project is created, by default the project file includes the directory it is in as a base path. As a result, when the project is opened, CertSAFE will scan the files in its current directory and all of its subfolders recursively for CertSAFE files to include in the project. For this reason, when starting a new project it is often a good idea to create a new folder and place your project file in this new folder.

To create a new project select File ‣ New ‣ New Project... and set a name and location for your new project. For this tutorial, create a new folder called “Temperature Display”. Name the project “Temperature Display” as well.

In CertSAFE the frame rate is a project setting. According to requirement #2 above the frame rate is 10 Hz. So to model the system described correctly, you need to set this. To do this first find the Projects View; it is on the tab labeled Projects and is likely docked with the other views. If you cannot find it, you can use the View menu to make sure it is enabled or to Restore Default Layout.

Once you have found the Projects View, expand the Project Tree for your project, and at the bottom you will see Project Options. Double click this to open the Project options editor. In the editor, look for the box labeled “Project frame rate in frames per second (Hz):” enter the value 10 into it, and then save it by going to File ‣ Save.

Now that requirement #2 has been handled, a strategy for handling the rest of the system needs to be developed. There are multiple approaches to breaking down the problem of designing this system. One strategy that will work well for this case is a bottom-up approach, in which you model small pieces of the system and then combine them together as larger systems. Since requirement #3 doesn’t have any direct dependencies on other requirements, this requirement is a good place to start.

## Creating a diagram¶

In CertSAFE, most logic is expressed in Diagrams. Requirement #3 is a mathematical formula, so it is appropriate to express it using a diagram. To start creating a new diagram, click the New Diagram icon in the the toolbar. Now find the Properties View. Notice in the Properties View that when a diagram editor is focused and nothing inside the diagram editor is selected, there is a size property. This size property controls the available grid space in the diagram editor. If throughout this quick start guide you ever feel like you need more space to diagram the requirements, changing the value here to larger numbers will allow you to do that.

Requirement #3 states that we need to convert from Celsius to Fahrenheit using the formula “°F = °C × 9/5 + 32”. One of the first things to note about this is the requirement describes how to calculate the value °F from the value °C. In other words, we want our diagram to consume the value °C as an input and produce the value °F as an output. You can create inputs and outputs to a CertSAFE diagram by adding Exported Name components.

When creating Exported Names, CertSAFE makes using names from existing documents very easy. To create a new Exported Name component named “°C”, you can select the text °C in this tutorial document and drag it into the new diagram you created. You will get a new Exported Name component with the name °C. Do this again with the name °F. You do not need to explicitly label an Exported Name as an input or an output to the diagram, as CertSAFE can figure this out based upon what the Exported Name is connected to.

After creating an exported name for both °C and °F, your diagram should look like this:

Remember, requirement #1 says that °C is coming in as a 32-bit floating point number. So to fulfill that requirement you will need to edit the properties of the °C component. To do this, select the °C component by clicking on the “°C” text in the diagram. (Be careful not to click on the adjacent circle - this does something different, as we’ll see in a moment.) Then, go to Properties View. In the Properties View you will see a field called Data Type, whose value is listed as <infer>. Click on <infer> to get a drop down menu, and in that menu select Float32. That will set the data type of °C to a 32-bit floating point type. Once set, CertSAFE will be able to infer that logic connected to °C is also operating on 32-bit floating point numbers. This means that there is no need to specify the type on the °F component, since °F will be calculated using °C by the time this diagram is completed.

Now that you have created the input and output for the requirement, you need to determine what part of the equation next to model. If you read the equation from left to right, it seems the next step will be to add a multiplier to the diagram.

Find the Palette View. There you will notice that it lists numerous components, and those components are separated out into groups. Go to the group labeled Numeric and drag out the Multiplier (2 inputs) into your diagram.

Notice that the new Multiplier component has two red pins and an orange pin. In CertSAFE, a red pin or red wire network indicates an error that will prevent your diagram from working correctly. In this case, the error is that there is no producer for the Multiplier’s inputs. Meanwhile, the orange pin indicates a warning, namely that the Multiplier is producing a value that is not being consumed.

To fix these issues, you will need to connect the multiplier’s pins to other components. This is done by drawing wires in the diagram. To begin drawing wires, click on the top left pin of the multiplier. This will put CertSAFE into wire drawing mode. While wire drawing, you will notice that a black line is being extended from the multiplier component. This black line is only being drawn in one axis. Clicking once will draw a wire segment where the black line is, and, if you didn’t click on a pin or wire segment end, allow drawing a new wire segment which may be drawn along a different axis. To end wire drawing, either double click to draw a single wire segment, or bring the black line to a pin and single click to end wire drawing and connect that component to the wire network. You can also cancel wire drawing by right clicking.

Here, the requirement says that °C is going to be multiplied, so create a wire network connecting the multiplier with °C. Once done, your diagram should look like this:

If you look at the °C component, you will notice that it has changed from a circle to a diamond shape. When CertSAFE determines that an Exported Name is an input into a diagram, it changes the component’s symbol to a diamond to reflect that. Similarly, when CertSAFE determines that an Exported Name is an output from a diagram, it changes the component’s symbol to a square.

Looking over the requirement, °C is supposed to be multiplied by 9/5. So, going back to the Palette View you will need a divider. You will notice that there is a Floating Division component in the Numeric section of the palette. Drag the Floating Division component from the palette to your diagram, and then connect its right pin to the bottom left pin on the multiplier. It should look like this:

Now, you have the divider in the diagram, but you have not yet told it which numbers to divide. You want to divide the constant value 9 by the constant value 5. To do that, you will need to add a Literal component from the palette. Literal components allow you to write statically defined constant values into diagrams. CertSAFE has a single Literal component that can be used to write literals of numeric, Boolean, and enumeration data types. The Literal is located in the Special section of the palette. Drag a Literal from the palette into the diagram and connect it to the pin labeled x on the Floating Division component. Once connected, you will want to edit the literal’s value to be 9 by selecting the literal component and changing its Value property to 9. When you are done, your diagram should look like this:

Now, you could drag another Literal from the Palette View, but there is a faster way. If you select the Literal you have already created and drag it with the right mouse button, this will make a copy of the Literal. So create a second Literal by selecting the Literal and dragging it with the right mouse button. Once you have done this, change the Value property of the second literal to 5, and connect it to the pin labeled y on the Floating Division component. It should look like this:

Looking over the diagram, you will notice that the wire networks going into and out of the Floating Division component are now colored gray instead of black. CertSAFE colors a wire network gray when it is able to determine that the wire network will always have a constant value. As both the literals are constants, CertSAFE can color the wire networks that they are connected to as gray. As only constants are fed into the Floating Division component, it can color the wire network it is the producer for gray as well.

For the “+ 32” part of the requirement, we will need an Inline Adder component. The Inline Adder component adds or subtracts a constant value. It is in the Palette View in the Numeric section. Drag it in from the Palette View and connect its left pin to the right pin of the multiplier. As the requirement tells you to add 32, you will need to select the Inline Adder component and in the Properties View change its Value property to 32.

Once that is done, all that is left to do now is connect the °F component to the output of the Inline Adder. To do so, move the °F component to the right side of the diagram, and then draw a wire from it to the Inline Adder’s output. When you do this, you will notice two things: that its symbol changes to a square, and that its text will automatically rotate to the right. When you finish, your diagram should look like this:

Once finished, you can quickly remove any extra grid space from the diagram by going to the menu bar and clicking Resize Grid To Fit, or by using its hot key of Ctrl + Shift + G. Do so now.

Now save your diagram as “Temperature Conversion” by clicking the Save icon in the top toolbar and entering the name in the save dialog.

## Simulating the diagram¶

You have successfully diagrammed requirement #3, but before moving on to the other requirements, you may want to simulate the diagram first and verify that it does properly convert Celsius to Fahrenheit. To do so, think on a few values you could put into the conversion equation to quickly determine if the logic was properly diagrammed. You know that 0 degrees Celsius translates to 32 degrees Fahrenheit, you know that 100 degrees Celsius translates to 212 degrees Fahrenheit, and you know that -40 degrees Celsius translates to -40 degrees Fahrenheit. So, you can use those values to verify that you have diagrammed the logic properly.

First, set your diagram as root. Setting your diagram as root tells CertSAFE that the diagram is what you want to simulate. You do this by locating your diagram in the Projects View, right clicking on the name of your diagram, and selecting Set As Specified Root. Once your root has been specified, create a new simulation by clicking New Simulation in the toolbar.

When creating a simulation, you’ll notice that the Simulation Editor is broken up into 3 parts. There’s a large, empty white area to the right, known as the Simulation Timeline. To the upper left of the Simulation Timeline is the Variable Table. Beneath the Variable Table is the IntelliPoint Table.

Also note that your simulation has properties. These can be seen in the Properties View. These properties allow you to change how long the simulation is (in seconds or frames), and allow you to change the simulation’s root if necessary.

Looking over requirement #3, you know that you’ll want °F and °C to be in your simulation. To do this, open the Instance View. In it, you will see a tree that looks like this:

In the Instance View, click on the diagram icon at the root of the tree and drag it into the simulation timeline. You will see two colored, horizontal lines. These are known as waveforms and correspond to the variables you have dragged into the simulation. You can drag the waveforms up and down in the Simulation Timeline. Waveforms also have properties associated with them which can be changed in the Properties View. The Vertical Offset property controls the waveform’s location, while the Vertical Scale property adjusts how large the waveform is along the Y-Axis.

You will also notice a translucent blue vertical line that moves with your mouse whenever you move around on the simulation timeline. This is called the Time Cursor. You can lock the Time Cursor down to one point by double-clicking empty space in the Simulation Timeline. Once locked, the Time Cursor can be unlocked by right clicking on it.

Now that our Simulation has the °F and °C variables in it, we want to use the simulation to make sure that our logic had been properly diagrammed. To do that, we will need to add IntelliPoints to the °C waveform. IntelliPoints allow you to control the value of a variable, what time the value changes, and how that value changes over time. To add an IntelliPoint to a waveform, simply double click on a waveform. This will add a small square on the waveform, which represents the IntelliPoint. You can control an IntelliPoint by dragging it around the simulation with the mouse, or by directly editing its properties in the Properties View. Since you need exact values for your simulation, it will be best to modify the IntelliPoint’s properties.

Create a total of 3 IntelliPoints on the °C waveform. On the farthest left IntelliPoint you created, set its Value property to -40. You should see both the °C waveform and the °F waveform change in response to the change of the IntelliPoint’s value. Set the middle IntelliPoint’s Value property to 0, and set the right IntelliPoint’s Value to 100. When you finish, your simulation should look like this:

Move the Time Cursor to each IntelliPoint and verify that, when °C is -40, °F is -40; when °C is 0, °F is 32; and when °C 100, °F is 212. This can be done either by reading the values in the Variable Table or looking at the values as listed in the simulation timeline. Congratulations, you have shown that the logic you diagrammed matches the third requirement your customer has given you.

In the next tutorial you will further flesh out this model, and learn a little bit about stitches and how to use them to link multiple diagrams together.