# 云网关设备接入

# 1 功能概述

云网关功能可以帮助您将存量设备迁移至 FogCloud 平台，您也可以自由定义设备的 MQTT 主题和消息格式，并使用云网关功能接入到 FogCloud 平台中。使用云网关接入的设备，可以使用 FogCloud 大部分功能，包括但不限于设备模拟器、设备调试、设备影子、规则引擎和设备消息订阅等。

# 2 设备数据流转

# 3 使用说明

# 3.1 云网关创建

云网关参数主要包含认证器、云网关解析器和设备控制器；

# 3.1.1 认证器

认证器用于云网关设备连接 FogCloud MQTT 服务器时的身份认证，您可以选择一方认证或者三方认证两种方式；

# 1. 一方认证

若选用该认证方式，FogCloud 会直接对云网关设备的 MQTT 连接参数进行身份认证，您在创建云网关设备时，需要传入：ClientID、用户名、密码，云网关设备使用这些参数连接 FogCloud MQTT 服务器。

# 2. 三方认证

三方认证需要您实现自己的 HTTP 认证服务器，并在创建云网关时，输入服务器的 URL 和 HTTP 请求方法；FogCloud 会在云网关设备连接 MQTT 服务器时，向您的服务器发起 HTTP 请求，请求体为：

{
    "username": "string",   
    "password": "string",  
    "clientid": "string"
}

第三方服务器需要按以下设定的格式响应请求：

认证通过，返回：

HTTP Status Code: 200

认证失败，返回：

HTTP Status Code: except 200

# 3.1.2 云网关解析器

云网关解析器（以下简称为解析器）用于将您为设备自定义的 MQTT 主题和消息体，转换为 FogCloud 平台标准设备通信协议（参考设备通信协议文档 (opens new window)）。解析器支持云函数、自定义 URL、解析脚本。

示例：

云网关设备上报物模型数据

自定义 topic：user/diy/device/data（内容由您自定义，此处仅给出示例）

自定义消息体：

{
  "props": {
    "prop1": 1,
    "prop2": 2,
    "prop3": "string"
  }
}

您需要将上述数据转换为以下格式：

FogCloud 物模型 topic：fogcloud/{pk}/{dn}/thing/up/property/post

FogCloud 物模型消息体：

{
    "id": 1,
    "version": "1.0",
    "timestamp": 1631585734,
    "params": {
         "prop1": 1,
         "prop2": 2,
         "prop3": "string"
    }
}

# 3.1.3 设备控制器

设备控制器（以下简称为控制器）用于将 FogCloud 平台下发的标准设备控制协议转换为您设备的自定义协议。控制器同样支持云函数、自定义 URL、解析脚本。

# 3.2 云网关设备创建

云网关设备创建时，需要传入：ClientID、用户名、密码，云网关设备应使用这些参数连接 FogCloud MQTT 服务器。注意：FogCloud 会使用 ClientID 和用户名生成唯一的设备标识，您需要保证ClientID+用户名的唯一性。

# 3.3 云网关设备数据处理

# 3.3.1 解析脚本

FogCloud 提供脚本解析器，您可以编写脚本对云网关设备的上下行数据进行处理。解析脚本使用 javascript 语言，您需要实现handleUplink、handleDownlink这两个函数；

# 1. `handleUplink`函数

该函数用于设备上行数据处理，入参是rawObj，其中rawObj.raw_payload字段是经过 base64 编码后的字符串。预设脚本中定义了base64DecToArr函数用于 base64 解码。

函数入参：rawObj

{
    "raw_topic": "string",
    "raw_payload": "string", // base64 encoded string
    "device_name": "string",
    "product_key": "string"
}

函数返回值：fogObj

{
    "fog_topic": "string",
    "fog_payload": "string"
}

# 2. `handleDownlink`函数

该函数用于设备下行数据处理，入参是fogObj，其中rawObj.raw_payload字段需要进行 base64 编码。预设脚本中定义了base64EncArr函数用于 base64 编码。

函数入参：fogObj

{
    "fog_topic": "string",
    "fog_payload": "string",
    "raw_clientid": "string",
    "raw_username": "string",
    "raw_password": "string"
}

函数返回值：rawObj

{
    "raw_topic": "string",
    "raw_payload": "string" // base64 encoded string
}

# 3. 字段说明

字段	类型	说明
raw_topic	string	云网关设备上报数据的 topic，内容由您自定义
raw_payload	string	云网关设备上报数据的 payload，内容由您自定义；（注意：作为入参时 FogCloud 会对其进行 base64 编码再作为入参；作为返回值时，您需要在脚本中对其进行 base64 编码）
fog_topic	string	FogCloud 设备通信协议中定义的 mqtt 主题，参考文档设备通信协议文档 (opens new window)
fog_payload	string	FogCloud 设备通信协议中定义的 mqtt payload，参考文档设备通信协议文档 (opens new window)
raw_clientid	string	云网关设备创建时您提填入的 ClientID
raw_username	string	云网关设备创建时您填入的用户名
raw_password	string	云网关设备创建时您填入的密码

# 3.3.2 云函数/自定义 URL

您可以使用云函数或自定义 URL 的方式实现上下行数据处理；

# 1. 上行数据处理

FogCloud 根据配置，向第三方服务器或者云函数发起 http 请求，请求体为：

{
    "raw_topic": "string",   //存量设备原始topic
    "raw_payload": "string", //存量设备原始payload，经过base64编码；
    "device_name": "string", //存量设备在fogcloud的dn
    "product_key": "string", //存量设备在fogcloud的pk
}

第三方服务器需要按以下设定的格式响应 http 请求： HTTP Status Code 200;

{
    "fog_topic": "string",  //fogcloud标准物模型topic
    "fog_payload": "string" //fogcloud标准物模型json数据格式
}

# 2. 下行数据处理