映射表(Mapping)脚本

1. 基本概念

1.1 什么是映射

Mixiot中数据采集和对象数据是分开的。一个对象的数据采集可以使用一个数据采集终端；一个复杂对象的数据采集，可以同时使用多个数据采集终端。同样，一个数据采集终端，也可以同时采集多个对象的数据。

一个数据采集终端一次采集的全部数据，称为一个栅格（Grid）；一个栅格就像一个棋盘，棋盘的每个格子中是采集的实际数据。比如温度（K1）、压力（K2）、频率（K3）、电流（K4）、电压（K5）等，其中K1、K2、K3、K4、K5叫做栅格的键（Key）。

映射表的作用就是把不同的采集数据拼接到一起，变成对象的一个完整数据。其中，拼接后的数据X1、X2、X3...称为对象的柔性变量（Flexible Varible，简称FV）。

对象拼接后的数据叫做“马赛克（Mosaic）”，马赛克与栅格之间的对应关系可以表示为：

X1 = $D-1:K1
X2 = $D-1:K2
X3 = $D-1:K3
X4 = $D-1:K4
X5 = $D-1:K5
X6 = $D-1:K6
X7 = $D-2:K1
X8 = $D-2:K2
X9 = $D-2:K3
X10 = $D-2:K4

1.2 什么是同步计算映射

Mixiot映射不仅仅是数据的直接拼接，还可以同步计算拼接。假设一个机电设备，K1,K2分别是机电设备的电流和电压；因为这个设备的阻抗在随时在变化，所以采集的电流和电压在一直变化。此时需要知道阻抗的数据以分析它们之间的关系，则可以多配置一个阻抗变量（X11）；其中组态变量等于电压除以电流。

X1 = $D-1:K1
X2 = $D-1:K2
X11 = X2/X1

1.3 什么是条件事件

Mixiot映射有一种特殊的情况，映射不是拼接数据，而是发布一个事件消息。假设一个锅炉设备，K1是采集的温度数据。当温度大于1000℃时，表示锅炉存在异常、需要进行报警；此时可以配置一个事件类型的FV变量，当满足条件时则发送事件消息。

1.4 什么是同步外源映射

Mixiot是开放的事件驱动的实时系统，映射拼接的数据来源不仅仅是数据终端采集的在线数据，也可以是卡片应用（或API接口）录入的离线数据，还可以是系统服务产生的事件数据（比如统计计算结果、数据分析结果等）。

2. 映射表

在Mixiot中通过“映射表”表示映射关系，映射表是一个Json格式的脚本。

2.1 脚本规则

一行映射表的格式如下：

[`FV/Code`, `LabelEn`, `LabelLocal`, `Category`, `Channel`, `Key`, `LogicExpr1`, `LogicExpr2`, `PublicParams`]

• 第一列

数据拼接时第一列称为FV（即Flexible Varible，柔性变量）， 是对象数据映射后的马赛克变量名（如“S01”为电流）；

FV一般是不超过64个字符的字符串（要用双引号括起来），FV命名不能以$1，$2，$3，$4，$5为后缀结尾。因为mosaic的FV为五层缓存结构，在表达式中如果要因为某一层的FV进行计算或比较，需要用FV名+$1的形式，如S01$1，其中$1表示最上面那层（也就是最近一次的FV数据），$5表示最低下那层（即最旧的一层）；

当表达式中引用某一层的FV，需要加上中括号[]，如"[S01$1]+1"的形式；

发布事件时第一列称为Code（事件编码），是发布事件消息的统一编码（如"C1001"为开始生产事件，"C1002"为结束结束事件）；Code也是不超过64个字符的字符串（要用双引号括起来）。当第八列（逻辑表达式2）满足条件时，会按照Code发布事件消息；

在一个映射表脚本中，定义的FV/Code需要是唯一的。

• 第二列

LabelEn为英文标签，主要对FV/Code用英文进行描述

• 第三列

LabelLocal为本地（中文）标签，主要对FV/Code用本地（中文）语言进行描述

• 第四列

Category为映射类型，分为STA, AGT, EVNT三类映射类型。

其中，STA是采集终端或者离线数据采集的数据进行拼接、AGT类型是订阅事件消息的数据进行拼接；EVNT为发布事件消息，当第八列（逻辑表达式2）满足条件时，生成事件给历程处理。

• 第五列

Channel为数据来源，分为终端编号、离线标识和事件消息条件。

当第四列Category为STA，填写终端编号或离线标识，表示从某个终端或某个离线采集数据。其中，Channel可以填写实际的编号（比如AX20211104001、COL114113310001）；也可以填写宏变量$AprusID-index或$CollectID-index（index为数字索引），比如：$AprusID-1表示对象关联适配器列表的第一个适配器, $CollectID-2表示对象关联离线列表的第二个离线数据, 拼接时映射表会自动进行宏变量替换为实际的编号；

当第四列Category为AGT时， 填写订阅事件消息条件，格式为{"key":"val"}。其中，key:value是订阅事件的过滤条件，映射表会根据这些条件去订阅事件；比如:{uid":"STATISTICS1395846800006","block":"statistics","event":"statistics_result","object_id":"OBJ202110100001"}，表示订阅统计编号为STATISTICS1395846800006、对象编号为OBJ202110100001的统计结果。其中，object_id的值也可以写成宏变量的方式$ObjectID-index，比如：$ObjectID-1表示对象子对象列表的第一个对象。特别地，$ObjectID-0表示对象本身编号。

• 第六列

Key为数据键名，比如L1_2_3、Temp、data。当Category为STA, EVNT时，与第五列对应填写采集终端上报的key后离线数据采集的key；当Category为AGT时，填写订阅事件消息返回值的键名。其中，事件消息时键名可以写成多层key的形式，如key1.key2.key3

• 第七列

LogicExpr1为逻辑表达式1，主要用于值计算，当第四列Category为映射类型为STA或AGT、且不是直接拼接而是需要计算后拼接情形填写。比如：min(S01,S02)，表示取S01和S02中较小的一个拼接。

• 第八列

LogicExpr2为逻辑表达式2，主要用于判断是否生成事件，当第四列Category为映射类型为EVNT时填写。比如：S01>100，表示S01大于100时发布事件消息，小于等于100则不发布。

• 第九列

PublicParams为公共参数，配置FV变量的一些特殊属性，包括FV过期时间(expire_time)、FV默认值(default_value)等。本列为Josn格式，比如{"expire_time": "1m5s", "default_value": 1}，表示FV过期时间是1分钟又5秒（65秒）、同时该FV默认值为 1

FV过期时间65秒的含义是，65秒内该FV都没上报拼接，则该FV将被清空

FV默认值为1的含义是，当FV初始化时还没有上报拼接数据、又需要使用该FV进行逻辑表达式计算，则使用默认值进行计算

2.2 脚本示例

下列脚本定义了 v1、v2、v3、v4、v5、v6、v7、v8、v9等9个马赛克变量和1001、1002、1003等3个事件消息。

[
    ["v1", "", "终端采集-宏变量方式", "STA", "$AprusID-1", "L1_3_7_2", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v2", "", "终端采集-宏变量方式", "STA", "$AprusID-1", "L1_3_7_2", "v1+10", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v3", "", "终端采集-固定适配器", "STA", "AX20210229000249", "L1_3_7_2", "v2+10", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v4", "", "离线数据-宏变量方式", "STA", "$CollectID-1", "Tem", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v5", "", "离线数据-固定离线编号", "STA", "COL12236500002", "Tem", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v6", "", "统计结果-事件消息", "AGT", {"uid":"STATISTICS1395846800006","block":"statistics","event":"statistics_result"}, "data", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v7", "", "Indass分析结果-事件消息", "AGT", {"uid":"index1001","block":"indass","event":"indass_result"}, "index_change_accelerate", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v8", "", "函数计算", "STA", "$AprusID-1", "L1_3_7_2", "min(v1, v2)", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v9", "", "比较运算", "STA", "$AprusID-1", "L1_3_7_2", "v1>v2?v1:v2", "", {"expire_time": "1m5s", "default_value": 1}],
    ["1001", "start event", "开始事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "v1==0", {}],
    ["1002", "stop event", "停止事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "v1==1", {}],
    ["1003", "stop event", "停止事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "[v1$5]==1", {}]
]

注意：针对以上映射表脚本第一列fv命名中包含-短横线的情况，需要用[]来对命名进行转义，如["v-1"]的情况

2.3 表达式

逻辑表达式1 与 逻辑表达式2 的语法规则是一样的，只是应用场景有所不同。逻辑表达式1一般是计算表达式，用于计算结果；逻辑表达式2一般是布尔表达式，用于判断条件是否成立。

• 运算符

注意：优先级值越大，表示优先级越高，如果因为运算符导致计算结果又偏差，可以使用 () 来规范表达式优先级

2.4 函数

注意：函数内参数一般都是整数或浮点数，非特殊情况，不要填入字符串，以免造成计算错误或其他不可预知的问题

2.5 参数说明

逻辑表达式由运算符、函数和参数组成，其中参数是已定义的FV变量，FV变量支持5层数据。假设一个变量为S01，则最新的第一层数据为[S01$1]，次新的第二层数据为[S01$2]...，最旧的第5层数据为[S01$5]；特别地，最新的一层[S01$1]一般直接写自身S01。

2.6 拼接顺序

假设定义了两个FV变量v1和V2

[
    ["v1", "", "终端采集-宏变量方式", "STA", "AX2021110400001", "L1_3_7_2", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v2", "", "终端采集-宏变量方式", "STA", "AX2021110400001", "L1_3_7_2", "v1+10", "", {"expire_time": "1m5s", "default_value": 1}]
]

变量v1是直接拼接的方式，在适配器AX2021110400001上报L1_3_7_2数据时则进行拼接。

变量V2是计算拼接的方式，当v1拼接完成后、自动计算 v1加10的结果进行拼接。

特别地，v2中填写的适配器AX2021110400001和键L1_3_7_2数据上报时也会触发计算；为保持数据一致一般与v1填写的一致，或者填写一个不存在的键（不会根据上报触发拼接，只根据v1联动触发拼接）