如何擴展自定義功能塊，以及代碼生成器的用法

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

背景

AWTK全稱 Toolkit AnyWhere，是 ZLG 開發的開源 GUI 引擎，旨在為嵌入式系統、WEB、各種小程序、手機和 PC 打造的通用 GUI 引擎，為用戶提供一個功能強大、高效可靠、簡單易用、可輕松做出炫酷效果的 GUI 引擎。

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

簡介

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

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

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;

}

*這樣的代碼看起來很簡單，但是恰恰容易出錯，更容易讓人厭倦，沒有什么樂趣。

2. API 和結構的注釋。我們來看看 ZTIMER 的結構注釋：

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

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

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

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

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

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

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

/**
*@property{uint8_t}state
*@annotation["private"]
*狀態。
*/
uint8_tstate;

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

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

}aw_plc_fb_ztimer_t;

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

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

}

*這個 JSON 文件中的內容，和前面結構的注釋很相似，除了呈現的格式不同，同時還加了一些新內容。4. IDE 需要的文檔。功能塊需要提供一個 markdown 文檔，這個文檔會被轉換成 html，在用戶查看幫助時顯示給用戶。ZTIMER 的文檔內容如下：

#ZTIMER

##功能

循環定時器。

>當輸入 IN 為 TRUE 時，開始計時，輸出 Q 為 FALSE，ET 開始記錄過去的時間。
>定時時間到時，COUNT 增加 1，輸出 Q 在本次循環為 TRUE，ET 重置為0。
>輸入 IN 為 FALSE 時重置定時器。

##輸入

* IN **BOOL**為 TRUE 開始計時，為 FALSE 時重置定時器。
* PT **TIME**預設時間(ms)。

##輸出

* Q **BOOL**定時時間是否到（僅在時間到的當次循環為 TRUE)。
* ET **TIME**過去時間(ms)。

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

在進入正題前，我們先聊一下代碼生成器的基本知識。

代碼生成器基本知識

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

代碼生成器是一個普通程序，它能夠生成另外的目標代碼?？梢圆灰a生成器，直接編寫目標代碼嗎？通常情況下是可以的，但是這違背了優秀程序員的第一美德-懶惰。因為懶惰，所以能讓計算機做的事，優秀程序員是不會自己去做的。

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

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

• 主動代碼生成器目標代碼生成之后，不需要進行修改和完善，每次都重新生成，如果需要修改，修改元數據和代碼生成器。比如編譯器就是此例。前面提到的 MVVM 的 ViewModel 和 AWFlow 應用代碼生成也屬于此類。如果可以，優先使用主動代碼生成器。

2.基本形式

這是代碼生成器的基本形式：代碼生成器讀取元數據，生成目標代碼。元數據是描述數據的數據，這里是描述目標代碼的數據，也就是控制目標代碼的參數。一般情況下，目標代碼整體結構由代碼生成器決定，而變化的部分由元數據決定。

代碼生成器本身一個很有意思的話題，有機會可以專門來聊聊，本文就不扯遠了。

AWPLC中的代碼生成器

按前面代碼生成器的分類方式，AWPLC 里實現了一個主動代碼生成器，實現成主動代碼生成器是很重要的，AWPLC 還在快速迭代中，有些接口可能會變化，主動代碼生成器保證，即使接口有變化，也只需要運行一些腳本，重新生成目標文件即可。

1.基本架構

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

2.功能塊描述文件格式

描述文件用標準的 JSON 格式，其內容包括兩個部分：

2.1基本信息

基本信息包括：

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

示例：

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

2.2屬性描述對于每個屬性，又包括下列信息：

• name 屬性名；
• desc 屬性描述；
• type 實際的數據類型；
• data_type（可選）用于在 IDE 中時類型檢查，缺省為 type 對應的 IEC 的數據類型，但是有時可用 ANY_INT 和 ANY_NUM 等來放寬類型檢查；
• annotation 用于額外的標識。目前主要用于指定輸入輸出等特性。

示例：

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

},

2.3使用方法

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

node gen.js 描述文件名。

如：

nodegen.jsinput/zlg/misc/ztimer.json

上面介紹了用 C 語言開發原生功能塊的方法。當然，也可以用 IEC 61131-3 中一些語言開發功能塊，除此之外，AWPLC 還會支持用 AWBlock 開發功能塊，在后續文章中，我們將一一介紹，敬請關注。AWPLC 目前還處于開發階段的早期，寫這個系列文章的目的，除了用來驗證目前所做的工作外，還希望得到大家的指點和反饋。