元素脉冲插件开发文档 V1.0.1

Element Pulse Plugin Developer Docs V1.0.1

[介绍]Introduce

元素脉冲基于NodeJS工作,它由前端和后台组成.

你可以基于强大的NPM快速构建自己需要的插件.

我们提供了一套友好的API面向开发者,通过阅读此文档可以快速开发组件原型.

[准备工作]Ready Work

想要开始开发自己的组件,首先你需要搭建开发环境和了解一下它的运行机制.

[成为开发者]

如果你希望自己的组件可以通过插件市场给与更多人使用,请按照以下操作进行:

​ 1.到官网上申请注册成为认证开发者

​ 2.在开发者后台创建自己的组件

​ 3.获取该组件的开发秘钥

[开发环境搭建]

1. 安装元素脉冲,系统会自动安装NodeJS、MongoDB、MQTTX
2. 安装代码编辑器,你可以使用VSCode或其他顺手的工具进行开发.

[工作流]Workflow

上图所示,系统从以下几个部分使用到了插件:

• 初始化插件库:系统启动时,遍历插件目录搜索config.json文件,并将其刷新到数据库当中.
• 前端蓝图初始化:每次前端打开蓝图编辑页面时,前端会向后端请求数据库列表.后端返回插件列表和每个插件的配置数据
• 运行蓝图:每个蓝图被运行时,系统会调用该蓝图中引用的所有插件并向其传递蓝图中设定的属性信息.

[开始制作]Getting started

[设计组件]Design plugin

开始制作组件的第一步,你应该清楚知道自己的组件要实现哪些功能,拥有哪些输入/输出节点和属性.

你可以使用插件设计器,直观的设计自己的组件接口和样式:

我们为你提供了描述组件所有的接口及信息的地方:config.json

**[注意]**这个文件应该存放在system/blueprint/plugins/{插件类别}/{插件名称}/config.json

系统只会从此级别的路径中搜索config.json文件

[配置示例] config.json

config.json example:

{
    "name": "example-plugin",
    "title": "example title",
    "type": "example",
    "version": "1.0.0",
    "description": "this is example plugin.please do not use it!",
    "author": "author name",
    "id": "xxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxx",
    "link": "https://www.elementpulse.com",
    "icon": "icon.png",
    "supportVer": "1.0.0",
    "input": {
        "test": {
            "title": "测试节点",
            "description": "测试输入节点,此文本将于前端鼠标指向该节点时显示.",
            "maxLink": 0,
            "allowTypes": []
        }
    },
    "output": {
        "onData": {
            "title": "",
            "description": "测试输出节点,此文本将于前端鼠标指向该节点时显示.",
            "type": "string"
        }
    },
    "attrib": {
        "address": {
            "title": "连接地址",
            "description": "连接地址",
            "val": "mqtt://localhost:1803/SMCC",
            "optional": [
                "mqtt://localhost:1803/SMCC"
            ],
            "onlyOpt": false
        }
    }
}

| 节点名 | 类型 | 注释 | | ----------- | ------ | ------------------------------ | | name | String | 组件名称 | | title | String | | | type | String | | | version | String | 组件版本 | | main | String | 入口文件,默认为index.json | | description | String | 组件说明 | | author | String | 作者名称 | | id | String | 插件全球唯一ID,可以到这里申请. | | link | String | 作者连接 | | icon | String | 插件图标路径,支持SVG、PNG | | input | Object | 输入接口定义 | | output | Object | 输出接口定义 | | attrib | Object | 属性接口定义 |

[input/output节点]

| 节点名 | 类型 | 注释 | | ----------- | ------ | --------------------------------------------- | | title | string | 节点名称 | | description | string | 节点注释,它将呈现在用户鼠标悬停该节点时 | | maxLink | int | 设置该节点最大可连接数,0为无限. | | outType | string | 该节点输出类型(该属性只有output拥有) | | allowTypes | array | 设置该节点允许接入的类型(该属性只有input拥有) |

[attribute节点]

请将以下数据包裹成数组进行传递

| 节点名 | 类型 | 注释 | | -------- | ------ | ------------------------------------------------------------ | | title | string | 属性名 | | val | any | 默认值 | | optional | Array | 待选值,它将显示在节点属性面板上,给用户提供选择.这个属性可以被动态设置 | | onlyOpt | bool | 只允许用户从待选值中选择数据. |

[创建工程]Create Compment

我们使用TypeScript标准进行插件开发，其语法书写更加清晰和方便，同时它和C++/C#/Java等编程语言相似，使得我们可以在熟悉的环境中友好的开发。

使用脚设计器构建工程:

你可以到这里在线设计和导出工程.

使用原始方法构建工程:

1. 创建插件目录:在system/blueprint/plugins/{插件类别}/目录下创建你的插件目录

2. 使用NPM创建工程:

   @PowerShell:
   cd /d system/blueprint/plugins/{插件类别}/{插件目录}
   npm init epp

[插件代码模板]Code template(index.js)

import Plugin from 'mgps-plugin-support';
export default class YourPluginName extends Plugin {
	#attrib={}
    //组件集构造时调用
    constructor(config) {
        super(config);//初始化组件JSON配置
    }
    
    //节点集启动时候调用
    begin(attrib) {
		this.#attrib=attrib;
    }
    //节点集合停止时候调用
    stop() {

    }
}

[接口]API

[输入节点]super.input

| 函数 | 类型 | 说明 | | -------------------- | ------------------------------------------------------------ | ---- | | addInvoke | 添加监听invoke事件的函数,当输出节点调用时,激活所有已添加的自定义函数 | | | removeInvoke | 移除监听的invoke事件函数 | | | __invoke(data=null) | [内部函数]当某个输出节点调用时激活 | | | __connect(output) | [内部函数]当某个输出节点连接到此节点时会调用此函数,用于反向追查哪些输出连接到了这个节点 | | | __disconnect(output) | [内部函数]当某个输出节点与此节点断开时触发 | |

[输出节点]super.output

| 函数 | 类型 | 说明 | | ------------------- | ------------------------------------------------------------ | ---- | | invoke | 添加监听invoke事件的函数 | | | removeInvoke | 移除监听的invoke事件函数 | | | __invoke(data=null) | [内部函数]激活这个节点函数 | | | __input | [内部函数]当某个input节点连接到此output节点时会调用此函数,用于反向追查哪些input连接到了这个节点 | |

[组件属性]super.attr

[全局唯一对象]super.global

我们为每一种类型的组件提供一个了全局唯一对象,它可以让多个组件实例访问同一个对象.

这有助于同类组件的相互通信和资源复用,比如串口通讯组件可以实现多组件实例引用同一个串口资源.

你可以任意的自定义数据到全局对象上.如:

super.global.myData={a:1,b:2};

组件的相互通讯示例:

class YourCompmentName extends Compment {
	//组件集构造时调用
    #mark="";
    constructor(config) {
        super(config);
        if(!super.global.instance)super.global.instance=[];
        this.#mark=super.global.instance.length.toString();
        super.global.instance.push(this);
    }mark

    //节点集启动时候调用
    run() {
		if(this.#mark==1){
            super.global.instance[0].echo();
            super.global.instance[0].getInstanceCount();
        }
    }
    //节点集合停止时候调用
    stop() {
		super.global.instance.splice(super.global.instance.indexOf(this), 1);
    }
    
  	//输出实例
    echo(){
        console.log(`我是实例${this.#mark}`);
    }
    getInstanceCount(){
    	console.log(`已实例的组件数量:${super.global.instance.length}`);
    }
}

[实例ID]super.id

​ 每一个组件实例都有一个系统生成的唯一ID,它由前端创建时生成,并随组件

[语言翻译]