RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Blinky
rkh_bunner.jpg


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".

rkh_blinky.png
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 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),


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_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);
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\platform\80x86\win32_st\vc08\

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

readme

Freescale Kinetis KL2 FRDM-KL25Z Codewarrior v10.x Native cooperative scheduler

readme

Freescale Kinetis K40 KWIKSTIK-K40 Codewarrior v10.x Native cooperative scheduler

readme

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