QP/C++ 6.9.3
Simple Blinky Application

The ultra-simple Blinky example is the embedded systems' equivalent of the venerable "Hello World!" program, that is, the simplest possible working QP application that does "something". In the case of Blinky, this "something" is blinking an LED at the rate of 1Hz, where an LED turns on and remains on for 0.5 seconds on then turns off and remains off for 0.5 seconds.

Blinky on EK-TM4C123GLX (TivaC LaunchPad)

The ultra-simple Blinky application, which consists of just one active object named Blinky, is intentionally kept small and illustrates only the most basic QP features, such as:

  • defining a simple Blinky active object (AO) class;
  • hand-coding the simple state machine of the Blinky AO;
  • using a periodic time event;
  • initializing the QP framework; and
  • starting an AO.

State Machine

The very simple state machine of the Blinky AO is shown in the figure below:

State Machine of the Blinky AO

  • 1 The top-most initial transition in this state machine arms a QP time event (QTimeEvt_armX()) to deliver the TIMEOUT signal every half second, so that the LED can stay on for one half second and off for the other half.

  • 2 The initial transition leads to state "off", which turns the LED off in the entry action (BSP_ledOff()).

  • 3 When the TIMEOUT event arrives in the "off" state, the "off" state transitions to the "on" state
  • 4 The "on" state turns the LED on in the entry action (BSP_ledOn()).
  • 5 When the TIMEOUT event arrives in the "on" state, the "on" state transitions back to "off", which cases execution of the entry action, in which the LED is turned off. From that point on the cycle repeats forever because the TIMEOUT events keep getting generated at the pre-determined rate.

State Machine Code

The Blinky state machine shown above is implemented in the blinky.c source file, as shown in the listing below. The code has been specifically organized not to access target resources directly, but instead encapsulate all such access in the calls to the BSP (Board Support Package). So for example, instead of turning the LED on and off by writing to a specific GPIO register on an embedded board, the code calls the BSP functions BSP_ledOn() and BSP_ledOff(). These functions can then be defined differently for each Target board (or even a desktop workstation), without the need to change the state machine code.

Note
The Blinky source code (blinky.c) is actually the same on all platforms, including Windows and the embedded boards. The only difference is in the Board Support Package (bsp.c), which is specific for the target.
1 //****************************************************************************
2 // Product: BSP for Blinky
3 // Last Updated for Version: 6.5.0
4 // Date of the Last Update: 2019-03-24
5 //
6 // Q u a n t u m L e a P s
7 // ------------------------
8 // Modern Embedded Software
9 //
10 // Copyright (C) 2005-2019 Quantum Leaps, LLC. All rights reserved.
11 //
12 // This program is open source software: you can redistribute it and/or
13 // modify it under the terms of the GNU General Public License as published
14 // by the Free Software Foundation, either version 3 of the License, or
15 // (at your option) any later version.
16 //
17 // Alternatively, this program may be distributed and modified under the
18 // terms of Quantum Leaps commercial licenses, which expressly supersede
19 // the GNU General Public License and are specifically designed for
20 // licensees interested in retaining the proprietary status of their code.
21 //
22 // This program is distributed in the hope that it will be useful,
23 // but WITHOUT ANY WARRANTY; without even the implied warranty of
24 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 // GNU General Public License for more details.
26 //
27 // You should have received a copy of the GNU General Public License
28 // along with this program. If not, see <www.gnu.org/licenses/>.
29 //
30 // Contact information:
31 // <www.state-machine.com/licensing>
32 // <info@state-machine.com>
33 //****************************************************************************
34 #include "qpcpp.hpp"
35 #include "bsp.hpp"
36 #include "blinky.hpp"
37 
38 //Q_DEFINE_THIS_FILE
39 
40 //............................................................................
41 class Blinky : public QActive {
42 private:
43  QTimeEvt m_timeEvt;
44 
45 public:
46  Blinky();
47 
48 protected:
49  Q_STATE_DECL(initial);
50  Q_STATE_DECL(off);
51  Q_STATE_DECL(on);
52 };
53 
54 // local bjects --------------------------------------------------------------
55 Blinky l_blinky;
56 
57 // global objects ------------------------------------------------------------
58 QActive * const AO_Blinky = &l_blinky; // opaque pointer
59 
60 //............................................................................
61 Blinky::Blinky()
62  : QActive(&initial),
63  m_timeEvt(this, TIMEOUT_SIG, 0U)
64 {
65  // empty
66 }
67 
68 // HSM definition ------------------------------------------------------------
69 Q_STATE_DEF(Blinky, initial) {
70  (void)e; // unused parameter
71 
72  // arm the time event to expire in half a second and every half second
73  m_timeEvt.armX(BSP_TICKS_PER_SEC/2U, BSP_TICKS_PER_SEC/2U);
74  return tran(&off);
75 }
76 //............................................................................
77 Q_STATE_DEF(Blinky, off) {
78  QState status;
79  switch (e->sig) {
80  case Q_ENTRY_SIG: {
81  BSP_ledOff();
82  status = Q_RET_HANDLED;
83  break;
84  }
85  case TIMEOUT_SIG: {
86  status = tran(&on);
87  break;
88  }
89  default: {
90  status = super(&top);
91  break;
92  }
93  }
94  return status;
95 }
96 //............................................................................
97 Q_STATE_DEF(Blinky, on) {
98  QState status;
99  switch (e->sig) {
100  case Q_ENTRY_SIG: {
101  BSP_ledOn();
102  status = Q_RET_HANDLED;
103  break;
104  }
105  case TIMEOUT_SIG: {
106  status = tran(&off);
107  break;
108  }
109  default: {
110  status = super(&top);
111  break;
112  }
113  }
114  return status;
115 }
QP::QState
std::uint_fast8_t QState
Type returned from state-handler functions.
Definition: qep.hpp:223
Q_STATE_DEF
#define Q_STATE_DEF(subclass_, state_)
Macro to generate a definition of a state-handler for a given state in a subclass of QP::QHsm.
Definition: qep.hpp:625
Q_STATE_DECL
#define Q_STATE_DECL(state_)
Macro to generate a declaration of a state-handler, state-caller and a state-object for a given state...
Definition: qep.hpp:619
qpcpp.hpp
QP/C++ public interface including backwards-compatibility layer.

As you can see, the structure of the state machine is very clearly recognizable in this code. Please refer to the Application Note A Crash Course in UML State Machines for exact explanation of the state machine coding techniques.

Defining Active Object (AO) Class

  • hand-coding the simple state machine of the Blinky AO;
  • using a periodic time event;
  • initializing the QP framework; and
  • starting an AO.

Next: Dining Philosophers Problem (DPP)