1.1. Overview

Network connection protocol for smart home gateway connection, control smart home

1.2. Usage scenarios

Smart home manufacturers hope to achieve local home control through the method of network protocols

1.3. Access Instructions

After confirming the method for connection, you need to download an APK and install it on the Xiao Ke host to connect via the document protocol.Click here to download the APK plugin After downloading the APK, you can connect the screen and computer with a USB cable, install it using the adb command, or copy it to the screen's storage. Go to the screen's desktop, select "Other Apps" - "File Manager" to find jdxy.apk and click to install.

2. Shenzhen Judian Interactive Technology Co., Ltd.

2.1. Smart Home Integration Protocol 4.2

2.2. Table of Contents

1. Integration Basic Requirements
2. Connection Method
3. Protocol Format
4. Command Allocation Rules
5. Data Sent by Each Command
   • 5.1 Heartbeat Request
   • 5.2 Heartbeat Response
   • 5.3 Request Device List
   • 5.4 Return Device List, Device List Updated
   • 5.5 Request Scene List
   • 5.6 Return Scene List
   • 5.7 Request Room List (Optional)
   • 5.8 Return Room List (Optional)
   • 5.9 Request Floor List (Optional)
   • 5.10 Return Floor List (Optional)
   • 5.11 Send Control Command
   • 5.12 Response to Control Command, Device Status Updated
6. Return Status Codes
7. Common Device Types
8. Control Commands

2.2.1. 1. Integration Basic Requirements

1.1 Must be able to provide all device list data. Device information must include Device ID, Device Name, Device Type, Device Status (optional), Room ID (optional), Floor ID (optional). 1.2 Must be able to provide all scene list data. Scene information must include Scene ID, Scene Name. 1.3 Must be able to provide all room list data. Room information must include Room ID, Room Name. (Optional) 1.4 Must be able to provide all floor list data. Floor information must include Floor ID, Floor Name. (Optional)

2.2.2. 2. Connection Method

1. Background music host sends UDP broadcast, port (tentative) 6666, sending data as follows:​

   {
   "type": "REQUEST_TCP",
   "sn": "xxxxx" // The SN code of the background music host, unique device ID
   }
   

2. After the server receives the broadcast from the background music host, it sends a UDP broadcast, port (tentative) 7777, sending data as follows:​

   {
   "type": "RESPONSE_TCP",
   "data": {
        "ip": "xxx.xxx.xxx.xxx",
        "port": 8888,
        "company": "xxxx",//The company field represents the integration partner
        "protocolVersion": "v1" //The protocolVersion field indicates the version used (optional v1 and v2. The protocol format changes accordingly)
        // V1 protocol header is 0xAA, length 2 bytes. V2 protocol header is 0xAB, length 3 bytes. The v2 version can receive more device data.
         }
   }
   

3. The background music host obtains the server's IP and connects to the server via TCP, port (tentative) 8888.​

4. Then obtain data through the protocol format below.​

2.2.3. 3. Protocol Format

protocolVersion=v1/v2

Protocol Length：

• v1 protocol total length = 6 + data length
• v2 protocol total length = 7 + data length

Verification Algorithm：XOR all bytes in "Length, Command Number, Data" with 0 and then multiply.

private boolean check(byte fcs, byte[] data) {
    int xorResult = 0;
    for (byte b : data) {
        xorResult ^= b;
    }
    return fcs == xorResult;
}

2.2.4. 4. Command Allocation Rules

Note：Client refers to the background music host.

2.2.5. 5. Data Sent by Each Command

5.1 Heartbeat Request

{
"type": "REQUEST_HEART_BEAT",
"sn": "xxxxx"
}

5.2 Heartbeat Response

{
"type": "RESPONSE_HEART_BEAT"
}

5.3 Request Device List

{
"type": "REQUEST_DEVICE",
"sn": "xxxxx"
}

5.4 Return Device List, Device List Updated

{
"type": "RESPONSE_DEVICE",
"deviceData": [
                {
                 "deviceId": "Device ID",
                 "deviceName": "Device Name",
                 "deviceType": "Device Type",
                 "roomId": "Room ID (optional)",
                 "floorId": "Floor ID (optional)",
                 "state": {
                          "order": "Device command on, off, pause (optional)",
                          "mode": "Device mode (optional)",
                          "temperature": "Temperature (optional)",
                          "fanSpeed": "Fan speed (optional)",
                          "fanDirection": "Fan direction (optional)",
                          "brightness": "Brightness 0-100 (optional)",
                          "colorTemp":"Color temperature value 0-100",
                          "position": "Progress 0-100 (optional)",
                          "angle": "Angle 0-180",
                          "sensorStatus": "1: Someone, trigger alarm 0: No one, no trigger",
                          "battery": "Battery level",
                          "humidity": "Humidity",
                          "universalSensorData": "Universal sensor data (jsonArray.toJSONString())"
                         },
                "modeAttributes": "Mode attributes, the desktop can custom display which modes to control based on the filled mode attributes",
                "speedAttributes": "Speed attributes, the desktop can custom display which speeds to control based on the filled mode attributes",
                "directionAttributes": "Direction attributes, the desktop can custom display which directions to control based on the filled mode attributes"
                }
             ]
}

Universal Sensor universalSensorData Explanation:：

Universal Sensor  type=DEVICE_TYPE_MULTIFUNCTIONAL_SENSOR
Specific sensor data, this value is in jsonArray form, can be passed as follows:
universalSensorData=jsonArray.toJSONString();
JSONArray jsonArray = new JSONArray();
        jsonArray.put(new JSONObject().put("key", "温度").put("value", "23.5℃"));
        jsonArray.put(new JSONObject().put("key", "湿度").put("value", "65%"));
        jsonArray.put(new JSONObject().put("key", "PM2.5").put("value", "35"));
        jsonArray.put(new JSONObject().put("key", "光照强度").put("value", "300lux"));
You can set whatever you want to display, key represents the name, value represents the corresponding value for that name.
"universalSensorData": "[
    {"key":"Temperature","value":"23.5℃"},
    {"key":"Humidity","value":"65%"},
    {"key":"PM2.5","value":"35"},
    {"key":"Illuminance","value":"300lux"}
]"

modeAttributes Mode Attributes Explanation:：

• Attributes supported by Air Conditioner/Thermostat: ["cold","heat","airsupply","dehumidification","auto","manual","comfortable","sleep"]
• Attributes supported by Fresh Air/Underfloor Heating:["auto","manual","sleep"]

speedAttributes Speed Attributes Explanation:：

• Attributes supported by Air Conditioner/Thermostat: ["low","medium","high","autoWind","sleepWind","quietWind"]
• Attributes supported by Fresh Air:["low","medium","high","autoWind","sleepWind"]

directionAttributes Direction Attributes Explanation:：

• Attributes supported by Air Conditioner:["leftright","updown"]

5.5 Request Scene List

{
"type": "REQUEST_SCENE",
"sn": "xxxxx"
}

5.6 Return Scene List

{
"type": "RESPONSE_SCENE",
"data": [
         {
          "id": "Scene ID",
          "name": "Scene Name",
          "aliasList": ["Scene Alias 1", "Scene Alias 2"]
         },
         {
          "id": "Scene ID",
          "name": "Scene Name",
          "aliasList": ["Scene Alias 1", "Scene Alias 2"]
         }
        ]
}

5.7 Request Room List (Optional)

{
"type": "REQUEST_ROOM",
"sn": "xxxxx"
}

5.8 Return Room List (Optional)

{
"type": "RESPONSE_ROOM",
"data": [
         {
          "id": "Room ID",
          "name": "Room Name"
         },
         {
          "id": "Room ID",
          "name": "Room Name"
         }
        ]
}

5.9 Request Floor List (Optional)

{
"type": "REQUEST_FLOOR",
"sn": "xxxxx"
}

5.10 Return Floor List (Optional)

{
"type": "RESPONSE_FLOOR",
"data": [
         {
          "id": "Floor ID",
          "name": "Floor Name"
         }
        ]
}

5.11 Send Control Command

{
"type":"REQUEST_CONTROL",
"sn":"xxxxx", 
"original":"Primitive", 
"data":[ 
        { 
         //Specific control command to send
         "id":"Device ID", 
         "name":"Device Name", 
         "scene":"Scene", 
         "state":"Status", 
         "action":"Action", 
         "attribute":"Attribute", 
         "attributeValue":"Attribute Value", 
         "mode":"Mode", 
         "floor":"Floor", 
         "room":"Room" 
        }
       ]
}

5.12 Response to Control Command, Device Status Updated

{
   "type": "RESPONSE_CONTROL", 
   "code":0,//Return code
   "msg":"Return message", //If empty, defaults to replying ["Okay"]
   "msgVoice":"What the background music host needs to say",
   "deviceId":"Device ID",
   "deviceName":"Device Name",
   "deviceType":"Device Type",
   "deviceState":{ 
               //Specific returned device status data
               "order":"Device command on, off, pause", 
               "mode":"Device mode", 
               "temperature":"Temperature", 
               "fanSpeed":"Fan speed", 
               "fanDirection":"Fan direction", 
               "brightness":"Brightness 0-100",
               "position":"Progress  0-100 ",
               "angle":"Angle  0-180",
               "sensorStatus":"1: Someone, trigger 0: No one, no trigger",
               "battery":"Battery level",
               "humidity":"Humidity",
               "universalSensorData":"Universal sensor(jsonArray.toJSONString())"
       }
}

Note：When the order field in 5.4 Get Device List and 5.12 Status Update is empty, it will be defaulted to STATE_OFF|Off.

2.2.6. 6. Return Status Codes

2.2.7. 7. Common Device Types

2.2.8. 8. Control Commands

Switches, lights, and other device types

• Control information
  • state=STATE_ON（on）
  • state=STATE_OFF（off）

Dimmer light

• Brightness:

  {
  "action": "ACTION_TO",
  "attributeValue": "brightness value"
  }
  

Color temperature light

• Color temperature：

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_COLORTEMP",
  "attributeValue": "Color temperature value"
  }
  

• Brightness：

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_BRIGHTNESS",
  "attributeValue": "Brightness value"
  }
  

Air conditioning, thermostat

• Mode：

  {
  "attribute": "ATTRIBUTE_MODE",
  "mode": "mode value"   //"MODE_COOL","MODE_HEAT","MODE_FAN","MODE_DRY","MODE_AUTO","MODE_MANUAL","MODE_COMFORTABLE","MODE_SLEEP"
  }
  

• Wind speed：

  {
  "attribute": "ATTRIBUTE_WIND_SPEED",
  "attributeValue": "Wind speed value"    //"MODE_WIND_LOW","MODE_WIND_MID","MODE_WIND_HIGH","MODE_WIND_AUTO","MODE_WIND_SLEEP","MODE_WIND_MUTE"
  }
  

• Air conditioning direction：

  {
  "attribute": "ATTRIBUTE_WIND_DIRECTION",
  "attributeValue": "Wind direction value"    //"MODE_SWING_UP_DOWN","MODE_SWING_LEFT_RIGHT"
  }
  

• Temperature regulation：

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_TEMPERATURE",
  "attributeValue": "Temperature value"
  }
  

Underfloor heating

• Mode：

  {
  "attribute": "ATTRIBUTE_MODE",
  "mode": "Mode value"   //"MODE_AUTO","MODE_MANUAL","MODE_SLEEP"
  }
  

• Temperature regulation：

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_TEMPERATURE",
  "attributeValue": "Temperature value"
  }
  

Fresh air

• Mode：

  {
  "attribute": "ATTRIBUTE_MODE",
  "mode": "Mode value"   //"MODE_AUTO","MODE_MANUAL","MODE_SLEEP"
  }
  

• Wind speed：

  {
  "attribute": "ATTRIBUTE_WIND_SPEED",
  "mode": "Wind speed value"  //"MODE_WIND_HIGH","MODE_WIND_MID","MODE_WIND_LOW","MODE_WIND_SLEEP"，"MODE_WIND_AUTO"
  }
  

Curtains,Progress curtains：

• Control information：
  • state=STATE_ON（ON，Progress 100）
  • state=STATE_OFF（OFF，Progress 0）
  • state=STATE_STOP（STOP，Progress 50）
• Progress：

  {
  "action": "ACTION_TO",
  "attributeValue": "Progress value"
  }
  

Dream Curtain (with angle adjustment)​:：

• Control command information:
  • state=STATE_ON（Turn on, progress 100）
  • state=STATE_OFF（Turn off, progress 0）
  • state=STATE_STOP（Pause, progress 50）
• Progress:

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_PROGRESS",
  "attributeValue": "Specific progress value"
  }
  

• Angle

  {
  "action": "ACTION_TO",
  "attribute": "ATTRIBUTE_ANGLE",
  "attributeValue": "Specific angle value"
  }
  

TV：

• Channel Up：

  {
  "action": "ACTION_ADD",
  "attribute": "ATTRIBUTE_CHANNEL",
  "attributeValue": "CHANNEL_UP"
  }
  

• Channel Down：

  {
  "action": "ACTION_REDUCE",
  "attribute": "ATTRIBUTE_CHANNEL",
  "attributeValue": "CHANNEL_DOWN"
  }
  

• Volume Up：

  {
  "action": "ACTION_ADD",
  "attribute": "ATTRIBUTE_VOLUME",
  "attributeValue": "VOLUME_UP"
  }
  

• Volume Down：

  {
  "action": "ACTION_REDUCE",
  "attribute": "ATTRIBUTE_VOLUME",
  "attributeValue": "VOLUME_DOWN"
  }
  

• Mute

  {
  "action": "ACTION_TO",
  "mode": "MODE_MUTE"
  }
  

• Unmute/Cancel Mute:

  {
  "action": "ACTION_TO",
  "mode": "MODE_CANCEL_MUTE"
  }
  

Status：

• STATE_ON：On
• STATE_OFF：Off
• STATE_STOP：Stop

Action：

• ACTION_TO：Adjust to, set to, change to, switch to, become, set
• ACTION_ADD：Brighten, Increase, Warm up, Heat up, Turn up, Make louder, Increase, Add, Brighter, A bit brighter, Higher, A bit higher, Next, Raise, Larger, A bit larger, Add, Increase, Pull up, Pull open

Mode：

• MODE_COOL：Cool
• MODE_HEAT：Heat
• MODE_FAN：Fan
• MODE_DRY：Dry
• MODE_AUTO：Auto
• MODE_MANUAL：Manual
• MODE_COMFORTABLE：Comfort
• MODE_SLEEP：Sleep
• MODE_WIND_HIGH：High Wind
• MODE_WIND_MID：Medium Wind
• MODE_WIND_LOW：Low Wind
• MODE_WIND_AUTO：Auto Wind
• MODE_WIND_MUTE：Mute Wind
• MODE_WIND_SLEEP：Sleep Wind
• MODE_PLAY：Play
• MODE_PAUSE：Pause
• MODE_MUTE：Mute
• MODE_CANCEL_MUTE：Cancel Mute
• MODE_NEXT：Next, Air conditioner mode switch
• MODE_PREVIOUS：Previous
• MODE_SWING_ANGLE：Swing, Oscillate
• MODE_SWING_NO：Stop swing, Stop oscillation
• MODE_SWING_LEFT_RIGHT：Left-right swing
• MODE_SWING_UP_DOWN：Up-down swing
• MODE_PURIFIER：Air Purification

Attribute：

• ATTRIBUTE_MODE：Mode
• ATTRIBUTE_WIND_SPEED：Wind Speed
• ATTRIBUTE_WIND_DIRECTION：Wind Direction
• ATTRIBUTE_TEMPERATURE：Temperature
• ATTRIBUTE_HUMIDITY：Humidity
• ATTRIBUTE_GEAR：Gear
• ATTRIBUTE_BRIGHTNESS：Brightness
• ATTRIBUTE_COLOR：Color
• ATTRIBUTE_COLOR_TEMP：Color Temperature
• ATTRIBUTE_VOLUME：Volume, Sound
• ATTRIBUTE_CHANNEL：Channel, Program, Station
• ATTRIBUTE_HOUR：Hour
• ATTRIBUTE_MINUTE：Minute
• ATTRIBUTE_SECOND：Second
• ATTRIBUTE_PROGRESS：Progress
• ATTRIBUTE_ANGLE：Angle

Attribute Value：

• VALUE_COLOR_WHITE：White
• VALUE_COLOR_RED：Red
• VALUE_COLOR_ORANGE：Orange
• VALUE_COLOR_YELLOW：Yellow
• VALUE_COLOR_GREEN：Green
• VALUE_COLOR_CYAN：Cyan
• VALUE_COLOR_BLUE：Blue
• VALUE_COLOR_PURPLE：Purple
• VALUE_COLOR_PINK：Pink
• VALUE_MAX：Brightest, Largest, Highest, Most
• VALUE_MIN：Darkest, Smallest, Lowest, Coldest
• VALUE_LITTLE：A little, A bit
• CHANNEL_UP：Channel Up
• CHANNEL_DOWN：Channel Down
• VOLUME_UP：Volume Up
• VOLUME_DOWN：Volume Down
• 0.5：0.5
• 1.5：1.5
• 2.5：2.5
• 3.5：3.5
• 4.5：4.5