Command Overview
MIP fields which have a descriptor set in the range 0x01 to 0x7F are commands. A command is issued by sending a MIP packet containing the intended command field to the device. Like all MIP fields, command fields contain the standard length and descriptor values, plus a payload. The payload is composed of zero or more parameters to the command, each of which has its own data type. Multiple commands may be issued in one packet, so long as the descriptor sets are all the same.
The device responds by sending a reply packet. The reply contains at minimum a standard ACK/NACK field for every command in the originating packet. This provides feedback as to whether the command was successfully executed, or why it failed. The ack/nack reply uses descriptor 0xF1, which is reserved in all command descriptor sets. Some commands can return additional data, for example to query the current setting. This response data comes as an additional field immediately after the corresponding ack field and will never be separated or split into a separate packet. The response field has a field descriptor in the range 0x81 to 0xEF. Many responses have a descriptor which matches the command descriptor + 0x80, but this is not always the case so make sure to check the DCP. Response data will not be sent for commands which are nacked (i.e., the reply field has a nonzero ack code).
Data types
Most commands take one or more parameters. These parameters may be represented by different data types. For example, the Get Data Base Rate (0x0C,0x0E) command has 1 parameter, a u8.
Some commands take enumerations or bitfields. These quantities are still represented by an underlying integral type (as listed in the standard types table linked above), but have special meaning assigned to particular values or bits, respectively. These meanings are described in the DCP by a table for the relevant enumeration or bitfield type.
Function Selectors
Most settings commands take a special first parameter called a function selector. Function selectors are a one-byte enum type and allow the setting to be set, read back, saved to non-volatile storage, reloaded from storage, or reset to the factory default. Many commands support all 5 options, while others support a subset such as just reading and writing. In read mode, a response field will be sent back along with the ack/nack as described above. No other modes send response data.
Settings commands often have several parameters which are only used when changing the setting (i.e., write mode). The length of the command field can be shorter in these cases, and many times the length is reduced to just include the function selector itself. Each command parameter documents the function modes for which it is required. Regardless, it is always permitted to send the full-length command with dummy values (typically zeros) as placeholders. For example, the PPS Source (0x0C,0x28) command accepts a function selector and one additional parameter called "source". Source must be specified for write mode, but may be omitted for all other modes. The field length would be 4 in write mode but could be 3 for read, save, load, or reset functions.
Reserved Values
Some fields and values are marked "reserved". Reserved fields and values are required to maintain compatibility and allow future expansion of the MIP interface and for factory programming. Unless otherwise specified, the behavior of any undocumented or reserved command, field, enumeration value, or bitfield bit is undefined and may change between device models or in future firmware versions. Do not use such values unless explicitly instructed to do so, even if the device behaves as desired. Microstrain by HBK is not responsible for any consequences (e.g. required maintenance or equipment downtime) resulting from use of reserved or undocumented api elements or behavior.
DCP Format
Commands listed in the DCP follow a standardized table format which is shown here.
| Description |
This is a brief description of what the command does. |
||||||||||
| Notes |
More information may be provided here. |
||||||||||
| Parameter Name | Data Type | Description | |||||||||
| Field Length | u8 | The field length describes the entire length of this MIP field, including the field length, field descriptor, and all parameters. | |||||||||
| Descriptor | u8 | This is the field descriptor which identifies the command. These are unique within the same descriptor set. | |||||||||
| Function Selector | u8 |
For commands which include one, the function selector determines what action will be taken. This area will indicate what functions are available for this command. Example:Write Read Save Load Default
[WRSLD]
|
|||||||||
Param_A
[WRSLD]
|
u8 | Each parameter will have a type and description entry in the table. The type of parameter can be a standard type or an enum or bitfield. For enums, the description will include a list of supported values. For bitfields, the description will list the behaviors of each bit. If a function selector is present, the parameter name will include one or more of the letters W, R, S, L, or D. These indicate if the parameter is required when the function selector is Write, Read, Save, Load, or Default, respectively. Parameters which are not required for a given function may be omitted from the command field, reducing its total length. |
|||||||||
Mode
[W]
|
u8 Enum |
An example enum parameter. This parameter is only required when the function selector is set to Write.
|
|||||||||
| Response Data | Data Type | Description | |||||||||
| Response Length | u8 | The field length describes the entire length of this MIP field, including the field length, field descriptor, and all response parameters. | |||||||||
| Response Descriptor | u8 | This is the response descriptor. For many commands, this matches the command field descriptor + 0x80. | |||||||||
| Param_A | u8 | For most commands, the response parameters match the command parameters less the function selector. | |||||||||
| Mode | u8 Enum | If this section is blank, refer to the command parameters above for description. | |||||||||
Example Command - Ping
Below is an example of a Ping (0x01,0x01) command from the Base Command set. A ping command has no parameters. Its function is to determine if a device is present and responsive.
| Header | Packet Payload | Checksum | ||||||
| SYNC1 “u" | SYNC2 “e” | Descriptor Set byte |
Payload Length byte | Field Byte Length | Field Descriptor Byte | Field Data | MSB | LSB |
| 0x75 | 0x65 | 0x01 | 0x02 | 0x02 | 0x01 | N/A | 0xE0 | 0xC6 |
| Copy-Paste version of command: “75650102 0201 E0C6” | ||||||||
The packet header has the “ue” starting sync bytes characteristic of all MIP Packet Overview. The descriptor set byte identifies the payload as being from the Base Command Set (0x01). The length of the packet payload consists of one field and is 2 bytes. The field starts with the length of the field (2) which is followed by the descriptor byte (0x01). The field descriptor value is the command identifier. Here the descriptor identifies the command as the “Ping” command from the Base command descriptor set. There are no parameters associated with the ping command, so the field data is empty. The checksum is a two byte (see the Fletcher Checksum for instructions on how to compute a Fletcher two byte checksum).
Example Ping Reply Packet
All commands will generate a reply packet from the device containing an ACK/NACK field. The ACK/NACK field contains the command field descriptor plus an error code. An error code of 0x00 is an “ACK” and a non-zero error code is a “NACK”:
| Header | Packet Payload | Checksum | ||||||
| SYNC1 “u | SYNC2 “e” | Descriptor Set byte |
Payload Length byte | Field Byte Length | Field Descriptor Byte | Field Data | MSB | LSB |
| 0x75 | 0x65 | 0x01 | 0x04 | 0x04 | 0xF1 | Command Echo: 0x01
Error code: 0x00 |
0xD5 | 0x6A |
| Copy-Paste version of reply: “7565 0104 04F1 0100 D56A” | ||||||||
The packet header has the “ue” starting sync bytes characteristic of all MIP Packet Overview. The descriptor set byte (0x01) identifies the payload fields as being from the Base command set. The length of the payload portion is 4 bytes. The payload portion of the packet consists of one field. The field starts with the length of the field (4) which is followed by the descriptor byte (0xF1) of the field. The field descriptor byte identifies the reply as the “ACK/NACK” from the Base command descriptor set. The field data consists of an echo of the original command descriptor (0x01) followed by the error code for the command (0x00). In this case the error is zero, so the field represents an “ACK”. Some examples of non-zero error codes that might be sent are Unknown Command (0x01), Invalid Parameter (0x03) and Command Failed (0x04). The checksum is a two byte Fletcher Checksum
Example Command with Response Data
The Get Data Base Rate (0x0C,0x0E) command reports the base sample rate for a given data descriptor set. It takes 1 parameter, "descriptor set", and returns 2 parameters, "descriptor set" and "base rate". For this example, we'll choose the Sensor Data (0x80) descriptor set, 0x80. The command field would be 030E80, corresponding to a length of 0x03, command descriptor 0x0E, and a "descriptor set" parameter of 0x80. Encoding this in a MIP packet with the 3DM command descriptor set (0x0C), we get 75650C03 030E80 7A7E.
Upon receipt of that command, the device will reply with an ack/nack and some response data: 75650C09 04F10E00 058E8003E8 F058. The reply packet is also from the 3DM descriptor set. The first field, 04F10E00, is the reply field. Per the DCP, the first byte is the length (0x04), the second byte is the ack/nack descriptor (0xF1), the third byte is the corresponding command descriptor (0x0E), and the fourth and final byte is the ack code (0x00). An ack of 0x00 indicates success, so the response data is present and can be decoded.
The next field immediately following the reply is the response data, 058E8003E8. The first value is again the length (0x05), followed by the field descriptor (0x8E). The requested descriptor set is echoed from the command (this is a common feature which allows the disambiguation of replies from multiple commands of the same type). Following that is the parameter which we're trying to obtain by this command: a u16 containing the base rate in Hz. In this case, the value is 0x03E8, which represents an AHRS base rate of 1000 Hz.
Example Command with a Function Selector
The PPS Source (0x0C,0x28) command controls how the device receives its pulse-per-second input. There are
The command takes a function selector and 1 parameter called "source". To start with, we'll set the source to Generated. To do this, we'll build the command field using the write function selector, 0x01. Source is a u8 (i.e. one byte) enum, with the value 0x04 corresponding to Internally Generated. The field bytes are 04280104, and the resulting MIP packet is 75650c04 04280104 1b55. The device will reply with an ack: 75650C04 04F12800 07FA. Since the write function was used, no response data is included. If you issue this command to a 3DM-CV7, you should see the LED flash white once per second indicating that a PPS is being received.
Now that the PPS is configured how we'd like, we'll save it so that this setting is remembered after a reset or power cycle. The save function selector (0x03) is used for this purpose. This time, the source parameter is not required, so the field length can be shortened to 3 bytes: 032803. (If desired for consistency, the source parameter could still be sent, in which case it would simply be ignored). The resulting packet is 75650C03 032803 1735, and the device acknowledges with 75650C04 04F12800 07FA. At this point, the device were power cycled or reset, the setting would persist and the LED would still flash once per second.
Now let's change the source to Disabled. Using the write mode again, this time with source 0x00, the command field is created: 04280100. Sending the resulting packet 75650C04 04280100 1751 results in the same ack message again. The LED will stop flashing in this mode.
Disabling the PPS is not particularly useful, so let's load back the previous setting. Using the load function selector, 0x04, the resulting MIP packet is 75650c04 04f12804 0bfe, and the device will ack the command. The LED will begin flashing once more.
Finally, if you're following along issuing commands to a real device, you'll want to reset the setting to the factory default to avoid later confusion. We'll load the factory default setting and then save it. While we're at it, we'll read back the default setting to see its value. We'll also take this opportunity to show how multiple commands can be sent in one packet.
For this task, three instances of the command are required, one each with function selectors default, save, and read. None of these are the write selector, so they can all have a field length of 3 by omitting the source parameter: 032805, 032803, 032802. Notice only the function selector (the last byte of each) is different. Combining these into a single packet results in 75650C09 032805 032803 032802 7A4A. The device will process each field in sequence and add the ack/nacks and any response data into a single reply packet. (In the event that the reply packet would exceed the maximum length of a MIP packet, the fields will be split into multiple reply packets as necessary). The packet bytes are 75650C0F 04F12800 04F12800 04F12800 03A801 F8D9. Notice there are four fields and not three like the command packet. The first three are acks and the last is response data for the third command, which used the read function selector. Decoding the response data indicates that the default PPS source is 0x01, Internal Receiver 1, for the device used in this example.
Other Commands
See Commands for a list of supported commands.