The following are the coding conventions used to develop OOSMOS and the examples. We strongly recommend that you use them as well, even for non-OOSMOS projects, where applicable.

1. Naming Conventions

1.1 Class Member Prefix

The name of each member of a class is prefixed with 'm_'.

1
2
3
4
5
6
7
8

struct pinTag
{
pin_eLogic m_Logic;
unsigned m_MemberA;
unsigned m_MemberB;
};

Member Name Examples

1.2 Pointer Prefix

Names of pointer variables are prefixed with a lowercase 'p'.

1
2
3
4
5

char * pString = "abc";

char Char = *pString;

Pointer Prefix Example

1.3 Enumeration Type Prefix

Names of enumeration types are prefixed with a lowercase 'e'.

1
2
3
4
5
6
7

typedef enum
{
evPressed = 1,
evReleased
} eStates;

Enumeration Type

1.4 External Name Prefixes and Filenames

We follow these important rules for externally visible names:

Carefully choose short, descriptive filenames.
Prefix every externally visible name with the root of that filename.
The filename also becomes the type name of the object.

1
2
3
4
5
6
7

//
// The filenames are 'pin.h' and 'pin.c', therefore the
// main type of the object is 'pin'.
//
typedef struct pinTag pin;

Interface in pin.h File

1
2
3
4
5
6
7
8
9
10
11
12
13
14

struct pinTag
{
// Member declarations...
};

extern pin * pinNew()
{
static pin Pins[1];
pin * pPin = Pins;

return pPin;
}

Implementation in pin.c File

1.5 Explicit Linkage Specification

We always specify the linkage for file scope names, using static for internal linkage and extern for external linkage, even though extern is the default linkage, we still specify it for consistency and clarity.
Note that using the static keyword at file scope keeps a name local to the file and thus prevents polluting the global namespace. Also note that because static symbols are local to the file, they don't need the filename root prefix.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

//
// The name 'Internal' has internal linkage and does not
// require the filename prefix.
//
static pin * Internal()
{
static pin PinList[1];
return PinList;
}

//
// The name 'pinNew' has external linkage, thus requires the
// filename prefix.
//
extern pin * pinNew()
{
return Internal();
}

Implementation in pin.c File

1.6 State Thread and Polling Function Names

While you are in a state, an oosmos_POLL event is called as fast as the OOSMOS control loop can call it. You can either do work at that rate, or call a state thread function that does sequential work. If you do call a state thread function, we recommend suffixing the state thread name with the string Thread. For example:

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
//	[...]
// 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"
#include "pin.h"
#include "btn.h"
#include <stdbool.h>
#include <stdio.h>
#include <stdint.h>

typedef struct testTag test;

//>>>EVENTS
enum {
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);
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)
{
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);
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

If you are not going to call a state thread during an oosmos_POLL event, then we recommend calling a function that ends with the string Poll instead.

2. Enumerators

Unless there is a compelling reason to do otherwise, we do not let the first enumerator default to zero. This is a defensive programming technique.

1
2
3
4
5
6
7

typedef enum
{
pinActiveHigh = 1,
pinActiveLow
} pin_eLogic;

Safe Enumerations

3. Constants vs. Variables

We distinguish between variables and constants. Variables, as the name indicates, can vary (be changed). Names that are declared const cannot (once they are initially assigned). We feel that it is good programming practice to make the distinction as it tells your reader something they would have to discover by reading the rest of the code. Further, depending on the compiler, local names that are declared const may not actually be materialized and thus may take no memory space.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

static void InterrogateColumns(matrix * pMatrix)
{
const unsigned RowIndex = pMatrix->m_CurrentRowIndex;
const unsigned Columns = pMatrix->m_Columns;

for (unsigned ColumnIndex = 0; ColumnIndex < Columns; ColumnIndex++) {
sw * pSwitch = pMatrix->m_pSwitch[RowIndex][ColumnIndex];

if (pSwitch == NULL) {
continue;
}

swRunStateMachine(pSwitch);
}
}

Use of the const keyword

4. Program Organization

We use the following program structure for OOSMOS programs.

4.1 File Structure

An OOSMOS object should have two files: an interface file in a .h file and an implementation file in either a .c or .cpp file depending on your environment.
Refer to the following two code blocks and expand them to view the underlying 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
//	[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	[Multiple Inclusion Check Begin]...
#define toggle_h

#include "pin.h"	[#includes]...
#include <stdint.h>

typedef struct toggleTag toggle;	[Class Type Declaration]...

extern toggle * toggleNew(pin * pPin, uint32_t TimeOnMS, uint32_t TimeOffMS);	[Interface Prototypes]...

#endif	[Multiple Inclusion Check End]...

Interface (toggle.h)

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
//	[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/>.
//

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

#ifndef toggleMAX	[Object Allocation Configuration]...
#define toggleMAX 4
#endif

struct toggleTag	[Class Type Definition]...
{
//>>>DECL
oosmos_sStateMachineNoQueue(ROOT);
oosmos_sLeaf Off_State;
oosmos_sLeaf On_State;
//<<<DECL

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

//>>>CODE
static bool Off_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)	[Generated Functions]...
{
toggle * pToggle = (toggle *) pObject;

switch (oosmos_EventCode(pEvent)) {
case oosmos_ENTER: {
return oosmos_StateTimeoutMS(pState, (uint32_t) pToggle->m_TimeOffMS);
}
case oosmos_TIMEOUT: {
return oosmos_Transition(pToggle, pState, On_State);
}
}

return false;
}

static bool On_State_Code(void * pObject, oosmos_sState * pState, const oosmos_sEvent * pEvent)
{
toggle * pToggle = (toggle *) pObject;

switch (oosmos_EventCode(pEvent)) {
case oosmos_ENTER: {
pinOn(pToggle->m_pPin);
return oosmos_StateTimeoutMS(pState, (uint32_t) pToggle->m_TimeOnMS);
}
case oosmos_EXIT: {
pinOff(pToggle->m_pPin);
return true;
}
case oosmos_TIMEOUT: {
return oosmos_Transition(pToggle, pState, Off_State);
}
}

return false;
}
//<<<CODE

extern toggle * toggleNew(pin * pPin, uint32_t TimeOnMS, uint32_t TimeOffMS)	[External Functions]...
{
oosmos_Allocate(pToggle, toggle, toggleMAX, NULL);

//>>>INIT
oosmos_StateMachineInitNoQueue(pToggle, ROOT, NULL, On_State);
oosmos_LeafInit(pToggle, Off_State, ROOT, Off_State_Code);
oosmos_LeafInit(pToggle, On_State, ROOT, On_State_Code);
//<<<INIT

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

return pToggle;
}

Implementation (toggle_state.c or toggle_state.cpp)

4.2 Object Allocation Structure

The next two code blocks show in more detail how to organize your code in order to declare, allocate and initialize an object. In this case, a toggle object.

1
2
3
4
5
6
7
8
9
10
struct toggleTag
{
oosmos_sStateMachineNoQueue(StateMachine);	[State Machine Declaration]...
oosmos_sLeaf On_State;
oosmos_sLeaf Off_State;

pin * m_pPin;	[Member Declarations]...
uint32_t m_TimeOnMS;
uint32_t m_TimeOffMS;
};

Type Declaration Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
extern toggle * toggleNew(pin * pPin, const unsigned TimeOnMS, const unsigned TimeOffMS)
{
oosmos_Allocate(pToggle, toggle, toggleMAX, NULL);	[Object Allocation]...

// StateName Parent	[State Machine Initialization]...
// ================================================
oosmos_StateMachineInitNoQueue(pToggle, ROOT, NULL, On_State );
oosmos_LeafInit (pToggle, On_State, ROOT, On_State_Code );
oosmos_LeafInit (pToggle, Off_State, ROOT, Off_State_Code);

pToggle->m_pPin = pPin;	[Member Initialization]...
pToggle->m_TimeOnMS = TimeOnMS;
pToggle->m_TimeOffMS = TimeOffMS;

return pToggle;	[Return Object Pointer]...
}

Object Allocation and Initialization

5. OOSMOS Encapsulation

OOSMOS is written in C, a non-object-oriented language, yet OOSMOS promotes one of the most important elements of object-oriented programming: encapsulation. In fact, we contend that what is presented here is a form of encapsulation that is superior to what can be achieved by classically programmed C++. We call it the OOSMOS encapsulation pattern.

Refer to Figure 1 as we cover the following four areas of the pattern:

File naming conventions.
Type declarations and information hiding.
Names and name visibility.
Object allocation.

5.1 File Naming Conventions

An OOSMOS object is always made up of a .h file that holds the interface and a .c file that holds the implementation. We use short yet descriptive names for these files. The names must be all lowercase. It is important to choose these names wisely because they have a greater role to play in the pattern — they are also used to form all external names of the object. See the section below on Names and Name Visibility.

5.2 Type Declarations and Information Hiding

The object's type name must be the root filename of the object. In this case, sample.
To implement this pattern, we use the incomplete type capability of C, declaring sample like this:

1
2
3

typedef struct sampleTag sample;

Snippet 1. sample.h

Because the content of struct sample is not yet defined, its size is not known, so users of the sample interface can only work with pointers to sample returned from sampleNew.
The completion of type sample is hidden in the implementation file sample.c. (See Snippet 2.)

1
2
3
4
5
6
7
8

struct sampleTag
{
// Declare class members.

unsigned m_Temperature;
};

Snippet 2. sample.c

5.3 Names and Name Visibility

Every external name that you declare in the object's header file must be prefixed with the root of the object's filename. For example, from Figure 1, we see that sampleGetTemp and sampleNew both begin with the filename root sample. Additionally, the name of the object's type must be the filename root. In this example, sample.

5.4 Object Allocation

Because only an incomplete type is declared in the interface, the user cannot allocate an object directly. Instead, they must call the object's "New" function. In this case sampleNew. This will return a pointer to a sample object that the user can then pass as the "this" pointer to methods that require access to the object. See sampleGetTemp on line 18 as an example.

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
#include "sample.h"
#include "oosmos.h"
#include <stdint.h>

struct sampleTag	struct sampleTag {...}
{
// Declare class members.

uint32_t m_Temperature;
};

static int LocalConstant = 42;	[File-local symbols]...

static void LocalFunc(sample * pSample, const int Arg)
{
}

extern int sampleGetTemp(sample * pSample)
{
LocalFunc(pSample, 10);
return pSample->m_Temperature;
}

extern sample * sampleNew(void)
{
oosmos_Allocate(pSample, sample, 3, NULL)

// Initialize members of the allocated object...

pSample->m_Temperature = 0;
return pSample;
}

sample.c

6. Perspective On Encapsulation

Figure 1. Perspective on Encapsulation