"A behavioral description of a system specifies dynamic aspects of the entire system or of a particular function, including control and timming. It specifies the states and modes that the system might reside in and the transitions between them. It also describes what causes activities to start and stop, and the way the system reacts to various events. A natural technique for describing the dynamic of a system is to use a finite state machine. The described system of function is always in one of a finite set of states. When an event occurrs, the system reacts by performing actions. The events causing the reaction are called triggers."

David Harel

This manual includes:

Overview

RKH (Reactive frameworK for Hierarchical state machines) is a framework used to build software for reactive and real-time embedded systems in a safely and timely way. It is composed of modules, procedures and supporting tools; such as a method for implementing and executing flat and Statechart state machines, asynchronous and synchronous messaging, cross-platform abstraction, runtime tracing, time management, dynamic memory mechanism to deal with fragmentation, unit test harness, among others. These elements make up the needed infrastructure to build apps in embedded systems.

Frequently, real-time embedded system’s development is slow, error-prone, and hard. Thanks to the use of RKH, this has been greatly improved. RKH enables higher quality and functionality, and decreases the development time. Since common software infrastructure do not have to be reimplemented, there is no need to reinvent the wheel over and over again.

Moreover, by using RKH, developers can build softwares in a user-friendly, well-defined, formal and structured environment. This is achieved because RKH's infrastructure enables them to code using event-driven programming paradigm.

Due to its event-driven nature, a state machine is usually employed to represent the dynamic behaviour of a reactive application. That is why RKH provides a powerful and efficient module for building and executing state machines. It almost entirely supports UML state machines semantics, which are based on David Harel’s statechart formalism.

RKH also provides the complete infrastructure for the execution of state machines which supports both synchronous and asynchronous event triggers. In the case of the asynchronous event triggers, the state machine is executed according to the Active Object execution model which is the UML concurrency unit. In RKH framework, an Active Object can be made up by one or more state machines.

RKH not only enables to develop a reactive application from the ground up, but also to reinforce the reactive part of an existing functional application.

RKH includes a platform abstraction layer (PAL) which allows the framework to be portable. By allowing the PAL to be replaced, the framework can be easily ported to different target platforms. The PAL contains the abstraction of operating system, compiler, IDE and hardware components.

RKH allows developers to verify and validate the reactive application’s behaviour at runtime by means of its built-in tracer, which is a flexible, configurable and cross-platform software module. In addition, RKH provides a very simple but powerful console application to visualize the trace events’ output in a legible manner. Since RKH has been carefully developed from the ground up by using best principles and practices of software engineering, such as OOD (Object-Oriented Design), software modeling, design patterns, TDD (Test-Driven Development), continuous integration, among others; it is considered a safe, flexible, maintainable, and reusable software.

In conclusion, RKH is a framework that provides the infrastructure for the quick and safe development of reactive applications for real-time embedded systems. It supplies an efficient method for both implementing and executing Statecharts. It also encourages the embedded software community to apply best principles and practices of software engineering for building flexible, maintainable and reusable software. And finally, RKH improves embedded softwares by increasing their quality and functionality and decreased their development time.

The key features of the RKH framework:

State machines representation is based on state tables.
Representing a state machine with RKH is intuitive, and easy.
Reflects the state diagram without obfuscation.
The RKH application are highly maintainable.
Easy to integrate with any event queuing and dispatching mechanism.
Useful in embedded systems.
The most of the RKH implementation is independent of any particular CPU, operating system, or compiler.
Flexible and user-configurable code generation.
Very small footprint.
Include a dispatching event mechanism based on active object's priority.
Include a queue module
Include a software timer module .
Include a fixed-size memory block module .
Include a native Tracing tool.
Support hierarchically nested states, and flat state machine.
Support multiple state machines.
Support conditional, choice, and history pseudostates.
Support compound transitions with guards.
Support submachine state.
Support local transitions.
Support the entry and exit actions.
Implement the traditional transition sequence.
Include mechanism for deferring events.
Support event dispatching with parameters.
Include dynamic events.
Support a easy way to use events with arguments.
Support systems-friendly assertion macros like assert, allege, error, require, and ensure.

Structure

As shown in the diagram below, the RKH framework has a layered structure.

Purpose and inspiration

For many years, I had been used the traditional state machine concepts based on state table strategy for modeling the dynamic behavior of several reactive-systems, in many industries. Over the years, this implementation was expanding its abilities to support system requirements increasingly complex, achieving hierarchically nested states, pseudostates, compound transitions, and more, proposed by Harel Statecharts.

The RKH not implements neither entire UML specs. nor entire Statechart specs. Instead, the RKH intention is to support just enough basic concepts of that powerful tools to facilitate the reactive-system modeling holding a solid, and efficient implementation. Broadly speaking, the RKH implementation has been designed from the ground up to be used in 8-bits platforms but can be easily adapted to 16 or 32-bits platforms.

Download

RKH download: https://github.com/vortexmakes/RKH/releases

Examples

Repo rkh-examples contains a collection of open source examples based on RKH framework to develop embedded software for several platforms. In this context, it refers to combination of CPU architecture, compiler or IDE, and operating system. Also, rkh-examples includes some demostrative and cross-platform applications running under Windows and Linux to improve and fast development cycle.

Other embedded applications based on RKH framework

Spora: open source project to build wearables.
DIMBA: IoT application, using MQTT protocol over GSM network.
YipiesAgro: IoT application, for precision agriculture.

How to collaborate on RKH?

Would you like to collaborate with RKH? Great, go ahead!. First of all, you must get the project from its official repository:

$ git clone –recurse-submodules https://github.com/vortexmakes/RKH

Then, you are ready to share your bug fixes and improvements with other users. Your contributions may enhance your professional training and increase your skills about embedded software development, specially in responsive systems. As a means of keeping a code quality, we strongly recommend you to use the ‘pull request’ mechanism to include your contributions. Once a pull request is opened, you will be able to discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. You can also use the test harness that RKH provides. If you are interested in collaborating with the project but you have not made any specific contribution yet, there is a list of desirable features available. In this way, you will be able to be part of the framework. By using a feature from the list, you can both develop and include it to the project. That is why, our goal is that you can easily join the RKH’s developer community.

Licensing

RKH is distributed under the terms of the GNU General Public License v3.0 with the following clarification and special exception.

Linking this framework statically or dynamically with other modules is making a combined work based on this framework. Thus, the terms and conditions of the GNU General Public License cover the whole combination.

As a special exception, the copyright holders of this framework give you permission to link this framework with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this framework. If you modify this framework, you may extend this exception to your version of the framework, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Licensing scheme

GPLv3 + linking exception license, which will allow a customer to link proprietary source code. Observe that, the GPLv3 can be used for research & development and educational purposes (academic purposes).
Commercial license, when the source code of your application should not be published under the GNU GPLv3 license (closed source code), please, contact us. See Contact information section.

Why does RKH use the GPL?

RKH is licensed under terms of GPL, since its main goal is to grant everyone the freedom to copy, redistribute, understand, and modify a program. A crucial aspect of free software is that users are free to cooperate. It is absolutely essential to permit users, who wish to help each other, to share their bug fixes and improvements with other users. For this reason, RKH’s goal is to be a free software; as FSF says, ‘Free software is a matter of liberty, not of price’.

Contact information

RKH site: http://vortexmakes.com/que-es/ RKH GitHub: https://github.com/vortexmakes/RKH RKH Sourceforge: https://sourceforge.net/projects/rkh-reactivesys/
e-mail: lf@vo.nosp@m.rtex.nosp@m.makes.nosp@m..com

Resources

M. Samek - "Practical UML Statecharts in C/C++, Second Edition: Event-Driven Programming for Embedded Systems", http://www.state-machine.com/psicc2/
M. Samek and P. Montgomery - "State-Oriented Programming", http://www.embedded.com/2000/0008/0008feat1.htm
D. Harel - "Statecharts: A Visual Formalism for Complex Systems", Sci. Comput. Programming 8 (1987), 231-274.
D. Harel and A. Pnueli - "On the Development of Reactive Systems", in Logics and Models of Concurrent Systems (K. R. Apt, ed.), NATO ASI Series, Vol. F-13, Springer-Verlag, New York, 1985, pp. 477-498.
D. Harel - "On Visual Formalisms", Comm. Assoc. Comput. Mach. 31:5 (1988), 514-530.
D. Harel and A. Naamad - "The STATEMATE Semantics of Statecharts", ACM Trans. on Software Engineering Method. 5:4 (October 1996), 293-333.
D. Harel and H. Kugler - "The Rhapsody Semantics of Statecharts", Lecture Notes in Computer Science, Vol. 3147, Springer-Verlag, 2004, pp. 325-354

Other implementations

Open-source frameworks that support Statecharts.

Quantum Leap - http://www.state-machine.com/

Acknowlegments

I would like to thank to Eduardo Martinez for introducing me to the reactive systems problems and Dario Balina for they suggestions, they time, and constructive criticism during lengthy period in which the RKH project was being developed.

Table of Contents