There are many cases where it is useful to monitor a system in real-time and trace the sequence of events. In this toolbox article we explain how to do code instrumentation and create a nice looking Sequence Diagram showing exactly the flow of events (trace) for a detailed analysis. For the graphics rendering we use Mscgen available here.The goal is to generate the following diagram more or less automatically. Figure 1: An example for a state flow we want to generate in this article (full picture).

To make things really practical we use the EnergiaBlink example available on GitHub. To follow the described steps yourself install Energia and one of the nice starter kits from TI. Here I use the EXP430F5969.

As first step it is necessary to instrument the state machine code. Luckily this is done automatically from the code-generator. The command line switch -Trace enables the generation of trace code. The following code snipped shows the result:

  switch (stateVars.stateVar) {
 
    case Slow:
      switch (stateVars.stateVarSlow) {
        case SlowLedOn:
          if(msg==evTimeout){
            /* Transition from SlowLedOn to SlowLedOff */
            evConsumed=1;
            /* OnEntry code of state SlowLedOff */
            digitalWrite(RED_LED, LOW);
 
            /* adjust state variables  */
            stateVarsCopy.stateVarSlow = SlowLedOff;
--->        StatemachineTraceEvent(0);    <----
          }else{
            /* Intentionally left blank */
          } /*end of event selection */
         break; /* end of case SlowLedOn  */

Figure 2: The generated state machine code with the trace method call.

The relevant line is the marked with the two arrows. Whenever this code executes the trace method is called. The content of this trace method can be freely defined. In our case we want to store the event for later usage. Figure 3 shows the required trace method. As you can see the event is already stored in the format needed later on from the Mscgen tool.

String event;
void StatemachineTraceEvent(int evt) {
  event = "[ ";
  event += "label = \"" ;
  event += myGeneratedSM.getNameByEvent((STATEMACHINE_EVENT_T)evt);
  event += " \" ]";
}

Figure 3: Trace code automatically called from the state machine each time an event gets processed.

The Mscgen tool expects a specific input format and requires some definitions like available states, diagram width and so forth at the begin. This is printed in the setup code once after reset.

Serial.println("__start__");
Serial.println("");
Serial.println("");
Serial.println("msc {\n\nhscale = \"2\";\n");
Serial.println(InnermostStates);
Serial.println("");
Serial.println("");

Figure 4: The initialise code executed once after reset to print the header of the Scmgen file

Then the code loops forever waiting for events to process (line 115). Whenever a transition is available we simply “ask” the state machine before it is executed what the current state is (line 127). Then the machine gets executed (line 131) and we ask again, what the current state is in the case the event was processed (line 134ff). In the case the event was not processed it is shown too in the diagram (line 140ff). See below the source code lines.

Figure 5: Manually written code generating the input for the Mscgen tool. This can be reused for each project again.

There are many possibilities to realize the PC side software. The most basic way is to use a simple terminal program and paste the received trace code in a file. Then the file can be converted into an image like shown here:

mscgen -T png -i sc.sc -o sc.png

Figure 6: Flow diagram generation using Mscgen.

Another more comfortable way is to automatically save the received trace text into a file whenever a magic pattern is received from the embedded system (i.e. after restart). The following code realises this as a showcase and was tested on OS-X but should also work on Linux. Full source code is available here.

With the help of the automatically generated trace code and a few lines of code it is possible to generate the required input for Mscgen. Mscgen then creates nice looking images showing the event flow in a very clearly arranged way. Hopefully this will help you to track down problems more easily in future.

Beside finding problems this is also a nice tool to document the behaviour of a system for defined sequences of events, specific test case etc.

Finally let me recommend the two following articles which provide interesting insights into model based testing of state machines and how SinelaboreRT can support you in this task.

• Model based testing of state machines part I
• Model based testing of state machines part II

Have fun! Peter