接入京东云

前言

基本流程

1. 成为开发者

1）、注册用户。
2）、创建产品：用户登入后进入IoT控制台，创建产品。

2. 接入SDK

1）、选择接入方案：根据产品特性选择接入方案，获取对应平台的SDK。
2）、SDK与平台适配：获取到SDK后，需移植到设备开发平台，并将产品信息写入程序接口。

3. 开发SDK

1）、功能，性能调试：完成代码移植和功能开发，进行配网，控制，升级等功能和产品性能测试验证。（测试环境）
2）、自测、提交审核：京东提供自测方法和工具，自测通过后提交审核，京东测试组进行测试验证。（测试环境）
3）、发布产品：审核通过后进行产品发布。（线上环境）

一.Wi-Fi模组接入

1、SoftAp简介

1）、基于配网成功率的考虑，本SDK采用了SoftAp配网方式；配网成功后进入主程序，SDK自动执行设备**流程；**设备成功后，云端将设备绑定到配网的帐户下。

2）、向云端请求**绑定采用的HTTPS安全通信，该通信方式云端证书会按年度更新，因为SDK请求**绑定时已经加入了双向认证机制，所以建议设备端不验证云端证书，避免云端证书更新设备出现问题。

2、配网流程

1）、开启AP模式：启动Wi-Fi模组的AP模式，AP必须设置为不加密，AP热点的名称是创建设备时由小京鱼平台生成。

2）、SoftAp配网：模组进入AP模式后，调用SoftAp配网循环处理函数joylink_softap_start()，开始AP配网。该函数传参是超时时间，单位是毫秒，超时时间建议5分钟。配网成功后，通过jl_softap_connect_wifi_router(char *ssid, char *passwd)接口将SSID，PASSWORD输出，配网失败joylink_softap_start()接口返回 -1 。

3）、Station模式：配网成功后，模组连接路由，调用SDK主循环处理函数joylink_main_start()，设备自动**绑定，成功后进入工作状态。

3、依赖接口

1）、信息接口：

SDK中配网需要的产品信息，SSID信息等，是通过PAL层的返回实现的，接口如下：

int32_t jl_softap_get_product_info(char *uuid, char *brand, char *cid, char *dev_soft_ssid)；

功能：获取创建产品的信息。

参数：uuid->产品唯一标识码；brand->品牌号；cid->品类号；dev_soft_ssid->SoftAp热点SSID。

注意项：创建产品时，上述参数云平台会一次性生成，用户需将参数通过接口返给SDK。

函数路径：pal/src/joylink_softap.c

2）、**接口：

为节约资源，SDK内部没有集成常用的HTTP/HTTPS协议，用户需实现对应接口，接口如下：

int joylink_dev_http_post( char *host, char *query , char *revbuf, int buflen)；

int joylink_dev_https_post( char *host, char *query , char *revbuf, int buflen) ；

功能：HTTP/HTTPS POST请求接口，需开发者根据选用平台实现。

参数：host->服务器URL；query->http协议发送的数据，包含http header和body；revbuf->HTTP响应body；buflen->HTTP响应body的长度。

注意事项：云端HTTPS服务默认使用443端口，HTTP服务默认使用80端口。

函数路径：example/joylink_extern.c

二. SDK开发

1、概述

SDK开发分为两个部分，一部分是应用层相关的涉及到设备与SDK的交互逻辑，另外一部分是平台适配层相关的，由厂商根据自己的平台特性做适配工作。

2、应用层接口

1）、产品适配

SDK需要关注下表所列的宏定义，这些是产品必须适配的参数，包含在example/joylink_extern.h文件中

公私钥/UUID等参数在开放平台创建产品时生成。

2）、接口列表

用户移植需要实现example/joylink_extern.c以下接口，后边是详细说明。

3）、设备控制

注意：收到控制指令，设备必须在400ms内返回，否则会导致设备控制失败。

用户设备真实数据关联接口：

int joylink_dev_user_data_get(user_dev_status_t *user_data);

功能描述：获取用户真实设备数据。

注意事项：数据取值范围要做判断，防止超限。

int joylink_dev_user_data_set(char *cmd, user_dev_status_t *user_data);

功能描述：设置用户真实设备数据。

注意事项：数据控制设备，注意转换。

int joylink_dev_parse_ctrl(const char *pMsg, user_dev_status_t *userDev)

功能描述：控制指令解析函数。

char *joylink_dev_package_info(const int retCode, user_dev_status_t *userDev)

功能描述：网络快照json组包函数。

注意事项：可以将数据都组成string类型。

4）、设备升级

设备升级源代码见SDK中example目录下的joylink_extern_ota.h、joylink_extern_ota.c、joylink_extern_user.c、joylink_extern_user.h等文件。

升级须知：

a) 云平台对上传的固件要求：.bin后缀，小于50M。

b) 设备的固件版本号是通过宏JLP_VERSION的修改确认的。第一次打包的固件版本号必须是0，OTA固件的版本号必须是IoT开放平台上次上传的固件ID加1。而云端记录版本高低的方式是：将第一次上传的版本号认为1，每次上传固件，后台版本号自动加1。SDK上报版本号同样为整数，云端对比版本号后，决定是否推送升级消息。

E_JLRetCode_t joylink_dev_ota(JLOtaOrder_t *otaOrder);

功能描述：设备升级通知

int joylink_memory_init(void *index, int flag)；

功能描述：升级固件存储，初始化。

int joylink_memory_write(int offset, char *data, int len)；

功能描述：升级固件存储，写入。

int joylink_memory_read(int offset, char *data, int len)；

功能描述：升级固件存储，读出。

注意事项：crc32校验时，需要将保存的数据读出校验。

int joylink_memory_finish(void)；

功能描述：升级固件存储，完成。

void joylink_server_ota_status_upload_req(JLOtaUpload_t *otaUpload)

功能描述：用户程序通过调用此函数上报OTA升级状态

注意事项：JLOtaUpload_t结构体中status和progress字段的含义如下表：

3、系统层接口

考虑到不同的平台环境有不同的特征，由此这里抽象出平台层相关的接口，设备厂商可根据自己平台环境特征作适配，这里提供Linux平台适配源码作为参考，以下头文件中的抽象接口是必须实现的。

名称：joylink_dev_sdk/pal/inc

├── joylink_log.h 日志打印

├── joylink_memory.h 内存与文件IO操作

├── joylink_socket.h SOCKET相关操作

├── joylink_softap.h 软件AP相关操作

├── joylink_stdint.h 整形类型相关定义

├── joylink_stdio.h 标准打印输出

├── joylink_string.h 字符串相关操作

├── joylink_thread.h 线程相关操作

├── joylink_time.h UTC时间相关操作

以下为源码文件适配了Linux平台，移植厂商可以参考实现源码适配到自己的平台：

名称：joylink_dev_sdk/pal/src

├── joylink_memory.c 内存与文件IO操作

├── joylink_ota.c OTA升级操作

├── joylink_socket.c SOCKET相关操作

├── joylink_stdio.c 标准打印输出

├── joylink_string.c 字符串相关操作

├── joylink_thread.c 线程相关操作

├── joylink_time.c UTC时间相关操作

三. 设备调试

​
1、联网图示

2、沙箱APP

新创建的设备需要从开发者中心下载沙箱环境APP进行联调，审核发布后的产品才用线上的APP。沙箱APP下载地址：https://smartdev.jd.com/docCenterDownload/list/2

​

​ 3、扫码配网

​ 设备创建时在销售信息中会生成产品对应的二维码，客户端添加设备时使用，需要注意的是创建设备时，基本信息需要填写完整，否则可能会没有二维码或者扫码后会出错。子设备是没有二维码的。

​

APP点击添加设备扫描二维码后，跳转到配网页面，根据说明进行下一步。配网成功之后会自主**绑定，绑定成功后小京鱼APP会显示绑定的设备。

​ 4、设备心跳

​ a）设备**绑定成功，或重新上电第一次连上云端时，设备会主动连接云端，并上报认证消息，云端下发认证应答。

​ b）设备认证成功后，定时上报心跳，云端收到心跳后会应答。如果多次未收到应答则认为离线，设备会自动重连云端。

​ c）为保证设备状态同步，设备每次收到心跳应答，都主动上报网络快照。

​ 5、网络快照

​

​

​ 网络快照需要注意以下几点：

​ a）网络快照是指设备的所有参数组合，要求设备端的参数同IoT开放平台的一致（注意首字母大写）。

​ b）设备自身状态变化时，需要设备立即主动上报给云端。接口函数为：joylink_server_upload_req();

网络快照需要注意以下几点：

a）网络快照是指设备的所有参数组合，要求设备端的参数同IoT开放平台的一致（注意首字母大写）。

b）设备自身状态变化时，需要设备立即主动上报给云端。接口函数为：joylink_server_upload_req(); 

**6、升级调试** 

升级SDK中已经包含升级代码，若用户有其他HTTP升级方案，可将joylink_dev_ota函数中升级代码替换。

升级调试要注意：

a) 收到升级开始指令，先应答。

b) 升级指令下发时除了携带url还会携带升级固件的crc32校验值，升级结束后，要求用户将保存的数据取出，进行crc32计算，并对比下发的校验值是否相等。

c) 升级过程中上报升级进度，结束后上报升级结果；另外升级成功后，新固件需上传最新的版本号。这些是云端判断升级是否中断和判断升级是否成功的依据。

总结

以上就是接入京东云开发的基本流程，实际上的sdk的灵活运用还需要进一步探索。