Prev: Cross-platform examples

The goal of "Blinky" demo application is to explain how to represent a "flat" state machine, how to use the timer services, and trace facility from RKH framework. To do that is proposed a very simple demo that use one state machine and one timer, which is shown and itself explained in the Blink a LED state diagram. This is the 'hello world' of RKH programming.

The platform-independent Blinky source code (in C) is located in the <rkh>/demo/cross/blinky/ directory, where <rkh> stands for the installation directory chosed to install the accompanying software and blinky.c, blinky.h and main.c are the platform-independent files. Thus, the code is actually identical in all Blinky versions, such as the Windows version, Linux version, arm-cortex version, and so on.

State machine

The following figure shows the state machine associated with Blinky active object, which clearly shows the life cycle consisting of states "led_on", and "led_off".

Blinky state machine

( 1) The blinky_init() function defines the topmost initial transition in the blinky state machine. The function prototype is defined as RKH_INIT_ACT_T. This argument is (optional), thus it could be declared as NULL.
( 2) The timer is declared with the RKH_TMR_T data type and is defined with the RKH_TMR_INIT() RKH service. The timer is initialized in a non-active state (stopped). In this case, a subsequent start service call is necessary to get the timer actually started.
( 3) Turn on the LED and trigger the timer as oneshot to expire in LED_ON_TIME milliseconds.
( 4-8) Upon receiving the TIMEOUT event, the Blinky re-trigger the timer to expire in LED_OFF_TIME milliseconds, turn off the LED, and increments the counter.
( 9-10) Turn off the LED and trigger the timer as oneshot to expire in LED_OFF_TIME milliseconds.

Note: The notation of UML Statecharts is not purely visual. Any nontrivial state machine requires a large amount of textual information (e.g., the specification of actions and guards). The exact syntax of action and guard expressions isnt defined in the UML specification, so many people use either structured English or, more formally, expressions in an implementation language such as C [Douglass]. In practice, this means that UML Statechart notation depends heavily on the specific programming language.

The blinky.c file implements the state machine of Blinky active object, which illustrates some aspects of implementing state machines with RKH framework. Please correlate this implementation with the state diagram shown above. On the other hand, the header file blinky.h contains the definitions of object structures related to the state machine.

"blinky.c" - State machine representation

/* ........................ States and pseudostates ........................ */
RKH_CREATE_BASIC_STATE(ledOn, NULL, NULL, RKH_ROOT, NULL);
RKH_CREATE_TRANS_TABLE(ledOn)
    RKH_TRREG(TIMEOUT, NULL, blinky_ledOff, &ledOff),
RKH_END_TRANS_TABLE
RKH_CREATE_BASIC_STATE(ledOff, NULL, NULL, RKH_ROOT, NULL);
RKH_CREATE_TRANS_TABLE(ledOff)
    RKH_TRREG(TIMEOUT, NULL, blinky_ledOn, &ledOn),
RKH_END_TRANS_TABLE

The related actions (entry, exit, guard, and state transition) to be executed by the state machine are implemented and declared in the blinky.c. Note that the rkhcfg.h file defines the prototypes of them.

"blinky.c" - Actions

/* ............................ Initial action ............................. */
static void
blinky_init(Blinky *const me)
{
    RKH_TR_FWK_AO(me);
    RKH_TR_FWK_QUEUE(&RKH_UPCAST(RKH_SMA_T, me)->equeue);
    RKH_TR_FWK_STATE(me, &ledOn);
    RKH_TR_FWK_STATE(me, &ledOff);
    RKH_TR_FWK_TIMER(&me->timer);
    RKH_TR_FWK_SIG(TIMEOUT);
    RKH_TMR_INIT(&me->timer, &e_tout, NULL);
    blinky_ledOn(me, NULL);
}
/* ............................ Effect actions ............................. */
static void
blinky_ledOn(Blinky *const me, RKH_EVT_T *pe)
{
    (void)pe;
    RKH_TMR_ONESHOT(&me->timer, RKH_UPCAST(RKH_SMA_T, me), LED_ON_TIME);
    bsp_led_on();
    ++me->cnt;
}
static void
blinky_ledOff(Blinky *const me, RKH_EVT_T *pe)
{
    (void)me;
    (void)pe;
    RKH_TMR_ONESHOT(&me->timer, RKH_UPCAST(RKH_SMA_T, me), LED_OFF_TIME);
    bsp_led_off();
}
/* ............................. Entry actions ............................. */
/* ............................. Exit actions .............................. */
/* ................................ Guards ................................. */

"blinky.h" - Action declarations

/* ........................ Declares initial action ........................ */
static void blinky_init(Blinky *const me);
/* ........................ Declares effect actions ........................ */
static void blinky_ledOn(Blinky *const me, RKH_EVT_T *pe);
static void blinky_ledOff(Blinky *const me, RKH_EVT_T *pe);
/* ......................... Declares entry actions ........................ */
/* ......................... Declares exit actions ......................... */
/* ............................ Declares guards ............................ */

Signals, events, and active objects

In RKH, signals are typically enumerated constants and events with parameters are structures derived from the RKH_EVT_T base structure. The next listing shows signals and events used in the Blinky application (blinky.h).

"blinky.h" - Signals, events, and active objects

/* -------------------------- Development history -------------------------- */
/*
 *  2016.03.17  LeFr  v1.0.00  Initial version
 */
/* -------------------------------- Authors -------------------------------- */
/*
 *  LeFr  Leandro Francucci  francuccilea@gmail.com
 */
/* --------------------------------- Notes --------------------------------- */
/* --------------------------------- Module -------------------------------- */
#ifndef __BLINKY_H__
#define __BLINKY_H__
/* ----------------------------- Include files ----------------------------- */
#include "rkh.h"
/* ---------------------- External C language linkage ---------------------- */
#ifdef __cplusplus
extern "C" {
#endif
/* --------------------------------- Macros -------------------------------- */
/* -------------------------------- Constants ------------------------------ */
/* ................................ Signals ................................ */
typedef enum Signals Signals;
enum Signals
{
    TIMEOUT,        /* timeout */
    TERMINATE,      /* press the key escape on the keyboard */
    BLINKY_NUM_EVENTS
};
/* ........................ Declares active object ......................... */
RKH_SMA_DCLR(blinky);
/* ------------------------------- Data types ------------------------------ */
/* -------------------------- External variables --------------------------- */
/* -------------------------- Function prototypes -------------------------- */
/* -------------------- External C language linkage end -------------------- */
#ifdef __cplusplus
}
#endif
/* ------------------------------ Module end ------------------------------- */
#endif
/* ------------------------------ End of file ------------------------------ */

Initializing and starting the application

Most of the system initialization and application startup can be written in a platform-independent way.
"main.c" - main() function

/* -------------------------- Development history -------------------------- */
/*
 *  2016.03.17  LeFr  v1.0.00  Initial version
 */
/* -------------------------------- Authors -------------------------------- */
/*
 *  LeFr  Leandro Francucci  francuccilea@gmail.com
 */
/* --------------------------------- Notes --------------------------------- */
/* ----------------------------- Include files ----------------------------- */
#include "rkh.h"
#include "bsp.h"
#include "blinky.h"
/* ----------------------------- Local macros ------------------------------ */
#define QSTO_SIZE           4
/* ------------------------------- Constants ------------------------------- */
/* ---------------------------- Local data types --------------------------- */
/* ---------------------------- Global variables --------------------------- */
/* ---------------------------- Local variables ---------------------------- */
static RKH_EVT_T *qsto[QSTO_SIZE];
/* ----------------------- Local function prototypes ----------------------- */
/* ---------------------------- Local functions ---------------------------- */
/* ---------------------------- Global functions --------------------------- */
int
main(int argc, char *argv[])
{
    bsp_init(argc, argv);
    RKH_SMA_ACTIVATE(blinky, qsto, QSTO_SIZE, 0, 0);
    rkh_fwk_enter();
    RKH_TRC_CLOSE();
    return 0;
}
/* ------------------------------ End of file ------------------------------ */

Running on various platforms

As said before, the only platform-dependent file is the board support package (BSP) definition. Each of supported platforms defines its own bsp.c and bsp.h files, which are contained in the proper directory, for example, the BSP for the Blinky application on Windows 32 (Visual Studio 2008) with a simple cooperative scheduler is located in <rkh>/demo/cross/blinky/build/80x86/win32_st/vc/

CPU Architecture	Manufacturer	MCU	Evaluation Board	Toolchain	Comments	Notes
ARM - Cortex	NXP	LPC1769	LPCXpresso	Codered	Native cooperative scheduler	readme
	Freescale	Kinetis K60	TWR-K60D100M	Codewarrior v10.x	Native cooperative scheduler	readme
	Freescale	Kinetis K60	TWR-K60D100M	IAR v7.2	Native cooperative scheduler	Deprecated
	Freescale	Kinetis KL2	FRDM-KL25Z	Codewarrior v10.x	Native cooperative scheduler	readme
	Freescale	Kinetis K40	KWIKSTIK-K40	Codewarrior v10.x	Native cooperative scheduler	Deprecated
	Freescale	Kinetis K64	FRDM-K64F	KDS	Native cooperative scheduler	readme
Freescale	Coldfire V1	MCF51QE128	DEMOQE128	Codewarrior v6.x	Native cooperative scheduler	readme
Freescale	S08	S08QE128	DEMOQE128	Codewarrior v6.x	Native cooperative scheduler	readme
80x86	—	—	—	Visual Studio C++ 2010	Win32 cooperative scheduler simulation
80x86	—	—	—	GNU	Linux cooperative scheduler simulation

Prev: Cross-platform examples

Table of Contents

State machine

Signals, events, and active objects

Initializing and starting the application

Running on various platforms