# API

The communication protocol is based on ASCII encoding.

### **Motor Command Parameter** <a href="#markdown-header-maintenance-commands" id="markdown-header-maintenance-commands"></a>

The motor command is set by sending the following message: **$!MC:value\r\n** where the value range is listed in the table below.&#x20;

| Parameter     | Code | Type  | Min   | Max  |
| ------------- | ---- | ----- | ----- | ---- |
| Motor command | MC   | int16 | -1000 | 1000 |

### **Run-time Parameters** <a href="#markdown-header-maintenance-commands" id="markdown-header-maintenance-commands"></a>

The following parameters are sent as either feedback messages or status messages.

| Parameter                | Code  | Type   | Min   | Max   |
| ------------------------ | ----- | ------ | ----- | ----- |
| Feedback counter         | FC    | uint16 | 0     | 65535 |
| Motor Encoder counter    | MCC   | int32  | -2^31 | 2^31  |
| Motor RPM Feedback       | MRPM  | int32  | -2^31 | 2^31  |
| Motor operational status | MSTAT | uint8  | 0     | 6     |
| Motor voltage            | MVOLT | uint8  | 0     | 255   |
| MCU temperature          | MTEMP | uint8  | 0     | 255   |
| Motor PID error          | MERR  | int32  | -2^31 | 2^31  |

#### **Feedback message structure**

The device transmits a feedback message regularly with 50 ms interval (freq. 20hz).

The format: **\&f:FC:MCC:MRPM:CRC16\r\n**. The minimum size is 12 bytes, the max is 40 bytes.

#### **Status message structure**

The device transmits a status message regularly with 200 ms interval (freq. 5 hz).

The format: **\&s:MSTAT:MVOLT:MTEMP:MC:MERR:CRC16\r\n**. The minimum size is 18 bytes, the max is 36 bytes.

#### CRC calculation

CRC16 is applied to the feedback and status messages.

Polynomial: `0x1021`. Initial value: `0xFFFF`.&#x20;

The crc16 value is calculated over the start of the message byte and all the data. For the feedback message it covers \&f:FC:MCC:MRPM, for the status message: \&s:MSTAT:MVOLT:MTEMP:MC:MERR. First the string message (in ASCII) is prepared with the crc16 appended at the end.&#x20;

Calculated crc16 is simply added as another data parameter to the end of the status or feedback.

### **Configuration Parameters**

Any configuration parameters could be set by using the following command: **$!conf\_param\_Code:value\r\n**&#x20;

For example, to set the motor acceleration rate the following command is used: $!MAC:25000\r\n. An a out of range value is ignored by the firmware.\
\
To save any configuration changes into FLASH memory please see maintenance commands.&#x20;

The command to read / output configuration parameters is: **$?conf\_param\_Code\r\n**.&#x20;

For example, the command to know the current value of motor acceleration rate is: $?MAC\r\n (the result from the motor controller will be &?MAC:value ).&#x20;

The command to request all configuration parameters is: **$??\r\n**

| Parameter                  | Code  | Type   | Min | Max   | Default |
| -------------------------- | ----- | ------ | --- | ----- | ------- |
| Motor operating mode       | MM    | uint8  | 0   | 1     | 0       |
| Motor acceleration rate    | MAC   | uint32 | 50  | 2^32  | 200     |
| Motor deceleration rate    | MDEC  | uint32 | 50  | 2^32  | 500     |
| Motor Amp limit            | MAMP  | uint8  | 0   | 3     | 2       |
| PID Proportional gain      | MKP   | uint16 | 0   | 65535 | 10      |
| PID Integral gain          | MKI   | uint16 | 0   | 65535 | 0       |
| PID Differential gain      | MKD   | uint16 | 0   | 65535 | 0       |
| Max RPM value              | MMRPM | uint16 | 10  | 65535 | 1000    |
| Motor pole pairs           | MPP   | uint8  | 1   | 255   | 2       |
| Stop braking timeout       | MBK   | uint16 | 0   | 65535 | 2000    |
| Motor watchdog timeout, ms | MWT   | uint16 | 0   | 65535 | 2000    |
| Enable PID error checking  | MPEC  | uint8  | 0   | 1     | 1       |

### **Maintenance commands**

A maintenance command is called by sending the following message: **$^cmd\_name\r\n**&#x20;

Where **cmd\_name** can be found from the table below.&#x20;

For example, the command **$^MVER\r\n** is used to request the version of the motor controller.

| Name                                                                      | Code  |
| ------------------------------------------------------------------------- | ----- |
| Reset encoder                                                             | MRE   |
| Reset configuration parameters                                            | MRCP  |
| Save configuration parameters                                             | MSAV  |
| Reset the device                                                          | MRESB |
| <p>Version request</p><p>Return format is: &?MVER:version\_string\r\n</p> | MVER  |
| Reset operational status                                                  | MRESS |