QM基础教程

官方原版教程:http://www.state-machine.com/qm/gs_tut.html#gs_tut_build

中文翻译教程首发CSDN，转载请标明出处:http://blog.csdn.net/chenbb8/article/details/52330325

NOTE:本中文教程相对官方原版教程，删减了Building Blinky on Windows/Linux 这章，读者可以参考我的另外一篇博文《使用QM的外部工具功能编译代码》中gcc的例子，其次增加了Add Free Operation章

这个教程介绍了怎么使用QM建模，并实现一个简单的、可以在嵌入式板子上闪烁一个LED的或者在桌面环境能够下打印LED的状态转换的”Blinky”应用。

NOTE:这个教程是使用的是QP/C框架(version 5).在其它的QP框架下运行也是类似



Blinky on TivaC LaunchPad

Creating New Model

打开File->Model…菜单或者点击在Edit Toolbar上的



按钮。接下来将会打开New Model Dialog Box窗口：



New Model dialog

选择model基于那个 QP framework type (“Frameworks” 面板)。这里可以选择：qpc for QP/C™, qpcpp for QP/C++™, and qpn for QP-nano™。在这个教程中，你保留默认的qpc framewords type。

给model命名(“Name:” 框)。NOTE：.qm后缀名会自动添加。 在这个教程中，重命名model为blinky。

选择model文件存放的目录(“Location:” 框)。你可以手动输入目录路径，也可以点击右侧图标选择路径。NOTE:model的路径也是生成代码的地方。所有成的目录和文件都是相对于model文件目录来说的。

点击OK按钮。

Adding Model Items

现在你可以开始添加items到一个新的model中。

Add a Package

第一个要添加的是Package。在UML中package是一个组结构，用于合并其他model items到一个higher-level单元。它一般用来将classes组合到一起，但package同样可以持有free attributes，free operations，和其他的packages。

在 Model Explorer 窗口右击blinky item，在弹出菜单中，选择Add Package。

`



Add Package

在Property Editor窗口中修改package的名字为AOs(Active Objects)，并选择stereotype为components。

`



Package Properties

Add a Class

接下来添加一个class到新的package中，因为只有class可以拥有行为 (i.e.,State Machines).

在Model Explorer窗口下右击AOs package并在弹出菜单中选择Add Class

`


Add Class

在Property Editor窗口中修改class名字为Blinky，并且选择superclass为qpc::QMActive.



Setting Superclass

NOTE:

在QM™ 一个状态机只可以和继承QP state machine classes的class相关联。所选择的状态机superclass决定状态机实现策略.

Add a Time Event

通过添加一个Time Event，以便传递周期事件到目标的blinky状态机中的blinking状态。

在Model Explorer窗口下右击Blinky类，并在弹出菜单中选择Add Attribute

`



Adding Attribute

在Property Editor窗口中修改attribute的名字为timeEvt，类型为QTimeEvt，visibility选择为private。

`



Attribute Properties

Add Free Operation (改动:新增)

增加一个Free Operation可以生成对应的普通函数，提供调用。

在Model Explorer窗口下右击AOs Package

`



Add Free Operation

在Property Editor窗口中修改Operation的名字为Blinky_ctor，并选择return type为void。添加如下代码：

Blinky * const me = &l_blinky;

QMActive_ctor(&me->super, Q_STATE_CAST(&Blinky_initial));

QTimeEvt_ctorX(&me->timeEvt, &me->super, TIMEOUT_SIG, 0U);

`



Operation Properties

Note 1:

上面的代码第二行的构造函数，应该和对应的类所选用的superclass一致

QMActive_ctor()对应qpc::QMActive

QActive_ctor()对应qpc::QActive

QMsm_ctor()对应qpc::QMsm

QHsm_ctor()对应qpc::QHsm

这几个构造函数的参数都是一致的。

Note 2:

之所以使用Operation定义构造函数，而不是在对应的源文件中手动定义，其中一个原因可能是因为free Operation和class同在AOs下，修改class的superclass后，很容易就找到对应的构造函数进行修改。无需翻看源文件。

Add State Machine

在Model Explorer窗口下右击Blinky类，并在弹出菜单中选择Add Start Machine

`



Adding State Machine

Drawing State Machine Diagram

在Property Editor窗口中右击SM状态机，并在弹出菜单中选择Show Diagram(显示图表)。另外你可以双击SM状态机执行默认动作：Show Diagram

`



Show State Machine Diagram

Add States

在Diagram Toolbox 点击选中state工具，移动鼠标（不用按下左键）到diagram窗口合适的地方，这里选择左上角。注意到现在鼠标的形状发生了变化(如下图)。按下鼠标左键放置state形状，然后鼠标右键不要放松，往右下角拖动改变大小。释放鼠标。

`



Adding the off State

在Property Editor窗口中修改state的名字为off，并增加entry动作BSP_ledOff();到这个状态。

使用类似的方法添加第二个state。在Property Editor窗口中修改state的名字为on，并增加entry动作BSP_ledOn();到这个状态。

`



Setting Properties of State ‘off’

Add Initial Transition

在Diagram Toolbox 点击选中initial transition工具。移动鼠标（不用按下左键）到diagram窗口合适的地方。注意到现在鼠标的形状发生了变化(如下图)。按下鼠标左键，并拖动它(长按左键)到state的边缘。注意鼠标形状变化在接触到边缘后。释放鼠标。

`



Adding the Initial Transition

在Property Editor窗口中给Initial Transition 增加动作QTimeEvt_armX(&me->timeEvt, BSP_TICKS_PER_SEC/2, BSP_TICKS_PER_SEC/2);

Note

在Initial Transition的动作代码为起始BSP_TICKS_PER_SEC/2次clock ticks，和其后每次BSP_TICKS_PER_SEC/2次clock ticks投递time event。

Add Transitions

在Diagram Toolbox 点击选中transition工具。移动鼠标（不用按下左键）到diagram窗口合适的地方。注意到现在鼠标的形状发生了变化(如下图)。按下鼠标左键，并拖动它(长按左键)到state的边缘。注意鼠标形状变化在接触到边缘后。释放鼠标。

`



Adding a Transition

在Property Editor窗口中修改这个transition的trigger为TIMEOUT。

使用类似的方法添加第二个transition并改变它的trigger为TIMEOUT。

`



Complete State Machine

Generating Code

相比于其他的图形化状态机工具，QM™ 让生成代码”上下颠倒(upside down)”了.QM™ 让你确定生成代码的结构，目录名，文件名和进入文件里的每个元素(看物理设计)。你可以混合你自己的代码到生成代码中，并使用QM生成你觉得合适的，尽可能多或者尽可能少的总代码。

Add Directory

首先需要创建一个目录，这个目录的设置决定了生成代码相对于QM Model File的位置。

·



Adding a Directory

在Model Explorer窗口下右击Blinky model项，并在弹出菜单中选择Add Directory。这将会是代码生成的目录。目录的路径参考于QM Model File并可以在Property Editor中编辑。在directory中填入”.”符号，代表了生成的代码使用和QM Model File相同的目录。

Add File

在directory里可以添加Files。在实际的项目中，通常会将代码分成头文件和源文件，并使用独立的源文件作为板级支持包(BSP)和mian()。但为了简单起见，这个教程在会在下面的步骤中，将会将他们都放到一个文件里:blinky.c里：



Adding a File

在Model Explorer窗口下右击directory项，并在弹出菜单中选择Add File。在这个文件创建后，你可以在Property Editor里编辑它的名字为blinky.c

Edit File (改动:手工代码，增加ctor函数的生成)

你需要为QP™每个file-template提供一个前体(body)，在其中你可以输入自己的代码以及代码生成指令。下面的代码将会演示最重要的两个指令

$declare(AOs::Blinky)

用于生成Blinky class的声明；

$define(AOs::Blinky)

用于生成Blinky class的定义和

$define(AOs::Blinky_ctor)

用于生成对应的构造函数。

#include "qp_port.h"
#include <stdio.h>
#include <stdlib.h>

#define BSP_TICKS_PER_SEC 100

void BSP_ledOff(void) {
printf("LED OFF\r\n");
}

void BSP_ledOn(void) {
printf("LED ON\r\n");
}
void Q_onAssert(char const Q_ROM * const Q_ROM_VAR file, int line) {
fprintf(stderr, "Assertion failed in %s, line %d", file, line);
exit(0);
}
void QF_onStartup(void) {}
void QF_onCleanup(void) {}
void QF_onClockTick(void) {
QF_TICK((void *)0);
}

enum BlinkySignals {
TIMEOUT_SIG = Q_USER_SIG,
MAX_SIG
};

/*************** ask QM to declare the Blinky class ******************/
$declare(AOs::Blinky)

static Blinky l_blinky;
QActive * const AO_Blinky = &l_blinky.super;

/*************** ask QM to define the Blinky_ctor operation *********/
$define(AOs::Blinky_ctor)

/*************** ask QM to define the Blinky class ******************/
$define(AOs::Blinky)

int main() {
static QEvt const *blinky_queueSto[10];

Blinky_ctor();
QF_init();

QActive_start(AO_Blinky, 1U,
blinky_queueSto, Q_DIM(blinky_queueSto),
(void *)0, 1024U, (QEvt *)0);
return QF_run();
}

`



Creating a Fully-Qualified Item Name by Drag-n-Drop



Opening blinky.c File and Pasting the Code

Generate Code

点击工具条中的Generate Code按键，生成代码。



Code Generation

这时QM已经在blinky.qm这个QM Model File相同的目录下生成了代码。可以使用一个代码编辑器对代码进行查看。

Building the Project (改动:删除)