RKH
Blinky


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_TRN_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 isn’t 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_TRREG(TIMEOUT, NULL, blinky_ledOff, &ledOff),
RKH_CREATE_BASIC_STATE(ledOff, NULL, NULL, RKH_ROOT, NULL);
RKH_TRREG(TIMEOUT, NULL, blinky_ledOn, &ledOn),
#define RKH_CREATE_BASIC_STATE(name, en, ex, parent, prepro)
This macro creates a basic state.
Definition: rkhsm.h:277
#define RKH_CREATE_TRANS_TABLE(name)
This macro creates a state transition table.
Definition: rkhsm.h:777
#define RKH_END_TRANS_TABLE
This macro is used to terminate a state transition table. This table have the general structure shown...
Definition: rkhsm.h:894
#define RKH_TRREG(evt_, guard_, effect_, target_)
This macro defines a regular state transition.
Definition: rkhsm.h:811
#define RKH_ROOT
This macro indicates the root state of a state machine.
Definition: rkhsm.h:1019


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_EVT_T *pe)
{
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 ................................. */
#define RKH_UPCAST(BaseType_, me_)
Convert a pointer to a base-class.
Definition: rkhfwk_cast.h:74
#define RKH_TMR_INIT(t_, e_, th_)
Initializes the previously allocated timer structure RKH_TMR_T.
Definition: rkhtmr.h:143
#define RKH_TMR_ONESHOT(t, sma, itick)
Start a timer as one-shot timer.
Definition: rkhtmr.h:187
#define RKH_TR_FWK_TIMER(timerObj_)
Entry symbol table for timer object.
#define RKH_TR_FWK_QUEUE(queueObj_)
Entry symbol table for queue object.
#define RKH_TR_FWK_AO(actObj_)
Entry symbol table for active object.
#define RKH_TR_FWK_SIG(stateObj_)
Entry symbol table for event signal.
#define RKH_TR_FWK_STATE(actObj_, stateObj_)
Entry symbol table for state object.
Represents events without parameters.
Definition: rkhevt.h:170
Describes the SMA (active object in UML).
Definition: rkhsma.h:772


"blinky.h" - Action declarations

/* ........................ Declares initial action ........................ */
static void blinky_init(Blinky *const me, RKH_EVT_T *pe);
/* ........................ 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 lf@vortexmakes.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 ------------------------------ */
RKH framwwork platform - independent interface.
#define RKH_SMA_DCLR(me_)
This macro declares a opaque pointer to previously created state machine application (SMA aka active ...
Definition: rkhsma.h:139



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 lf@vortexmakes.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);
return 0;
}
/* ------------------------------ End of file ------------------------------ */
#define RKH_SMA_ACTIVATE(me_, qSto_, qStoSize, stkSto_, stkSize_)
Invoke the active object activation function rkh_sma_activate(). If RKH_CFG_SMA_VFUNCT_EN is set RKH_...
Definition: rkhsma.h:250
#define RKH_TRC_CLOSE()
Close the tracing session.
Definition: rkhtrc_out.h:138
void rkh_fwk_enter(void)
RKH framework is started.



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

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

GNU Linux cooperative scheduler simulation

Prev: Cross-platform examples