# Brief Introduction

#Abstract

MXMesh AT command was developed by MXCHIP and runs on the serial in the MXCHIP EMB101x series Bluetooth BLE wireless module. Users can interact with the Bluetooth module through this command system and connect to the MXMesh network to obtain complete MXMesh end/edge/cloud three end comprehensive functionality. This greatly shortens the development cycle and enables rapid market launch.

Through the MXMesh AT command system, the Bluetooth BLE wireless module mainly completes two major functions:

  • Construction of MXMesh object model: Create MXMesh attributes/services/instances based on product functionality. The MXMesh object model can also be directly defined through JSON format configuration files, and customized firmware can be generated through HyperPack tool packaging with the original firmware. After burning this customized firmware to the module, you can obtain an out of the box module.
  • MXMesh network communication: Start the MXMesh network, and then achieve network communication function by reading and writing MXMesh object model instances.

In general, after the module is started, it is necessary to first build the object model and then start the MXMesh network. The object model only needs to be configured once and can be configured through JSON files for out of the box use; Starting the MXMesh network can also be set to automatic. So in the simplest case, as long as you power on, you can start network communication.

#Command Type

MXMesh AT command have 4 types.

Type

Command Format

Description

Test Command（TEST）

AT+<Command Name>=?

Query the internal parameters and their value range of the setting command

Query Command（QUERY）

AT+<Command Name>?

Returns the current parameter value

Set Command（SET）

AT+<Command Name>=<…>

Set user-defined parameter values and run commands

Execute Command（EXE）

AT+<Command Name>

Run commands without user-defined parameters

  1. Not every AT command has the four types of commands mentioned above.
  2. Input parameters in the command. Currently, only string parameters and integer number parameters are supported.
  3. The parameters in angle brackets<>cannot be omitted.
  4. The parameters in square brackets [] can be omitted, and default values are used when omitted. In the setting command, if parameters are omitted, these omitted parameters will not be set and the previous values or default values will be maintained, such as:

-Omit certain parameters when running the AT+XMUPDATE command:

AT+XMUPDATE=0,"0",1,"1",2,"4332"

AT+XMUPDATE=0,"0",1,"1",2,"4332",3,"-33",4,"26.9",6,"210.45 4.45 56.7"

  1. When there are still parameters to be filled in after the omitted parameters, commas must be used to separate them. Omit a few parameters and add a few commas For example:

-There are still parameters that need to be input after the omitted parameters

AT+UART_DEF=115200,,1,0,3

  1. Use double quotation marks to represent string parameters, for example:

AT+BLENAME="XBT peripheral"

  1. Special characters need to be escaped, such as,、"、`. 等。

    • .<span class="ne-text" style="color: rgb(64, 64, 64); font-size: 16px">：</span>Escape backslash.
    • .<span class="ne-text" style="color: rgb(64, 64, 64); font-size: 16px">：</span>Escape commas, commas separating parameters do not need to be escaped.
    • .<span class="ne-text" style="color: rgb(64, 64, 64); font-size: 16px">：</span>Escape double quotes, indicating that double quotes for string parameters do not need to be escaped.
    • .any><span class="ne-text" style="color: rgb(64, 64, 64); font-size: 16px">：</span>Escape the<any>character, that is, use only the<any>character without using a backslash.

  2. The default baud rate for the AT command is 115200.

  3. The length of each AT command should not exceed 255 bytes (including (CR-LF)).

  4. The AT command ends with a new line (CR-LF), so the serial tool should be set to "new line mode".

  5. Using AT+SYSLOG can open the error code display function. AT command error code format: (AT-MODULE_NUM<<24) | (subcategory)<<16) | (extension)&0xFFFF), where AT_ Module_ NUM=1, subcategory is as follows. For more information, please refer to at_errno.h in the AT engineering source.

enum {
    AT_SUB_OK                       = 0x00,              /*!< OK */
    AT_SUB_COMMON_ERROR             = 0x01,              /*!< reserved */
    AT_SUB_NO_TERMINATOR            = 0x02,              /*!< terminator character not found (".." expected) */
    AT_SUB_NO_AT                    = 0x03,              /*!< Starting "AT" not found (or at, At or aT entered) */
    AT_SUB_PARA_LENGTH_MISMATCH     = 0x04,              /*!< parameter length mismatch */
    AT_SUB_PARA_TYPE_MISMATCH       = 0x05,              /*!< parameter type mismatch */
    AT_SUB_PARA_NUM_MISMATCH        = 0x06,              /*!< parameter number mismatch */
    AT_SUB_PARA_INVALID             = 0x07,              /*!< the parameter is invalid */
    AT_SUB_PARA_PARSE_FAIL          = 0x08,              /*!< parse parameter fail */
    AT_SUB_UNSUPPORT_CMD            = 0x09,              /*!< the command is not supported */
    AT_SUB_CMD_EXEC_FAIL            = 0x0A,              /*!< the command execution failed */
    AT_SUB_CMD_PROCESSING           = 0x0B,              /*!< processing of previous command is in progress */
    AT_SUB_CMD_OP_ERROR             = 0x0C,              /*!< the command operation type is error */
};
  1. The header (AT+command name) of the AT command is not case sensitive. The string parameter in the parameter is case sensitive, but if a string is used to represent hexadecimal numbers, it is not case sensitive
  1. After the device starts, it will actively send an OK..

XAT command which parameters is saved in Flash

The parameter changes of the following AT command will always be saved in the KV area of the flash, so it will be used directly after restarting. AT+UART_ DEF: AT+UART_ DEF=115200,8,1,0,3

Whether the parameter changes of other commands are saved to flash can be configured through the AT+SYSSTORE command. By default, they are all saved in the KV area. Please refer to the detailed description of the command for details.

Some configuration parameters are directly included in the binary file in the form of JSON configuration files, which ensures that the module can be used without configuration after burning. Please refer to: Modify default settings.

#Message Return Type

There are two types of AT messages returned from the AT command port: AT response (passive) and AT message report (active).

#Passive Response

Each AT command inputed will return a response, informing the sender of the execution result of the AT command. The last message in the response must be OK or ERROR.

AT Response

Description

OK

After processing the AT command, return OK

ERROR

AT command error or error during execution

+<Command Name>:...

Detailed description of AT command processing results

#Active Response

Through AT message reporting, AT will report important status changes or messages in the system.

AT message report

Description

OK

After the system starts, it will actively send once, only once

+XM_PROVED

The module has been connected to the network and can now send and receive messages using the saved network parameters.

+XM_PROVED_NEW

Module's first successful network distribution

+XM_PROVING

Module enters distribution network mode

+XM_UNPROVED

Module distribution network timeout. If the device saves the previous network parameters, the module will restart and restore the network; Otherwise, the module will disable network functionality

+XM_STARTED

Device side MXMesh protocol stack startup completed

+XM_GW_FOUND

Discover gateway devices

+XM_GW_FOUND

Lost gateway device

+XM_IDENTITY

Upon receiving an Identify message, the device should perform Identify related actions to facilitate the user's identification of the currently controlled device.

+OTA_START

The module has started OTA and currently can only update the firmware of the module itself.

+OTA_STOP,<result>

OTA stopped, result=1 indicates OTA success, and result=0 indicates OTA failure.

+XM_WRITE_START

Received attribute write message and started generating+WRITE event. Set through the AT+XMEVENT command.

+WRITE:[<ins-idx>, <.quot;value.quot;>,...]

Received a property instance write message, the message body is an array composed of<ins idx>,< "value ">pairs. Set it through the AT+XMEVENT command.

  • Ins idx: A numerical parameter that represents the attribute instance number.
  • Value: A string parameter that represents the new value written by the attribute.

+XM_WRITE_FINISHED

Received attribute write message, generated+WRITE event all completed. Set through the AT+XMEVENT command.

+XM_REBOOT,<result>

The system restarts, and result indicates the reason for the restart. The types of reasons are as follows:

0: Restart to enter distribution mode

1: Distribution network timeout, restart to restore previous network state

2: Distribution network failure, restart to restore the previous network state

#Modify default configuration

The module can be used after being powered on. If you need to modify the system default parameters, you can use a configuration file to modify it, and package the configuration file and firmware together to form a new firmware and burn it to the module. Some configuration parameters can also be modified through the AT command, which dynamically adjusts the working parameters of the module or executes specific functions during module operation.

#Configuration file format

The configuration file format is a JSON formatted text that is published along with the firmware. Modifying the configuration file can adjust the default settings of the MXMesh AT instruction firmware. For the method of synthesizing firmware and configuration files, refer to the next chapter: HyperPack Configuration File Packaging Tool.

The following is an example of a configuration file:

{
    "manufacturer": "MXCHIP",             // Manufacturer name, no more than 32 characters
    "device_name": "xMesh Node",          // Device name, no more than 32 characters
    "model": "AT_NODE",                   // Device model, no more than 32 characters
    "fw_code": "0000.XM00.AT",            // Firmware SN
    "module": "MX1510",                   // Module model, optional: EMB1016, or directly using chip model, optional: MX1510.
                                          // By setting the module model, correspond the pin numbers in the configuration file to the selected module.
                                          // 
    "conf_version": "003",                // Version of Configuration file, please do not modify

    "uart": {                             // Detailed configuration of button products
        "uart": 1,
        "tx_pin": 20,
        "rx_pin": 19,
        "baud_rate": 115200,              // Serial data baud rate
        "data_width": 3,                  // 0: 5bits, 1: 6bits, 2: 7bits, 3: 8bits, 4: 9bits
        "parity":0,                       // 0: No parity, 1: Even parity, 2: Odd parity
        "stop_bits": 0,                   // 0: 1 stop bit, 1:2 stop bit
        "flow_control": 0,                // 0: No flow control， 1: CTS， 2:RTS， 3:CTSRTS
        "echo": 1                         // 0: AT command has no echo, 1: AT command has echo
    },

    "prov": {                             // Configuration of distribution network parameters
        "timeout": 5,                     // Time out, in minutes
    },

    "sys": {                              // system configuration
        "auto": 0,                        // Automatically start the xmesh system when powered on
    },

    "xmesh_database": {
        "ATTS": [
            // =========== OPT: BITMAP ===============
            // 1: READ  Can be read and the values read are meaningful
            // 2: WRITE Can be written in device
            // 4: CORE  Include in full attribute response
            // =========== UP: ENUM ==================
            // 0: NONE
            // 1: TRIGGER   After the device value changes, it is immediately sent out through Mesh multicast, usually used to trigger linkage
            // 2: LOGGER    After being called through update, regardless of whether the properties have changed, after a random delay, it is sent to the gateway through unicast
            // 3: PUBLISH   After the PUBLISH device value changes, it undergoes a random delay and compares whether the attribute value changes again before sending it out through multicast
            // 4: STATE TRIGGER   After calling Update, it is immediately sent out through Mesh multicast. If the device value changes, the "change bit" will be set, usually used to trigger state linkage
            // =========== F: ENUM ==================
            // 0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32
            // 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 12: DATA 13: STRING 14: STRUCT 255: INVALID
            { "TYPE": "0100", "OPT": 7, "UP": 3, "F": 0 },      // On
            { "TYPE": "010A", "OPT": 3, "UP": 3, "F": 1 },      // Thermostat.wind-speed
            { "TYPE": "0116", "OPT": 3, "UP": 3, "F": 2 },      // Ambient-light
            { "TYPE": "0119", "OPT": 3, "UP": 3, "F": 4 },      // vertical-tilt.target
            { "TYPE": "010E", "OPT": 3, "UP": 3, "F": 9 },      // temperature.target
            { "TYPE": "0102", "OPT": 3, "UP": 3, "F": 13, "LEN": 16},  // name
            { "TYPE": "0160", "OPT": 3, "UP": 3, "F": [8, 8, 11] }  // power
        ],

        "SVCS": [
            { "TYPE": "FF" } 
        ],

        "CHARAS": {
            "INS": [                   // All mxmesh characteristics, reference to attribute index
                { "ATT": 0, "SVC": 0 },
                { "ATT": 1, "SVC": 0 },
                { "ATT": 2, "SVC": 0 },
                { "ATT": 3, "SVC": 0 },
                { "ATT": 4, "SVC": 0 },
                { "ATT": 5, "SVC": 0 },
                { "ATT": 6, "SVC": 0 },
            ],
            "PRI": 0                   // characteristics instance index start from 0, in "instance" array
        }
    }
  }

#JSON Profile

Property

Key

JSON Type

Description

"manufacturer"

string

Manufacturer name, stored in MXMesh attribute database.

Manufacturer Name

"device_name"

string

The device name, stored in the MXMesh attribute database and displayed in the MXMesh distribution network broadcast package.

Model

"model"

string

Device model, stored in MXMesh attribute database.

Firmware SN

"fw_code"

string

Firmware number, used for outputting production testing information, is the basis for detecting firmware during MXCHIP module production.

Module

"module"

string

Module model, or chip: MX1510 can be directly selected.

Serial Port

"uart"

object

AT serial port default parameters, refer to: AT serial port default parameters.

Distribution network parameters

"prov"

object

Distribution network parameters, refer to: Distribution network parameters.

system parameter

"sys"

object

system parameter, refer to system parameter.

Attribute Database

"xmesh_database"

object

MXMesh Attribute Database, reference: Attribute Database.

#AT Serial Port Default Parameters

Property

Key

JSON Type

Description

Port

"uart"

number

The serial port number of the chip.

Send Pin

"tx_pin"

number

Serial port sending pin number of chip MX1510 or module.

Receive Pin

"rx_pin"

number

Serial port receiving pin number of chip MX1510 or

module

Baud Rate

"baud_rate"

number

Serial Port Baud Rate

Data Bit Width

"data_width"

number

0: 5bits, 1: 6bits, 2: 7bits, 3: 8bits, 4: 9bits

Parity Bit

"parity"

number

0: No parity, 1: Even parity, 2: Odd parity

Stop bit width

"stop_bits"

number

0: 1 Stop bit， 1：2 Stop bit

Serial Port Flow Control

"flow_control"

number

0: No flow control， 1: CTS， 2:RTS， 3:CTSRTS

#Distribution network parameters

Property

Key

JSON Type

Description

Configuration time

"timeout"

number

Configuration time, unit: minute.

#System Parameter

Property

Key

JSON Type

Description

Start Automatically

"auto"

number

0: 不自动启动，

1: 自动启动。

启动前要确保属性数据库配置正常。

#Attribute database

Property

Key

JSON Type

Description

Attribute List

"ATTS"

array

Array, element is an attribute object and cannot be empty. Attribute Object Reference: Attributes.

Service List

"SVCS"

array

Array, element is a service object and cannot be empty. Attribute Object Reference: Service.

Instance Description

"CHARAS"

object

Example description, reference: Example description.

#Attribute

Property

Key

JSON Type

Description

Type

"TYPE"

string

Attribute Number

Function Option

"OPT"

number

Function options, each BIT bit of the number represents different functions, and multiple functions can be selected.

BIT(0): The attribute can be read.

BIT(1): The attribute can be written.

BIT(2): Core attribute: When reading an attribute, if it does not include the type of attribute being read, the core attribute is used as the response for the read.

Automatically Reporting

"UP"

number

When updating the attribute value through the AT instruction (AT+XMUPDATE), the module automatically sends the new value to the multicast address (D003) or gateway address behavior definition:

0: NONE, disable the automatic sending of attributes after updates.

1: TRIGGER, immediately sent to the multicast address (D003), is usually used to trigger linkage, and can continuously trigger linkage after updating the same value.

2: LOGGER, regardless of whether the attributes have changed, is randomly delayed and then sent to the gateway through unicast. If the gateway does not exist, it will not be sent.

3: PUBLISH, after a random delay and comparing the attribute values again to see if they have changed, is sent to the multicast address.

4: State TRIGGER, if the device value changes, immediately send to the multicast address. Therefore, compared to TRIGGER, the same linkage cannot be triggered continuously.

Data Type

"F"

number

Attribute data types can be one of the following types. The data type definition refers to the MXMesh protocol.

0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 12: DATA 13: STRING

array

The attributes of a structure type composed of multiple attribute data can be one of the following types. The data type definition refers to the MXMesh protocol.

0: BOOLEAN, 1: UINT8, 2: UINT16, 3: UINT32, 4: INT8, 5: INT16, 6: INT32 7: UINT16_1F, 8: UINT16_2F, 9: INT16_1F, 10: INT16_2F, 11: FLOAT, 1

Data Length

"LEN"

number

The length of attribute data is usually defined by the attribute data type, except for the following two situations:

1. The control point attribute represents the maximum length that can be sent and received.

2. The attribute type is 12: DATA 13: STRING, and the corresponding length needs to be filled in

#Service

Property

Key

JSON Type

Description

Type

"TYPE"

string

Service Number

#Instance Description

Property

Key

JSON Type

Description

Instance list

"INS"

array

The element is an instance object and cannot be empty. Instance Object Reference: Instance

Main Instance

"PRI"

number

The instance number selected as the main attribute must be within the range of the instance list array.

#**Instance**

Property

Key

JSON Type

Description

Attribute

"ATT"

number

Attribute number, the current instance uses the current attribute. The attribute number must be within the range of the attribute list array.

Service

"SVC"

number

Service number, which contains the current instance. The service number must be within the range of the service list array.

#HyperPack Profile Packaging Tool

By using the HyperPack tool developed by MXCHIP, the development free standard firmware can be configured to be suitable for the final product hardware platform.

Namely: Product firmware=HyperPack (standard firmware, product configuration file).

The standard firmware is obtained from firmware release.

#Install and UseHyperPack

HyperPack is a Python based packaging tool that can be run in two ways:

  • Using Docker, run the pre generated HyperPack runtime environment image (recommended)
  • Install Python environment and HyperPack dependencies locally, and run HyperPack scripts

#Run under Docker container (recommended)

1. Install Docker, https://www.docker.com/products/docker-desktop (opens new window)

2. Obtain HyperPack Docker Run Script,

3. Run the pack. sh in Shell.

Note: The pack.sh script runs on Linux. If running on Windows, you can refer to the methods in the pack.sh script to call the Docker image to complete the packaging.

Usage: pack.py [-h] -c CHIP [-o OPTION] -b BINARY -C CONF [-O OUTPUT]

Options:

  -h                    Print usage
  -c string             Package tool name. (rtl87x2|bl602|mx1510)
  -o string             Package tool Options
                        For rtl87x2, parameters: select chip module (rtl8752/rtl8762)
                        For bl602, parameters: select module (emc3025)
  -b string             Input executable binary file generated by project
  -C string             Input configuration file
  -O string             Output directory

Example: Run the pack script to combine the standard MXMesh AT firmware xxx. bin (note not xxx. all. bin or xxx. ota. bin) and configuration file config.json into the final product firmware:

$ ./pack.sh -c mx1510 -b xxx.bin -C config.json -O out
go encrypt.
...
Pack Done

The script generates an out folder in the current directory, which contains all outputs.

Last Updated: 11/29/2023, 1:52:34 PM

← Basic Command →