miot

Xiaomi Miot Serial Communication

Translated and converted to .md from Xiaomi IoT Developer Platform

Serial command interaction

Serial text commands are used to transfer commands between the hardware product MCU and the Xiaomi IoT module in the way of “repeat questions and answers”. Regardless of whether the command is executed successfully or not, the corresponding result and error message will be returned:

Precautions

The developer needs to send the “get _ down” command to the Xiaomi IoT module in a polling manner (the time range is 100~200ms, the recommended cycle period is 200ms) , and receive the Xiaomi IoT module from the Xiaomi IoT platform and translate it Instruction If the Xiaomi IoT module replies “down none”, use the “get_down” command to poll the module, otherwise, it needs to immediately reply to the command according to the obtained command and execute the corresponding action; After the MCU completes the execution of the instruction, it needs to call the “result” instruction to send the instruction execution result to the module; if the instruction received by the MCU is not supported in the instruction list or executes incorrectly, it needs to call the “error” instruction to send it to the module Error code and error description. If the Xiaomi IoT module has received the error code and error description, it will reply “ok”.

Command Flow

illustrate

The MCU of the hardware product and the Xiaomi IoT module use the serial port command to interact. The serial port command can transmit up to 512 bytes of data at a time, and the parameters carried by the command do not exceed 64 bytes. Therefore, it is recommended that the MCU of the developer’s hardware product supports not Less than 512 bytes of serial port processing capacity; Use attribute commands to report changed attributes. Do not report normal attributes with high frequency; when a set event (Event) occurs, developers can report the event through the event report command; If the MCU of the developer’s hardware product cannot recognize the commands issued by the Xiaomi IoT module, the MCU of the hardware product must reply to the Xiaomi IoT module with an error.

Property report

“Property report” is a function used to report device status. In order to enable users to control hardware products through control terminals such as Mijia APP or Xiaoai Communication and realize functions such as “automation”, developers must implement the “Attribute report” function, as follows Take “Temperature Sensor Reporting Temperature” as an example to introduce the process of implementing the attribute reporting function.

  1. The sensor detects that the current temperature is 26
  2. The sensor calls the attribute report command of the MIIO module, and reports the temperature attribute value to the cloud through the MIIO module
  3. The MIIO chip replied “ok”, notifying that the result has been received, and reporting the response to the cloud

Order issuance

“Instruction issuance” is a function used to issue device control instructions. In order to enable the device to be controlled by users, developers must implement the “Instruction Issuance” function. The following takes “Issuing and Turning on the Power Switch” as an example to introduce the implementation instructions The process of delivering functions.

  1. The MIIO chip receives the downlink message of the app and translates it into a text command;
  2. The main control MCU continuously polled the MIIO chip with the “get_down” command, and got the text command;
  3. The master MCU completes the power-on operation
  4. The master control MCU calls the “result” response command to inform the MIIO chip to complete successfully
  5. The MIIO chip replied “ok”, notifying that the result has been received, and reporting the response to the cloud

Serial command rules

When developers develop product firmware functions on the hardware product MCU, they need to design instructions according to the following rules:

Note: If a developer encounters an error when developing product firmware using serial port commands, please refer to the document “Wi-Fi Product Development FAQ” to solve the problem.

Basic function instructions

model

After a developer creates a product on the Xiaomi IoT platform, he can get the product Model. The Model string consists of the company name, product category name, and product version, and the total length cannot exceed 23 characters.

Note: After the hardware product MCU is powered on, the product model should be reported to the Xiaomi IoT platform as soon as possible. The Xiaomi IoT platform will bind the module and the product model. Therefore, the developer should correctly configure the product model and the same module Do not reuse different models

    ↑model   
    ↓xiaomi.dev.v1   
    ↑model xiaomi.prod.v2  
    ↓ok   
    ↑model   
    ↓xiaomi.prod.v2   
    ↑model company.product_name_that_is_too_long.v2   
    ↓error   
    ↑model plug   
    ↓error  

mcu_version

MCU should call this command to report the version immediately after the application firmware is booted, and ensure that the setting is successful and the module responds “ok”; if the downstream command receives MIIO_mcu_version_req, it should also report the MCU firmware version immediately, otherwise the product will fail Acceptance Test.

Note: The MCU firmware version must be a 4-digit number.

    ↑mcu_version 0001  
    ↓ok  
    ↑mcu_version A001                                   
    ↓error  
    ↑mcu_version 1  
    ↓error 

ble_config (only dual-mode modules need to use this command)

Set and view the module PID and ble firmware version number.

    ↑ ble_config set 156 0001                          
    ↓ ok  
    ↑ ble_config dump   
    ↓ ["product id":190,"version":1.3.0_0000]           

Server communication instructions

get_down

Get the downstream instructions.

result

Return the corresponding execution result according to different downstream commands

Note: Up to 64 parameters are used after the instruction, and the entire instruction is up to 512 bytes.

    ↑get_down   
    ↓down set_properties 1 1 10                     
    ↑result 1 1 0   
    ↓ok  

error

Note: If the downstream command is executed incorrectly or receives an unrecognized command, the MCU can use this command to send error information. After sending successfully, return to MIIO chip to reply ok. The message must be a string enclosed in double quotes, and the error code must be an integer between -9999 and -5000 (including boundary values). The error message and error code can be customized.

    ↑get_down  
    ↓down error_cmd   
    ↑error "memory error" -5003                        
    ↓ok   
    ↑error "stuck" -5001   
    ↓ok 

properties_changed

Used to report attributes, the parameter must have at least a set of attribute iid and value.

Note: properties_changed is updated once per second, and the property with the same name within one second is only the last one reported to the Xiaomi IoT platform; when there is a corresponding property change locally, this command is called, and a maximum of 64 parameters are used after the command (the following example uses 6 Parameter), the entire instruction is up to 512 bytes.

    ↑properties_changed 1 1 17 1 2  "hi"               
    ↓ok   
    ↑properties_changed 1 1      
    ↓error   

Note: If the device needs to report SN, the developer can use the Spec definition in the product function definition (siid=1 piid=5), when the device is connected to the network, that is, net=cloud, properties_changed report the device SN code.

// Example
↑get_down
↓down MIIO_net_change cloud
// The format of SN needs to conform to the definition of String in spec, and the initial length should be 30 bytes
↑properties_changed 1 5 “12345/A026Z00001”
↓ok

event_occured

Used to report events

illustrate:
When the corresponding event changes locally, call this command to report the event event, event_occured is not more than 3 times per second;

    ↑event_occured 1 1 1 17 2  "hi"                    
    ↓ok   
    ↑event_occured 1       
    ↓error   

Serial tool debugging instructions

echo

illustrate:
Turn on the serial port echo function. When this function is enabled, the serial port output of the MIIO chip will echo the input;

Control instruction

reboot

Note: After the module receives this command, it will restart within 0.5 seconds.

    ↑reboot                             
    ↓ok  

restore

After the Xiaomi IoT module receives the command, the module will clear the Wi-Fi network configuration and remote control related information, and restart within 0.5s.

    ↑restore                                          
    ↓ok  

factory

After receiving the instruction, the MIIO chip enters the factory test mode within 2 seconds.

illustrate: In this mode, the chip will connect to the router according to the preset information;

    ↑factory                                
    ↓ok  

Get module information command

net

Ask about the network status.

illustrate: offline-connecting (or offline);

    ↑net                                             
    ↓offline   
    ↑net   
    ↓local  
    ↑net  
    ↓cloud  

time

    ↑time
    ↓2015-06-04 16:58:07
    ↑time posix
    ↓1434446397

mac

Get the mac address of the current module.

    ↑mac               
    ↓34ce00892ab7      

version

Note: Some modules return the version of the serial port protocol (this protocol), and the firmware version of the module after the 2.xx version.

    ↑version                                            
    ↓2.0.0  

help

Reserved downstream serial port commands

The MIIO chip reserves part of the command name to notify the hardware product MCU of specific events. This type of command can be obtained with get_down, but the MCU in the hardware product needs to be processed accordingly.

set_properties

Serial RPC Downlink Related Commands (Controlled by Xiaomi IoT Platform)

The code value can refer to the “code status code definition” at the end of this document

Note: The set property of Xiaomi IoT platform needs to be processed by the MCU and the result is returned immediately. The general RPC communication of the module is 4S timeout failure. The reply result command uses up to 64 parameters (the following example uses 6 parameters), and the entire command is up to 512 words Section, otherwise the product will fail the acceptance test.

    ↑ get_down  
    ↓ down set_properties 1 1 10 1 88  "str_value"       
    ↑ result 1 1 0 1 88 -4003
    ↑properties_changed 1 1 10
    ↓ok

get_properties

illustrate:
For the specific content of the code value, please refer to the “code status code definition” at the end of this document;

    ↑ get_down  
    ↓ down get_properties 1 2 1 3                        
    ↑ result 1 2 0 10 1 3 0 "str_value"

action

illustrate: For the specific content of the code value, please refer to the “code status code definition” at the end of this document;

    ↑ get_down  
    ↓ down action 1 1 1 10                              
    ↑ result 1 1 0 3 10

MIIO_net_change

The network connection status of the Xiaomi IoT module has changed.
Return value: The parameter represents the latest network status of the chip. For detailed description of the network status, please refer to the net command. The developer can change the state of the Wi-Fi status light according to this command.

    ↑get_down  
    ↓down MIIO_net_change cloud                          

update_fw

Upgrade the MCU in the hardware product through the serial port. Different platforms have different limitations on the size of the MCU firmware (ESP(32)-WROOM-32D(32U) module MCU firmware is not greater than 1MB, MHCWB4P module MCU firmware is not greater than 236KB), details Please refer to the serial OTA document for introduction.

return value:

    ↑get_down  
    ↓down update_fw  
    ↑result "ready"  
    ↓ok  
    Enter xmodem to start downloading                                    

status code

code explanation
0 success
1 The request was received, but the operation has not been completed
-4001 Attribute is not readable
-4002 Property is not writable
-4003 Properties, methods, and events do not exist
-4004 Other internal errors
-4005 Attribute value error
-4006 Method in parameter error
-4007 did error