OOSMOS Introduction
1 Introducing OOSMOS
2 Quick Overview
2.1 Simple -- Blink
2.2 Advanced -- Async APIs
3 Benefits of OOSMOS
4 The Best Way to Learn OOSMOS
1 Introducing OOSMOS
2 Quick Overview
2.1 Simple -- Blink
2.2 Advanced -- Async APIs
3 Benefits of OOSMOS
4 The Best Way to Learn ...
1 Introducing OOSMOS
2 Quick Overview
2.1 Simple -- Blink
2.2 Advanced -- Async AP...
3 Benefits of OOSMOS
4 The Best Way to Lear...
1 Introducing OOSMOS
2 Quick Overview
2.1 Simple -- Blink
2.2 Advanced -- Async ...
3 Benefits of OOSMOS
4 The Best Way to Le...

1 Introducing OOSMOS

OOSMOS, the Object Oriented State Machine Operating System, is an open source implementation of threadless concurrency for C/C++. The portable, single-source file implementation makes it easy to integrate into any environment – from bare boards to mainframes.
Out of the box, it compiles and runs on many small processors and boards (including Arduino) as well as on Windows and Linux. It is our goal for developers of any skill level to be able to use OOSMOS effectively, whether building a science project on an Arduino or building an advanced medical device. Many examples are supplied to get you started, and more are added all the time.
Students of computer science will find that OOSMOS has many of the characteristics of the Actor Model.

2 Quick Overview

To get you started, we will show you:
  • A simple example where we blink multiple LEDs all at different rates.
  • An advanced example where we introduce you to the OOSMOS Async APIs that simplify control over the execution of asynchronous functions.
An OOSMOS program is made up of objects. Each object can have a state machine that reflects the current state of the object.
Refer to Figure 1, below, as you read the rest of this section.
Using bold red lines to reflect the current state, we see that Toggle Object A is currently in the On state and Toggle Object B is in the Off state.
OOSMOS works by "running" each object's state machine one by one - forever.
When OOSMOS runs Toggle Object A, the object "knows" that it is in the On state, and that the only way to exit the On state is when the tm(m_TimeOnMS) timeout expires. So each time this object's state machine is executed, OOSMOS checks whether the timeout has expired. If it has, the application will be sent the TIMEOUT event, where it will then call oosmos_Transition to transition from the On state to the Off state. As part of this transition, OOSMOS will call the application with the EXIT event for the On state and then the ENTER event for the Off state. If the timeout has not yet expired, no transition will occur and the state machine will remain in the On state.
To see the full Blink example, visit this page.
To see the source code for the toggle class, visit this page.
Figure 1. Snapshot of Two Running Toggle Objects

2.2 Advanced -- Async APIs

One thing that's nice about threads is that you can serialize asynchronous operations and have the thread block until each operation is complete. OOSMOS supports the same type of capability with a set of Async APIs. Simply stated, an Async API blocks the object during the execution of an asynchronous function.
Snippet 1 uses the non-blocking socket class sock to connect to a server and then, in a loop, send data to that server and then receive the data echoed back from the server all in one state.
In lines 56-58, we call the asynchronous function sockConnect under the control of Async API oosmos_AsyncWaitCond_TimeoutMS_Event . If the 2000 millisecond timeout occurs, event ConnectionTimeoutEvent will be delivered to ourselves (the current object) and handled beginning on line 82. If the sockConnect is successful, it drops through and continues with the printf on line 60.
Line 62 begins our endless send/receive loop.
On lines 66-68, we use the asynchronous function sockSend under the control of object-blocking Async API oosmos_AsyncWaitCond until the send is complete.
On lines 72-74, we receive the echoed data back using the non-blocking call sockReceive under the control of the object-blocking oosmos_AsyncWaitCond Async API.
Async APIs are described in the User's Guide and the full Sockets Example can be found in the Portfolio of Examples.
static bool Running_State_Code(void * pObject, oosmos_sRegion * pRegion, const oosmos_sEvent * pEvent)
client * pClient = (client *) pObject;
switch (pEvent->Code) {
case oosmos_INSTATE: {
const uint32_t IP_HostByteOrder = sockDotToIP_HostByteOrder(pClient->m_pHost);
oosmos_AsyncWaitCond_TimeoutMS_Event(pRegion, 2000, ConnectionTimeoutEvent,
sockConnect(pClient->m_pSock, IP_HostByteOrder, pClient->m_Port)
printf("%p: CONNECTED\n", (void *) pClient->m_pSock);
while (true) {
size_t BytesReceived;
printf("%p: Sending...\n", (void *) pClient->m_pSock);
sockSend(pClient->m_pSock, "123456", sizeof("123456"))
printf("%p: Waiting for incoming data...\n", (void *) pClient->m_pSock);
sockReceive(pClient->m_pSock, pClient->m_Buffer, sizeof(pClient->m_Buffer), &BytesReceived)
printf("%p: Client side Received '%s', BytesReceived: %u\n", (void *) pClient->m_pSock, pClient->m_Buffer, (unsigned) BytesReceived);
return true;
case ClosedEvent:
printf("Server closed. Terminating...\n");
Snippet 1. oosmos/Classes/Tests/Sockets/client.c

3 Benefits of OOSMOS

  • Ideal for:
    • Internet of Things (IOT).
    • Education - STEM.
    • The Maker movement.
    • Medical Devices.
    • Automotive.
    • Control Systems.
    • Aerospace.
    • Enterprise.
    • GUIs.
    • Robotics.
    • Basically, any event-driven system.
  • Dual License
    • Free Open Source Software (FOSS) -- GPL version 2.
    • Commercial open source license without the GPL restrictions.
  • Implemented in C, yet C++ friendly.
  • Small footprint.
  • Low CPU overhead.
  • No threads, therefore no thread stacks.
  • Promotes superior object-oriented encapsulation and information hiding.
  • Scales very well.
  • Highly efficient, constant time memory allocation for objects.
  • Powerful state machine engine.
    • Supports an unlimited number of current active timeouts.
    • Supports state aware polling.
    • Implements a set of Async APIs to control execution of asynchronous functions.
    • Supports orthogonal regions (also known as "and" states).
    • Implements UML completion semantics.
    • Supports state machine debugging.
    • Superior event management.
      • Event codes are managed locally within each object's class.
      • Events support argument passing.
      • Events use a Publish/Subscribe pattern.
      • Each object has its own event queue (if the object uses events).
  • Very portable. Tested on these environments & processors:
    • Linux. Tested on Red Hat, Ubuntu, Raspberry Pi (Raspbian) and Mac OS X (Darwin).
    • Windows. Tested with Visual Studio Express.
    • MPLAB X (any PIC32 including ChipKit).
    • Arduino (AVR, ARM).
    • ChipKit (PIC32. Use either Arduino-like IDE or MPLAB X).
    • Energia (MSP430. Use Arduino-like IDE).
    • Intel Galileo.
    • mbed (ARM. Using web based IDE).
    • MSP430. (Use Arduino-like IDE Energia).
    • LightBlue Bean.
    • ESP8266.

4 The Best Way to Learn OOSMOS

The best way to learn OOSMOS is to download and unpack the ZIP or tar.gz file, then compile one of the examples on whatever platform is readily available to you and that you are the most familiar with, then make a simple change and watch the new behavior.
It may be useful to use a Windows or Linux example to start. That way you can use any familiar source-level debugging tools to set breakpoints and display variables.
The OOSMOS User's Guide goes over all the concepts and techniques for using OOSMOS effectively, and the OOSMOS API Reference provides a quick lookup for all OOSMOS calls and macros.
Copyright © 2014-2016  OOSMOS, LLC