用AWTK和AWPLC快速開發(fā)自定義功能塊

AWPLC 是 ZLG 自主研發(fā)的 PLC 系統(tǒng)（兼容 IEC61131-3)，本文以定時(shí)器為例介紹一下如何擴(kuò)展自定義功能塊，以及代碼生成器的用法。

背景

AWTK全稱 Toolkit AnyWhere，是 ZLG 開發(fā)的開源 GUI 引擎，旨在為嵌入式系統(tǒng)、WEB、各種小程序、手機(jī)和 PC 打造的通用 GUI 引擎，為用戶提供一個(gè)功能強(qiáng)大、高效可靠、簡(jiǎn)單易用、可輕松做出炫酷效果的 GUI 引擎。

AWPLC是 ZLG 自主研發(fā)的 PLC 系統(tǒng)（兼容 IEC61131-3)，其中 AWPLC 的運(yùn)行時(shí)庫(kù)(Runtime)基于 ZLG TKC 開發(fā)，可以移植到到任何主流 RTOS 和嵌入式系統(tǒng)。AWPLC 的集成開發(fā)環(huán)境(IDE)基于 AWTK 開發(fā)，可以運(yùn)行在 Windows、MacOS 和 Linux 系統(tǒng)之上。AWPLC 的主要目標(biāo)之一是把 PLC 中低代碼開發(fā)方法引入到嵌入式軟件，從而提高嵌入式軟件的開發(fā)效率和可靠性。

簡(jiǎn)介

在前一篇文章中，我們介紹了自定義 AWPLC 功能塊的基本方法，但是有些部分的內(nèi)容并沒有提到，比如：

1. 功能塊的部分虛函數(shù)的實(shí)現(xiàn)。這些函數(shù)在不同功能塊中的實(shí)現(xiàn)是不同的，所以要做成虛函數(shù)，但是在各個(gè)功能塊中的實(shí)現(xiàn)又是相似的，不得不去寫一遍。比如 get_prop 這個(gè)函數(shù)，它在 ZTIMER 中的實(shí)現(xiàn)如下：

staticret_taw_plc_fb_ztimer_get_prop(aw_plc_fb_t*fb,constchar*name,value_t*v){
aw_plc_fb_ztimer_t*ztimer=AW_PLC_FB_ZTIMER(fb);

if(tk_str_eq(name,AW_PLC_FB_ZTIMER_PROP_IN)){
value_set_bool(v,ztimer->in);
returnRET_OK;
}

if(tk_str_eq(name,AW_PLC_FB_ZTIMER_PROP_PT)){
value_set_uint64(v,ztimer->pt);
returnRET_OK;
}

if(tk_str_eq(name,AW_PLC_FB_ZTIMER_PROP_Q)){
value_set_bool(v,ztimer->q);
returnRET_OK;
}

if(tk_str_eq(name,AW_PLC_FB_ZTIMER_PROP_ET)){
value_set_uint64(v,ztimer->et);
returnRET_OK;
}

if(tk_str_eq(name,AW_PLC_FB_ZTIMER_PROP_COUNT)){
value_set_uint32(v,ztimer->count);
returnRET_OK;
}

returnRET_NOT_FOUND;

}

*這樣的代碼看起來(lái)很簡(jiǎn)單，但是恰恰容易出錯(cuò)，更容易讓人厭倦，沒有什么樂趣。

2. API 和結(jié)構(gòu)的注釋。我們來(lái)看看 ZTIMER 的結(jié)構(gòu)注釋：

/**
*@classaw_plc_fb_ztimer_t
*@parentaw_plc_fb_t
*@annotation["fb"]
*循環(huán)定時(shí)器。
*
*>當(dāng)輸入 IN 為 TRUE 時(shí)，開始計(jì)時(shí)，輸出 Q 為 FALSE，ET 開始記錄過去的時(shí)間。
*>定時(shí)時(shí)間到時(shí)，COUNT 增加 1，輸出 Q 在本次循環(huán)為 TRUE，ET 重置為0。
*>輸入 IN 為 FALSE 時(shí)重置定時(shí)器。
*/
typedefstruct_aw_plc_fb_ztimer_t{
aw_plc_fb_tfb;

/**
*@property{bool_t}in
*@annotation["in"]
*為 TRUE 開始計(jì)時(shí)，為 FALSE 時(shí)重置定時(shí)器。
*/
bool_tin:1;

/**
*@property{iec_time_t}pt
*@annotation["in"]
*預(yù)設(shè)時(shí)間(ms)。
*/
iec_time_tpt;

/**
*@property{bool_t}q
*@annotation["default","out"]
*定時(shí)時(shí)間是否到（僅在時(shí)間到的當(dāng)次循環(huán)為 TRUE)。
*/
bool_tq:1;

/**
*@property{iec_time_t}et
*@annotation["out"]
*過去時(shí)間(ms)。
*/
iec_time_tet;

/**
*@property{uint32_t}count
*@annotation["out"]
*定時(shí)器時(shí)間到的次數(shù)。
*/
uint32_tcount;

/**
*@property{bool_t}prev_in
*@annotation["private"]
*前一次的輸入。
*/
bool_tprev_in:1;

/**
*@property{uint8_t}state
*@annotation["private"]
*狀態(tài)。
*/
uint8_tstate;

/**
*@property{iec_time_t}current_time
*@annotation["private"]
*當(dāng)前時(shí)間(ms)。
*/
iec_time_tcurrent_time;

/**
*@property{iec_time_t}start_time
*@annotation["private"]
*開始時(shí)間(ms)。
*/
iec_time_tstart_time;

}aw_plc_fb_ztimer_t;

*上面的代碼看起來(lái)很美觀，讀起來(lái)很舒服，但是寫起來(lái)卻是有些費(fèi)勁。3. IDE 需要功能塊的描述信息，以方便把它呈現(xiàn)到界面上。比如 ZTIMER 的描述信息如下：

{
"type":"fb_zlg_misc.ztimer",
"real_type":"ZTIMER",
"helpUrl":"https://developer.zlg.cn",
"style":"fb",
"desc":"循環(huán)定時(shí)器。 >當(dāng)輸入 IN 為 TRUE 時(shí)，開始計(jì)時(shí)，輸出 Q 為 FALSE，ET 開始記錄過去的時(shí)間。
>定時(shí)時(shí)間到時(shí)，COUNT 增加 1，輸出 Q 在本次循環(huán)為 TRUE，ET 重置為0。 >輸入 IN 為 FALSE 時(shí)重置定時(shí)器。",
"ins":[
{
"name":"IN",
"desc":"為 TRUE 開始計(jì)時(shí)，為 FALSE 時(shí)重置定時(shí)器。",
"min_connections":1,
"max_connections":1,
"data_type":"BOOL"
},
{
"name":"PT",
"desc":"預(yù)設(shè)時(shí)間(ms)。",
"min_connections":1,
"max_connections":1,
"data_type":"TIME"
}
],
"outs":[
{
"name":"Q",
"desc":"定時(shí)時(shí)間是否到（僅在時(shí)間到的當(dāng)次循環(huán)為 TRUE)。",
"data_type":"BOOL"
},
{
"name":"ET",
"desc":"過去時(shí)間(ms)。",
"data_type":"TIME"
},
{
"name":"COUNT",
"desc":"定時(shí)器時(shí)間到的次數(shù)。",
"data_type":"DWORD"
}
]

}

*這個(gè) JSON 文件中的內(nèi)容，和前面結(jié)構(gòu)的注釋很相似，除了呈現(xiàn)的格式不同，同時(shí)還加了一些新內(nèi)容。4. IDE 需要的文檔。功能塊需要提供一個(gè) markdown 文檔，這個(gè)文檔會(huì)被轉(zhuǎn)換成 html，在用戶查看幫助時(shí)顯示給用戶。ZTIMER 的文檔內(nèi)容如下：

#ZTIMER

##功能

循環(huán)定時(shí)器。

>當(dāng)輸入 IN 為 TRUE 時(shí)，開始計(jì)時(shí)，輸出 Q 為 FALSE，ET 開始記錄過去的時(shí)間。
>定時(shí)時(shí)間到時(shí)，COUNT 增加 1，輸出 Q 在本次循環(huán)為 TRUE，ET 重置為0。
>輸入 IN 為 FALSE 時(shí)重置定時(shí)器。

##輸入

* IN **BOOL**為 TRUE 開始計(jì)時(shí)，為 FALSE 時(shí)重置定時(shí)器。
* PT **TIME**預(yù)設(shè)時(shí)間(ms)。

##輸出

* Q **BOOL**定時(shí)時(shí)間是否到（僅在時(shí)間到的當(dāng)次循環(huán)為 TRUE)。
* ET **TIME**過去時(shí)間(ms)。

* COUNT **DWORD**定時(shí)器時(shí)間到的次數(shù)。 *這個(gè)文檔的內(nèi)容和前面結(jié)構(gòu)的注釋，除了形式不同，內(nèi)容是差不多的。很抱歉貼了這么代碼，希望您并沒仔細(xì)去讀它們。不要被這些代碼嚇到，它們都是自動(dòng)生成的。如果手工去寫這些代碼，一天能寫一個(gè)功能塊就不錯(cuò)了，不但辛苦而且容易出錯(cuò)。這些工作必須自動(dòng)完成！所以 AWPLC 中提供了一個(gè)代碼生成器，實(shí)測(cè)這個(gè)代碼生成器讓工作效率提高 10倍，幸福指數(shù)提高 10倍。

在進(jìn)入正題前，我們先聊一下代碼生成器的基本知識(shí)。

代碼生成器基本知識(shí)

* 編寫能編寫代碼的代碼。-- 《程序員修煉之道》

代碼生成器是一個(gè)普通程序，它能夠生成另外的目標(biāo)代碼?？梢圆灰a生成器，直接編寫目標(biāo)代碼嗎？通常情況下是可以的，但是這違背了優(yōu)秀程序員的第一美德-懶惰。因?yàn)閼卸?，所以能讓?jì)算機(jī)做的事，優(yōu)秀程序員是不會(huì)自己去做的。

這里所說的目標(biāo)代碼，也并非一定是嚴(yán)格意義上的代碼，也可能是另外一些數(shù)據(jù)。當(dāng)然，有時(shí)候要嚴(yán)格區(qū)分?jǐn)?shù)據(jù)和代碼，本身就是一件困難的事情。不過，這不是我們要說的重點(diǎn)，重點(diǎn)是通過代碼生成器提升我們的工作效率。*一個(gè)人的數(shù)據(jù)就是另外一個(gè)人的代碼。--《編程珠璣 II》1.代碼生成器的分類要說分類，就要先說分類的標(biāo)準(zhǔn)，在不同的分類標(biāo)準(zhǔn)和分類依據(jù)下，分出的類別迥異?！冻绦騿T修煉之道》里提到的一個(gè)分類標(biāo)準(zhǔn)具有極強(qiáng)的實(shí)用意義，這里我們重點(diǎn)介紹一下。它根據(jù)生成的目標(biāo)代碼是否需要二次修改來(lái)分類，將代碼生成器分為兩類：

• 被動(dòng)代碼生成器目標(biāo)代碼生成之后，需要進(jìn)行修改和完善，然后獨(dú)立發(fā)展和維護(hù)，與代碼生成器再與關(guān)系。比如 IDE 的 Wizard 就是此例。前面提到的自定義控件生成器，代碼生成之后，你需要在上面添加需要的功能。如果過了一段時(shí)間，你想為控件添加一個(gè)新的屬性，可能會(huì)遇到一點(diǎn)麻煩，要么手工添加；要么重新生成代碼，然后把之前修改的代碼重新加上，無(wú)論哪種方式都不是愉快的方式。被動(dòng)代碼生成器雖然有它的缺陷，但是仍然可以給我們帶來(lái)很大幫助。

• 主動(dòng)代碼生成器目標(biāo)代碼生成之后，不需要進(jìn)行修改和完善，每次都重新生成，如果需要修改，修改元數(shù)據(jù)和代碼生成器。比如編譯器就是此例。前面提到的 MVVM 的 ViewModel 和 AWFlow 應(yīng)用代碼生成也屬于此類。如果可以，優(yōu)先使用主動(dòng)代碼生成器。

2.基本形式

這是代碼生成器的基本形式：代碼生成器讀取元數(shù)據(jù)，生成目標(biāo)代碼。元數(shù)據(jù)是描述數(shù)據(jù)的數(shù)據(jù)，這里是描述目標(biāo)代碼的數(shù)據(jù)，也就是控制目標(biāo)代碼的參數(shù)。一般情況下，目標(biāo)代碼整體結(jié)構(gòu)由代碼生成器決定，而變化的部分由元數(shù)據(jù)決定。

代碼生成器本身一個(gè)很有意思的話題，有機(jī)會(huì)可以專門來(lái)聊聊，本文就不扯遠(yuǎn)了。

AWPLC中的代碼生成器

按前面代碼生成器的分類方式，AWPLC 里實(shí)現(xiàn)了一個(gè)主動(dòng)代碼生成器，實(shí)現(xiàn)成主動(dòng)代碼生成器是很重要的，AWPLC 還在快速迭代中，有些接口可能會(huì)變化，主動(dòng)代碼生成器保證，即使接口有變化，也只需要運(yùn)行一些腳本，重新生成目標(biāo)文件即可。

1.基本架構(gòu)

AWPLC 功能塊代碼生成器架構(gòu)如下圖所示。其中功能塊描述文件就是前面所說的元數(shù)據(jù)，代碼生成器用它生成前面介紹的各種代碼和數(shù)據(jù)。

2.功能塊描述文件格式

描述文件用標(biāo)準(zhǔn)的 JSON 格式，其內(nèi)容包括兩個(gè)部分：

2.1基本信息

基本信息包括：

• name 功能塊的名稱。英文小寫，必須是合格的 C 語(yǔ)言變量名；
• category 功能塊所屬的分類。各層級(jí)之間用/分隔，它決定了生成文件的位置；
• is_function_block true 表示功能塊，false 表示函數(shù)；
• impl 具體實(shí)現(xiàn)的源文件；
• author 作者聯(lián)系方式；
• version 版本號(hào)；；
• date 更新時(shí)間；
• desc 功能描述；
• properties 屬性列表。具體定義如下。

示例：

"name":"ztimer",
"category":"zlg/misc",
"is_function_block":true,
"impl":"input/zlg/misc/ztimer.c",
"author":"LiXianJing",
"desc":"循環(huán)定時(shí)器。 >當(dāng)輸入 IN 為 TRUE 時(shí)，開始計(jì)時(shí)，輸出 Q 為 FALSE，ET 開始記錄過去的時(shí)間>。 >定時(shí)時(shí)間到時(shí)，COUNT 增加 1，輸出 Q 在本次循環(huán)為 TRUE，ET 重置為0。 >輸入 IN 為 FALSE 時(shí)重
置定時(shí)器。",

2.2屬性描述對(duì)于每個(gè)屬性，又包括下列信息：

• name 屬性名；
• desc 屬性描述；
• type 實(shí)際的數(shù)據(jù)類型；
• data_type（可選）用于在 IDE 中時(shí)類型檢查，缺省為 type 對(duì)應(yīng)的 IEC 的數(shù)據(jù)類型，但是有時(shí)可用 ANY_INT 和 ANY_NUM 等來(lái)放寬類型檢查；
• annotation 用于額外的標(biāo)識(shí)。目前主要用于指定輸入輸出等特性。

示例：

{
"name":"count",
"desc":"定時(shí)器時(shí)間到的次數(shù)。",
"type":"uint32_t",
"annotation":{
"out":true
}

},

2.3使用方法

代碼生成器用 nodejs 編寫，需要安裝 nodejs。具體用法如下：

node gen.js 描述文件名。

如：

nodegen.jsinput/zlg/misc/ztimer.json

上面介紹了用 C 語(yǔ)言開發(fā)原生功能塊的方法。當(dāng)然，也可以用 IEC 61131-3 中一些語(yǔ)言開發(fā)功能塊，除此之外，AWPLC 還會(huì)支持用 AWBlock 開發(fā)功能塊，在后續(xù)文章中，我們將一一介紹，敬請(qǐng)關(guān)注。AWPLC 目前還處于開發(fā)階段的早期，寫這個(gè)系列文章的目的，除了用來(lái)驗(yàn)證目前所做的工作外，還希望得到大家的指點(diǎn)和反饋。如果您有任何疑問和建議，請(qǐng)?jiān)谠u(píng)論區(qū)留言。