租赁共享解决方案快速接入分享

[Mack.zhang]

移远租赁共享全链路开发

1. 引言

本文档规范了 使用 Quecthing 的移远模组连接开发者中心的标准流程，本文已共享充电桩为例。

2. 范围

本文档适用于包含 Quecthing 功能的移远蜂窝模组与开发者中心开发者中心、移远租赁共享Saas、微信小程序。

3. 术语与定义

名词	描述
ProductKey	开发者中心为产品颁发的全局唯一标识。
ProductSecret	由开发者中心颁发的产品密钥，与ProductKey成对出现，用于一型一密的认证方案。
产品	设备的集合，通常是将具有相同功能定义（物模型）的设备归属到一个产品下。
设备激活码	设备接入开发者中心后若累计上下行消息达到指定阈值，会消耗一个设备激活码。
DeviceKey	在注册设备时，自定义的或系统生成的设备标识。
DeviceSecret	在设备使用ProductKey、ProductSecret、DeviceKey进行平台认证通过后，开发者中心会为该设备下发设备密钥即DeviceSecret。

缺少

4 设备快速上云的流程

4.1 平台侧操作

4.1.1 登录开发者中心

登录开发者中心，未注册可单击立即注册完成注册。

4.1.2 创建产品

根据实际的项目需求在开发者中心创建产品 。

提示：ProductKey、ProductSecret码需用户保存好，设备的连接将会需要使用到该ProductKey、ProductSecret。

4.1.3 添加物模型

创建产品后进入到产品开发 >功能定义添加标准物模型，亦可根据实际的项目需求去增删查改。该物模型用作于整条链路的调试。

4.2 设备侧操作（QuecOpen方案）

从下载中心下载对应模组的QuecOpen SDK，若未找到则需要联系移远技术支持。

4.3.1 初始化配置

开发前您还需要完成工程的QuecOpen方案的初始化，需要在使用联网服务前调用。

/* 初始化QuecThing SDK */ Ql_iotInit();

4.3.2 事件回调

事件回调处理接口简单的说就是为事件源(组件)添加一个监听任务 Ql_iotEventCB() 。

/* 注册事件回调函数 */ Ql_iotConfigSetEventCB(Ql_iotEventCB);

4.3.3 配置产品信息（初次连接需配置）

/* 配置产品信息*/ Ql_iotConfigSetProductinfo(“p1xxxS”, “VnhyxxxxxxxxSTFh”);

4.3.4 连接开发者中心

模组启动连接开发者中心。

/* 启动云平台连接 */ Ql_iotConfigSetConnmode(1);

4.3.5 查询当前连接状态

为了进一步确认设备是否正常连接开发者中心，可通过调用 Ql_iotGetWorkState() 函数查看其返回值判断状态，若已确定设备与平台建立连接并可进行数据交互业务。

/* 获取当前工作状态 */ QIot_state_e status = Ql_iotGetWorkState();

5 租赁共享Saas使用

5.1 开通租赁共享Saas行业解决方案

登录开发者中心后，点击左侧菜单栏“行业解决方案”，进入行业解决方案页。 在该页面可查看移远目前开放提供的行业解决方案介绍，先开通租赁共享解决方案。

5.2 注册租赁共享平台

初次登陆租赁共享Saas时可选择授权登陆，使用开发者中心的账号注册租赁共享Saas的账号，该两个账号可不相同。

5.3 开启消息订阅

开启消息订阅主要用于实时接收设备上报的数据。

5.4 设备列表

若已完成本文中第四步的操作，现打开设备管理 >设备列表即可看到该设备也已经同步到租赁共享Saas。导入设备有两种方式

1、设备上线后 开发者中心平台自动同步到Saas平台

提示：设备端需上报一条数据或者是设备重新上线后即可同步到Saas平台

2、在商用Saas平台点击导入按钮进行导入。

6 流程配置（Saas侧与设备侧联调）（确定服务模式）

在租赁共享Saas 产品管理 >产品列表选择所创建的产品，点击流程配置按钮。

流程配置预览如下图所示

6.1 首页配置（可选）

配置首页的页面元素，更换地图图标，地图图标展示的是设备或运营场所。

6.2 扫一扫

6.2.1 Saas平台侧配置

配置设备不可用的规则，扫码时，当设备命中以下规则时，设备不可用，用户扫描设备码时将提示该设备不可使用。

6.2.2 设备端开发

当设备端获取设备高温告警时则上报物模型属性 设备状态-高温告警，示例代码如下所示：

void ttlvHead = NULL; / 添加整型数据-设备状态-高温告警*/ Ql_iotTtlvIdAddInt(&ttlvHead, 1 , 1); /* 发送数据*/ Ql_iotCmdBusPhymodelReport_ex(2,ttlvHead); Ql_iotTtlvFree(&ttlvHead);

6.3 选择端口（仅服务模式为按端口使用）

6.3.1 Saas平台侧配置

若服务模式为“按端口”，提供该界面的功能属性配置，设置端口的图标，端口信息来源物模型的映射，端口号来源物模型的映射，以及端口状态在使用中、禁用中、可使用、故障中时的物模型映射。

6.3.2 设备端开发

当设备端设备端上报设备端口信息-端口号-1/端口状态-使用中/端口禁用标记-启动，示例代码如下所示：

/* 设备端上报设备端口信息-端口号-1/端口状态-使用中/端口禁用标记-启动 */ void *intArrayHead = NULL; void *intArrayHead1 = NULL; Ql_iotTtlvIdAddInt(&intArrayHead, 1, 1); Ql_iotTtlvIdAddInt(&intArrayHead, 2, 1); Ql_iotTtlvIdAddBool(&intArrayHead, 3, TRUE); Ql_iotTtlvIdAddStruct(&intArrayHead1, 0, intArrayHead); Ql_iotTtlvIdAddStruct(&ttlvHead, 2, intArrayHead1); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvHead); Ql_iotTtlvFree(&ttlvHead);

PS：若设备端有多个端口则需要在该数组中上报多个结构体。

6.4 选择购买量

配置页面的显示元素图标，暂可不配置

6.5 启动设备

6.5 .1 下发订单参数设置

用户支付成功后，将对设备下发订单，控制设备启动

6.5.1.1 开始订单

开始订单标识，用于下发您配置的物模型数据控制启动设备，下发后订单为待启动状态

6.5.1.2 订单购买量

先付后用场景，用于对设备下发订单的购买量，设备按照此购买量计算及控制设备输出量

6.5.1.3 购买量单位

订单购买量对应单位

当设备端收到云端下发的 下发订单后，则需要调用打开对应的端口。示例代码如下所示：

当模组接收到物模型请求数据后，则会自动调用 Ql_iotEventCB() 事件回调函数，您可根据相对应的事件进行数据响应处理。例如(*eventCB)(5, 10211,value,valLen)事件表示设备端接收到云端下发的物模型查询命令。

void Ql_iotTtlvHandle(const void *ttlvHead) { quint32_t count = Ql_iotTtlvCountGet(ttlvHead); /获取数据表的节点数量/ quint32_t i; for(i=0;i<count;i++) { uint16_t id; QIot_dpDataType_e type; void *node = Ql_iotTtlvNodeGet(ttlvHead, i, &id, &type); /数据表中提取数据节点/ if(node) { switch (id) { case 2: { /若是结构体在遍历一次数据/ Ql_iotTtlvHandle(Ql_iotTtlvNodeGetStruct(node)); if(node){ switch (id) { case 1: { /若是结构体在遍历一次数据/ Ql_iotTtlvHandle(Ql_iotTtlvNodeGetStruct(node)); break; } default:break; } } break; } default:break; } } } }

6.5 .2 设备启动状态配置

设备使用中标识，用于标识设备已启动成功更新订单状态为使用中

6.3.2 设备端开发

当云端下发订单开始动作时

若设备端启动成功，则需要上报使用中状态的物模型，示例代码如下所示：

/* 设备端上报设备端口信息-端口号-1/端口状态-使用中/端口禁用标记-禁止 */ void *intArrayHead = NULL; void *intArrayHead1 = NULL; Ql_iotTtlvIdAddInt(&intArrayHead, 1, 1); Ql_iotTtlvIdAddInt(&intArrayHead, 2, 1); Ql_iotTtlvIdAddBool(&intArrayHead, 3, FALSE); Ql_iotTtlvIdAddStruct(&intArrayHead1, 0, intArrayHead); Ql_iotTtlvIdAddStruct(&ttlvHead, 2, intArrayHead1); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvHead); Ql_iotTtlvFree(&ttlvHead)

若设备端启动失败，则需要上报对应启动失败状态的物模型，示例代码如下所示：

/* 设备端上报设备端口信息-端口号-1/端口状态-禁用中/端口禁用标记-启动 */ void *intArrayHead = NULL; void *intArrayHead1 = NULL; Ql_iotTtlvIdAddInt(&intArrayHead, 1, 1); Ql_iotTtlvIdAddInt(&intArrayHead, 2, 2); Ql_iotTtlvIdAddBool(&intArrayHead, 3, TRUE); Ql_iotTtlvIdAddStruct(&intArrayHead1, 0, intArrayHead); Ql_iotTtlvIdAddStruct(&ttlvHead, 2, intArrayHead1); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvHead); Ql_iotTtlvFree(&ttlvHead)

6.5 .3 订单状态流转

设备启动成功但检测到用户未使用设备时，可上报此状态用于提示用户尽快使用，若不配置则设备启动成功后将默认订单使用中。示例代码如下所示：

/* 设备端上报设备端口信息-端口号-1/端口状态-禁用中/端口禁用标记-启动 */ void *intArrayHead = NULL; void *intArrayHead1 = NULL; Ql_iotTtlvIdAddInt(&intArrayHead, 1, 1); Ql_iotTtlvIdAddInt(&intArrayHead, 2, 0); Ql_iotTtlvIdAddBool(&intArrayHead, 3, FALSE); Ql_iotTtlvIdAddStruct(&intArrayHead1, 0, intArrayHead); Ql_iotTtlvIdAddStruct(&ttlvHead, 2, intArrayHead1); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvHead); Ql_iotTtlvFree(&ttlvHead)

6.6 订单详情

6.6.1 订单异常配置

当设备命中以下规则时，进入订单异常流程

图文中举例了两种订单异常规则。

规则 1 是当设备由于网络原因离线后，开发者中心通过小程序通知用户订单状态（无需设备端发送心跳包与物模型）

规则 2 是当设备遇到高温告警时，上报该物模型从而触发中断订单。示例代码如下所示：

/* 设备端添加物模型事件类型数据，引用参数：1 */ void *ttlvHead = NULL; void *ttlvEventHead = NULL; Ql_iotTtlvIdAddInt(&ttlvHead, 1, 1); Ql_iotTtlvIdAddStruct(&ttlvEventHead, 50, ttlvHead); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvEventHead); Ql_iotTtlvFree(&ttlvEventHead);

6.6.2 订单完成参数配置

当设备上报以下配置物模型时，将认为订单已完成

若用户线下主动关闭订单时，设备端可上报以下物模型，用作触发云端结束订单操作。示例代码如下所示：

/* 设备端上报物模型-事件-订单事件上报-端口数据*/ void *ttlvHead = NULL; void *ttlvStructHead = NULL; void *ttlvEventHead = NULL; Ql_iotTtlvIdAddInt(&ttlvHead, 10, 3); Ql_iotTtlvIdAddFloat(&ttlvHead, 20, 50.6); Ql_iotTtlvIdAddStruct(&ttlvStructHead, 3 , ttlvHead); Ql_iotTtlvIdAddStruct(&ttlvEventHead, 102 , ttlvStructHead); /发送物模型数据至平台/ Ql_iotCmdBusPhymodelReport_ex(2, ttlvEventHead); Ql_iotTtlvFree(&ttlvEventHead);

6.6.3 下发结束订单配置

6.6.4 设备异常通知配置

当订单进行中的设备触发以下条件时，给商家推送通知，设备可无需上报物模型。

6.6.5 详情页个性化配置（可选）

若有自定义详情页请填入自定义详情页URL，不填则展示默认详情页。

7 支付计费模块

7.1 支付配置

7.1.1 应用配置

支持添加自有小程序或公众号应用，通过对应平台参数的录入进行对接。微信小程序注册申请链接：小程序 (qq.com)

7.1.2 商户配置

支持配置对应级别系统用户，厂商/各运营商等的收款商户号。仅仅配置一个商户即可。

微信商户（直连商户）：

客户需要在微信小程序-打通汇付，从而获取商户号、商户公钥、商户私钥（微信小程序官网https://pay.weixin.qq.com/static/product/product_index.shtml）

汇付商户：

客户需要在微信小程序-打通汇付，从而获取商户号、商户公钥、商户私钥（汇付官网https://nspos.chinapnr.com/nsposomweb/login）

7.2 计费规则

运营商可以维护多个计费规则，将不同的计费规则应用到各运营场所、设备上，实现差异化租赁共享定价模式。列表支持具体计费规则的详情查看、编辑以及查看。

7.3 分润管理（可选）

8 运营管理

8.1 运营商管理

8.1.1 新增运营商

通过点击【运营管理】-【运营商管理】列表进入，该页面显示该账号层级下的所有下属运营商信息。

第一步可新增运营商且分配运营商的账号密码，给运营商用于登陆租赁共享Saas平台。如下图所示填写好运营商信息。

8.1.2 分配设备

添加好运营商之后，需分配指定的设备给对应的运营商，分配之后运营商即可有该设备的使用权限。

8.1.2.1 服务规则设置

设备服务模式，分别有免费使用与付费使用，根据实际的项目需求选择。若是付费使用则需配置试用期、单价等信息。

8.2 运营场所

8.2.1 新增运营场所

可根据区域规划运营场所，支持按运营场所的维度导出该运营场所下设备的应用二维码。

8.2.1 分配设备

9 小程序使用（用户端）

微信小程序名称	场景	描述
小Q商家	To B （商家端）	设备管理（使用运营商账号登陆）
小Q随享	To C（用户端）	购买商品界面、订单详情（使用微信一键登陆）

9. 1 扫码使用设备

微信搜索小Q随享并登陆，通过首页地图扫一扫点击进行二维码扫码，或使用微信右上角【+】扫一扫直接进行设备二维码的识别。

9. 2 选择套餐及订单支付

扫码设备后，进行商品套餐的选择及购买，或进行单价型定价的商品购买量的输入；完成选择后进行【立即支付】，调起对应的支付模块，生成订单。

9. 3 中途订单结算

订单支付完成后进行设备的启动，跳转至订单实时详情页，查看订单进行状态，如倒计时或使用量等。

此时可进行中途中断订单的操作，订单中断后，按基本计费单价进行结算退款。

10 小程序微信后台配置（可选）

倘若不使用移远公版小程序则可以通过以下操作进行配置

10 .1 小程序微信后台配置说明（商家端）

10. 1 .1 登录小程序后台

打开“微信公众平台”页面，管理员扫描登录二维码登录到商家小程序后台

10 .1 .2 开发管理

左侧菜单栏“开发管理”–“开发设置” 开发者 ID。

AppID：自动生成；而AppSecret：需要手动生成/重置

10 .1 .3 服务器域名

Request 合法域名：https://后台 api 接口域名

uploadFile 合法域名：https://后台 api 接口域名

downloadFile 合法域名：https://后台 api 接口域名

如果有其他域名，可根据情况添加。

10 .1 .4 消息推送

URL(服务器地址)：https://后台 api 接口域名/notice/wxma/portal/{appId}

Token(令牌)：开启时自动配置

EncodingAESKey(消息加密密钥)：开启时自动配置

保存之前，在 WEB 系统后台-“支付计费”-“支付配置”-“应用配置”中添加应用，填写对应的必填信息后保存

10 .2 小程序微信后台配置（用户端）

10. 2 .1 登录小程序后台

打开“微信公众平台”页面，管理员扫描登录二维码登录到商家小程序后台。

10. 2 .2 开发管理

左侧菜单栏“开发管理”–“开发设置” ，开发者 ID。

AppID：自动生成；而AppSecret：需要手动生成/重置

10. 2 .3 服务器域名

Request 合法域名：https://后台 api 接口域名

uploadFile 合法域名：https://后台 api 接口域名

downloadFile 合法域名：https://后台 api 接口域名

如果有其他域名，可根据情况添加

10. 2 .4 消息推送

URL(服务器地址)：https://后台 api 接口域名/notice/wxma/portal/{appId}

Token(令牌)：开启时自动配置

EncodingAESKey(消息加密密钥)：开启时自动配置

保存之前，在 WEB 系统后台-“支付计费”-“支付配置”-“应用配置”中添加应用，填写对应的

必填信息后保存

WEB 系统保存完毕后，微信后台可进行保存。

10. 2 .5 扫普通链接二维码打开小程序

二维码规则：后台 api 域名/device/qrcode/app

前缀占用规则：占用

校验文件：下载

小程序功能页面：packageMain/pages/loadingGif/loadingGif

测试范围：体验版，可自行选择

测试链接：可自行添加，也可以不添加

10. 2 .6 接口设置

开通"获取当前的地理位置、速度"接口权限

10. 2 .7 订阅消息

左侧菜单“订阅消息”-“公共模板库”

“一次性订阅”-“服务状态提醒”-“选用”

获得模板 ID，在 WEB 系统后台–系统管理–通知管理–小程序通知管理–添加模板

10. 2 .8 微信支付

关联商户号

扫码登录微信商户后台

选择产品中心–AppID 账号管理–关联 AppID

填写对应的 AppId 和小程序主体名称–保存回到小程序–微信支付–确认关联商户号

11 FAQ

1.设备端已上线，Saas平台为何没有同步该设备的在线状态？

答：

2.为什么使用微信小程序扫码仅仅只有一个端口？

答：因为设备端没有上报两个端口的物模型，请按照流程配置中的上报数组结构体（一个结构体分别代表一个端口）。

3.为什么使用微信小程序扫码仅仅只有一个端口？

答：初次连接开发者中心前需配置产品信息ProductKey(简称PK)、ProductSecret(简称PS)。