StateMachine
The MARTe StateMachine components allows to associate the sending of Messages to events.
Each state contains one, or more, StateMachineEvent elements. The StateMachine can be in one (and only one) state at a given time.
The StateMachine is a key component which is used in many MARTe applications to synchronise the application state against the external environment.
Upon receiving of a Message, the StateMachine will verify if the Message function (see GetFunction) is equal to the name of any of the declared StateMachineEvent elements for the current StateMachine state. If it is, the StateMachine will change to the declared state and trigger any messages associated to this transition.
Note
If a state change requests arrives while the state is being changed, this request will be queued and served once the previous state transition is completed.
Configuration
Each state is declared as a ReferenceContainer of StateMachineEvent elements.
+StateMachine = {
Class = StateMachine
+STATE1 = {
Class = ReferenceContainer
+GOTOSTATE2 = {
Class = StateMachineEvent
...
}
+ERROR = {
Class = StateMachineEvent
...
}
...
}
+STATE2 = {
Class = ReferenceContainer
+GOTOSTATE1 = {
Class = StateMachineEvent
...
}
+ERROR = {
Class = StateMachineEvent
...
}
...
}
Each StateMachineEvent contains the NextState (where to go), the NextStateError (where to go in case of any error while sending the messages) and one or more messages to be sent when the event is triggered.
+StateMachine = {
Class = StateMachine
+STATE1 = {
Class = ReferenceContainer
+GOTOSTATE2 = {
Class = StateMachineEvent
NextState = "STATE2"
NextStateError = "ERROR"
Timeout = 0
+DoSomething = {
Class = Message
Destination = Receiver1
Mode = ExpectsReply
Function = Function1
+Parameters = {
Class = ConfigurationDatabase
param1 = 2
param2 = 3.14
}
}
+DoSomethingElse = {
Class = Message
Destination = Receiver1
Mode = ExpectsReply
Function = Function0
}
}
+GOTOSTATE3 = {
Class = StateMachineEvent
NextState = "STATE3"
NextStateError = "ERROR"
Timeout = 0
+DoSomething = {
Class = Message
Destination = Receiver1
Mode = ExpectsReply
Function = Function1
+Parameters = {
Class = ConfigurationDatabase
param1 = 4
param2 = 5.312
}
}
}
...
Note
The StateMachine is not compatible with the usage of the GAMBareScheduler for more than two states. The first state being the state started in and then the second being the next state. This is because the StartNextExecution function of the GAMBareScheduler is a non-returning infinite while loop and stalls the StateMachine at the state transition point while executing the second state.
The Timeout parameter sets the maximum amount of time allowed for the state transition (including waiting for all the requested replies to arrive). An infinite timeout is defined with a value of 0.
Note
The message replies can be used to guarantee that the state transitions only complete when given events occur/complete.
If an event named ENTER of type ReferenceContainer exists, all of its contained messages will be triggered when entering the state.
+StateMachine = {
Class = StateMachine
+STATE1 = {
Class = ReferenceContainer
+ENTER = {
Class = ReferenceContainer
+DoSomethingWhenEntering = {
Class = Message
Destination = Receiver1
Mode = ExpectsReply
Function = Function1
+Parameters = {
Class = ConfigurationDatabase
param1 = 4
param2 = 5.312
}
}
+DoSomethingElseWhenEntering = {
Class = Message
Destination = Receiver2
Mode = ExpectsReply
Function = Function1
+Parameters = {
Class = ConfigurationDatabase
param1 = 8
param2 = -5.312
}
}
}
+GOTOSTATE2 = {
Class = StateMachineEvent
...
Examples
The following is an example which shows how a state machine can be used to trigger remote function calls:
Example of a StateMachine receiving and triggering messages.
1/**
2 * @file StateMachineExample1.cpp
3 * @brief Source file for class StateMachineExample1
4 * @date 25/04/2018
5 * @author Andre Neto
6 *
7 * @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
8 * the Development of Fusion Energy ('Fusion for Energy').
9 * Licensed under the EUPL, Version 1.1 or - as soon they will be approved
10 * by the European Commission - subsequent versions of the EUPL (the "Licence")
11 * You may not use this work except in compliance with the Licence.
12 * You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
13 *
14 * @warning Unless required by applicable law or agreed to in writing,
15 * software distributed under the Licence is distributed on an "AS IS"
16 * basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
17 * or implied. See the Licence permissions and limitations under the Licence.
18
19 * @details This source file contains the definition of all the methods for
20 * the class StateMachineExample1 (public, protected, and private). Be aware that some
21 * methods, such as those inline could be defined on the header file, instead.
22 */
23#define DLL_API
24/*---------------------------------------------------------------------------*/
25/* Standard header includes */
26/*---------------------------------------------------------------------------*/
27
28/*---------------------------------------------------------------------------*/
29/* Project header includes */
30/*---------------------------------------------------------------------------*/
31#include "AdvancedErrorManagement.h"
32#include "CLASSMETHODREGISTER.h"
33#include "ConfigurationDatabase.h"
34#include "ErrorLoggerExample.h"
35#include "ObjectRegistryDatabase.h"
36#include "RegisteredMethodsMessageFilter.h"
37#include "StandardParser.h"
38#include "StateMachine.h"
39
40/*---------------------------------------------------------------------------*/
41/* Static definitions */
42/*---------------------------------------------------------------------------*/
43
44namespace MARTe2Tutorial {
45
46/**
47 * @brief A MARTe::Object class that registers a set of RPC functions that can be called
48 * with messages.
49 */
50class MessageReceiverEx1: public MARTe::Object, public MARTe::MessageI {
51public:
52 CLASS_REGISTER_DECLARATION()
53
54 /**
55 * @brief Install the RegisteredMethodsMessageFilter filter.
56 */
57MessageReceiverEx1 () : MARTe::Object(), MARTe::MessageI() {
58 using namespace MARTe;
59 filter = ReferenceT<RegisteredMethodsMessageFilter>(GlobalObjectsDatabase::Instance()->GetStandardHeap());
60 filter->SetDestination(this);
61 MessageI::InstallMessageFilter(filter);
62 fun0Called = false;
63 fun1Called = false;
64 fun2Called = false;
65 fun3Called = false;
66 }
67
68 virtual ~MessageReceiverEx1 () {
69 if (GetName() != NULL) {
70 REPORT_ERROR_STATIC(MARTe::ErrorManagement::Information, "No more references pointing at %s [%s]. "
71 "The Object will be safely deleted.", GetName(), GetClassProperties()->GetName());
72 }
73 }
74
75 virtual void Purge(MARTe::ReferenceContainer &purgeList) {
76 RemoveMessageFilter(filter);
77 }
78
79 MARTe::ErrorManagement::ErrorType Function0 () {
80 REPORT_ERROR_STATIC(MARTe::ErrorManagement::Information, "Function0 called.");
81 fun0Called = true;
82 return MARTe::ErrorManagement::NoError;
83 }
84
85 MARTe::ErrorManagement::ErrorType Function1 (MARTe::uint32 a, MARTe::float32 b) {
86 REPORT_ERROR_STATIC(MARTe::ErrorManagement::Information, "Received %u %f.", a, b);
87 fun1Called = true;
88 return MARTe::ErrorManagement::NoError;
89 }
90
91 MARTe::ErrorManagement::ErrorType Function2 (MARTe::int32 a, MARTe::float32 b, MARTe::uint32 c) {
92 REPORT_ERROR_STATIC(MARTe::ErrorManagement::Information, "Received %u %f %u.", a, b,c);
93 fun2Called = true;
94 return MARTe::ErrorManagement::NoError;
95 }
96
97 MARTe::ErrorManagement::ErrorType Function3 (MARTe::StreamString a) {
98 REPORT_ERROR_STATIC(MARTe::ErrorManagement::Information, "Received %s.", a.Buffer());
99 fun3Called = true;
100 return MARTe::ErrorManagement::NoError;
101 }
102
103 bool fun0Called;
104 bool fun1Called;
105 bool fun2Called;
106 bool fun3Called;
107
108private:
109 MARTe::ReferenceT<MARTe::RegisteredMethodsMessageFilter> filter;
110};
111
112CLASS_REGISTER(MessageReceiverEx1, "")
113CLASS_METHOD_REGISTER(MessageReceiverEx1, Function0)
114CLASS_METHOD_REGISTER(MessageReceiverEx1, Function1)
115CLASS_METHOD_REGISTER(MessageReceiverEx1, Function2)
116CLASS_METHOD_REGISTER(MessageReceiverEx1, Function3)
117
118}
119/*---------------------------------------------------------------------------*/
120/* Method definitions */
121/*---------------------------------------------------------------------------*/
122
123int main(int argc, char **argv) {
124 using namespace MARTe;
125 using namespace MARTe2Tutorial;
126 SetErrorProcessFunction(&ErrorProcessExampleFunction);
127
128 StreamString configurationCfg = ""
129 "+Receiver1 = {\n"
130 " Class = MessageReceiverEx1\n"
131 "}\n"
132 "+Receiver2 = {\n"
133 " Class = MessageReceiverEx1\n"
134 "}\n"
135 "+StateMachineExample1 = {\n"
136 " Class = StateMachine\n"
137 " +STATE1 = {\n"
138 " Class = ReferenceContainer\n"
139 " +GOTOSTATE2 = {\n"
140 " Class = StateMachineEvent\n"
141 " NextState = \"STATE2\"\n"
142 " NextStateError = \"STATE1\"\n"
143 " Timeout = 0\n"
144 " +DoSomethingOnRec1 = {\n"
145 " Class = Message\n"
146 " Destination = Receiver1\n"
147 " Mode = ExpectsReply\n"
148 " Function = Function1\n"
149 " +Parameters = {\n"
150 " Class = ConfigurationDatabase\n"
151 " param1 = 2\n"
152 " param2 = 3.14\n"
153 " }\n"
154 " }\n"
155 " +DoSomethingElseOnRec1 = {\n"
156 " Class = Message\n"
157 " Destination = Receiver1\n"
158 " Mode = ExpectsReply\n"
159 " Function = Function0\n"
160 " }\n"
161 " }\n"
162 " +GOTOSTATE3 = {\n"
163 " Class = StateMachineEvent\n"
164 " NextState = \"STATE3\"\n"
165 " NextStateError = \"STATE1\"\n"
166 " Timeout = 0\n"
167 " +DoSomethingOnRec2 = {\n"
168 " Class = Message\n"
169 " Destination = \"Receiver1\"\n"
170 " Mode = ExpectsReply\n"
171 " Function = Function1\n"
172 " +Parameters = {\n"
173 " Class = ConfigurationDatabase\n"
174 " param1 = 2\n"
175 " param2 = 3.14\n"
176 " }\n"
177 " }\n"
178 " +DoSomethingElseOnRec2 = {\n"
179 " Class = Message\n"
180 " Destination = \"Receiver2\"\n"
181 " Mode = ExpectsReply\n"
182 " Function = Function0\n"
183 " }\n"
184 " }\n"
185 " }\n"
186 " +STATE2 = {\n"
187 " Class = ReferenceContainer\n"
188 " +GOTOSTATE1 = {\n"
189 " Class = StateMachineEvent\n"
190 " NextState = \"STATE1\"\n"
191 " NextStateError = \"STATE1\"\n"
192 " Timeout = 0\n"
193 " +DoSomethingOnRec1 = {\n"
194 " Class = Message\n"
195 " Destination = Receiver1\n"
196 " Mode = ExpectsReply\n"
197 " Function = Function3\n"
198 " +Parameters = {\n"
199 " Class = ConfigurationDatabase\n"
200 " param1 = \"BACKTOSTATE1!\"\n"
201 " }\n"
202 " }\n"
203 " }\n"
204 " }\n"
205 " +STATE3 = {\n"
206 " Class = ReferenceContainer\n"
207 " +ENTER = {\n"
208 " Class = ReferenceContainer\n"
209 " +DoSomethingOnRec1 = {\n"
210 " Class = Message\n"
211 " Destination = Receiver1\n"
212 " Mode = ExpectsReply\n"
213 " Function = Function2\n"
214 " +Parameters = {\n"
215 " Class = ConfigurationDatabase\n"
216 " param1 = 1"
217 " param2 = 2"
218 " param3 = 3"
219 " }\n"
220 " }\n"
221 " }"
222 " +GOTOSTATE2 = {\n"
223 " Class = StateMachineEvent\n"
224 " NextState = \"STATE2\"\n"
225 " NextStateError = \"STATE2\"\n"
226 " Timeout = 0\n"
227 " +DoSomethingOnRec2 = {\n"
228 " Class = Message\n"
229 " Destination = Receiver2\n"
230 " Mode = ExpectsReply\n"
231 " Function = Function3\n"
232 " +Parameters = {\n"
233 " Class = ConfigurationDatabase\n"
234 " param1 = \"BACKTOSTATE2!\"\n"
235 " }\n"
236 " }\n"
237 " }\n"
238 " }\n"
239 "}\n";
240
241 REPORT_ERROR_STATIC(ErrorManagement::Information, "Loading CFG:\n%s", configurationCfg.Buffer());
242 ConfigurationDatabase cdb;
243 StreamString err;
244 //Force the string to be seeked to the beginning.
245 configurationCfg.Seek(0LLU);
246 StandardParser parser(configurationCfg, cdb, &err);
247 bool ok = parser.Parse();
248 ObjectRegistryDatabase *ord = ObjectRegistryDatabase::Instance();
249 if (ok) {
250 //After parsing the tree is pointing at the last leaf
251 cdb.MoveToRoot();
252 ok = ord->Initialise(cdb);
253 }
254 else {
255 StreamString errPrint;
256 errPrint.Printf("Failed to parse %s", err.Buffer());
257 REPORT_ERROR_STATIC(ErrorManagement::ParametersError, errPrint.Buffer());
258 }
259 ReferenceT<MessageReceiverEx1> rec1 = ord->Find("Receiver1");
260 ReferenceT<MessageReceiverEx1> rec2 = ord->Find("Receiver2");
261
262 //Send a message to the state machine
263 ReferenceT<Message> msg1(GlobalObjectsDatabase::Instance()->GetStandardHeap());
264 ConfigurationDatabase msg1Cdb;
265 msg1Cdb.Write("Destination", "StateMachineExample1");
266 msg1Cdb.Write("Function", "GOTOSTATE3");
267 msg1->Initialise(msg1Cdb);
268 MessageI::SendMessage(msg1, NULL);
269
270 while (!rec2->fun0Called) {
271 Sleep::Sec(0.1);
272 }
273
274 ReferenceT<Message> msg2(GlobalObjectsDatabase::Instance()->GetStandardHeap());
275 ConfigurationDatabase msg2Cdb;
276 msg2Cdb.Write("Destination", "StateMachineExample1");
277 msg2Cdb.Write("Function", "GOTOSTATE2");
278 msg2->Initialise(msg2Cdb);
279 MessageI::SendMessage(msg2, NULL);
280
281 while (!rec2->fun3Called) {
282 Sleep::Sec(0.1);
283 }
284
285 ReferenceT<Message> msg3(GlobalObjectsDatabase::Instance()->GetStandardHeap());
286 ConfigurationDatabase msg3Cdb;
287 msg3Cdb.Write("Destination", "StateMachineExample1");
288 msg3Cdb.Write("Function", "GOTOSTATE1");
289 msg3->Initialise(msg3Cdb);
290 MessageI::SendMessage(msg3, NULL);
291
292 while (!rec1->fun3Called) {
293 Sleep::Sec(0.1);
294 }
295 //Purge all the Objects!
296 ObjectRegistryDatabase::Instance()->Purge();
297 return 0;
298}
Instructions on how to compile and execute the examples can be found here.