Translated and converted to .md from Xiaomi IoT Developer Platform
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:
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”.
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” 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.
“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.
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.
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 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
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]
Get the downstream instructions.
Return value：down <method_name> <arg1> <arg2> <arg3> …
After the application firmware is booted, the MCU should call this command cyclically to obtain whether there is a command (the time range is 100~200ms, the recommended time interval is 200ms). If the MCU receives a downlink command, it should also respond immediately. For the command, the developer needs to use the error response module, otherwise the product will fail the acceptance test.
↑get_down ↓down none ↑get_down ↓down set_properties 1 1 10 ↑result 1 1 0 ↓ok ↑get_down ↓down action 1 1 ↑get_down ↓error
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
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
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
Used to report events
When the corresponding event changes locally, call this command to report the event event, event_occured is not more than 3 times per second;
- Compared with properties_changed, the information when an event occurs will be updated to the Xiaomi IoT platform immediately. The properties_changed is updated every second, and the property with the same name within one second is only the last one reported to the Xiaomi IoT platform;
- Up to 64 parameters are used after the instruction (6 parameters are used in the following example), and the entire instruction is up to 512 bytes.
↑event_occured 1 1 1 17 2 "hi" ↓ok ↑event_occured 1 ↓error
Turn on the serial port echo function. When this function is enabled, the serial port output of the MIIO chip will echo the input;
- When serial port debugging is performed through the serial port tool, normal debugging may not be possible if the echo function is not turned on.
Note: After the module receives this command, it will restart within 0.5 seconds.
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.
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;
- Default router SSID: miio_default, password: 0x82562647;
- The factory mode needs to ensure that it can only be triggered in the factory, and the device network status is local and connected to the router;
- You can use reboot/restore to exit factory mode.
Ask about the network status.
illustrate: offline-connecting (or offline);
- local-connected to the router but not connected to the Mi Cloud Server;
- updating-firmware upgrading, uap mode waiting for connection, unprov-close wifi (not connected quickly in half an hour).
↑net ↓offline ↑net ↓local ↑net ↓cloud
↑time ↓2015-06-04 16:58:07 ↑time posix ↓1434446397
Get the mac address of the current module.
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.
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.
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
For the specific content of the code value, please refer to the “code status code definition” at the end of this document;
- The get property of the Xiaomi IoT platform needs to be processed by the MCU and the result is returned immediately. The general RPC communication of the module is a 4S timeout failure. The reply result command uses up to 64 parameters (the following example uses 8 parameters), and the entire command is up to 512 bytes.
↑ get_down ↓ down get_properties 1 2 1 3 ↑ result 1 2 0 10 1 3 0 "str_value"
illustrate: For the specific content of the code value, please refer to the “code status code definition” at the end of this document;
- The Xiaomi IoT platform executes Action, which needs to be processed by the MCU and returns the result immediately. The general RPC communication of the module is a 4s timeout failure. The command uses up to 64 parameters (the following example uses 5 parameters), and the entire command is up to 512 bytes.
↑ get_down ↓ down action 1 1 1 10 ↑ result 1 1 0 3 10
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
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.
↑get_down ↓down update_fw ↑result "ready" ↓ok Enter xmodem to start downloading
|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|