Blinky LED for RKH framework on Linux

Overview

This is a simple example of how to use the RKH framework together with Yakindu Statechart Tool, since it provides a RKH specific C code generator for statecharts.

The behavior of blinky is defined by a simple statechart that looks as follows.

What RKH is?

RKH is a flexible, efficient, highly portable, and freely available open-source state machine framework providing the infrastructure for quickly and safely developing reactive applications for real-time embedded systems.

RKH provides not only an unusual, efficient and straightforward method for implementing and executing state machines, but also the needed infrastructure to build reactive applications in embedded systems. It is composed of modules, procedures, and supporting tools; such as a method for implementing and executing flat state machines and statecharts, asynchronous messaging, cross-platform abstraction, run time tracing, time management, dynamic memory mechanism to deal with fragmentation, unit-test harness, plus others.

RKH allows developers to verify and validate a reactive application’s behaviour at runtime by means of the framework’s built-in tracer. It can utilize any traditional OS/RTOS or work without one. It also encourages the embedded software community to apply best principles and practices of software engineering for building flexible, maintainable and reusable software.

RKH is open source and licensed under the GNU v3.0. You can find the source code on GitHub.

If you want to learn more about the benefits of this flexible, efficient and highly portable state machine framework read on here.

Setup

In order to run and verify this example you have to download the RKH framework, install both Trazer tool and RKH code generator.

Get RKH framework

RKH can be obtained from its official repository by using the following Git commands:

1. cd path/to/org.yakindu.sct.examples.rkh.blinky/
2. git clone https://github.com/vortexmakes/RKH.git

Refresh your project after cloning. Right click the project and click on Refresh. Otherwise the project will not compile.

Install Trazer tool

RKH allows developers to verify and validate a reactive application’s behaviour at runtime by means of its built-in tracer. In addition, RKH provides a very simple but powerful console application, called Trazer, to visualize the trace events’ output in a legible manner. It can be downloaded and installed as follows.

1. Download Trazer for Linux 64-bits from its official repository
2. Copy downloaded file to a folder and extract it
3. Change the directory to previous folder
4. Check it is alright by executing ./trazer

Install RKH code generator

If code generation does not work and Yakindu shows error markers on the model/Blinky.sgen file then you likely have to install the Yakindu RKH code generator. This can be done in the example wizard or in the SGen wizard.

1. Open File > New > Code generator module
2. Click on 'next'
3. Choose a 'Generator' and click on 'Install more..'
4. Follow the instructions and select the RKH Generator
5. Finish and Restart.

Project structure

model contains Blinky state machine (blinky.sct) and generator model (blinky.sgen) src Includes both application code and BSP (Board Support Package) code. The most important files and directories are listed below:

• signals.h: defines signals as enumerated constants, which are used as state machine triggers.
• main.c: contains the main() function, which initializes both BSP and Blinky active object, then executes the RKH framework in order to orchestrates this reactive application.
• rkhcfg.h: adapts and configures RKH in compile time.
• bsp: this folder contains the source code of BSP for Linux platform. It emulates interrupts, implements the communication with Trazer tool and a simple event-loop, which is a non-preemptive cooperative scheduler. In the Yakindu’s Standard Edition you cannot include header files, but it is possible to create operations, in which the platform specific C code can be called. Within these operations we can call the specific code to interact with the platform, which is located in this folder.

src-gen Includes the generated C code compatible with RKH framework, which will be automatically be updated when you edit and save the statechart.

• Blinky.h/.c: specifies and implements the state machine of Blinky active object. Please correlate this implementation (Blinky.c) with the state diagram shown above.
• BlinkyAct.h/.c: specifies and implements the state machine actions (entries, exits, effects and guards).
• BlinkyActRequired.h: in the Yakindu’s Standard Edition you cannot include header files, but it is possible to create operations, in which the Blinky specific c code can be called. Within these operations we can call the specific C code to interact with the platform.

rkh Here is located the RKH framework’s source code.

Build

• Right-click on project 'org.yakindu.sct.examples.rkh.blinky' in the 'Project Explorer'
• Choose 'Build Project'

Run and debug

• Open a console, change the directory where you previously downloaded Trazer, and run it by executing the following command line: ./trazer -t 6602
• Right-click on project 'org.yakindu.sct.examples.rkh.blinky' in the Eclipse 'Project Explorer'
• Choose 'Run As > Local C/C++ Application'

The embedded Eclipse console shows up and the application starts

In order to debug the example

• Open a console, change the directory where you previously downloaded Trazer, and run it by executing the following command line: ./trazer -t 6602
• Right-click on project 'org.yakindu.sct.examples.rkh.blinky' in the Eclipse 'Project Explorer'
• Choose 'Debug As > Local C/C++ Application'

You will now see the debug perspective with the blinky application window open. The C/C++ editor repositions in the perspective.

Verify and validate

While the application is running, you can validate and verify its behaviour through the trace events showed on the Trazer output. Each trace event includes a time stamp and additional information associated with it. A capture of Trazer output is shown below. It shows the trace records when the state machine processes a after 1 sec trigger. Since RKH can generate more than 100 different trace events during its execution, its trace module allow you to filter one or more of them in runtime, so you can choose the traces that you need.