1. What is OOSMOS?

OOSMOS, the Object-Oriented State Machine Operating System, implements object and state based concurrency for C/C++.

Main Features:

Hierarchical State Machine - Draw a hierarchical state chart for each of your event-driven objects using the open source drawing tool UMLet and then use the OOSMOS code generator to generate C code. Jump ahead to an example.
Object Threads - A lightweight thread that has object scope and is analogous to the async/await feature of recent versions of C# and JavaScript. Jump ahead to an example.
State Threads - Like Object Threads, but only live for the life of each state -- created on entry to a state and deleted when exiting that state. Jump ahead to an example.
Reusable Classes - Common classes found in embedded control systems are supplied. Classes like pin, button, switch, toggle, pwm, adc, pid, and more.
Portable - Runs on Arduino, ESP8266, ESP32, STM32, PIC32, TI, Windows, Linux/Raspberry Pi, etc.
Small - Core source files oosmos.h and oosmos.c total less than 1700 lines of C.
LINT - Thoroughly scrubbed using PC-LINT on OOSMOS and OOSMOS classes. We also provide an oosmos-user.lnt file with rules for applications that use OOSMOS.
It's Open Source:

Get

OOSMOS

from GitHub

2. Hierarchical State Machine Example

What follows is a complete example of an OOSMOS object and its hierarchical state machine that reacts to keystroke events. It demonstrates a feature unique to OOSMOS -- State Threads. That is, a simple thread of execution that you get for free when you enter a state. This powerful feature allows you do things that would otherwise require many states.
In the state chart below, find the Flashing state. While the object is in this state, the POLL event is called continuously by OOSMOS and the FlashingThread is serviced. Following the logic of the state chart, when either a 'b', 'r', or 'q' key is pressed, the Flashing state is exited and the thread is no longer active. State Threads can be nested in your hierarchical state charts. Note that the Flashing state is inside the Running state. Thus, both RunningThread and FlashingThread are active at the same time.
This is the code snippet for the FlashingThread function, which prints 'Flashing...' every 50 milliseconds as long as it is active (i.e., in the Flashing state.)

1
2
3
4
5
6
7
8
9
10
11

static void FlashingThread(oosmos_sState * pState)
{
oosmos_ThreadBegin();
for (;;) {
printf("Flashing...\n");
oosmos_ThreadDelayMS(50);
}
oosmos_ThreadEnd();
}

FlashingThread

2.1 State Chart That Uses State Threads

This state chart represents the exact behavior of your object and doubles as its formal behavioral requirements. Too often, projects will use a drawing tool to draw state charts intended to reflect behavior, but it doesn't reflect how the system actually behaves because code is not generated from the state chart like it is with OOSMOS.

State Chart Using Nested State Threads

2.2 Generated Code

Below is the entire .c file for the example object along with the main function that initializes and drives it. You supply the .c file with four code insertion markers into which the OOSMOS code generator injects its code from the state chart. Note: In this example, we gave the generator the debug option.
Click on the '+' signs to expand each collapsed snippet and view the generated code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
//	[GPLv2]
// OOSMOS StateTimeout Example
//
// Copyright (C) 2014-2020 OOSMOS, LLC
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, version 2 of the License ("GPLv2").
//
// This software may be used without the GPLv2 restrictions by entering
// into a commercial license agreement with OOSMOS, LLC.
// See <https://www.oosmos.com/licensing/>.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//

#include "oosmos.h"	[#includes...]
#include "pin.h"
#include "btn.h"
#include <stdbool.h>
#include <stdio.h>
#include <stdint.h>

typedef struct testTag test;

//>>>EVENTS
enum {	[Code Generated by OOSMOS]
ev_b_Pressed = 1,
ev_b_Released = 2,
ev_q_Pressed = 3,
ev_r_Pressed = 4,
ev_r_Released = 5
};

#ifdef oosmos_DEBUG
static const char * OOSMOS_EventNames(int EventCode)
{
switch (EventCode) {
case ev_b_Pressed: return "ev_b_Pressed";
case ev_b_Released: return "ev_b_Released";
case ev_q_Pressed: return "ev_q_Pressed";
case ev_r_Pressed: return "ev_r_Pressed";
case ev_r_Released: return "ev_r_Released";
default: return "";
}
}
#endif
//<<<EVENTS

typedef union {
oosmos_sEvent Event;
} uEvents;

struct testTag
{
//>>>DECL
oosmos_sStateMachine(ROOT, uEvents, 3);	[Code Generated by OOSMOS]
oosmos_sComposite Active_State;
oosmos_sComposite Active_Running_State;
oosmos_sLeaf Active_Running_Flashing_State;
oosmos_sLeaf Active_Running_Beeping_State;
oosmos_sLeaf Active_Idle_State;
oosmos_sLeaf Done_State;
//<<<DECL
};

static void RunningThread(oosmos_sState * pState)
{
oosmos_ThreadBegin();
for (;;) {
printf("RUNNING...\n");
oosmos_ThreadDelayMS(750);
}
oosmos_ThreadEnd();
}

static void FlashingThread(oosmos_sState * pState)
{
oosmos_ThreadBegin();
for (;;) {
printf("Flashing...\n");
oosmos_ThreadDelayMS(50);
}
oosmos_ThreadEnd();
}

static void BeepingThread(oosmos_sState * pState)
{
oosmos_ThreadBegin();
for (;;) {
printf("Beeping...\n");
oosmos_ThreadDelayMS(100);
}
oosmos_ThreadEnd();
}

//>>>CODE
static bool Active_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)	[Code Generated by OOSMOS]
{
test * pTest = (test *) pObject;

switch (oosmos_EventCode(pEvent)) {
case ev_q_Pressed: {
return oosmos_Transition(pTest, pState, Done_State);
}
}

return false;
}

static bool Active_Running_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
test * pTest = (test *) pObject;

switch (oosmos_EventCode(pEvent)) {
case oosmos_POLL: {
RunningThread(pState);
return true;
}
case ev_r_Released: {
return oosmos_Transition(pTest, pState, Active_Idle_State);
}
}

return false;
}

static bool Active_Idle_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
test * pTest = (test *) pObject;

switch (oosmos_EventCode(pEvent)) {
case ev_r_Pressed: {
return oosmos_Transition(pTest, pState, Active_Running_State);
}
case oosmos_ENTER: {
return oosmos_StateTimeoutSeconds(pState, (uint32_t) 7);
}
case oosmos_TIMEOUT: {
return oosmos_Transition(pTest, pState, Done_State);
}
}

return false;
}

static bool Active_Running_Flashing_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
test * pTest = (test *) pObject;

switch (oosmos_EventCode(pEvent)) {
case oosmos_POLL: {
FlashingThread(pState);
return true;
}
case ev_b_Pressed: {
return oosmos_Transition(pTest, pState, Active_Running_Beeping_State);
}
}

return false;
}

static bool Active_Running_Beeping_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
test * pTest = (test *) pObject;

switch (oosmos_EventCode(pEvent)) {
case oosmos_POLL: {
BeepingThread(pState);
return true;
}
case ev_b_Released: {
return oosmos_Transition(pTest, pState, Active_Running_Flashing_State);
}
}

return false;
}

static bool Done_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
switch (oosmos_EventCode(pEvent)) {
case oosmos_ENTER: {
printf("Terminating.\n");
oosmos_EndProgram(1);
return true;
}
}

oosmos_UNUSED(pObject);
oosmos_UNUSED(pState);
return false;
}
//<<<CODE

static test * testNew(void)
{
oosmos_Allocate(pTest, test, 1, NULL);

//>>>INIT
oosmos_StateMachineInit(pTest, ROOT, NULL, Active_State);	[Code Generated by OOSMOS]
oosmos_CompositeInit(pTest, Active_State, ROOT, Active_Idle_State, Active_State_Code);
oosmos_CompositeInit(pTest, Active_Running_State, Active_State, Active_Running_Flashing_State, Active_Running_State_Code);
oosmos_LeafInit(pTest, Active_Running_Flashing_State, Active_Running_State, Active_Running_Flashing_State_Code);
oosmos_LeafInit(pTest, Active_Running_Beeping_State, Active_Running_State, Active_Running_Beeping_State_Code);
oosmos_LeafInit(pTest, Active_Idle_State, Active_State, Active_Idle_State_Code);
oosmos_LeafInit(pTest, Done_State, ROOT, Done_State_Code);

oosmos_Debug(pTest, OOSMOS_EventNames);
//<<<INIT

return pTest;
}

extern int main(void)
{
test * pTest = testNew();

pin * p_r_Pin = pinNew('r', pinActiveHigh);
btn * p_r_Button = btnNew(p_r_Pin);
btnSubscribePressedEvent(p_r_Button, oosmos_EventQueue(pTest), ev_r_Pressed, NULL);
btnSubscribeReleasedEvent(p_r_Button, oosmos_EventQueue(pTest), ev_r_Released, NULL);

pin * p_b_Pin = pinNew('b', pinActiveHigh);
btn * p_b_Button = btnNew(p_b_Pin);
btnSubscribePressedEvent(p_b_Button, oosmos_EventQueue(pTest), ev_b_Pressed, NULL);
btnSubscribeReleasedEvent(p_b_Button, oosmos_EventQueue(pTest), ev_b_Released, NULL);

pin * p_q_Pin = pinNew('q', pinActiveHigh);
btn * p_q_Button = btnNew(p_q_Pin);
btnSubscribePressedEvent(p_q_Button, oosmos_EventQueue(pTest), ev_q_Pressed, NULL);

for (;;) {
oosmos_RunStateMachines();
oosmos_DelayMS(1);
}
}

NestedStateThreads.c

3. Object Threads Example

The following two code snippets are the interface and implementation of reusable class toggle implemented using an Object Thread.

`toggle.h`

Simple interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
//	[GPLv2]
// OOSMOS toggle Class
//
// Copyright (C) 2014-2020 OOSMOS, LLC
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, version 2 of the License ("GPLv2").
//
// This software may be used without the GPLv2 restrictions by entering
// into a commercial license agreement with OOSMOS, LLC.
// See <https://www.oosmos.com/licensing/>.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//

#ifndef toggle_h
#define toggle_h

#include "pin.h"
#include <stdint.h>

typedef struct toggleTag toggle;

extern toggle * toggleNew(pin * pPin, uint32_t TimeOnMS, uint32_t TimeOffMS);

#endif

oosmos/Classes/toggle.h

`toggle.c`

See lines 45-59 for the Object Thread's function and then lines 38 and 65 to see how to the thread is created.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
//	[GPLv2]
// OOSMOS toggle Class
//
// Copyright (C) 2014-2020 OOSMOS, LLC
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, version 2 of the License ("GPLv2").
//
// This software may be used without the GPLv2 restrictions by entering
// into a commercial license agreement with OOSMOS, LLC.
// See <https://www.oosmos.com/licensing/>.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <http://www.gnu.org/licenses/>.
//

#ifndef toggleMAX
#define toggleMAX 5
#endif

//===================================

#include "oosmos.h"
#include "toggle.h"
#include "pin.h"
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

struct toggleTag
{
oosmos_sObjectThread m_ObjectThread;

pin * m_pPin;
uint32_t m_TimeOnMS;
uint32_t m_TimeOffMS;
};

static void ToggleThread(const toggle * pToggle, oosmos_sState * pState)
{
oosmos_POINTER_GUARD(pToggle);
oosmos_POINTER_GUARD(pState);

oosmos_ThreadBegin();
for (;;) {
pinOn(pToggle->m_pPin);
oosmos_ThreadDelayMS(pToggle->m_TimeOnMS);

pinOff(pToggle->m_pPin);
oosmos_ThreadDelayMS(pToggle->m_TimeOffMS);
}
oosmos_ThreadEnd();
}

extern toggle * toggleNew(pin * pPin, uint32_t TimeOnMS, uint32_t TimeOffMS)
{
oosmos_Allocate(pToggle, toggle, toggleMAX, NULL);

oosmos_ObjectThreadInit(pToggle, m_ObjectThread, ToggleThread, true);

pToggle->m_pPin = pPin;
pToggle->m_TimeOnMS = TimeOnMS;
pToggle->m_TimeOffMS = TimeOffMS;

return pToggle;
}

oosmos/Classes/toggle.c

The underlying structure of OOSMOS threads is based on protothreads by Adam Dunkels.

4. Quick Start

4.1 On Windows

From GitHub, you can either:
- Clone the OOSMOS repository from this GitHub page.
- Visit the OOSMOS releases page and download the latest .zip file.
Build NestedStateThreads.exe following these steps:
1. Make sure that Python is installed and runnable from a command line. We use the latest version from https://www.python.org/.
2. Make sure that you have a Microsoft C/C++ compiler that can be run from a command line. We use Visual Studio Community 2019 (free) but any Microsoft compiler that can compile c99 will work.
3. Open a command line window that has the necessary environment variables to run the compiler and then change directory to oosmos\Examples\NestedStateThreads\Windows.
4. Run the build script from the command line with this command:
  python bld.py
Run NestedStateThreads.exe. Referring to the state chart above, press any of these keys: r, b, or q.
To get the full effect, press and hold the r key, then keep pressing and releasing the b key. Then release the r key.
Per the state chart, when in the Idle state, you must press the r key within 7 seconds or the program will terminate.

4.2 On an Embedded Device

Clone OOSMOS from GitHub.
Open a command line window and then change directory to oosmos.
Run populate.py. (Python must be installed.)
Change directory to oosmos\Examples\Blink.
Build one of the Blink examples using the appropriate IDE. If you would like to see other mainstream boards supported, let us know.