小米Yeelight智能灯开放API与通信协议.pdf-资料库

syrchina-9591516-4744300845369930222.pdf-第1页.png

第1页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第2页.png

第2页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第3页.png

第3页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第4页.png

第4页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第5页.png

第5页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第6页.png

第6页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第7页.png

第7页 / 共19页

syrchina-9591516-4744300845369930222.pdf-第8页.png

第8页 / 共19页

Initial Draft Version 1.0 Version 1.1 Version 1.2 Version 1.3 Version 1.4 Version 1.5 Yeelight WiFi Light Inter-Operation Specification www.yeelight.com 2016/01/22 weiwei@yeelink.net 2016/02/01 weiwei@yeelink.net Add HSV support 2016/02/15 weiwei@yeelink.net Fix typo and format issue 2016/03/25 weiwei@yeelink.net Add set_adjust interface 2016/05/26 weiwei@yeelink.net Fix typo and format 2016/05/31 weiwei@yeelink.net Add “flow_params” property 2016/07/11 weiwei@yeelink.net Add music mode support 0

Table of contents 1 Introduction .......................................................................................................................... 2 2 Overview .............................................................................................................................. 2 3 Local Discovery .................................................................................................................... 3 3.1 Search request and response ............................................................................................. 4 3.2 Advertisement .................................................................................................................... 6 4 Control Protocol ................................................................................................................... 8 4.1 COMMAND message ......................................................................................................... 8 4.2 RESULT message .............................................................................................................. 16 4.3 NOTIFICATION message .................................................................................................. 17 5 Issues and Future consideration ......................................................................................... 18 6 Reference ........................................................................................................................... 18

1 Introduction Yeelight smart LED products support remote control through WiFi. When user received the smart LED device for the first time, he/she needs to complete a configuration procedure to provision the router's SSID and password to the device. This procedure is normally called SmartConfig or QuickConnect. Due to security consideration, the protocol used for SmartConfig is proprietary, which means no 3rd party could know about it or use it. However, after the device is connected to the router, it can be seen by all the devices under the same network, thus could also be controlled by 3rd party equipment that understands the inter-operation control protocol. The purpose of this document is to help 3rd party equipment vendors that want to work with Yeelight smart devices or users who are willing to play with the device with their own softwares to understand the technical details of discovering and controlling of the device . 2 Overview Currently, Yeelight WiFi LED is controlled through cloud. The command will be sent to a cloud server and then forwarded to the device. Figure 2-1 As Figure 2-1 shows, all the WiFi LEDs are keep in touch with cloud server. If the cloud server is down or the WAN network undergoes some issue, then user will lose control of the

device. Therefore we think local control is very necessary and begin to work on the local control mechanism. Local control can be further divided into two parts: the discovery procedure and the control procedure. For local discovery, we used a SSDP like protocol but it's greatly simplified. For control protocol, we define a set of control commands that expressed in JSON. The two parts will be explained in great detail in section 3 and 4. 3 Local Discovery As SSDP defined, there are actually two kinds of discover message: searching and advertising messages. Searching is used by device that wants to find other devices or services that it has interests while advertising is used by any device that is willing to announce it's presence on the network. Yeelight smart LED supports both kinds of message. It will listen on a multi-cast address, waiting for any incoming search requests. If the request is targeted for Yeelight smart LED (ST header contains Yeelight pre-defined value), then the device will uni-cast a response to the searcher. The response contains some basic information about the device, e.g. IP and port of the control service, current power status, current brightness as well as all the supported control methods. So when the searcher received the response, it can get the basic idea of the device. With these information, it can do further contact and control. The advertising message is sent by Yeelight smart LED after it joined the network or after a fixed period of time (this is to refresh it's state). The message is sent to a multi-cast address with some basic information. The receiver of the message should not respond to the advertisement. Figure 3-1 shows the discover procedure. Figure 3-1

Different from SSDP protocol, we choose to send multi-cast messages to port 1982 instead of standard SSDP port 1900. This is to avoid excessive multi-cast messages being received by both smart LED and 3rd party devices. It's especially important if the 3rd party device is power- consumption-sensitive (e.g. smart watch powered by battery). 3.1 Search request and response The searching message generated by 3rd device should follow below format and rules and being sent to multi-cast address 239.255.255.250:1982 over UDP. ------------------------------------------------------------- M-SEARCH * HTTP/1.1 HOST: 239.255.255.250:1982 MAN: "ssdp:discover" ST: wifi_bulb ------------------------------------------------------------- 1. The start line must be "M-SEARCH * HTTP/1.1" without any leading LWP. 2. "HOST" header is optional, if it's present, the value should be "239.255.255.250:1982". 3. "MAN" header is required. The value for "MAN" header must be "ssdp:discover", double quotes included. 4. "ST" header is required. The value for "ST" header must be "wifi_bulb". 5. The headers are case-insensitive while the start line and all the header values are case sensitive. Each line should be terminated by "\r\n". Any messages that doesn't follow above rules will be silently dropped, which means the searching device won't be able to find any Yeelight smart LED. If the message is deemed as a valid request, the response message will be generated by Yeelight smart LED and uni-casted to request sender's sending IP and port. For instance, if the request is sent by 192.168.1.22 on UDP port 43210, then response will be sent to 192.168.1.22:43210. The response will be in following format. ------------------------------------------------------------- HTTP/1.1 200 OK Cache-Control: max-age=3600 Date: Ext: Location: yeelight://192.168.1.239:55443 Server: POSIX UPnP/1.0 YGLC/1 id: 0x000000000015243f model: color fw_ver: 18 support: get_prop set_default set_power toggle set_bright start_cf stop_cf set_scene cron_add cron_get cron_del set_ct_abx set_rgb

power: on bright: 100 color_mode: 2 ct: 4000 rgb: 16711680 hue: 100 sat: 35 ------------------------------------------------------------- The start line will always be "HTTP/1.1 200 OK". "CACHE-CONTROL" field contains the status refresh interval. Smart LED will send another advertisement message after that amount of seconds. "LOCATION" field contains the service access point of the smart LED deivce. The URI scheme will always be "yeelight", host is the IP address of smart LED, port is control service's TCP listen port. "DATE", "EXT" and "SERVER" header doesn't contain any important information, it's there just to confirm with SSDP. All other headers are Yeelight specific. "ID": The ID of a Yeelight WiFi LED device, 3rd party device should use this value to uniquely identified a Yeelight WiFi LED device. "MODEL": The product model of a Yeelight smart device. Current it can be "mono", "color", “stripe”. For "mono", it represents device that only supports brightness adjustment. For "color", it represents device that support both color and color temperature adjustment. “Stripe” stands for Yeelight smart LED stripe. More values may be added in future. "FW_VER": LED device's firmware version. "SUPPORT": All the supported control methods separated by white space. 3Rd party device can use this field to dynamically render the control view to user if necessary. Any control request that invokes method that is not included in this field will be rejected by smart LED. "POWER": Current status of the device. "on" means the device is currently turned on, "off" means it's turned off (not un-powered, just software-managed off). "BRIGHT": Current brightness, it's the percentage of maximum brightness. The range of this value is 1 ~ 100. "COLOR_MODE": Current light mode. 1 means color mode, 2 means color temperature mode, 3 means HSV mode.

"CT": Current color temperature value. The range of this value depends on product model, refert to Yeelight product description. This field is only valid if COLOR_MODE is 2. "RGB": Current RGB value. The field is only valid if COLOR_MODE is 1. The value will be explained in next section. "HUE": Current hue value. The range of this value is 0 to 359. This field is only valid if COLOR_MODE is 3. "SAT": Current saturation value. The range of this value is 0 to 100. The field is only valid if COLOR_MODE is 3. NOTE: HUE and SAT should be used in combination. CT mode, RGB mode and HSV mode are mutually exclusively. After 3rd party device received the response, it's recommended to do following operations: 1. Parses and validate the response message. 2. Identify the device, check if the device is already maintained in local storage by searching local database by ID. 3. Display the status to user if necessary. 4. Follow the information in "LOCATION" header to establish a TCP connection with the WiFi smart LED. 5. After the TCP connection is successfully established, send control message to control the smart LED or monitor the status change of the device and display any change to user. 3.2 Advertisement Right after Yeelight smart LED joined the local network, it will announce its presence by multi-casting a advertisement requests. The purpose of this message is to notify 3rd party devices that smart LED is online and ready to serve control request. Without this advertisement message, 3rd party devices would have to probe the network from time to time in order to achieve PnP (plug and play), which is obviously power-consuming and inefficient. After the initial announcement, Yeelight smart LED will refresh its state by sending the advertisement message at a fixed interval. The format of the advertisement message is: ------------------------------------------------------------- NOTIFY * HTTP/1.1 Host: 239.255.255.250:1982 Cache-Control: max-age=3600

Location: yeelight://192.168.1.239:55443 NTS: ssdp:alive Server: POSIX, UPnP/1.0 YGLC/1 id: 0x000000000015243f model: color fw_ver: 18 support: get_prop set_default set_power toggle set_bright start_cf stop_cf set_scene cron_add cron_get cron_del set_ct_abx set_rgb power: on bright: 100 color_mode: 2 ct: 4000 rgb: 16711680 hue: 100 sat: 35 ------------------------------------------------------------- The start line will always be "NOTIFY * HTTP/1.1 ". "NTS" header's value will always be "ssdp:alive". "CACHE-CONTROL" field contains the status refresh interval. Smart LED will send another advertisement message after that amount of seconds. "LOCATION" field contains the service access point of the smart LED. The URI scheme will always be "yeelight", host is the IP address of smart LED, port is control service's TCP listen port. All Yeelight specific headers are exactly same as those in search response message. (See section 3.1) After 3rd party device received the advertisement, it's recommended to do following operations: 1. Parses and validate the response message. 2. Identify the device, check if the device is already maintained in local storage by searching local database by ID. 3. If the device is already in local storage, refresh its state and display to user. 4. If the device is not found in local storage, present the new device to user. 5. Follow the information in "LOCATION" header to establish a TCP connection with the WiFi smart LED. 6. After the TCP connection is successfully established, send control message to control the device or monitor the status change of the device and display any change to user.

资料库

小米Yeelight智能灯开放API与通信协议.pdf

相关推荐

开发技术

热门标签

最新资料