SinelaboreRT - wiki:toolbox

What is Bela?

anonymous@undisclosed.example.com (Anonymous) — Mon, 17 Apr 2023 16:43:22 +0000

What is Bela?

Bela is an open-source embedded computing platform for creating responsive, real-time interactive systems with audio and sensors. It features ultra-low latency, high-resolution seneor sampling, a convenient and powerful browser-based IDE, and a fully open-source toolchain that includes support for both low-level languages like C/C++.

There is ready made hardware based on the Beagle single-board computers. The Bela software extends the functionality of the Beagle systems by integrating audio processing and sensor connectivity in a single, high-performamce package.

Bela comes with excellent online tutorials explaining how to use and program the system. Tutorial 13 introduces the concept of the finite state machine modelling a metronome and debouncing buttons.

It it really worth watching the tutorial video and doing the exercises.

Have fun with BELA!

Event-based vs polling

anonymous@undisclosed.example.com (Anonymous) — Sun, 21 Oct 2012 10:31:48 +0000

Event-based vs polling

When designing an embedded system an important design decision is how the system should work: event-based or polling based.

The type of the connected hardware can provide a first hint. Communication interfaces and many other hardware interfaces are nowadays mostly realized event based (e.g. a CAN network interface). If binary input/output channels are the dominating interface polling can be the better choice. In case of doubts better choose the event-based design. In both system types state-machines are the right tool to model state based behavior. In event-based systems also the state-machines should be modeled state-based. I.e. the machine waits for new events, possibly changes state, perform actions as a reaction to an event and then waits for the next event. If there is no event the state machine needs not to run. In polling-based systems the state machine is executed cyclically independent if it is necessary or not. The cycle time must be chosen in a way that no relevant signal change is missed. In the following section a simple example is presented first in an event-based and then as polling-based design. The task of the machine is similar to an AND function. If one input appears the other must appear within a certain time, otherwise a fault state is entered.

Event-based model

In this model transitions are triggered by events that are sent form outside to the machine. E.g. from an interrupt service routine detecting a change of the digital inputs. The do not loose events often a queue is used. Whenever the state machine runs it looks for new events in the queue, processes them and does not consume any CPU time if there are no events. If a RTOS is used the state-machine often runs in its own thread and blocks the thread execution until a new event arrives.

Generated source code looks like this (reduced to fit in here):

/*Events which can be sent to the state-machine  */
typedef enum
{
evAB=0U,
evB,
evA,
evNoInput,
evEnable,
evTimeout,
evDisable,
_NO_MSG
} A_EVENT_T;
 
void  event_example(A_EVENT_T msg){
  switch (stateVar) {
    case Idle:
      if(msg==evEnable){
        setReady(1);
        stateVar = Init;
      }else{
        /* Intentionally left blank */
     } 
   break;
 
   case Init:
     if(msg==evA){
       startTimer();
       stateVar = WaitB;
     }else if(msg==evAB){
       setOut(1);
       timerStop();
       stateVar = AandB;
     }
    ...
   break;
 
   case WaitA:
     if(msg==evNoInput){
       setReady(1);
       stateVar = Init;
     }else if(msg==evTimeout){
       stateVar = Error;
     }
   ...
}

Polling-based model

In this model transitions are triggered by boolean conditions. The state machine has to run cyclically. This type of state machine is often found in systems based on a big main loop. The cycle time of the main loop must be fast enough to ensure that no condition changes are lost e.g. input inA going from low to hight and low again.

Generated source code looks like this (reduced to fit in here):

void  polling_example(void){
 
  /* action code */
  inA = getA();
  inB = getB();
  enable = getEnable();
 
  switch (stateVar) {
    case Idle:
      if(enable){
        setReady(1);
        stateVar = Init;
      }else{
         /* Intentionally left blank */
      } 
    break;
 
  case Init:
    if(inA && !inB){
      timerStart();
      stateVar = WaitB;   
     }else if(inA && inB){
       setOut(1);
       timerStop;
       stateVar = AandB;
     }
   ...
  break;
 
  case WaitA:
   /* action code  */
   timout = isTimeout(); 
 
   if(!inB){
     setReady(1);
     stateVar = Init;
   }if(timeout){
     stateVar = Error;
   }
...
 
}

The SinelaboreRT code generator can generate both machine types for you. As you can see the overall structure looks very similar but the two run-time models - event-based vs. polling are very different.

Be aware of the different run-time models during architecture design and make a conscious decision! In case of doubts better choose the event-based model.

If you have any feedback or suggestions for improvement please send me an email.

Features for High-Availability and Safety Systems

anonymous@undisclosed.example.com (Anonymous) — Tue, 10 Nov 2020 21:12:45 +0000

Features for High-Availability and Safety Systems

For high availability applications it is desirable to detect serious errors happening outside the state machine code but effecting the correct execution of the state machine. Such errors might come from a runaway pointer overwriting key variables, power brownout corrupting a bit or a bad ram cell losing a bit to name a few. To detect and handle such situations is an overall system design task. But the code generator can help you to detect inconsistencies of the state machine offering the following two mechanisms:

Undefined State Error Handler

You can provide error handler code that is executed in the default path of the switch/case statements. This helps to detect undefined values of the state variables. See configuration key UnknownStateHandler. Example:

switch (instanceVar−>stateVar) { 
  case S1:
    ...
  case S2:
    ...
  default:
    error_handler(); // your error handler
    break; 
}

Validate State Transitions

The code generator optionally generates a validate function that checks if a transition from a present state to a new target state is allowed (i.e. modeled in the state diagram). To enable the generation of the validate function set parameter ValidationCall=yes in the configuration file. This validate function has to be called from a user provided handler that is automatically called from the generated state machine code. This indirection allows you to define the reaction in the case a transition is not allowed. The validation code is automatically generated for you. In a single CPU setup the validation function runs on the same controller that executes the state machine code. But it is also possible to execute the validate function on a second CPU in a redundant CPU setup.

Example state machine:

case S22:
  if(msg==(TESTCASE EVENT T)ev32){
     /∗ Transition from S22 to S21 ∗/ 
     testcaseValidationHandler(S22, S21, instanceVar−>inst id); 
     evConsumed=1U;
     /∗ OnExit code of state S22 ∗/
     ...

Example for an user defined handler:

// your own handler begins here
void testcaseValidationHandler(uint16_t from, uint16 t to, uint8_t machineId){
  uint8_t testcaseValidate(from, to); // checks if this transitions is allowed
  if (retCode!=0U){
    // transition not allowed
    reboot(); // or whatever is best in your system
  }else{
    printf ("Transition␣allowed\n");
    return;
  }
}

Generated validation code for some example machine:

#define SIZE_TRANSITION_TABLE (31U)
#define TRANSITION(from,to)  (uint16_t)((from * 127) + to)
 
/* Hash table of valid transitions */
static const uint16_t valid_transitions[] = {
  16249U , /* S1->S3 */
  10880U , /* S111->S111 */
  9728U , /* S11->S11 */
  10489U , /* S132->S131 */
  15360U , /* S3->S3 */
  9754U , /* S11->S12 */
  13030U , /* S12->S11 */
  13056U , /* S12->S12 */
  6680U , /* S13->S11 */
  9704U , /* S11->S13 */
  16181U , /* S1->S13 */
  10892U , /* S111->S112 */
  15292U , /* S3->S13 */
  12404U , /* S112->S111 */
  6724U , /* S13->S3 */
  5745U , /* S22->S21 */
  6731U , /* S13->S1 */
  3855U , /* S21->S22 */
  1009U , /* S4->S3 */
  15247U , /* S3->S4 */
  914U , /* S4->FINAL0 */
  1016U , /* S4->S1 */
  896U , /* S4->S4 */
  5461U , /* S2->S1 */
  16159U , /* S1->S21 */
  9694U , /* S11->S2 */
  9682U , /* S11->S21 */
  9779U , /* S11->S1 */
  16205U , /* S1->S11 */
  16256U , /* S1->S1 */
  16171U , /* S1->S2 */
};
 
uint8_t testcaseValidate(uint16_t from, uint16_t to){
 
  uint16_t hash = TRANSITION(from,to);
  uint16_t x;
 
  for(x = 0U; x < SIZE_TRANSITION_TABLE; x ++)
  {
    if(valid_transitions[x] == hash)
    {
      return 0U;
    }
  }
  /* return an error */
  return 1U;
}

The validate code uses some predefined types. Define them in a header that fits your system needs and include it by setting the parameter AdditionalValidateIncludes in the configuration file.

Generate State/Event Definitions with Hamming Distance

It is possible to generate the states and events in an ascending order but using a user defined hamming distance between them. So in case one or more bits swap accidentally the state machine will end up in the default path which can then call an error handler. See parameters UseHammingCodesForEvents, UseHammingCodesForStates and HammingDistance.

Example:

UseHammingCodesForEvents=yes UseHammingCodesForStates=yes HammingDistance=3

/*Events which can be sent to the state-machine  */
typedef enum
{
  evInnerS3=0U,
  ev3434=7U,
  ev111=25U,
  evInnerS111=30U,
  evBH=42U,
  evBG=45U,
  evBF=51U,
  ...
  TESTCASE_NO_MSG = 461U
} TESTCASE_EVENT_T;

In case of any questions and suggested send us a mail.

Model-based testing of state machines

anonymous@undisclosed.example.com (Anonymous) — Mon, 01 Nov 2021 13:51:20 +0000

Model-based testing of state machines

This article explains how sinelaboreRT helps you to test your state based software.

In 2000 Martin Gomez wrote on embedded.com: “The beauty of coding even simple algorithms as state machines is that the test plan almost writes itself. All you have to do is to go through every state transition. I usually do it with a highlighter in hand, crossing off the arrows on the state transition diagram as they successfully pass their tests. This is a good reason to avoid “hidden states”-they're more likely to escape testing than explicit states. Until you can use the “real” hardware to induce state changes, either do it with a source-level debugger, or build an “input poker” utility that lets you write the values of the inputs into your application.” In many teams this is still common practice.

On a more general view state machine testing covers the following steps: (1) building a (test) model, (2) generating test cases (3) generating expected outputs, (4) running the tests, (5) comparing actual outputs with expected outputs, and (6) deciding on further actions (e.g. whether to modify the model, generate more tests, or stop testing).

Model based testing usually means that the test cases and other required data (e.g. test stimuli or expected test results) are derived automatically from the state machine model. And often also the automated test execution and validation is associated with model based testing. Probably only few organizations have implemented a fully automated test system covering all these steps. Especially for smaller teams the required investment for tools etc. is out of budget.

This article explains the features of sinelaboreRT that are relevant for (model based) testing. We use I) the Equivalent PCLopen function block and II) the microwave oven from the manual throughout this article. Both examples are available for download and allows you to follow all steps in. As we use the same model to generate code and testcases from step one is already done.

Generating test cases

Defining testcases is the 2nd important step that usually consumes a lot of time if it must be done manually. The code generator can save you a lot of time by auto-matically suggesting test routes through a given state machine.

The used algorithm ensures that all transitions are taken at least once (100% transition coverage that also means 100% state coverage). So it is not anymore necessary to go through the diagram with a highlighter in hand. The following figure 1 shows the coverage information from the equivalent machine. The command line option '-c' switches on the coverage data generation. The following command generates code and test routes from a Magic Draw model.

java -jar codegen.jar -v -c -p md -o equivalent -t "Model:Equivalent" equivalent.xml

The output looks the following:

Figure 1: Coverage output generated from the code generator for the Safety Function Block state machine. The colored lines were added to better indicate the different routes.

You can see that the first test route starts from the initial state in line 0 and ends at line 9 where no untaken transitions are left to go (take a look in the state diagram below and follow the red arrows). The output moves to the right at every new transition on the route. Sometimes not all outgoing transitions of a state can be tested. In this case a branch in the test route is necessary. Take «WaitChannelB» as an example. As you can see not all transitions starting from WaitChannelB could be tested in one route. Two further branches are necessary. They are shown in line 21 and 23 (follow the yellow line) in figure 1. Branches are indicated by the same indentation level. Other branches in our example are marked with the red, green and blue lines.

SinelaboreRT can also generate an Excel sheet with all the test routes. More about this feature follows below.

Figure 2: State machine with test path from step 0 to 8 as suggested from the coverage algorithm shown in figure 1.

Expected outputs

To assess the test results the expected behavior must be defined. SinelaboreRT can not determine output values from the transitions or guards. It is your responsibility to define the output variables of the state machine (either hardware or software). But if you embed the expected output values in the state machine the code generator can extract it for you automatically.

To be able to extract the outputs you have to define it as so called state constraints. The UML does not directly support this so you have to define a comment and attach it to a state. In the comment use the ‘Constraints:’ key-word to start the constraints section. The format of the specification is up to you. An example for the ‘SafetyOutputState’ is shown in the following figure 3. In this case it is stated that the error output must be zero whereas the normal output must be one.

Figure 3: Use a comment to specify a constraint per state.

Beside the console output from above - which provides a quick overview about the test effort - an Excel file can be created. It contains one route per sheet. Each line in a sheet is a single test step on the test route starting from the init state. There are as many sheets as routes are necessary to achieve the 100% transition coverage. A sheet lists the present state and the trigger to reach the next state. In addition the constraints of the source and the target states are listed. The constraint information is taken from the state diagram if specified (see figure 3 above). The following figure 4 shows the sheet for the state diagram from figure 2.

Figure 4: Excel sheets with the test routes for the equivalent state machine.  Each line contains a test step. If constraint data is provided in the state diagram  (test oracle) it is added too. A tester can use this data as input for the test plan.

Running tests

Test-beds are usually very hardware dependent in the embedded world. Therefore sinelaboreRT can’t generate a test-bed and the test case code for you. Using a unit test toolkit as described in [2] can be of great help here. To check that the machine is in the correct state you can instruct SinelaboreRT to generate trace code. Within the trace function you can send the trace data to a monitoring PC or store it e.g. for later analysis. This feature of SinelaboreRT is discussed in more detail in the second part of this article.

Comparing actual outputs and deciding on further actions

Comparison of the actual outputs with expected outputs, and the decision on further actions (e.g. whether to modify the model, generate more tests, or stop testing) is a manual step. SinelaboreRT does not directly support this work.

Summary

This part 1 of a 2 parts (-> 2nd part) article has discussed how to test your state machine model and how the SinelaboreRT code-generator does support you in creating test routes to reach 100% transition coverage. Part II of this article shows how SinelaboreRT helps trace the test execution and to visualize the actual status of your state machine and the actually reach coverage. If you want to read more about MBT look here.

Your feedback is very welcome!

Model-based testing of state machines - part II

anonymous@undisclosed.example.com (Anonymous) — Sun, 21 Oct 2012 18:39:23 +0000

Model-based testing of state machines - part II

This article explains how sinelaboreRT helps you to test your state based software.

In the first part of this article we have seen how SinelaboreRT helps you to generate test cases to reach 100% transition coverage. But sinelaboreRT can do more. You can connect your running target with an automatically generated visualization, show the present state of the state machine, show possible triggers etc. - all visually. And finally it shows the actually reached transition coverage.

This article uses the microwave oven from the manual as example. Code is available in the examples folder of the code generator.

Enabling tracing

The first step is to close the link between the state machine running on the target with the sinelaboreRT visualization running on the PC. In this article we assume that the state machine was created with the built-in editor. If you have used another UML tool used just convert your model file into the sinelaboreRT internal format by using -l ssc as output format on the command line. The following example shows how to convert a cadifra model into the internal scc representation:

java -jar codegen.jar -p CADIFRA -l ssc -o oven.xml oven.cdd

To generate trace code use the -Trace command line switch. An example is shown as follows:

java -jar codegen.jar -c -Trace -p ssc -l cx -o oven oven.xml

The trace function itself has to be provided by yourself because it is typically very system dependent. Within the trace function trace data can be sent to the monitoring PC. As the trace function is in your hand you can use whatever hardware interface is feasible to send the trace events. In most cases it might be a kind of serial uart interface. If you have a target with TCP/IP capabilities the use of UDP is recommended. The following code shows the trace function we use in this example.

void ovenTraceEvent(int evt){
    if (sendto(s,ovenTraceEvents[evt],
            strlen(ovenTraceEvents[evt]), 0,(const struct sockaddr *)&si_other,slen)==-1){
        perror("sendto\n");
        exit(1);
    }
}

Display the state diagram

To actually display the state diagram call the code generator with the -S command line switch. The window as shown in figure 1 pops up. The status of the state machine in its initial state is displayed.

java -jar codegen.jar -S -p ssc -o oven oven.xml

Figure 1: The example here is the microwave oven state machine used in the manual. It is available in the examples folders of the SinelaboreRT download.

he main window shows the automatically generated state diagram. Events that can be handled at that moment are shown in blue. They are also listed in left tree view. The output field on the bottom of the window shows the so far executed action code.

You can now send events to the machine by clicking on an event in the tree view. The display is updated accordingly and shows the new status.

But as we want to trace the real machine we need the connection between the target and the visualization. Therefore the code generator is able to receive events via UPD. This is what was shown in the code snipped above. Most embedded systems will not offer an Ethernet connection directly. In this case send the trace data e.g. via a serial interface to the PC and forward them from there via UDP to the visualization. This can be done in a view lines of code. This has been realized in the Asuro Mobile Robot example.

Testing at work

Now we have prepared the visualization. So let’s start the microwave oven example. To make it simple for you to follow this example the microwave oven code was compiled as a simple console program. This program allows you to set the cooking time, cooking power and to open and close the door via keyboard commands. When a cooking time was set and the door is closed the cooking starts. The console application prints out some debug messages e.g. how much cooking time is left. When the time is zero the microwave generator is switched off and the door must be opened before the next cooking cycle can start. The following figure shows just this situation. Cooking has ended. The actual state is “Completed”. As you can see only a transition coverage of 57% was reached during this test run.

Figure 2: While testing available transitions are displayed in blue and the active states in red. The presently achieved transition coverage is shown as progress bar below the event list.

The transitions not yet taken can be displayed as tooltip of the progress bar. As you can see we have not yet changed the cooking power nor have we opened the door while cooking.

With this information at hand it is easy to add the missing transitions to the test script to reach the 100% transition coverage. Be aware that 100% transition coverage also means 100% state coverage!

So far we have interactively tested the device i.e. the console application in our case. To avoid this manual interaction (which is really annoying for large machines) it is highly recommended to create a test environment that can be fed with the test routes generated from the code generator (see first part of this article series). This pays back quickly if extensions or bug fixes are necessary and regression tests must be performed.

Testing not modeled behavior

Even with 100% transition coverage you have only tested what was modeled. Often transitions that do not lead to a state change are omitted during the initial design. But from a testing point of view it is highly recommended to model such transitions too. Then the test route automatically include steps that check if the machine reacts correctly to transitions that do not change state!

Of course also perform boundary tests of used variables. For the microwave oven machine check for example what happens if the cooking time is zero and you still decrement it, or if it has reached its maximum and you still increment it etc. See the two recommended books listed in the first part of the article for many more practical hints.

Summary

We close this article with citing again Martin Gomez who wrote “ … require a fair amount of patience and coffee, because even a mid-size state machine can have 100 different transitions. However, the number of transitions is an excellent measure of the system's complexity. The complexity is driven by the user's requirements: the state machine makes it blindingly obvious how much you have to test. With a less-organized approach, the amount of testing required might be equally large-you just won't know it.”

This article has shown how sinelaboreRT helps you in testing your state based software. Therefore the different steps of testing were presented and how the sinelaboreRT code-generator supports you during the different test steps was discussed in detail.

We hope you enjoyed these two articles. Your feedback is very welcome!

Regions or no regions

anonymous@undisclosed.example.com (Anonymous) — Sun, 18 Apr 2021 15:55:55 +0000

Regions or no regions

For some systems you want to model certain parts which run independently from each other but react on the same set of events. These independent parts can be modelled using regions in UML state diagrams. Another term often used are orthogonal states or AND states (model is in state A and state B at the same time).

Let's take a microwave oven as an example. The model above is designed around the states that can be perceived from the outside (i.e. the user). Either the oven is on or off or paused. All other elements in the oven (lamp, timer …) are handled in these states and the transitions between them.

Benefits:

compact diagram
Eventually easier to understand for an outsider (e.g. customer) not knowing or interested in the internal organisation of the device.

Drawbacks:

the individual parts of the system are not represented and separated clearly

Model with regions

Introducing regions separates the parallel running parts of a system in an own region of the model. A region has a name and should focus on one part of the system. A state can contain two or more regions which are executed in parallel. Each region receives the same events that are sent to the containing state. Entering a state with regions enters all regions at the same time. Leaving a state with regions leaves all regions at the same time.

Benefits:

Clear separation of parallel running parts of the system
Reuse is simpler because different parts of the system are not mixed with each other.

Drawbacks:

Slightly bigger model and more states to model

Conclusions

Both models creates the same output. So it is not about right or wrong but more what is more appropriate for the current case. If reuse is a design goal regions can have a benefit. If a most compact design is a design goal regions have a slight drawback.

Send us a mail in case you want receive the model and test bench to get an own impression.

~~DISCUSSION|Leave your comments~~

[Learning]

Time Events in State Machines

anonymous@undisclosed.example.com (Anonymous) — Sun, 12 Mar 2023 17:14:14 +0000

Time Events in State Machines

In almost every embedded application, time-controlled activities are required. Examples of this are activities that are to run in a fixed cycle, or activities that are to be triggered in the event of a timeout, or also to implement certain signal patterns.

In UML state machines, a time event specifies an instance in time that triggers a transition to be taken when the specified time has elapsed. E.g. move from a state S1 to a state S2 after 1 second.

Time events might be relative and be used in the context of a trigger and the starting point is the time at which the trigger becomes active. A relative time trigger is specified with the keyword after followed by an expression that evaluates to a time value, such as “after (5 seconds).”

Alternatively an absolute time trigger is specified with the keyword at followed by an expression that evaluates to a time value, such as “Oct. 1, 2023, 12:00:00.”

While this looks very clear at first sight, it is not sufficient for code generation.

The first major problem is that there is no standard way to specify a timer ID or timer name for the timeout event. However, this is required in practice to associate the timeout with an underlying timer service. In embedded systems, it is not practical to create a new timer from scratch every time an “after” or “at” trigger is encountered. Quite the opposite - you just want to create a timer and reuse it in multiple places in a diagram. Of course, you could specify a name or ID in a linked UML comment or similar, but that's not really a nice solution.

The other big problem is that not all UML tools allow the specification of time events.

Finally, the code generator should not introduce any restrictions or constraints on the system's time services. However, a meaningful use of time events would require the code generator to specify how the time services are to be implemented. And that would certainly not always meet your needs and would only force unnecessary restrictions.

So what is the proposed solution for implementing time events with the Sinelabore//RT// code generator?

Two aspects must be considered when using timed transitions.

All different ways of realizing timers in embedded systems must be possible, and no restrictions should be introduced by using the code generator.
All relevant information should be contained in the state diagram itself

The recommended way is not to use the time event specification of the UML tools, but to use regular signal events. Timers can be “manually”, created started or stopped in any action code. If static system initialization is required, timers can also be created at system startup. The underlying timer service of your choice (see below) simply sends the provided timeout events to the state machine input queue. To indicate in the diagram that an event is a timer, it is recommended to use a naming convention and start the name of the timeout event with, for example, evTout.

In the following figure a state machine uses two independent timers. One creates looping between S11 and S12 and is created as cyclic timer. The other second timeout stops this looping after some time (one shot timer) and stops timer1 at the transition to S2.

RTOS based Designs

Each RTOS offers the possibility to define software timers. If a timeout occurs, a user-defined timeout function is called. In this function, the timeout event is then placed in the state machine event queue. Examples can be found here, here or here for various real-time operating systems.

Mainloop Designs

In mainloop/foreground background designs, you need to provide some sort of timer service. Often there is a hardware timer that supplies the system tick. Within the system tick, a software timer service can be implemented. This software timer service checks each tick to see if a timeout has occurred, and then places the corresponding timeout event in the state machine's event queue. An example of such a system is available here. And an example of a simple timer service that can be invoked by a timer irq can be found at github.

Conclusions

The use of timed transitions can be realized with signal events in a very flexible way for any kind of system architecture. All relevant information is available and represented in the state diagram so that 100% of the state machine code can be generated without requiring hidden specifications and introducing constraints on the design of your system.

Using Mscgen for nice looking State Flow Diagrams - Trace the flow of Events

anonymous@undisclosed.example.com (Anonymous) — Sat, 13 Nov 2021 13:33:48 +0000

Using Mscgen for nice looking State Flow Diagrams - Trace the flow of Events

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.

Step 1: Instrumenting your code

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.

Step 2: Writing the Mscgen text to the serial line

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.

Step 3: Receiving the text on PC side and generate the image

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.

Conclusions

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.

Have fun! Peter

~~DISCUSSION|Leave your comments~~

Using State-Machines in Low-Power Embedded Systems - Part II

anonymous@undisclosed.example.com (Anonymous) — Sun, 25 Sep 2022 09:52:31 +0000

Using State-Machines in Low-Power Embedded Systems - Part II

In the last part I've described a basic system design based on state machines, timers and queues. In this short update I extend the existing design with a radio transmitting the measured temperature to a central server. The updated hardware diagram looks as follows:

One new hardware signal is the /RTS line indicating readiness of the radio. The other one is an output signal to drive the radio into sleep mode and back into active mode.

The updated state machine works as follows. To keep the battery driven system running as long as possible the radio is in low-power mode most of the time. Only just before sending the µC wakes-up the radio in Step2a. The falling edge of the /RTS signal indicates the radio readiness which leads into Step2. In Step2 transmission takes place on interrupt basis (started by putchar()). During transmission /RTS is high. If transmission is over /RTS goes to low again. If this happens the radio is switched off again. In case transmission couldn’t completed the radio is switched off latest after 200ms. In Step3 we wait for 5s then the board signals the successful transmission with a short blink code (state BlinkGood). An then the cycle begins again. Output PORT1/Bit1 is used for debugging purposes. In low power mode just the LED blinks two times slowly to indicate low battery.

To feed in the /RTS signal into the state machine a new interrupt handler was added as shown below:

#pragma vector=PORT2_VECTOR
__interrupt void Port_2(void)
{
	if(fifoPut(&buf1, evFallingEdgeRTS)){
		globalErrHandler(); // buffer full
	}else{
		P2IFG &= ~RADIO_RTS;
		disableRtsIRQ();
		// wake up main routine to process state machines
		__bic_SR_register_on_exit(LPM3_bits);
	}
}

Listing 1: The falling edge event is put into the fifo queue. The state machine takes out event by event from that queue processing the events.

The main part of the UART code is the putchar() function and the transmit interrupt.

// Send a character via serial interface. If no transmission is running
// the character is directly put into the tx register, otherwise enqueued.
void putchar(uint8_t cByte)
{
	TX_INT_DISABLE; // disable transmit interrupt (in IE2)
	if(fifoIsEmpty(&txbuf) && (!txrunning)){ // queue empty and no transmission running
	    txrunning=true;
	    TXBUF0 = cByte; // load tx register, inc index
	}else{
		fifoPut(&txbuf, cByte);
	}
	TX_INT_ENABLE; // enable interrupt (in IE2)
}
 
 
 
// UART0 TX ISR. 
// The isr takes out the next char from the fifo.
#pragma vector=USART0TX_VECTOR
__interrupt void usart0_tx (void){
 
	static uint8_t txchar;
 
	bool empty = fifoGet(&txbuf,&txchar);
	_EINT();
	if(!empty){
		TXBUF0 = txchar;
	}else{// buffer empty, nothing to do
		txrunning=false;
	}
}

The updated state machine design was created with the built-in state machine editor of SinelaboreRT. The reason is simple: I wanted to use the development environment CCS from Texas Instruments on Linux. And Cadifra is only available on Windows. But this was no problem because every state machine can be automatically migrated to the internal editor. Those of you not knowing CCS should really take a look on it. It has some really cool features - e.g. the power measurement option to just name one.

Let me know if you are interested in the complete source code or need more explanation.

[MSP430, Application Example]

Using State-Machines in Low-Power Embedded Systems

anonymous@undisclosed.example.com (Anonymous) — Sun, 25 Sep 2022 09:51:20 +0000

Using State-Machines in Low-Power Embedded Systems

Introduction

I got requests from time to time asking how to integrate state-machines in a specific system design. Usually I can only give some general advice. But I like to present some design principles here which are hopefully useful for developers of deeply embedded systems in general and those of low power systems in particular.

The CPU in a low power system is usually only active from time to time to react on events triggered from outside (e.g. a pressed key) or triggered from inside the system (e.g. ADC ready, timer expired). After processing the event the CPU goes into low power mode again.

All this is done to keep the batteries running as long as possible. A good example for such a system is a wireless temperature sensor mounted outside the window sending temperature data from time to time to a central display, or a monitor attached to a bird to track the flight route or a bike computer etc. The longer the batteries last, the better.

But also systems connected to power all the time might benefit from a low-power design. Power consumption of a device is a real buying criteria nowadays.

System Design

The following example is based on a small MSP430F1232 header board with just 256 bytes of RAM and 8K of program memory. For the development the Code Composer Studio from TI was used. At the end the program needs <2k Flash and 182 bytes RAM incl. stack. The following block diagram shows the controller with its I/O connections.

Figure 1: MSP430F1232 block diagram

To not hide the design principles behind too much details the uC runs just two state machines fully generated from UML state diagrams. One machine is measuring the battery voltage every 2 seconds. The other one measures the temperature also on a cyclic basis using a TMP100 from TI connected via I2C to the uC. Temperature measurement happens only if battery voltage is high enough. Otherwise a LED is pulsed to indicate low voltage state (P1.3). The radio part which sends the temperature to a central server was omitted here.

The two state machines realizing the user application are shown in figure 2 below. The state machines were designed with the built-in Java UML editor. To change or extend the functionality just modify the state machines, regenerate the state-machine code and then compile and link as usual. Changes on I/O port 1 were added to verify the timing via oscilloscope (see below).

Figure 2: Application logic implemented as state machines. Top: Triggering the voltage measurement with a cyclic timeout. Bottom: Switching between two operation modes depending on supply voltage level. Single-shot timers are used for timing.

Reusable Library Layer

The design is based on the following library elements which can be reused from project to project:

A timer abstraction layer provides timers for the user application. The timer abstraction is based on a system tick realized with hardware timer A here. If a timer has expired the tick() routine returns true and the CPU is woken-up. Otherwise the low power mode is entered again.

__interrupt void Timer_A0(void)
{
  bool retVal;
  P1OUT ^= BIT0;        // toggling bit for debugging
  retVal = tick();    // timer service. Check if any timer has expired
 
  if(retVal){
    // at least one timeout timer fired.
    // wake up main loop
    __bic_SR_register_on_exit(LPM0_bits); 
  }
}

Listing 1: Timer interrupt service routine calling the timer handler tick().

The user code can create multiple timers and receive time-out events in case they expire. During timer creation the event queue and the timer event has to be provided. If a timer expires this event will be stored in the given event queue. The timer implementation can be found in the library folder in files timer.c and timer.h. The tick() function is the core of the timer library and shown below:

bool tick(void){
  bool timeoutAvailable=false;
 
  // Iterate over the timers and enque
  // timer events once a timeout has happend.
  for(uint8_t i=0; i<MAX_TIMERS; i++){
 
    if(timers[i].timerStatus==ON){
 
      timers[i].elapsedTicksSinceStart++;
 
      if(timers[i].elapsedTicksSinceStart==timers[i].preset){
        // timeout time elapsed.
        timers[i].timerStatus=OFF; // stop timer
        fifoPut(timers[i].rbuf, timers[i].evTimeout); // enqueue timeout event
        timeoutAvailable=true;
      }
    }
  }
 
  return timeoutAvailable;
}
 
 
// starts timer
// Returns either ON if started or OFF if not started (e.g. preset=0)
TIMER_STATE_T timerStart(uint8_t t_id, uint16_t ticks);
 
// stops timer
void timerStop(uint8_t t_id);
 
// either returns ON or OFF or PAUSE
TIMER_STATE_T timerStatus(uint8_t t_id);
 
// set timer timeout in ticks
void timerSet(uint8_t t_id,uint16_t ticks);
 
// Timer function to be called from the timer irq handler.
// If at least on timer fired the function returns 1. Otherwise 0.
bool tick(void);
 
// pause timer
void timerPause(uint8_t t_id);
 
// resume timer
void timerCont(uint8_t t_id);
 
// Not yet implemented
void timerErase(uint8_t t_id);

Listing 2: The timer interface and the tick handler. The tick handler is checking if any timer has elapsed. In this case the user provided event is stored in the corresponding queue.

A queue service. Queues are used to store events from timers or other event sources in fifo order. Multiple queues can be created usually one per state-machine. The queue code is available in the library folder in files ringbuf.c and ringbuf.h.

typedef struct Buffer {
    uint8_t *data;
    uint8_t mask; // size - 1
    uint8_t read; // index of oldest element
    uint8_t write; // index of field to write to
} FIFO_T;
 
void fifoInit(FIFO_T * const buffer, uint8_t  * const pByte, uint8_t size);
bool fifoPut(FIFO_T * const buffer, uint8_t byte);
bool fifoGet(FIFO_T  * const buffer, uint8_t * const pByte);
bool fifoPutHead(FIFO_T * const buffer,  uint8_t byte);
bool fifoIsEmpty(const FIFO_T * const buffer);

Listing 3: The queue interface. Multiple queues can exist. A state machine usually has one input queue to pick the next event from.

Weaving the state machines and the library part together

On top of the minimal abstraction layer (timers, queues) the application specific part is located. It is implemented as state-machines reacting on the events. The state machine code is fully generated. All is generated from the UML state machine diagrams. The main routine initializes the hardware and then enters a main-loop waiting in low-power mode. ADC and timer iqr handlers wake-up the CPU after they enqueued an event. When woken-up the main loop pulls out these events and calls the appropriate state-machine with the event as parameter. See the following code snippet for the implementation details:

/**
 * Main loop initializes the hardware and software
 * and then waits in low power mode until new events
 * are present. Events are then pulled out of the
 * queues and forwareded to the apropriate state-machine.
 */
void main( void )
{
  // Stop watchdog timer to prevent time out reset
  WDTCTL = WDTPW + WDTHOLD;
 
  // initialize timer 
  TACCTL0 |= CCIE;                           // CCR0 interrupt enabled
  TACCR0 =  41U;
  TACTL = TASSEL_1 + MC_1 + ID_3;           // SMCLK/8, upmode  
 
 
  P1OUT &= 0x00U;               // Shut down everything
  P1DIR &= 0x00U;
  P1DIR |= BIT0 + BIT1+BIT2+BIT3;       // set pins to output the rest are input
  P1OUT |= BIT1 + BIT1+BIT2+BIT3;         //Select pull-up mode
 
  fifoInit(&buf1, buf1data ,sizeof(buf1data)/sizeof(uint8_t));
  fifoInit(&buf2, buf2data ,sizeof(buf2data)/sizeof(uint8_t));
 
  timerInit();
  init_uart();
  radio_init();
  initWindSensor();
 
  // run once to init
  toggle(&smToggle, TOGGLE_NO_MSG);
  pwr(&smPwr, PWR_NO_MSG);
 
  while(1){                      //Loop forever
 
    uint8_t retVal;
    uint8_t bufVal;
 
    do{                         // first process all events for task A
      retVal = fifoGet(&buf1, &bufVal);
      if(retVal!=QUEUE_EMPTY){
        toggle(&smToggle, bufVal);
      }
    }while(retVal!=QUEUE_EMPTY);
 
    do{                        // then all evenets for task B
      retVal = fifoGet(&buf2, &bufVal);
      if(retVal!=QUEUE_EMPTY){
        pwr(&smPwr, bufVal);
      }
    }while(retVal!=QUEUE_EMPTY);
    // more tasks could follow here
 
    __bis_SR_register(LPM3_bits + GIE);  // Enter low power mode once
    __no_operation();                    // no more events must be processed
 
  }
}

Listing 4: The main routine waiting in low power mode until events are available. Then these events are forwarded to the state machine handlers.

How to treat with longer lasting tasks

Execution time for handling events should be as short as possible. Longer lasting tasks should be split into chunks. Take the temperature measurement as an example. The temperature sensor TMP100 requires about 320ms conversion time according to the data sheet. The uC shouldn't wait and burn CPU cycles but either wait in low-power mode or process other events. This can easily be done by starting the conversion in one state (Step1) and then start a timer and enter low-power mode. If the timer fires we pick-up the conversion result (Step2) and process it further.

Another example is the wake-up procedure of the radio. After finishing low-power mode it takes a while before it is ready. Readiness is signalled via a transition of the RTS pin from high to low. After switching on the radio in state Step2a we enter low-power mode again. The level change creates an irq and sends the event evFallingEdgeRTS. Now the radio is ready to transmit data.

Object Diagram

The software design is shown in the next figure as UML object diagram. You can clearly see how the queues decouple the event sources from the event consumers. The main-loop serves as event dispatcher being only active if events are available in one of the queues. The main loop can also be used to prioritize one state machine over an other or ensure the order in which state machines are executed.

Figure 3: Object diagram of the whole application.

To verify the overall system behavior some output port pins were used as follows:

Timer A interrupt routine shown als clk in the first line. The port pin is inverted in each interrupt i.e. every 100 ms.
The supply voltage goes down. As reaction the measurement stops (line 2) and the power fail LED starts flashing (line 4). The evPowerFail starts from state Running. As a result it can happen that the temperature measurement cycle just starts in case a evPowerFail event happens but can't finish. You can see this in the oscilloscope image. There is just one peak. To fix this let the evPowerFail transition start from state Step2. This would ensure that a measurement cycle always completes before state changes to PowerFail.
Line 3 shows the timing of voltage measurement state machine (cycle of 2 seconds).

Figure 4: Oscilloscope image showing the timing of the whole application. Line 1: system tick. Line 2: timing of the temperature measurement phases. Measurement only happens if the supply voltage is above a defined threshold. Line 2: Supply voltage measurement. Line 3: LED output plus: Analog line: battery voltage.

Discussion

This article shows the principle concepts for designing low power embedded systems using state-machines, timers and queues.
Queues and timers as basic services which are application independent and can be reused from system to system. Timer resolution and number of timers and queues can be adjusted to optimize memory needs.
The user application is modeled as state machines receiving events from the outside or inside sources via queues. I.e. decoupling is done with queues.
State-machine processing time must be short enough to ensure that no events get lost and overall response time is ensured.

The source code is just meant for demonstration purposes. I'm happy to receive suggestions for improvement which I will add and make available for others again. The code composer workspace is available for download here.

Hope you enjoyed this article. Let me know your feedback!

Peter Mueller

[MSP430, Application Example]

Using Statemachines with the embOS Real-Time Operating System (RTOS)

anonymous@undisclosed.example.com (Anonymous) — Wed, 08 Mar 2023 20:07:26 +0000

Using Statemachines with the embOS Real-Time Operating System (RTOS)

This article shows how to use state charts in the context of a real-time operating system. In this example the WIN32 version of embOS from Segger is used as an RTOS. So you can build, modify and run the example yourself!

The Starting Point

System partitioning often requires to run state machines in different tasks, timer handlers or interrupt service routines. The different state machines then typically communicate through interprocess communication mechanisms provided from the operating system such as queues or messages (aka active objects). The following figure shows a fictive system with different active parts and their relation.

In this example the two blue marked parts (a task and a timer) are modelled as state machines. The Sender periodically sends different events to the Receiver. The receiver task then reacts on the received events. The two state machines are kept simple and just print out some trace messages. But this is enough to understand the design principle.

Implementation

Step 1: Modelling the sender & receiver state machines

For each state machine an own UML state diagram has to be developed. The diagram for the Receiver is shown first. The two accepted events are ‘ev1’ and ‘ev2’. Whenever an event is received a state change happens. The code provided after the ‘action‘ keyword (right note) is inserted from the code generator at the beginning of the state machine handler. This code reads the next available event from a mailbox, otherwise it blocks. The code following the ‘header‘ keyword (left note) is inserted at the beginning of the generated code. It includes the required header files and declares the needed variables (e.g. the shared mailbox).

The next diagram shows the sender machine. Whenever the timer fires a state change happens (evTimeout). The action code in the transitions put new messages in the message box. The timer is re-triggered (→ see action code) after each timeout.

Step 2: Integrate the state machines

In our example the sender state machine is called from within the embOS timer callback function.

// embOS timeout callback function
void TimerHandler(void) {
   sender(&sndInst);
}

The receiver state machine is called from the task body.

// receiver task
void Task0(void) {
   while(1){
       OS_Delay(50);
       receiver(&recInst);  // state machine function blocks if no event is available
   }
}

Nothing else is required. The generated code does not need any other runtime libraries!

Conclusions

As you can see it is quite simple to use generated state machine code in the context of an real-time operating system. It is also possible to run a state machine function from within an interrupt service handler. Checkout the manual on how to set the related generator flags.

To change the state diagram you need the Cadifra UML editor which was used to design the example. Demo versions of Cadifra and the Sinelabore code-generator are available in the download area. To compile the code you also need the Visual C++ Express Edition from Microsoft. The source code and the executable is provided for download below. After starting the exe the trace output is written to c:\trace.txt. No other output is shown on the screen!

Download the embos example here.

~~DISCUSSION|Leave your comments~~

[MBOS, RTOS]

SinelaboreRT - wiki:toolbox

What is Bela?

What is Bela?

Event-based vs polling

Event-based vs polling

Event-based model

Polling-based model

Features for High-Availability and Safety Systems

Features for High-Availability and Safety Systems

Undefined State Error Handler

Validate State Transitions

Generate State/Event Definitions with Hamming Distance

Model-based testing of state machines

Model-based testing of state machines

This article explains how sinelaboreRT helps you to test your state based software.

Generating test cases

Expected outputs

Running tests

Comparing actual outputs and deciding on further actions

Summary

Further readings

Model-based testing of state machines - part II

Model-based testing of state machines - part II

Enabling tracing

Display the state diagram

Testing at work

Testing not modeled behavior

Summary

Regions or no regions

Regions or no regions

Model with regions

Conclusions

Time Events in State Machines

Time Events in State Machines

So what is the proposed solution for implementing time events with the Sinelabore//RT// code generator?

RTOS based Designs

Mainloop Designs

Conclusions

Using Mscgen for nice looking State Flow Diagrams - Trace the flow of Events

Using Mscgen for nice looking State Flow Diagrams - Trace the flow of Events

Step 1: Instrumenting your code

Step 2: Writing the Mscgen text to the serial line

Step 3: Receiving the text on PC side and generate the image

Conclusions

Using State-Machines in Low-Power Embedded Systems - Part II

Using State-Machines in Low-Power Embedded Systems - Part II

Using State-Machines in Low-Power Embedded Systems

Using State-Machines in Low-Power Embedded Systems

Introduction

System Design

Reusable Library Layer

Weaving the state machines and the library part together

How to treat with longer lasting tasks

Object Diagram

Discussion

Using Statemachines with the embOS Real-Time Operating System (RTOS)

Using Statemachines with the embOS Real-Time Operating System (RTOS)

The Starting Point

Implementation

Step 1: Modelling the sender & receiver state machines

Step 2: Integrate the state machines

Conclusions