属性上报预处理规则


属性上报预处理规则

属性上报预处理规则 的触发时间,是在云平台接收到硬件上报的属性,且在正式更新设备属性之前。适合用于对设备上报属性做必要的格式处理、二次计算、转化、合并等,总之可以进行任意的加工。

目前支持的操作如下:

预处理函数

提供了可编程的云函数,支持 Javascript 编程语言,如下:

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象,同时作为函数返回值。函数中可操作属性对象。
     */
    
    return report_attributes;
}

举个简单的例子,假如我们要记录设备上报湿度 humidity 的次数,可以写一个这样的预处理函数:

module.exports = function (report_attributes) {

    if (report_attributes.humidity !== undefined) {
        // 读取设备当前的属性
        var curr_attrs = Cloud.getCurrentAttributes();

        if (curr_attrs.count === undefined) {
            // 计数count不存在,说明是首次上报
            report_attributes.count = 1;
        } else {
            // 计数+1
            report_attributes.count = curr_attrs.count + 1;
        }
        
    }

    return report_attributes;

}

在此基础上,只要熟悉一定的 Javascript 编程,还可以改为只统计当日的上报次数,或者计算当日的湿度平均值。

内置函数

预处理函数中除了可以调用 Javascript 的标准函数外,ThingsCloud 还提供了一系列的内置函数,增强了云函数的能力。这些内置函数将会不断增加。

Cloud.getCurrentAttributes

读取设备当前的所有属性当前值。

在对上报属性进行预处理时,如果需要设备当前的所有属性值,可以调用该函数。

参数

返回值
  • object 类型,设备的属性当前值键值对集合,例如:
{
    "activity": 0,
    "battery": 69,
    "co2": 855,
    "humidity": 36.5,
    "illumination": 34,
    "infrared": 15
}
示例

举个简单的例子,我们将 小米 Zigbee 无线按键 通过智能网关接入 ThingsCloud,这是一个功能强大的多状态按键,不像通常的智能开关只有 ON/OFF 两个状态,它支持 单击、双机、三击、长按 共四个状态。

当按键每次被单击时,会上报属性,如下:

{
    "click": "single"
}

假如我们希望通过单击按键来切换灯泡的开关,可我们并不知道这次单击是开灯还是关灯。这时我们可以利用如下预处理函数,来生成一个新的状态,表示按键的虚拟开关状态。

module.exports = function (report_attributes) {
     
    if (report_attributes.click == 'single') {
        // 读取设备当前属性值,如果无该属性,默认为 false
        const attributes = Cloud.getCurrentAttributes().status || false;
        // 根据上一次开关状态来更新本次状态
        report_attributes.status = attributes.status ? false : true;
        // 顺便生成显示在应用上的文字
        report_attributes.status_text = attributes.status ? 'OFF' : 'ON';
    }
    
    return report_attributes;
}

属性上报经过这个预处理函数后,会变为如下:

{
    "click": "single",
    "status": true,
    "status_text": "ON"
}

所以云平台上该设备最终接收到的实际上是上边这组属性。

Cloud.gpsWGS84toGCJ02

用于将 GPS 原始 WGS84 坐标转化为国内的 GCJ02 坐标,转化后的坐标可以在腾讯地图、高德地图上正确显示位置。

参数
  • pointMapPoint 类型,参考 MapPoint 数据类型。输入 GPS 原始坐标位置,通常为 GPS 模组直接返回的坐标信息。
返回值
  • MapPoint 类型,经过转化的坐标位置。
示例
module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        report_attributes.location_gcj02 = Cloud.gpsWGS84toGCJ02(report_attributes.location);
    }
    
    return report_attributes;
}

Cloud.gpsWGS84toBD09

用于将 GPS 原始 WGS84 坐标转化为国内的 BD09 坐标,转化后的坐标可以在百度地图上正确显示位置。

使用方法同上。

Cloud.isPointInCircle

用于判断某个坐标位置是否处于圆形地理区域内部,实现电子围栏的功能。

参数
  • pointMapPoint 类型,输入当前位置坐标。
  • circleMapCircle 类型,圆形地理区域。参考 MapCircle 数据类型
返回值
  • Boolean 类型。true 表示是区域内,false 表示不在区域内。
示例

假如我们已经为设备写入电子围栏的属性,如下:

{
    "circle": {
        "centerPoint": {
            "lat": 39.462,
            "lng": 140.391
        },
        "radius": 100
    }
}

然后属性上报预处理函数如下:

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值,拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInCircle(report_attributes.location, attributes.circle);
    }
    
    return report_attributes;
}

当设备上报当前位置后,会立即触发以上规则,电子围栏的判断结果将写入设备的属性 in_area

每个设备都可以独立设置自己的电子围栏,然后共用所属设备类型的同一个预处理规则。

Cloud.isPointInPolygon

用于判断某个坐标位置是否处于多边形地理区域内部,实现电子围栏的功能。

参数
  • pointMapPoint 类型,输入当前位置坐标。
  • polygonMapPolygon 类型,多边形地理区域。参考 MapPolygon 数据类型
返回值
  • Boolean 类型。true 表示是区域内,false 表示不在区域内。
示例

假如我们已经为设备写入电子围栏的属性,如下:

{
    "polygon": [
        {
            "lat": 38.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 141.391
        },
        {
            "lat": 38.462,
            "lng": 141.391
        }
    ]
}

然后属性上报预处理函数如下:

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值,拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInPolygon(report_attributes.location, attributes.polygon);
    }
    
    return report_attributes;
}

当设备上报当前位置后,会立即触发以上规则,电子围栏的判断结果将写入设备的属性 in_area

每个设备都可以独立设置自己的电子围栏,然后共用所属设备类型的同一个预处理规则。

GPS 位置坐标系转换

用于将 GPS 原始 WGS84 坐标转化为国内的 GCJ02(火星坐标)或 BD09(百度坐标),转化后的坐标可以在国内地图平台上正确显示位置。

在 ThingsCloud 的可视化看板中也提供了地图组件,同样经过这个坐标体系转换后,就可以显示正确的位置。如果直接显示 GPS WGS84 原始坐标,大概有几百米距离的偏移。

该操作需要填写以下内容:

  • 输入坐标属性:填写设备上报原始 GPS 位置的属性标识符,该属性必须是 MapPoint 类型。
  • 转换方式:选择希望转换的目标坐标体系。
  • 输出坐标属性:填写用于保存转换结果的属性标识符,该属性必须是 MapPoint 类型。

如果设备所属设备类型已经创建了相应的属性功能定义,以上填写属性标识符时,会有联想提示。

GPS 位置电子围栏检查(圆形)

用于判断某个坐标位置是否处于圆形地理区域内部,实现电子围栏的功能。

该操作需要填写以下内容:

  • 位置属性:填写表示设备当前位置的属性标识符。该属性必须是 MapPoint 类型。
  • 电子围栏属性:填写用于保存转换结果的属性标识符。该属性必须是 MapCircle 类型。
  • 结果属性:填写用于保存计算结果的属性标识符,输出结果的数据类似是 Boolean,代表是否处于电子围栏内部。

如果设备所属设备类型已经创建了相应的属性功能定义,以上填写属性标识符时,会有联想提示。

GPS 位置电子围栏检查(多边形)

用于判断某个坐标位置是否处于多边形地理区域内部,实现电子围栏的功能。

该操作需要填写以下内容:

  • 位置属性:填写表示设备当前位置的属性标识符。该属性必须是 MapPoint 类型。
  • 电子围栏属性:填写用于保存转换结果的属性标识符。该属性必须是 MapPolygon 类型。
  • 结果属性:填写用于保存计算结果的属性标识符,输出结果的数据类似是 Boolean,代表是否处于电子围栏内部。

如果设备所属设备类型已经创建了相应的属性功能定义,以上填写属性标识符时,会有联想提示。