智能家居SDK对接协议 V1.1.0

  智能家居SDK对接方式，适用于有嵌入式linux下C开发能力的公司，可支持设备登录，发现设备，控制设备以及设备状态反馈。

一. 快速体验

1. 编译环境构建

  本插件仅支持ubuntu系统下编译开发，点击下载 GCC交叉编译工具链。电脑安装adb工具（使用android标准的adb工具），并通过usb线连接电脑和声必可主机，不支持网络adb。

2. 下载demo插件

  点击下载 demo插件, 通过 adb push jdsmart_demo_xxx_sunxi.ipk /data/jdsmart_demo.ipk 命令推送ipk文件至主机端, 然后在电脑端通过 adb shell 命令进入声必可主机终端，执行 opkg install /data/jdsmart_demo.ipk 命令，即可安装demo插件(仅需安装一次)。

3. 重启UI进程

  通过 adb shell 命令进入声必可主机终端，执行 /etc/init.d/jd_ui restart命令，即可重启UI进程，并加载新的demo插件。

4. 智能家居demo演示说明

  智能家居demo插件演示了登录二维码，发现设备及场景，设备状态反馈等基本功能。

  可通过主机 桌面->设置->智能家居->智能主机管理查看登录二维码，demo演示10秒后自动登录成功，并发现设备。设备发现完成后，就可以在桌面左屏看到设备，右屏看到场景。然后可以点击或语音控制设备或场景。

登录 -> 发现设备及场景 -> 显示设备及场景 -> 界面点击或语控场景及设备

5. 第三方智能家居模块硬件对接（可选）

  第三方智能家居可以将自有的硬件模块（如蓝牙、zigbee模块或485）替换掉原有zigbee硬件模块，以实现硬件网关和中控屏一体化集成，具体需要联系声必可商务和技术沟通细节。主控跟第三方智能家居硬件模块通过串口通信（可使用带流控的串口），节点是/dev/ttyS3。

二. 编译开发插件

1. 编译并调试demo插件

  请先查看快速体验章节，安装好demo插件。点击下载 demo插件源码, 解压后修改build.sh文件中COMPILE_PREX路径为交叉编译器的路径，执行./build.sh命令可编译生成 libjdsmart_demo.so 并通过usb adb推送库更新至声必可主机。(如何开启ADB？可通过设置》关于本机》右上角空白处点击5次以上》进入开发者选项》勾选ADB调试即可)。执行 /etc/init.d/jd_ui stop命令，关闭UI服务，执行 /mnt/app/jd_ui/bin/SmartSpeaker, 启动UI应用，可通过c printf打印调试。

2. 流程图

3. API说明

  对接插件需要实现如下函数，具体函数功能描述，参考demo源码注释。

/**
 * @brief  预初始化
 * @note   
 * @param  params: 暂无
 * @param  listener: 应用层回调函数，需本地保存
 * @retval 
 */
int smarthome_preinit(char* params, callback_func listener);

/**
 * @brief  初始化
 * @note   
 * @param  params: {
                      "uuid":    "AIS后台绑定的插件设备id（如果使用AIS管理设备id和key）",
                      "key":    "AIS后台绑定的插件设备key",
                      "deviceID":    "本机设备唯一ID"
                  }
 * @param  listener: 暂不需要
 * @retval 
 */
int smarthome_init(char* params, callback_func listener);

/**
 * @brief  获取状态
 * @note   
 * @retval      PLUGIN_STATE_FAIL 
                PLUGIN_STATE_IDLE 
                PLUGIN_STATE_INITED
                PLUGIN_STATE_GET_CODE
                PLUGIN_STATE_GET_TOKEN
                PLUGIN_STATE_LOGGED
 */
int smarthome_get_state();

/**
 * @brief  获取插件信息
 * @note   
 * @retval 
 */
char* smarthome_get_pluginfo();

/**
 * @brief  linux中控发送的控制指令
 * @note   
 * @param  params: {
                    "id":"vdevo161103533857949",   //设备id
                    "type":"aircondition",         //设备类型
                    "sub_type":"unknown",          //设备子类型
                    "action":"SetTemperature",     //动作
                    "value":"19"                   //值
                    }
 * @param  callback: (void* context, int code, void *result)
    context: 暂时没有用到
    code:  0:正常 -1:异常
    result: code异常时传文本，用于显示，例如“控制失败，网络错误”
 * @retval 
 */
int smarthome_device_control(const char* params, callback_func callback)

/**
 * @brief  发现设备，通常用于刷新设备列表
 * @note   
 * @param  method: 
 * @param  callback: 
 * @retval 
 */
int smarthome_device_discover(int method, callback_func callback);

/**
 * @brief  重置或解除绑定
 * @note   
 * @retval 
 */
int smarthome_reset();

/**
 * @brief  扩展命令
 * @note   
 * @retval 
 */
int smarthome_ioctl(char* cmd, char* key, char* value);

三. 协议描述

3.1 对接基本要求

1. 能够提供所有设备列表数据，设备信息中要包含设备ID、设备名、设备类型
2. 能够提供所有场景列表数据，场景信息中要包含场景 ID、场景名
3. 能够提供所有房间列表数据，房间信息中要包含房间 ID、房间名

3.2 设备发现协议

示例：

{
    "version":1,                                //版本号
    "name":"DiscoveryDevicesResponse",
    "devices":[
        {
            "deviceId":"vdevo162130282208556",   //设备id
            "deviceName":"彩光灯",                //设备名
            "online":1,                          //设备在线状态 1在线，0离线
            "actions":[                            //动作
                {
                    "action":"TurnOn"
                },
                {
                    "action":"TurnOff"
                },
                {
                    "action":"SetMode",
                    "instructions":[
                        {
                            "value":"lightWhite",
                            "code":"lightWhite",
                            "desc":"白光"
                        },
                        {
                            "value":"lightColour",
                            "code":"lightColour",
                            "desc":"彩光"
                        },
                        {
                            "value":"lightScene",
                            "code":"lightScene",
                            "desc":"情景"
                        }
                    ]
                },
                {
                    "action":"SetBrightness"
                },
                {
                    "action":"SetColorTemperature"
                },
                {
                    "action":"SetColor"
                },
                {
                    "action":"SetScene",
                    "instructions":[
                        {
                            "value":"light_scene_1",
                            "code":"light_scene_1",
                            "desc":"晚安"
                        },
                        {
                            "value":"light_scene_2",
                            "code":"light_scene_2",
                            "desc":"阅读"
                        },
                        {
                            "value":"light_scene_3",
                            "code":"light_scene_3",
                            "desc":"工作"
                        },
                        {
                            "value":"light_scene_4",
                            "code":"light_scene_4",
                            "desc":"休闲"
                        }
                    ]
                }
            ],
            "properties":[                                  //属性
                {
                    "name":"powerstate",
                    "value":"on"
                },
                {
                    "name":"mode",
                    "value":"lightWhite"
                },
                {
                    "name":"brightness",
                    "value":"18"
                },
                {
                    "name":"color_temperature",
                    "value":"10"
                },
                {
                    "name":"color_hsv",
                    "value":"{\"h\":0,\"s\":0,\"v\":1}"
                }
            ],
            "zone":"阳台",                      //房间名
            "deviceType":"light",               //设备类型
            "deviceSubType":"unknown"           //设备子类型
        },
        {
            "deviceId":"SN8hzCSAbWrCtjIE",
            "deviceName":"晨起",
            "icon":"scene_meet",
            "deviceType":"smartscene",
            "actions":[
                {
                    "action":"TurnOn"
                }
            ]
        }
    ]
}

3.3 设备控制协议

  通过smarthome_device_control函数 params参数传递APP层控制指令。

亮度控制
{
    "id":"vdevo162192408876410",
    "type":"light",
    "sub_type":"",
    "action":"SetBrightness",
    "value":"53"        //亮度值为 0~100
}

颜色控制
{
    "id":"vdevo162130282208556",
    "type":"light",
    "sub_type":"",
    "action":"SetColor",
    "value":"{\"h\":359.37823486328125,\"s\":0.75686275959014893,\"v\":1}"  //h: 0~360 s: 0~1 v: 0~1
}

色温控制
{
    "id":"vdevo161847485227864",
    "type":"light",
    "sub_type":"",
    "action":"SetColorTemperature",
    "value":"50"        //色温值为0~100
}

温度控制
{
    "id":"vdevo161103533857949",
    "type":"aircondition",
    "sub_type":"",
    "action":"SetTemperature",
    "value":"20"        //温度值
}

风速控制
{
  "id": "vdevo161103533857949",
  "type": "aircondition",
  "sub_type": "unknown",
  "action": "SetWindSpeed",
  "value": "medium"
}

模式控制
{
  "id": "vdevo163635070912018",
  "type": "aircondition",
  "sub_type": "unknown",
  "action": "SetMode",
  "value": "cold"
}

风向控制
{
    "version":1,
    "deviceId":"vdevo161103533857949",
    "name":"switch_horizontal",     //switch_horizontal左右摆风，switch_vertical上下摆风
    "value":"on"                    //on为开启，off为关闭
}

频道控制
{"id":"deviceid_xxx","type":"tv","action":"AdjustUpChannel"}
{"id":"deviceid_xxx","type":"tv","action":"AdjustDownChannel"}

声音控制
{"id":"deviceid_xxx","type":"tv","action":"AdjustUpVolume"}
{"id":"deviceid_xxx","type":"tv","action":"AdjustDownVolume"}
{"id":"deviceid_xxx","type":"tv","action":"Mute"}

3.4 设备属性状态反馈

  参考demo源码，设备端的属性变化，通过 g_context->listener(NULL, PLUGIN_EVENT_ON_DEVICE_PROP_CHANGE, result); result参数传递给APP层。

在线状态属性反馈
{
    "version":1,
    "deviceId":"vdevo162088709984066#1",
    "name":"online",
    "value":"1"     // 1为在线，0为离线
}

开关属性反馈
{"version":1,"deviceId":"vdevo163005316473671","name":"powerstate","value":"off"}

亮度属性反馈
{"version":1,"deviceId":"vdevo163005316473671","name":"brightness","value":"51"}

颜色属性反馈
{"version":1,"deviceId":"vdevo162130282208556","name":"color_hsv","value":"{\"h\":5,\"s\":1,\"v\":0.400000}"}

温度属性反馈
{"version":1,"deviceId":"vdevo163635070912018","name":"temperature","value":"26"}

模式属性反馈
{"version":1,"deviceId":"vdevo163635070912018","name":"mode","value":"cold"}

四. 目前所支持的设备品类

智能设备类

传感器类型

五. 设备指令集及属性

5.1 设备指令集

5.2 设备属性

5.3 模式定义

5.4 风速定义

六、其他

6.1 log日志存储

  插件可以将log日志存储到/tmp/路径，如果用户操作上传日志，日志将会打包上传到声必可服务器。参考如下代码，不要修改.smart.log的文件名。

static FILE* g_fp_log;
static int g_log_size;

void my_log(char* str) {
  // printf("%s", str);  //debug

  if (g_fp_log == NULL) {
    g_fp_log = fopen("/tmp/.smart.log", "w");
    g_log_size = 0;
  }

  if (g_fp_log) {
    int len = fprintf(g_fp_log, "%s", str);
    fflush(g_fp_log);
    g_log_size += len;
    // printf(">>>> g_log_size=%d\n", g_log_size);

    if (g_log_size > 1024 * 512) {
      fclose(g_fp_log);
      system("mv /tmp/.smart.log /tmp/.smart.log.0");
      g_fp_log = NULL;
    }
  }
}

6.2 解除绑定

  解除绑定退出登录时通常需要重启应用，可以调用 g_listener(NULL, PLUGIN_EVENT_REQ_REBOOT, NULL); 或 exit(0) 函数来重启应用。

6.3 插件打包测试发布

• 当开发完成，试量产前，需要将将编译好的插件库及配置文件等打包为ipk格式。首先下载ipk打包脚本 点击下载。解压后，打开ais_tlos_ipk_pack.sh文件，修改配置信息，注意PKG_NAME即插件名称的设置，例如jdsmart_abcd。可通过 设置》智能家居 》插件信息，查看到该名称为abcd。
• 运行ais_tlos_ipk_pack.sh文件，打包成ipk格式后。开发者通过adb shell终端opkg remove jdsmart_demo命令先删除测试的的插件包，然后通过 opkg install jdsmart_abcd_0.0.1-1_sunxi.ipk命令重新安装新的插件包。安装后，如果需要修改代码，调试更新动态库，则需要通过adb push覆盖终端设备的/data/libjdsmart_abcd.so文件。安装后，可通过 设置》智能家居 》插件信息，查看插件相关的信息。
• 开发者测试通过后，将ipk包放在开发者的服务器上，并通过opkg install http://xxx.com/xx.ipk 测试通过后，将下载链接给声必可。开发者如有id参数需求，声必可访问下载链接时可以传递设备id参数。开发者还需提供测试设备的id设置>关于本机>拍个照给声必可。
• 声必可后台根据测试设备id标注对应的插件appid，配置ipk下载链接，未来插件如有升级，重复如上步骤。插件支持后台静默升级，已标注的设备恢复出厂设置后，联网会自动重新下载安装插件。
• 下批量生产订单时，需要通知业务标注好需要安装appid的插件，声必可生产部门将会收集该订单的设备的id，并在声必可后台标注对应的插件。

6.4 Plug标志

  可以在smarthome_get_pluginfo()函数中修改flag标志实现一些特定的功能。

6.5 RS485插件开发

1. RS485插件开发首先需要设置6.4节的PLUG_FLAG_SMART_BUS标志，RS485操作文件节点为 /dev/ttyS5

2. 485发送接收时需要操作的IO节点为 /sys/xfocus/max485/pin_re，如下为485发送的伪代码:

    echo 1 > /sys/xfocus/max485/pin_re
    len = write(fd, data, datalen);
    int ret = ioctl(fd, 0xFFFF5555, 300);
   

6.6 插件空间以及数据存储

  插件代码占用空间建议控制在4MB以内。插件数据可存储在/data/jdsmart_open/，空间不宜超过2MB，否则将会引起OTA升级空间不足。

6.7 插件反向控制中控屏设备指令集

  通过调用如下slave_on_dp_cb函数,可向中控屏设备发送控制命令。相应的参数定义如下

/**
 * @brief  
 * @note   
 * @param  i0:  //命令值
           i1:  //其他参数
           s0:  //其他参数
 * @retval 
 */
static void slave_on_dp_cb(int i0, int i1, char *s0) {
  cJSON* root = cJSON_CreateObject();
  cJSON_AddNumberToObject(root, "i0", i0);
  cJSON_AddNumberToObject(root, "i1", i1);
  cJSON_AddStringToObject(root, "s0", s0);
  char* json_str = cJSON_PrintUnformatted(root);
  cJSON_Delete(root);
  g_listener(NULL, PLUGIN_EVENT_SLAVE_CONTROL, json_str);
  free(json_str);
}

6.7 带继电器产品接入指南

  本节适用于声必可L9等带继电器产品，如设备不带继电器，可以忽略本章节。

6.7.1 查询本设备继电器信息

  smarthome_preinit() 函数参数会传递继电器路数 switchs_count参数给插件

6.7.2 控制继电器开关

  流程: 手机端操作继电器开关=>智能家居云把开关状态通知给插件=>插件上报开关状态到设备应用层=>应用层去控制继电器开关

  参考demo源码，demo_device_relay_control()函数，通过 g_context->listener(NULL, PLUGIN_EVENT_SLAVE_CONTROL, result); 回调通知APP层去控制继电器开关。

6.7.3 继电器开关状态消息

  流程: 设备端操作继电器开关=>设备端通知插件开关状态=>插件通知智能家居云开关状态

  参考demo源码，smarthome_slave_report()函数，通过 DEVICE_REPORT_DEVICE_PROP 命令通知给插件

6.7.4 继电器开关重命名

  流程: 手机端操作继电器开关重命名=>智能家居云把开关重命名消息通知给插件=>插件上报开关重命名到设备应用层

  参考demo源码，demo_device_relay_rename()函数，通过 g_context->listener(NULL, PLUGIN_EVENT_SLAVE_CONTROL, result); DEVICE_SWICTH_NAME，回调通知APP层存储继电器名称。继电器开关重命名后，需要通知应用层PLUGIN_EVENT_ON_DEVICES_SYNC，重新拉取一遍设备，UI界面才能实时更新。

6.8 插件支持设备发现并自动配对功能

  设置PLUG_FLAG_PAIRD_DEVICES标志，插件登录成功后，点击 设置→ 智能家居→ 智能主机管理，将会进入插件设备发现界面，点击设备发现按钮将调用smarthome_ioctl("discovery_device",,)接口，并显示的插件发现设备的过程信息，可支持多行文本。具体实现参考demo源码。

6.9 插件调试UI界面

  点击 设置→ 智能家居→ 插件信息→ 插件信息处点击5次以上，将会进入插件调试UI界面，本界面将调用smarthome_ioctl("get_debug_info",,)接口获取需要显示的插件调试信息，可支持多行文本。

6.10 自定义场景图片

  在插件中，可以通过icon字段(参考设备发现协议定义)，自定义场景图片，如果未设置icon字段，上层应用将根据场景名称包含的特殊字符决定选择某些图片，如果不包含特殊字符，则随机使用4张默认场景图片。

static char* get_scene_pic(char *name) {
  if(strstr(name, "回家"))
    return "scene_go_home";
  else if(strstr(name, "离家") || strstr(name, "外出") )
    return "scene_leave_home";
  else if(strstr(name, "晨起"))
    return "scene_wakeup";
  else if(strstr(name, "睡眠") || strstr(name, "睡觉"))
    return "scene_sleep";
  else if(strstr(name, "电影")) {
    return "scene_movie";
  }else if(strstr(name, "会客")) {
    return "scene_meet";
  }else if(strstr(name, "休闲")) {
    return "scene_leisure";
  }else if(strstr(name, "运动")) {
    return "scene_sport";
  }else if(strstr(name, "娱乐")) {
    return "scene_entertainment";
  }else if(strstr(name, "全开")) {
    return "scene_all_light_on";
  }else if(strstr(name, "全关")) {
    return "scene_all_light_off";
  }
  else {
    int hash_code = 随机int函数 % 4; 
    switch (hash_code)
    {
    case 1:
      return "scene_default_1";
    case 2:
      return "scene_default_2";
    case 3:
      return "scene_default_3";
    default:
      return "scene_default_4";
    }
  }
}

6.11 产测方法

  点击 设置→ 高级设置→ 右上角连续点击3次以上 → 测试模式 ，将会进入测试界面，将会自动调用smarthome_ioctl("test_mode_start",,)接口，插件开始进入产测，测试完成后，调用PLUGIN_EVENT_ON_TEST_RESULT消息通知测试结果，具体参考源码。

FAQ

FAQ.1 如何恢复出厂设置

  点击 设置→ 关于本机→ 连续点击软件版本5次以上 → 恢复出厂设置→ 重置主机

FAQ.2 如何清除插件数据

  点击 设置→ 智能家居→ 插件信息→ 右上角空白处点击5次以上→ 清除数据，将会删除 /data/jdsmart_open/ 路径下的数据

FAQ.3 插件如何播放tts文本

  调用slave_on_dp_cb函数 MEDIA_PLAY_TTS 命令即可