产品文档

物联网操作系统

Joylink 接入指南

1. 介绍

Joylink 京东小京鱼 IoT 开放平台(以下简称小京鱼) 可以为京东平台产品提供一体化的智能解决方案,包括 App、云服务、数据运算、增值服务等,使得该产品可以和小京鱼平台上其他品牌产品实现相互连接,为用户提供更好的使用体验 。

Joylink 软件包是 RT-Thread 系统基于 Joylink v2.0.19 版本移植的用于连接小京鱼 IoT 平台的软件包,该软件包目前完成功能:

  • 设备激活上线;
  • 设备信息存储;
  • 自定义数据收发功能;
  • softap 配网功能;
  • thunderconfig 配网(音箱配网)功能;
  • 联盛德 W600 W601 支持

1.2 依赖

2. 软件包使用

下面分三个部分介绍小京鱼接入和软件包使用流程:

  • 云端准备流程;

  • 参数配置和移植流程;

  • 软件包运行流程;

2.1 云端准备流程

1. 账号注册登录

小京鱼平台地址:https://jdwhale.jd.com

可以使用个人京东账号登录,也可以注册企业账号登录,建议注册使用企业账号。

2. 创建产品

参考官方 创建产品说明 ,创建成功之后需要获取并记录产品 UUIDProduct Key(公钥),用于后面设备的激活和认证过程。

如下图所示为创建产品基本参数,当前创建的产品类型为**智能手环**:

UUID

Product Key

3. 通过 MAC 地址生成设备密钥

创建产品之后,正常应该是创建新设备,小京鱼提供 设备密钥管理 机制,通过表格传入的设备 MAC 地址生成该 MAC 地址设备特有的**Private Key(设备私钥)**,用于设备激活认证。

进入设备密钥管理, 选中上面创建的产品,点击右边 密钥管理, 点击 导入 MAC 地址,按照 MAC 地址表格模板填写 MAC 地址,点击 导入。导入成功之后,再次点击进入 密钥管理,可以查看密钥列表,如下所示:

设备 MAC 地址导入

设备私钥导出

至此,针对每一个设备,获取到了四个重要的属性信息,分别是:

  • UUID:产品唯一标识
  • Product Key:产品公钥
  • MAC:设备硬件地址
  • Device Key:设备私钥

2.2 参数配置流程

通过上述云端准备流程获取产品相关信息,之后可以在 menuconfig 中配置信息, menuconfig 配置如下:

shell [] Joylink: Joylink IoT SDK poting for RT-Thread  [ ] Enable OTA update feature  [ ] Enable network configure feature  [ ] Enable thunderconfig mode  Output LOG level (DEBUG) --->  Sample product type (Heater) --->  [] Enable automatic initialize  (uuid) Device uuid  (public_key) Device public key  (private_key) Device private key  Version (latest) ---> 
- Enable OTA update feature:配置开启 OTA 功能支持;同时需要自行移植 - Enable network configure feature:配置配网方式支持,目前有两种:softap、thunderconfig;同时需要自行移植 - Enable softap mode: 开启手机热点配网功能支持;同时需要自行移植 - Enable thunderconfig mode:开启叮咚/京鱼座音箱配网功能支持;同时需要自行移植 - Output LOG level:配置日志等级,目前支持等级:DEBUG、WARN、ERROR、INFO、NOTICE、FATAL - Sample product type:配置示例类型,目前支持两种:Heater、Wristband - Enable automatic initialize:配置开启云端自启动功能支持 - Device uuid:配置示例产品 UUID - Device public key:配置示例产品公钥 - Device private key:配置示例设备私钥(该设备 MAC 地址对应私钥)

软件包运行流程

下载编译运行成功,设备上电,连接网络成功,若想要设备在云端上线需要 小京鱼 APP 配合设备完成设备激活过程。

1. 下载安装小京鱼 APP

小京鱼 APP 下载地址:https://smartdev.jd.com/docCenterDownload/download/156100001

下载完成,使用创建产品和设备的京东账号登录。

2. 设备二维码生成

每个设备对应一个二维码,用于设备的联网和激活认证,在 产品管理->销售信息 -> 二维码处生成,如下图所示:

生成二维码

需要注意的一点,**只有在产品基本信息填写完整的情况下,二维码才能正常显示**。

3. 云端启动

设备第一次上线进入配网模式,默认开启 softap 配网方式,如下图所示:

启动 softap 配网

4. SoftAP 配网功能

目前设备默认配网方式为 SoftAP 配网, SoftAP 配网支持**设备自行激活绑定**的绑定策略,设备在配网之前需要在云端配置设备配网信息,具体 softap 配网方式使用流程如下:

  • 设置产品配网方式

设置配网方式

产品管理,基本信息界面,设置配网方式为SoftAP(有些模块不支持该配网方式,这里使用联盛德 W600模块),设置激活绑定策略为设备自行激活

获取当前产品 AP 名称为 JDQuNuanQi6316,用于 ENV 选项配置。

  • 配置工程参数

使用 ENV 工具,配置 SoftAP 配网模式,配置使用的 AP 名称。

ENV 配置

  • 使用 APP 配网

手机连接设备需要连接配置的 WIFI,进入小京鱼 APP,点击设备又上角加上 “+” 号,扫描产品生成的二维码,设备进入配网。配网完成,设备提示配网成功,之后设备进入自动激活过程,激活完成手机 APP 中能查看配网成功的设备。

注:如果 APP 提示配网失败,需要 FinSH 中执行 Joylink_stop 停止配网,再执行 Joylink_start 命令再次进入配网,手机重新扫描配网。

softap 网成功如下图所示:

softap 配网成功

5. thunderconfig 配网

除了 softap 配网,小京鱼还支持叮咚/京鱼座音箱配网,需要 menuconfig 配置中开启 thunderconfig mode 配网模式支持,并且叮咚/京鱼座音箱固件版本为最新版本(需要联系小京鱼官方支持确定音箱版本是否支持音箱配网)。

首先通过小京鱼 APP 给叮咚/京鱼座音箱配网,使音箱设备连接 WIFI,然后让设备进入待配网模式,设备默认使用 softap 配网方式,可以在 FinSH 中执行 Joylink_mod_change 命令切换配网状态为 thunderconfig 配网。然后通过语音唤醒音箱配网功能,设备端会收到音箱发送的配网信息并自动连接网络。示例使用音箱设备为京鱼座 A1 音箱,音箱固件版本为 206,设备 thunderconfig 配网连接日志如下所示:

音箱配网

6. 设备上线

配网成功之后,设备自动上线,设备上线后云端可以通过获取的设备 Feed ID 查看设备在线情况,也可以查看设备日志等信息。

设备端激活完成之后,可以向云端发送自定义的 JSON 数据格式,如果没有数据发送,设备端也会定期发送心跳数据检查连接状态。

7. OTA 升级功能

menuconfig 配置中如果开启 Enable OTA update feature 选项,则产品支持固件 OTA 空中升级功能。

OTA 升级主要分为如下几个步骤:

  • 更新设备分区表 更新设备分区表

  • 本地生成最新固件

OTA 功能配置完成,编译生成最新固件,Joylink 软件包固件升级只支持后缀为 .bin 文件,如果工程中生成的可用于固件升级的文件是其他后缀名称,需要将文件修改为 .bin 后缀用于后面云端固件上传。

  • 上传固件到云端

固件准备完成之后,需要上传最新固件到云端,选择产品管理 -> 固件升级 -> 添加固件

添加固件

然后进入添加固件界面,选择版本号为标准自定义,输入自定义版本信息;然后点击 添加文件,选择刚才生成的realthread_upload.bin 文件上传;然后添加 APP展示信息,可以使用推荐的默认文案,最后点击保存按键上传固件。

上传固件

注意:产品第一次上传固件默认为基础版本,不做固件更新,如果想要在 APP 中显示有新版本更新,则**产品固件列表中必须有两个或两个以上固件**。

  • APP 端下发 OTA 升级控制

云端上传固件完成之后,APP 端会显示有最新固件可以升级,如下所示:

APP OTA 控制

  • 设备端固件升级

APP 点击开始升级之后,会向设备端下发 OTA 升级信息,设备接收到之后开始进入设备升级,升级流程如图所示:

OTA 启动

  • 重启设备完成 OTA 升级

设备端 OTA 文件下载完成, APP 上提示 固件升级成功,待设备重启后即可使用!,重启设备进入 Bootloader 固件更新,固件升级完成。

8. 更多命令支持

FinSH 中执行 Joylink_stop 命令,用于关闭 Joylink 云端连接。如果开启 Wristband 类型产品示例支持,执行Joylink_band_set 命令,用于设置产品对应信息。

shell msh />Joylink_band_set sport 1 // 设备手环产品信息 [DEBUG][packages\Joylink-latest\samples\Joylink_sample_band.c][Joylink_dev_user_data_set][85] set wristband device sport status(1). msh /> msh />Joylink_band_set sleep 2 [DEBUG][packages\Joylink-latest\samples\Joylink_sample_band.c][Joylink_dev_user_data_set][90] set wristband device sleep status(2). msh /> msh />Joylink_band_set physique 3 [DEBUG][packages\Joylink-latest\samples\Joylink_sample_band.c][Joylink_dev_user_data_set][95] set wristband device physique status(3). .... [INFO][packages\Joylink-latest\samples\Joylink_sample_band.c][Joylink_dev_get_snap_shot_with_retcode][343] // 拼接当前设备信息到云端 ------>{  "code": 0,  "streams": [{  "stream_id": "Sport",  "current_value": "1"  }, {  "stream_id": "Sleep",  "current_value": "2"  }, {  "stream_id": "Physique",  "current_value": "3"  }] }:len:199

[DEBUG][packages\Joylink-latest\Joylink\Joylink\Joylink_dev_server.c][Joylink_server_upload_req][330] send to server len:224:ret:224 // 上传设置的当前设备信息到云端 ...

3. 注意事项

  • 开启示例功能,需要在源码中修改三个配置参数,且针对不同设备参数不同。
  • 如果 产品管理->销售信息中不显示 二维码,需要先补全产品基本信息。
  • OTA 功能默认关闭,功能实现需要自行移植
  • 配网功能默认关闭,功能实现需要自行移植
  • EASYFLASH 的移植部分需要自行完成 EASYFLASH

4. 技术支持

  • 现已在联盛德 w60X 等设备上全面支持了配网和 OTA 功能
  • 更多模块接入和功能支持请联系 RT-Thread 官网商务

参考资料

  • 小京鱼官网:https://jdwhale.jd.com/
  • 小京鱼官方文档中心:https://smartdev.jd.com/docCenterDoc/index
  • 小京鱼下载中心:https://smartdev.jd.com/docCenterDownload/list/2
更新时间:2020-04-09 19:30:37
文档反馈 docs feedback