SinelaboreRT - wiki:examples

Electric Window Lift Controller Example

anonymous@undisclosed.example.com (Anonymous) — Sat, 28 Nov 2015 13:52:49 +0000

Electric Window Lift Controller Example

The following example describes an electric window lift as it can be found in most modern cars today. The example is based on a requirement specification that is provided from Fraunhofer IESE and can be downloaded here. In the document it is stated that the specification has a similar complexity and level of detail as it can be found in real specifications written by car manufactures. But it does not describe a real existing system.

The specification describes a complete door controller. One small part of it - the window lift unit - is modelled here. In fact only the opening of the pane was realized. The closing part is very similar and was left out to make it easier to follow the example. Unfortunately the specification is available in German language only. Therefore the window lift related parts are presented below in English.

Besides showing how the requirements are transfered into a state machine it also shows how to integrate a state machine into a real-time operating system. In this example the Windows emulation of embos from Segger was used.

Electric Window Lift Specification

The movement of the pane is controlled through keys in the car doors. Pane movement continues as long as the stimulus is present or the pane has reached its end-position (either open or close). While closing the pane it is controlled if a barrier disturbes the movement. If yes, the closing operation is stopped and the pane is opened totally (clamping protection).

In reality the number and kind of stimuli depends a lot on the car type. Here the implementation of just one type is shown.

Opening a pane

When receiving an opening command the opening starts if the battery voltage is above 10V. Below this level a “LowBatt” message is sent to the central control unit.

The following cases needs to be considered for moving:

If the command is “pane down manually” the pane will be moved downwards. Downwards movement will be stopped under the following conditions:

the down command is not anymore present
the pane is totally open
there is a new command
the movement sensor detects no movement anymore although the window is not totally open and the motor was switched on (an error message is sent in this case)
The total traveling time is longer than 3 sec but the pane is not totally open (an error message is sent in this case)

When receiving the command “pane down automatically” the pane will be moved downwards until it is completely open. Downwards movement will be stopped under the following conditions:

the pane is totally open
there is a new command
the movement sensor detects no movement anymore although the window is not totally open and the motor was switched on (an error message is sent in this case)
The total traveling time is longer than 3 sec but the pane is not totally open (an error message is sent in this case)
It is not necessary that the “pane down” command is pending
during the complete traveling time.

Mechanically it is not possible to move the electric window lift command key directly from “pane down auto” into the “not pressed” state. Therefore the command “pane down manual” is ignored up to 0.5sec if the previous position was “pane down auto”. If the command key is present longer than 0.5 sec the mode will be changed to manual moving mode. Releasing the command key afterwards stopps the movement immediately.

The Sample Solution

The figure below shows a possible state chart of the window lift.

The generated state machine is executed in an embos task. Therefore it blocks until an event was recieved. Embos provides several mechanisms for inter task communication. In the example events were used to signal timeouts, pane movement and new key commands. The event selection code is specified in an 'action:' note (see image at the top). The action code is executed at the very beginning of the generated state machine function.

/* action code */
evt = OS_WaitEvent(0xff); // wait blocking
if(evt==1) msg=evTimeoutLongMove;
else if(evt==2) msg=evTimeoutMoving;
else if(evt==4) msg=evTimeoutInter;
else if(evt==8) msg=evMotion;
else msg=keybMsg;

Important! SinelaboreRT does not restrict you in any way on how to send events to a state machine.

The motor is simulated in a second task (see motor.c / motor.h). If the motor is switched 'on' the task sends evMotion events every 20ms. As long as the motor is 'off' the task is suspended and does not send events.

For the supervision timers (long move, moving, inter) embos software timers were used. In their callback functions they simply send the according timeout event to the state machine task.

// Timer handler for the long move timer.
// On timeout send the message to the statechart
void TimerLongMoveFct(void) {
  OS_SignalEvent(0x1,&statemachineTaskTcb);
}

A third task realizes a small test bed by sending commands like (manual down, auto down, …) to the state machine. Several test cases are realized to test the machine. For example entering the manual mode from the auto mode. Another test case tests the 'long movement' requirement.

// This tasks sends simulated user commands.
void SimulatorTask(void){
  extern TUSIGN8 pos;
  while(1){
    OS_Delay(1000);
    Trace("\n\nFirst test. Must result in long move error.");
    keybMsg=evManDown;
    Trace("evManDown");
    OS_SignalEvent(0x80,&statemachineTaskTcb);
    OS_Delay(1000);
   ...

Running the Example

The example comes pre-built. The executable start.exe can just be started. If started it does not display any output but writes its output to trace.txt which is located under c:\. After execution all test cases (takes about 30s) the program finishes automatically.

File main.c contains the simulation - and the state machine task as well as the code to initialize all tasks, timers etc. In files motor.* the simple motor simulation was realized. All files starting with window_lift.c/h were automatically generated from the state-chart window_lift.cdd. In folder embos the Visual C++ project as well as the embos library can be found.

To rebuilt the state machine files execute

java -jar codegen.jar -p CADIFRA -o window_lift  window_lift.cdd'

To rebuilt the executable file you have to install Microsoft C++ 2005 Express Edition (or later) which you can download from Microsoft.

Thanks to the people from Segger allowing us to use the windows evaluation version of embos in this example.

If you have comments or questions just send an email to info@sinelabore.com.

~~DISCUSSION:closed|Leave your comments~~

[Application Example]

DCF77 Radio Clock

anonymous@undisclosed.example.com (Anonymous) — Sat, 21 Jan 2023 15:42:29 +0000

DCF77 Radio Clock

In this example a decoder for the DCF77 standard-frequency radio signal is realised based on two cooperating state machines. You will learn how to use the features of the code generator.

Machines based on conditional and event based triggers
Adding own variables to the machine instance data
Adding own code to the generated state machine file
Using an own event type that includes the event and data

DCF77 Basics

The transmitter is located nearby Frankfurt in Germany and continuously transmits a 77.5 kHz signal that encodes the local time using amplitude and phase modulation. The sender is controlled by the high-precision atomic clocks of the German institute of standards (Physikalische Bundesanstalt in Braunschweig). The signal can be received almost everywhere in central Europe with very simple and cheap receivers. A short description about the motivation and the encoding of the DCF-77 signal can be found here here.

The DCF-77 modulation reduces the signal amplitude for 0.1 seconds (short pulse, 0-bit) or 0.2 seconds (long pulse, 1-bit) at the beginning of each second, allowing to transmit 1 bit of data per second. A simple BCD-encoding scheme is used to transmit the hours, minutes, days, and data information for the next following minute. Encoding scheme of the time information transmitted with DCF77 is presented here.

To allow synchronization into the continuously sent signal, no pulse is send during the 59th second, so that the start of the next pulse exactly marks the beginning of the minute.

The receiver application was splitted into two separate state machines.

The pulse detection state machine

The pulse detection state machine runs within a cyclic timer interrupt service routine. It initially searches for the minute start 'M' and then detects the long and short pulses. This state machine runs cyclically and does not need any external triggers (events). Instead all state transitions are based by the DCF77 output signal level. We call such state machines “conditional machines” because state transitions are based on some input conditions or variable values. The types of transitions are described here in the section about transitions.

The CPU is normally in low-power state. But when a pulse or minute start is detected the decoder machine and wakes up the CPU.

#pragma vector=TIMERA0_VECTOR
__interrupt void Timer_A0(void){
 
    // set debug output high if pin of dcf77 signal is high
    if((P1IN & 0x01) == 1U) P1OUT |= 0x04;
    else P1OUT &= ~(0x04);                  // clr debug pin
 
    P1OUT |= 0x08;                          // set debug len of irq
 
    dcf77_irq(&irqSM);
    if(irqSM.msg==evTick || irqSM.msg==evMinStart){
        // wake up main CPU, got valid pulse
        __bic_SR_register_on_exit(LPM3_bits);
    }
 
    P1OUT &= ~(0x08);                       // clr debug len of irq
}

The state machine was created with the integrated state diagram editor. A screenshot is shown here. The editor allows to create state machine diagrams in very efficient way. A multipart tutorial is available here.

The state diagram editor allows to directly add code to various sections of the state machine. In this example some helper functions and variables were added to the begin of the state machine file. More details about the offered possibilities can be found in the tutorial part I in figure 5 . In addition is is also possible to add variables to the state machine instance type. These variables can then be used for data exchange, storing local data etc. In this example we use this possibility to store several internal variables used for the pulse detection state machine.

The decoder state machine

The second state machine runs in the endless main loop and executes once if a pulse was detected. Initially it waits for the minute begin. Once found the state machine processes the events coming from the pulse detection machine (in opposite to the above conditional state machine). The first 20 bits contain special information and are ignored. Then once the minutes bits come the time and date information is captured and decoded. And finally the clock is set before the cycle starts again.

The following code shows the main loop which only runs if a new pulse is available for processing. The state machine uses an own event type (see below) which is filled before the machine is called. Then the low power mode is entered again.

    while(1) {
      _BIS_SR(LPM3_bits + GIE);                 // Enter LPM3 
      __no_operation();
 
      P3OUT |= 0x8;                             // set D2 debug output
 
      // update event information and call the decoder
      decoderEvt.msg = irqSM.msg;
      decoderEvt.len = irqSM.len;
      decoder(&decoderSM, &decoderEvt);
 
      P3OUT &= ~(0x8);
    }

Event Type

This example presents another feature of the code generator. The state machine handler can have different signatures. Usually a pointer to the instance data and the event to process, is handed over. Here we have defined an own event type (OWN_DECODER_EVENT_T) which contains not just the event but also some data (the length of the detected pulse).

For this state machine handler signature:

void  decoder(DECODER_INSTANCEDATA_T *instanceVar, OWN_DECODER_EVENT_T *userData){...

the following parameters must be set in the configuration file. Note: the integrated editor has as helper function to find the right parameters for you (Code→Handler Signature).

UseInstancePointer=yes
HsmFunctionWithEventParameter=yes
InlineChangeToStateCode=yes
HsmFunctionUserDefinedEventParameter=OWN_DECODER_EVENT_T

Debugging Trace

To better understand the timing of the design some debug signals are generated in the irq handler and the main loop. The following figure shows the generated debug signals. D0 shows a received dcf77 pulse with a len of 100ms. D0 shows the duration of the irq handler routine. And finally D2 shows the execution time of the main loop. You can see that the most time the CPU can stay in sleep mode.

Organization of the Code

Each state machine is in its own folder. Within each folder you will find the state machine model file (*.xml) and the corresponding configuration file. You can open and edit the files easily using the state machine executable (right-click on the file and open with sinelabore.exe). In the tool you can then regenerate the code in the case you made changes. In main.c the board is initialised and the state machines called.

Conclusion

This tutorial presented how to use conditional and event based state machines to realise a complete application on a small embedded system. The whole code fits in 2kB of code and 110 bytes of ram.

The complete source code and model files are available for download. Feedback is very recommended.

[Application Example, MSP430]

Signal Forming Function Block Design with State Diagrams

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:44:10 +0000

Signal Forming Function Block Design with State Diagrams

In this tutorial you will learn

how to use conditions to trigger state transitions in your state machine
how to benefit from adding attributes to a stateful class
using state machines to create library of reusable function blocks for control signal forming

In another example you can learn how to create a PLCOpen safety function block using the same concept.

What are conditional events

The code generator supports two basic modes of operation which should not be mixed. Either it processes events. Only if an event is present a transition is taken. Events are eventually send to the state machine using an event queue. Alternatively transitions are triggered by boolean conditions. If a boolean condition is true a state change happens. The latter one is useful if binary signals should be processed like we will see in our example. In this case the state machine runs without receiving a dedicated event but depending on state boolean state is used to trigger state transitions.

The Problem

Image an embedded system - such as an industrial control device - which has several binary inputs. Often the behaviour of such a device is influenced by the state of these inputs. E.g. an actor should be switched on, a lamp should be activated etc. But often not the raw input signal should be used but a preprocessed signal such as:

Trigger an activity on the rising or falling edge of an input signal (ftrig, rtrig). These bocks are useful to create an event from a boolean signal.
Delay the input signal for some time (so called on-delay)
Wait until an input signal was switched off again (so called off-delay)
Combination of the two above (on/off delay)
Offering a pause input to pause the time condition of the above signals
Offer an option to reset a started timing
Shaping an input signal - i.e. creating a pulse of defined length independent from the length of the input signal
Debounce inputs

There exist many more such functions. You might have come across them in your own practise.

The Solution

It would be very beneficial to have a library of such functions that can be easily integrated into a system design. All the above ones require some state so it makes sense of course to model them as state machines. The design presented here is based on Enterprise Architect and uses the option to model additional attributes in the class. Such attribute are added to the instance data. It can be used for internal variables but also as interface to the outside. We will use both in the examples here. Lets start with the ftrig and rtrig functions first. They do not depend on time and are therefor a bit simpler to model.

Before looking into the state machines take a look in the class diagram first.

Each function is modelled as class. The classes have more or less additional attributes. All have binary signals such as q (output) and set. Others have also the additional binary signals pause and reset or variables defining the delay times. Then also internal data is modelled e.g. to store the elapsed time.

To model attributes it is recommend to define your own data types using the 'primate data type' feature of UML. This allows to ensure the use of a consistent set of data types with the rest of your code not modelled in UML. The following figure shows the model tree with the classes and data type definitions inside a common package.

RTRIG and FTRIG Function

The following two state diagrams show the models for the falling edge (ftrig) and the rising edge (rtrig) function. There is no time information needed. Only the status of the previous input signal. Conditional triggers are marked with a hash # as first character.

Pulse Function

The single pulse function is shaping the length of an input signal to a defined pulse length at the output. It requires a notion of time. The implementation just uses the system tick to get time information and calculating the elapsed time with each call of the state machine.

On/Off Delay with Pause and Reset Inputs

This function block is the most complex one. It requires several internal variables to store temporary information and two independent time settings. The reset and pause inputs make the function even more flexible.

Generating Code

To generate code from the state machine model the following command lines were used (the class path -cp points to the location of the codegen.jar file):

java -cp "../../../*" codegen.Main -p ea -t "Model:signal_processing:package:on_off" -o ton_toff signalprocessing.xmi
java -cp "../../../*" codegen.Main -p ea -t "Model:signal_processing:package:ftrig" -o ftrig signalprocessing.xmi
java -cp "../../../*" codegen.Main -p ea -t "Model:signal_processing:package:rtrig" -o rtrig signalprocessing.xmi
java -cp "../../../*" codegen.Main -p ea -t "Model:signal_processing:package:single_pulse" -o single_pulse signalprocessing.xmi
clang -l ncurses ton_toff.c main_on_off.c -o ton_toff
clang -l ncurses main_rtrig.c rtrig.c -o rtrig 
clang -l ncurses main_ftrig.c ftrig.c -o ftrig
clang -l ncurses main_single_pulse.c single_pulse.c -o single_pulse

The only two additional functions that must be provided are the ones delivering the elapsed time information.

uint32_t getSystemMilli(){
    struct timeval now;
    gettimeofday(&now, NULL);
    return now.tv_usec/1000 + now.tv_sec*1000;
}
 
uint32_t getDiffMilli(uint32_t old_milli){
    uint32_t milli = getSystemMilli();
    uint32_t diff =  milli - old_milli;
    //printf("Milli=%d, old_milli=%d Diff=%d", milli, old_milli, diff);
    return diff;
}

That's all. All the rest is generated!

Testing the Implementation

To test the implementations test patters were generated with which the state machines were called. The inputs and outputs of relevant signals were displayed via the curses library over time. Some examples:

ton with pause  tond=500, toffd=0
  Set:___***************_______________
Reset:_________________________________
Pause:_____****________________________
    Q:____________******_______________
 
 
ton/toff  tond=300, toffd=800
  Set:__*******___________***__________
Reset:_____________________*___________
Pause:_________________________________
    Q:_____************________________
 
rtrig testcase 2
Set:___****__*___
  Q:___*_____*___
 
ftrig testcase 1
Set:___****_*__*_
  Q:_______*_*__*
 
 
single pulse false at begin
Set:___*************______*__________
  Q:___***________________***________
 
Debounce button test
 Input__*__*_**__****************_*_**_*_*___*____*__________
 Out  _____________*************************_________________
 Cnt  0011120120012345678999999997867867564201111120000000000

Final Thoughts

State machines with conditional transitions are a powerful way to model signal forming functions. The shown approach makes reuse more easily possible within the same or further projects. In addition it has the general benefit that the model is the documentation and both is always 100% in sync with the implementation. Alone this benefit should motivate you to not write your next state based design by hand but use a modelling tool and generate the code.

If you are interested in the complete code just send me a mail. The model files are available here:

EA: Enterprise Architect Model file (created with version 16)

UModel: UModel Model file

Built in Editor: Model files for the built-in state diagram editor

Looking forward to receive your thoughts and ideas for other useful blocks.

~~DISCUSSION:closed|Leave your comments~~

Automatic Light Controller

anonymous@undisclosed.example.com (Anonymous) — Mon, 09 Dec 2019 19:00:29 +0000

Automatic Light Controller

State machine example

Everybody knows outdoor automatic light switches. They offer the comfort to automatically switch on/off the outside light. This way they even help to save energy. Other names for such a device are: motion-activated (or motion-sensing) porchlight, dusk-to-dawn sensor porchlight

The following figure shows a simplified state machine of such a device.

Functional Requirements

The device has three modes which can be changed using a simple switch. It has the positions OFF, Auto and ON. The switch is realized in a way that the user can only go from OFF to AUTO to ON and vice versa.

In ON mode the light is permanently switched on. In OFF mode the light is permanently switched off. In Auto the light is automatically switched on and off as described in the next section.

When its becoming dark and the auto mode is active the device automatically switches on the light if a person is detected. If the person walks away the light is switched off again. The light is on for at least a configurable time (e.g. 60s). If the person is still nearby after that time the light is kept on as long as no person can be detected anymore.

The light should not be switched on during daylight. Therefore the device permanently measures the ambient brightness. Only if the measured value is below an adjustable threshold the device switches on the light automatically.

State Machine Design

The three modes of the device can be easily transferred into states. The auto state is a hierarchical state which realizes the night/day behavior when a person was detected. The design was created using the SinelaboreRT state machine editor. The diagram is shown in the figure above.

The automatic light controller zip files contains the fully worked out example with a simple text based command interface. Start the executable and type in one of the supported letters to trigger the machine.

Available commands:

+ There is a person
- There is no person
t Ambient brightness low (twilight, night)
d Ambient brightness high (dawn, day)
a Auto mode
o Permanent on
x Permanent off
q Quit the program

The files gui.c/h realizes the keyboard handling. In the file light_trace.c a simple trace function was realized to trace the event flow. Main.c calls the state machine and checks the keyboard for new events. All other files are automatically generated from the state machine as shown above.

To test the machine type in e.g.: o x a t + … (repeat 20 times) + -

Graphical Trace

The sinelaboreRT codegen tool is able to display state diagrams based on an automatic layout engine. In simulation mode trace data can be received via a UDP connection. The received evens are then used to trigger the same state changes as in the compiled C program. This makes it possible to follow the state changes of the light.exe program while we stimulate it with the keyboard events.

The prepared example already sends the trace data via UDP (see light_trace.c). To display the state machine start the editor in simulation mode as follows:

$ java -jar codegen.jar -p ssc -S -o automatic_light.xml automatic_light.xml

This command line brings up a window showing the state machine¹⁾. Start the light executable again and type in commands. You can now follow the current state of the state machine and the C-code executed as reaction to your keyboard input.

The ZIP file contains an executable that was built with Cygwin on Windows (light.exe) and for OS X (light_osx). To change the state machine or to generate the code yourself download the demo version of the Sinelabore code generator.

Have fun!

~~DISCUSSION|Leave your comments~~

[Application Example]

¹⁾

Make sure graphviz is installed on your system and the correct path to the dot.exe (layout engine) is defined in the codegen.cfg file. Otherwise you will get an error message when starting the codegen in simulation mode.

ASURO programming using state diagrams

anonymous@undisclosed.example.com (Anonymous) — Sat, 08 Feb 2020 15:51:50 +0000

ASURO programming using state diagrams

State diagrams describe behaviour!

Watch the short video above. It shows a little mobile robot (ASURO¹⁾) exploring its environment. Consider how the exploration algorithm might work …

The diagram below shows the state chart of the software running on the robot. If you examine the diagram you can clearly understand what is happening why. This is the first major benefit of state diagrams. State diagrams are perfect to fully describe reactive systems.

Ok - does this diagram really describes the software or is it just an early design sketch which is not valid anymore because it was never updated after coding has started?

To make sure that this does not happen the code running on the robot was directly generated from the state diagram. This is the second major benefit. State diagrams are perfect to fully describe reactive systems and generate code out of them. If you are interested in the ASURO code just send us a mail.

Whats going on in the robot?

Debugging an application that is based on generated code from a state diagram is a bit different compared to debugging hand written state machine code. Why? Because you can assume that the generated code is correct. You don’t have to worry about all the nitty gritty details of the realisation of a state machine in C (e.g. handling history, handling hierarchical designs, placement of entry/exit …). If the machine does not what it should do then most probably the model is not correct. To track down the problem - especially in deeply embedded real-time systems - typically means to add a tracing mechanism which allows you see which events do fire etc. Here the code generator can support you.

Automatic generation of trace code

The code generator can add trace code automatically. You only have to call the generator with the -Trace command line switch. In this case calls to a trace function are inserted in the generated code. The argument of the trace function is the processed event. A part of the ASURO state machine is displayed below. For every handled event the trace function is called (e.g. xxxTraceEvent(2U)). If the trace code is not anymore needed just call the codegenerator again without the -Trace option.

case EXPLORE:
 
	switch(instanceVar->stateVarEXPLORE){
 
		/*
		  Code for transitions starting from inner states
		 */
		case AHEAD:
			/* action code  */
			flag=drive(speed,FWD,flag);
 
			if(usDist<15){
				behaviourTraceEvent(2U);
				/*Transition from AHEAD to AHEAD_WITH_BARR */
				evConsumed=16U;
 
				/*Action code for transition */
				flag=1;speed=80; StatusLED(RED);
				instanceVar->stateVarEXPLORE=AHEAD_WITH_BARR;
			}else if(msg==(BEHAVIOUR_EVENT_T)evTimeoutT0){
				behaviourTraceEvent(0U);
				/*Transition from AHEAD to IDLE3 */
				evConsumed=1U;
 
				/*onEntry code of state IDLE3 */
				startTimer(TIMER0, 1000);MotorSpeed(0,0);
				instanceVar->stateVarEXPLORE=IDLE3;
			}
			else
			{
				/* Intentionally left blank  */
			}
		break;
                ...

If tracing is enabled an additional header file is generated which provides a table to map event ids to event strings. E.g. the argument 2U from above corresponds to the second entry in the table. This allows you to easily display the event as text.

const char* const behaviourTraceEvents[] = {
	"evTimeoutT0",
	"turned==1",
	"usDist<15",
	"usDist>30",
	"evKey"
};

The trace function must be provided by yourself. Within the trace function you can decide now what to do with this trace information.

store it in a ring buffer and read it out later (post mortem)
display it somehow
forward it to a monitoring station
…

The following code was used on the ASURO robot and simply sends the processed event to a monitoring PC.

void behaviourTraceEvent(BEHAVIOUR_EVENT_T evt){
	SerPrint(behaviourTraceEvents[evt]);
	crlf();
}

On the PC it is now possible to watch the event flow in a terminal window.

Watching events in a terminal is not good enough

Watching events in a terminal window is not bad but sinelaboreRT can do even better. When starting the codegen.jar with the -S command line switch an interactive graphical simulation window pops up. The status of the state machine after startup is displayed. The events that can be handled presently are shown in blue and are also listed in left window. The output window shows the executed statemachine code. You can now send events to the machine by clicking on an event. The display is updated accordingly and shows the new status.

Beside the interactive mode it is possible to send events via an UPD port. This is what we show next. A small application receives the events sent from the ASURO robot over a wireless serial link and translates it into a UDP message (see diagram below). The UDP message is received from the simulator and the display is updated accordingly. Click on the simulation image above and watch how the state diagram is updated while ASURO is exploring its environment.

Summary

The sinelaboreRT code generator provides several mechanisms to support you during debugging and testing of your state machine design.

It can automatically add trace code to the state machine
It provides an interactive simulation window which can display the status of your embedded target in real-time.
With the UPD/IP interface a flexible mechanism is available to use the communication interface your hardware offers. A simple “event forwarder” is all what you need.

~~DISCUSSION:closed|Leave your comments~~

[Application Example, Asuro]

¹⁾

Want to know more about this robot called ASURO? ASURO is a small, freely in C programmable mobile robot kit which has been developed for educational use especially in the DLR School Lab.

Getting started with the PIC16F18446 and State Machines

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:43:46 +0000

Getting started with the PIC16F18446 and State Machines

This tutorial explains the use of state machines with the PIC16F18446 Curiosity Nano board. It provides 2k of RAM and 16k program memory. More than enought for this small tutorial.

(Source: Microchip)

Install the required software if you want to follow all steps yourself. Otherwise just go on reading.

For this tutorial we will use just the push botton and the LED on the board. So you can follow it without any additional hardware required. The LED shall blink all the time. The frequency can be changed from slow to fast by pressing the button. Simple enough but sufficient to show all the key concepts we are going to use.

The PINs are allocated using the MPLAP X IDE Resource Manager as well as the 4MHz system clock and the 10ms Timer0. I've not used this configurator before. But have to say that it is a very convinient way to setup the hardware. I would wish to have the same for the MSP430 μCs I also often use.

Step 1 - Deciding the system architecture

For small systems e.g. sensor nodes it is usually sufficient use a main loop design. The main loop cycles endlessly and waits for events. Events are benefitially stored in an event queue. The queue is filled from timer events, other state machines (cooperating machines) or interrupt handlers. If events are available the state machine(s) are called from the main loop to process them.

In our little example events are sent from the keyboad interrupt and from a software timer module which is called regulary from the cyclic hardware timer. The following figure shows the system architecture.

The below code snippets show the irq handlers and the main loop processing the evens.

// cyclic timer interrupt
void TMR0_IRQHandler(void){
    tick(); // if a timer has fired this function stores a timer event in the message queue
}
 
// keyboard interrupt
void SW0_IRQHandler(void){
    fifoPut(&fifo,evKey);
}
 
void main(void){
    ...
 
    while (1)
	{
        do {
            // check if there are one or more events in the queue.
            // if yes, process all events in the state machine
            retVal = fifoGet(&fifo, &bufVal);
            if (retVal != QUEUE_EMPTY) {
                sm(&instData, bufVal);
            }
        } while (retVal != QUEUE_EMPTY);
        __delay_ms(10U);
    }
}

In the library folder (see project tree below) the required timer and fifo files are provided. They can easily reused also with other Controller types. I used them in several MSP430 projects before.

Step 2 - Realizing the state machine

So far we have not seen how the state machine looks like. To realize this simple job just two evens are reqired. - evKey: Indicates that the user pressed the switch - evTimeout: Indicating that it is time to toggle the LED

For this simpel state machine the editor which is built into the code generator is sufficient. For more complex machines is is recommended to use an advanced UML modelling tool of your choice. See the list of supported tools here. The next figure shows the complete state machine:

Initally the state machine enters the state Slow. The initial transition triggers the start of the timer with timeout time 10U (10U represents 10 times the base clock of the hardware interrupt (i.e. 100ms)). Then the machine waits for further events. Every time event evTimeout occures there is a self transition and as action the LED is toggeled.

In case evKey occures a state transitions from state Slow to state Fast and vice versa is triggered and the timeout time is updated.

Example action code for the transition going from state Slow to state Fast.

timerStop(timer_id);
timerStart(timer_id, 10U);

Step 3 - Integrating the state machine in MPLAB X

The generated state machine code files can be easily added to the PIC project. It is recommended to create a new folder e.g. called state_machine_generated_files. All state machine related files go in there. sm.scc contains the state machine model. sm.c/h contains the generated state machine code.

The following figure shows the project tree with all generated files.

To convienently edit the state machine model and generate code from it two batch files were created. Call edit.bat to start up the editor. And call gen.bat to generate the code. The generated files start all with the prefix sm_ (see command line). The output when calling gen.bat is shown below.

C:\Users\PM\develop\microchip\blink.X\state_machine_generated_files>java -Djava.ext.dirs=C:\Users\PM\Desktop\sinelaborert\bin\ -jar C:\Users\PM\Desktop\sinelaborert\bin\codegen.jar -p ssc -l cx -o sm sm.scc
Starting robustness tests of state machine ...
State names: ..............
Machine hierarchy: ........
Machine height = 1
Transitions: ..............
Default states: ...........
Final states: .............
Choices: ..................
No. of children in composites: ...
Connectivity of states: ...

The code generator needs a configuration file to set basic parameters. Take a look into the configuration file and read the Manual if the meaning of the parameters is not clear.

Wrapup

The chosen system architecture with state machines, an event queue and software timers is very powerful. It is proven in praxis since many years and used sucessfully in many projects. Quite complex systems can be built this way and no RTOS is requrid. It can be expaned easily by adding additional state machines and by using more than one software timer.

Use the example and expand it to learn. To receive a copy just send a mail.

Hope you like the tutorial

Have fun

Peter

~~DISCUSSION:closed|Leave your comments~~

[PIC, Application Example]

Safety Function Block

anonymous@undisclosed.example.com (Anonymous) — Sun, 25 Sep 2022 08:58:16 +0000

Safety Function Block

The PLCOpen organization has defined a set of standard function blocks (FB) for safety-related functionality. The function block specifications are given as state diagrams. The example presented here realizes the equivalent function block.

According to the PLCopen specification this function block converts two equivalent SAFEBOOL inputs to one SAFEBOOL output with discrepancy time monitoring. If one channel signal changes from TRUE to FALSE the output immediately switches off (FALSE) for safety reasons. Discrepancy time monitoring: The discrepancy time is the maximum period during which both inputs may have different states without the function block detecting an error. Discrepancy time monitoring starts when the status of an input changes. The function block detects an error when both inputs do not have the same status once the discrepancy time has elapsed.

The machine presented below is a sample realization of the state diagram specified in the PLCopen document. In opposite to the original PLCopen specification all states - which set the READY output to TRUE - are sub-states of the superstate called ACTIVE. As soon as the ENABLE input becomes inactive the ACTIVE state is left and IDLE will be entered. Using sub-states reduces the number of required transitions in the diagram a lot.

The class diagram below shows how the sample implementation is designed. The class io_interface provides a hardware abstraction layer to the inputs and outputs required by the function block. The timer class provides general timer functions. Please note that it is only good enough to test the state machine. Classes are realized as C/H-Files. The class diagram shows two comments using the action and header keywords which are supported from the code generator. C-code in the „action comment“ is copied into the C-file just before the state-chart code. The listed C-code reads and stores the function block inputs in local variables for faster processing. These variables as well as some required headers etc. are defined in the other comment. Code following the header keyword is simply copied to the beginning of the generated C-file.

The attached example implementation shows how the generated code can be used. The inputs come from a test vector. The code is built with cygwin and gcc but can be also compiled on Linux or Mac OS X for example. Main is the starting point of the code and initializes everything. A number of test cases are implemented wich can be commented in as needed.

Generated Files:

[Application Example]

Sump Controller

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:41:51 +0000

Sump Controller

This example presents the software necessary to realize a simplified pump controller which might be used in a mining environment. It is based on a case study presented in ¹⁾.

The task of the system is to pump water from a sump to the surface. There are two level monitors which start pumping if the sump is full and stop pumping if it is empty again.

Pumping shall only start if the methane level is below a certain threshold. In case the pump is already running it shall stop automatically.

There is some additional requirements:

After starting the pump a pressure monitor must signal pressure within a defined time to ensure the pump does not run dry. Otherwise the pump becomes hot and finally breaks.
If stopped the run signal (checkback) from the motor must be absent (i.e. contactor opened)
When running the checkback signal must be present.
After a fault a manual reset signal is necessary to restart the controller.

The controller behavior can be modelled as a flat state chart. The model below was created using ArgoUML an open source modeling tool. There are two main states PumpStopped and PumpRunning. Changing from run to stopped is only possible via two intermediate states (PumpStarting, PumpStopping) which check that the pump motor checkback signal is present after a switching command. If the checkback from the motor is missing the Error state gets entered.

In another possible design all states beside the Error state are children of a NoError state.

To create the state machine implementation code export the diagram to an XMI file and then call the state machine generator:

java -jar codegen.jar -S -p ARGOUML -t "sump controller:Controller" -o controller controller.xmi

In this case the C implementation is generated. The -t flag defines the path to the state diagram within the xmi model file.

With the optional -S command line flag the graphical simulation is started (see below). The graphical simulation allows to interactively send events to the machine and observe the new active state and the executed C-code. The diagram below shows the state machine in state PumpRunning. Events that are now accepted from the machine are listed on the left and are shown in blue in the diagram. To send a transition just click on the event in the list. The output window displays a trace of the executed code as provided in the diagram.

It is also possible to observe a real target which is connected to the graphical simulation. More information on how to connect an embedded target e.g. via a CAN communication link is available in the sinelabore manual. If you are interested in the model file or the generated code just send a mail to info at sinelabore dot com.

~~DISCUSSION:closed|Leave your comments~~

[Application Example]

¹⁾

Burns and Wellings, Real-Time Systems and Programming Languages, Addison Wesley 2001

Room Thermostat

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:41:57 +0000

Room Thermostat

This example shows the model of a room thermostat that controls heating, cooling and a fan to maintain a user defined temperature.

It uses regions to model the three parts of such a controller.

The user interface that allows to set the temperature for heating or cooling using the set, up and down key.
The temperature controller that tries to maintain the user selected temperature
The fan that is active in case furnace or air condition is on.

The thermostat model is based on an example from Testcover.com.

Why regions are useful

In state diagrams usually only one state is active at a time. In UML state diagrams regions also allow to model concurrency - i.e. more than one state is active at a time (AND states).

A UML state may be divided into regions. Each region contains sub-states. Regions are executed in parallel. You can think of regions as independent state machines displayed in one diagram. The state machine below (Fig. 1) shows three regions each running in parallel. Dashed lines are used to divide a state into regions.

Class diagram. In the attached comment C-code can be defined that is just included into the generated state machine code.

Regions are useful in the following situations

Regions react on the same set of events. Implementing all the functions in one state machine does not require to model two machines with the same set of events.
Regions need access to the same internal variables or helper functions. In the thermostat case the first two regions need access to the user settings such as coolTemp, heatTemp and the current room temperature (roomTemp).
Regions need to know the state of other regions. In the thermostat example the fan control region changes state based on the state of the heat control region.

In fact it would be possible to model the three regions as individual machines, but due to their close interaction is makes sense to model them in one state diagram.

Implementation

The following state diagram in figure 2 shows the classes (i.e. C-files) involved in the solution. The thermostat is the central state machine. It is fully generated from the state machine diagram shown in figure one. For code generation only the yellow marked information is needed. All other classes are more or less documentation.

The helper classes are just examples and simply print out the name of the called action on the console. Here is an example for the fan implementation:

#include <stdint.h>
#include <stdio.h>
#include "fan.h"
 
void fanOff(){
    printf("Fan Off\n");
}
 
 
void fanOn(){
    printf("Fan On\n");
}

The timer implementation is taken from a recent article published on Embedded.com.

In main.c the keyboard is cyclically scanned and the user can send events to the machine (e.g. increment the room temperature).

The following code shows an extract of the generated state machine code. In case you are interested in the full example running on various operating systems just send a request to info@sinelabore.com.

void  thermostat(THERMOSTAT_INSTANCEDATA_T *instanceVar, THERMOSTAT_EVENT_T msg){
 
	THERMOSTAT_EV_CONSUMED_FLAG_T evConsumed = 0U;
 
	/* Create a copy of the instance data.
	   Changes during the machine execution are done on the copy 
	   while tests (e.g. isIn) must use the unmodified instance data */
	THERMOSTAT_INSTANCEDATA_T instanceVarCopy = *instanceVar;
 
	/*execute entry code of default state once to init machine */
	if((&instanceVarCopy)->thermostatEntry==1U){
		tm_timer_init(&displayTimer);
		tm_timer_init(&keyHTimer);
		tm_timer_init(&keyCTimer);
		tm_timer_init(&tempControlTimer);
		tm_timer_init(&fanControlTimer);
 
		tm_timer_start(&fanControlTimer, TM_1SEC);
		roomTemp = getTemp();
		display("Room:", roomTemp);
		tm_timer_start(&displayTimer, TM_500MSEC);
 
 
		(&instanceVarCopy)->thermostatEntry=0U;
	}
 
 
	switch (instanceVar->stateVar) {
 
		case Thermostat:
			/* calling region code */
			evConsumed |= thermostatThermostatFanControl(instanceVar, &instanceVarCopy, msg);
			evConsumed |= thermostatThermostatTempControl(instanceVar, &instanceVarCopy, msg);
			evConsumed |= thermostatThermostatTempSet(instanceVar, &instanceVarCopy, msg);
		break; /* end of case Thermostat  */
 
		default:
			/* Intentionally left blank */
		break;
	} /* end switch stateVar_root */
 
	/* Save the modified instance data */
	*instanceVar = instanceVarCopy;
}

In this example we have shows how regions can be beneficially used for modeling parallel actions and how easy it is to generate code from the state diagram. The generated code can be adjusted to your needs and requires no additional run-time libraries.

~~DISCUSSION:closed|Leave a comment~~

[Application Example]

State machine based user interfaces generation

anonymous@undisclosed.example.com (Anonymous) — Wed, 17 Aug 2022 17:43:54 +0000

State machine based user interfaces generation

Most developers know state diagrams for modelling control behaviour or protocol machines. But also user interfaces can be specified with their help with great clearness.

Often small devices monitoring or controlling a process value like drive shaft speed, temperatures or the like have a built-in display. It is used to show the current device status and to configure thresholds such as low or high limits of the process value.

The figure below shows a simple HMI of a frequency monitoring device. The top line presents the actually measured value, whether the value is within the given limits (triangle points to the right) and the status of an output relay signalling an alarm. The bottom part of the HMI shows the frequency spectrum of the measured signal.

Figure 1: GUI of a frequency monitoring device

The state machine below is used to model the behaviour of the complete HMI. The state Display on the left allow to navigate between various displays showing the different measured values (min, max, actual). The right state Edit of the machine shows the configuration part of the HMI. The interaction is done with the help of three buttons. Two buttons are used to step up/down triggering events evInc/evDec. The third button is used for selection a menu item (evButtonLong/evButtonShort).

Figure 2: State machine of a small embedded GUI based on the PicoTK toolkit.

State machines are a flexible tool to model all kinds of stateful applications. Might it be control tasks, user interface interactions or realising protocol machines.

The Sinelabore code generator automatically generates code from your model. The payback comes in very short time because all the error-prone stupid coding is taken from the developer. Focus can be put on the model and model correctness. Model and code is always in sync. Fast development cycles are ensured.

Acknowledgement: The HMI uses PicoTk a great small footprint C GUI kit for embedded systems

~~DISCUSSION:closed|Leave your comments~~

[HMI Example]