# User Guide ## Hardware Overview

RoverHatGen2 LEDs (D1-D4) and pushbutton (SW1). The silk screen denotes the phase of each motor channel with PA and PC

## BLE Role Selection The device boots as a BLE Central device after POR by default. D1 will be BLUE. Press and hold push button (SW1) during POR to boot as a BLE Peripheral Device. D1 will be GREEN. ## BLE Central Role ### LED States | RGB1 | RGB2 | RGB3 | RGB4 | State | | ------------------------------------- | ------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- | -------------- | | BLUE | OFF | OFF | OFF | Idle | | BLUE | BLUE | OFF | OFF | Scanning | | BLUE | BLUE | BLUE | OFF | Paired | | BLUE | BLUE | BLUE | BLUE GREEN | Bond Saved | | BLUE | BLUE | BLUE | BLUE | Encrypted Pair | ## BLE Peripheral Role ### LED States | RGB1 | RGB2 | RGB3 | RGB4 | State | | --------------------------------------- | --------------------------------------- | --------------------------------------- | ---- | ----------- | | GREEN | OFF | OFF | OFF | Idle | | GREEN | GREEN | OFF | OFF | Advertising | | GREEN | GREEN | GREEN | OFF | Paired | ### Unsolicited Data Characteristic This characteristic is used to send telemetry data to the host via BLE notifications. Each 20-byte notification has the following format: | Byte | Field | Description | | :--: | :----------: | :----------------------------------------------------------------------------------: | | 0 | Packet ID | Describes the contents of the Data Byte Field | | 1 | Packet Index | Rolling counter. Packets with equal Packet Indices are from the same sample interval | | 2 | Data Byte 0 | Refer to dedicated section | | ... | | | | 19 | Data Byte 17 | | {% hint style="info" %} *Unsolicited Data* notifications will be sent out at a rate of 1 Hz. Frames with equivalent *Packet Indices* will have an inter-frame delay of 100 ms between them. {% endhint %} #### Packet ID 1 Data Bytes This packet contains the raw IMU data and TOF distance measurement in mm (if active).

Byte	Description	Type
0	Accel X LSB	int16
1	Accel X MSB
2	Accel Y LSB	int16
3	Accel Y MSB
4	Accel Z LSB	int16
5	Accel Z MSB
6	Gyro X LSB	int16
7	Gyro X MSB
8	Gyro Y LSB	int16
9	Gyro Y MSB
10	Gyro Z LSB	int16
11	Gyro Z MSB
12	TOF Distance LSB (mm)	uint16
13	TOF Distance MSB (mm)
14	Reserved
15	Reserved
16	Reserved
17	Reserved

#### IMU Data Conversion The following code snippets show how to convert the raw int16 accelerometer and gyroscope data to their respective units: {% code title="Accelerometer" overflow="wrap" lineNumbers="true" %} ```c float_t lsm6dsox_from_fs8_to_mg(int16_t lsb) { return ((float_t)lsb) * 0.244f; // mg } ``` {% endcode %} {% code title="Gyroscope" overflow="wrap" lineNumbers="true" %} ```c float_t lsm6dsox_from_fs500_to_mdps(int16_t lsb) { return ((float_t)lsb) * 17.50f; // mdps } ``` {% endcode %} {% hint style="info" %} Accelerometer full-scale: +/- 8g Gyroscope full-scale: +/- 500 dps {% endhint %} #### Packet ID 2 Data Bytes This packet contains the motor current measurements in A. | Byte | Description | Type | | :--: | :------------------: | :---: | | 0 | Motor 1 Current XLSB | float | | 1 | Motor 1 Current LSB | | | 2 | Motor 1 Current MSB | | | 3 | Motor 1 Current XMSB | | | 4 | Motor 2 Current XLSB | float | | 5 | Motor 2 Current LSB | | | 6 | Motor 2 Current MSB | | | 7 | Motor 2 Current XMSB | | | 8 | Motor 3 Current XLSB | float | | 9 | Motor 3 Current LSB | | | 10 | Motor 3 Current MSB | | | 11 | Motor 3 Current XMSB | | | 12 | Motor 4 Current XLSB | float | | 13 | Motor 4 Current LSB | | | 14 | Motor 4 Current MSB | | | 15 | Motor 4 Current XMSB | | | 16 | Reserved | | | 17 | Reserved | | ### BLE Commands The following table outlines BLE commands supported by the Rover. Refer to respective section for more information.

Command Name	Value (HEX)	Mailbox Parameter(s)
Set Motor 1 Throttle**	0x0003	Motor 1 Throttle
Set Motor 2 Throttle**	0x0004	Motor 2 Throttle
Set Motor 1 and 2 Throttles**	0x0005	Motor 1, Motor 2 Throttles
Kill All Motors**	0x0007	N/A
Set Peripheral State	0x000D	Peripheral ID, Peripheral State
Set Motor 3 Throttle	0x0010	Motor 3 Throttle
Set Motor 4 Throttle	0x0011	Motor 4 Throttle
Set Motor 3 and 4 Throttles	0x0012	Motor 3, Motor 4 Throttles
Set All Motor Throttles	0x0013	Motor 1, Motor 2, Motor 3, Motor 4 Throttles
Set All Motor Throttles (Finite)	0x0014	Throttle and timeout for each motor
System Reset	0x0015	N/A
No Operation (NOP)	0x0016	N/A
Set Stick Dead Zones	0x0017	Left Stick X and Y Dead Zone, Right Stick X and Y Dead Zone
Set Motor CSA Gains	0x0018	Motor 1,2,3 and 4 CSA Gains
Control Telemetry	0x0019	Enable/Disable

\*\*Legacy MotorHAT BLE commands. #### Set Motor 1 Throttle * Command: 0x0003 * Mailbox: * Byte 0: * Description: Motor Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor 2 Throttle * Command: 0x0004 * Mailbox: * Byte 0: * Description: Motor Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor 1 and 2 Throttles * Command: 0x0005 * Mailbox: * Byte 0: * Description: Motor 1 Throttle * Range: -100 to 100, inclusive * Type: int8 * Byte 1: * Description: Motor 2 Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Kill All Motors * Command: 0x0007 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Peripheral State Enables/disables optional on-board/off-board peripherals. {% hint style="info" %} State stored in NVM. Default: All peripherals disabled. {% endhint %} {% hint style="warning" %} If successful, device performs a power-on-reset (POR) after 500 ms. {% endhint %} * Command: 0x000D * Mailbox: * Byte 0: * Description: Peripheral ID * Range: * Supported ID(s) * 0x00: MODI * Type: uint8 * Byte 1: * Description: Peripheral State * Range: * 0 (dec): Peripheral disabled * 1 (dec): Peripheral enabled * Type: uint8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor 3 Throttle * Command: 0x0010 * Mailbox: * Byte 0: * Description: Motor Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor 4 Throttle * Command: 0x0011 * Mailbox: * Byte 0: * Description: Motor Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor 3 and 4 Throttles * Command: 0x0012 * Mailbox: * Byte 0: * Description: Motor 3 Throttle * Range: -100 to 100, inclusive * Type: int8 * Byte 1: * Description: Motor 4 Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set All Motor Throttles * Command: 0x0013 * Mailbox: * Byte 0: * Description: Motor 1 Throttle * Range: -100 to 100, inclusive * Type: int8 * Byte 1: * Description: Motor 2 Throttle * Range: -100 to 100, inclusive * Type: int8 * Byte 2: * Description: Motor 3 Throttle * Range: -100 to 100, inclusive * Type: int8 * Byte 3: * Description: Motor 4 Throttle * Range: -100 to 100, inclusive * Type: int8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set All Motor Throttles (Finite) * Command: 0x0014 * Mailbox: * Byte 0: * Description: Motor 1 Throttle * Range: -100 to 100, inclusive * Type: int8 * Bytes 1-4: * Description: Motor 1 Timeout * Range: -1, 0 to 2^31, inclusive * 0 (dec): Motor throttle is applied indefinitely * -1 (dec): Current motor state remains unchanged * Type: int32 * Byte 5: * Description: Motor 2 Throttle * Bytes 6-9: * Description: Motor 2 Timeout * Byte 10: * Description: Motor 3 Throttle * Bytes 11-14: * Description: Motor 3 Timeout * Byte 15: * Description: Motor 4 Throttle * Bytes 16-19: * Description: Motor 4 Timeout * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### System Reset Performs a power on reset (POR) after 1 second. * Command: 0x0015 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_FAILURE #### No Operation (NOP) Does nothing. Can be used to poll telemetry data safely. * Command: 0x0016 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS #### Set Stick Dead Zones Sets the dead zone for both the left and right sticks of the controller. For example, if dead zone is set to 100 (dec), a stick value that falls within range -100 <= *stick value* <= +100 will be set to 0. {% hint style="info" %} Value is stored in NVM. Default: 20 (dec) {% endhint %} {% hint style="warning" %} Analog sticks experience stick drift as they experience heavy use. Therefore, it is typical for the user to increase the dead zone to prevent false positives. {% endhint %} * Command: 0x0017 * Mailbox: * Bytes 0-1: * Description: **Left** Stick X Dead Zone (+/-) * Range: 0 to 2^16 -1 * Type: uint16 * Bytes 2-3: * Description: **Left** Stick Y Dead Zone (+/-) * Range: 0 to 2^16 -1 * Type: uint16 * Bytes 4-5: * Description: **Right** Stick X Dead Zone (+/-) * Range: 0 to 2^16 -1 * Type: uint16 * Bytes 6-7: * Description: **Right** Stick Y Dead Zone (+/-) * Range: 0 to 2^16 -1 * Type: uint16 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Set Motor CSA Gains Sets the gain of the Current Sense Amplifier (CSA) for each of the motor channels. {% hint style="info" %} Value is stored in NVM. Default: 0x03 (2.0 V/A , +/- 825 mA max current) {% endhint %} {% hint style="warning" %} If successful, device performs a power-on-reset (POR) after 500 ms. {% endhint %} * Command: 0x0018 * Mailbox: * Byte 0: * Description: Motor 1 CSA Gain * Range: * 0x00: 0.25 V/A (+/- 6.6 A max current) * 0x01: 0.5 V/A (+/- 3.3 A max current) * 0x02: 1.0 V/A (+/- 1.65 A max current) * 0x03: 2.0 V/A (+/- 825 mA max current) * Type: uint8 * Byte 1: * Description: Motor 2 CSA Gain * Range: See above * Type: uint8 * Byte 2: * Description: Motor 3 CSA Gain * Range: See above * Type: uint8 * Byte 3: * Description: Motor 4 CSA Gain * Range: See above * Type: uint8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_INV\_PARAM * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Control Telemetry This enables/disables telemetry data which consists of on-board sensor data and/or active, off-board peripherals (i.e. MODI) data. If enabled, UART *Command Response* frames will contain sensor data. When device is in the *Peripheral* state and paired with via BLE, telemetry data will be sent in the form of BLE notifications via the *Unsolicited Data* characteristic. Refer to [dedicated section](#unsolicited-data-characteristic) for more information. If disabled, UART *Command Response* frame sensor data fields will be zero. No BLE notifications will be sent. {% hint style="warning" %} When in *BLE Peripheral* mode, telemetry will automatically be disabled upon link termination. *Control Telemetry* command will need to be resent by host upon link re-establishment to re-enable telemetry BLE notifications. {% endhint %} * Command: 0x0019 * Mailbox: * Byte 0: * Description: Enable/Disable * Range: If 1 (dec), telemetry is enabled. If 0 (dec), telemetry is disabled. * Type: uint8 * Command Response(s) * MDRDIOPROFILE\_CMDRSP\_SUCCESS * MDRDIOPROFILE\_CMDRSP\_FAILURE #### Command Response Codes

Name	Value (uint16)	Notes
MDRDIOPROFILE_CMDRSP_SUCCESS	0x0000	Generic success
MDRDIOPROFILE_CMDRSP_BUSY	0x0001	System busy with previous command
MDRDIOPROFILE_CMDRSP_INV_PARAM	0x00FD	Invalid command parameter(s)
MDRDIOPROFILE_CMDRSP_INV_CMD	0x00FE	Invalid command
MDRDIOPROFILE_CMDRSP_FAILURE	0x00FF	Generic failure

## UART Interface This section outlines the UART functionality of the device. ### UART Settings * Baud Rate: 115200 * Data Bit(s): 8 * Stop Bit(s): 1 * Parity: None * Flow Control: None * Endianness: Little (LSB first) ### Host To RoverGen2: *Command* Frame Format The *Command* frame consists of the 4-byte preamble (0xDEADBEEF), command ID, mailbox data and the 8-bit CRC, for a total of **27 bytes**.

Byte #	Byte Description	Value
0	Preamble XLSB	0xEF
1	Preamble LSB	0xBE
2	Preamble MSB	0xAD
3	Preamble XMSB	0xDE
4	Command LSB	Commands
5	Command MSB
6	Mailbox Byte 0
...	...
25	Mailbox Byte 19
26	8-bit CRC

### RoverHatGen2 To Host: *Command Response* Frame Format The *Command Response* frame is solicited; it is generated on each received *Command* frame from the host. It consists of the 4-byte preamble (0xDEADBEEF), the Command ID which generated the Command Response frame, the Response ID itself, IMU data, TOF distance data, and the 8-bit CRC, for a total of ~~**23**~~** 39 bytes**. {% hint style="warning" %} It is highly recommended that the Host await the *Command Response,* before sending any subsequent *Command* frames. {% endhint %} | Byte # | Byte Description | Value | | :----: | :------------------: | :----------------------------------: | | 0 | Preamble XLSB | 0xEF | | 1 | Preamble LSB | 0xBE | | 2 | Preamble MSB | 0xAD | | 3 | Preamble XMSB | 0xDE | | 4 | Command LSB | [Commands](#ble-commands) | | 5 | Command MSB | | | 6 | Response LSB | [Responses](#command-response-codes) | | 7 | Response MSB | | | 8 | Accel X LSB | int16 | | 9 | Accel X MSB | | | 10 | Accel Y LSB | int16 | | 11 | Accel Y MSB | | | 12 | Accel Z LSB | int16 | | 13 | Accel Z MSB | | | 14 | Gyro X LSB | int16 | | 15 | Gyro X MSB | | | 16 | Gyro Y LSB | int16 | | 17 | Gyro Y MSB | | | 18 | Gyro Z LSB | int16 | | 19 | Gyro Z MSB | | | 20 | TOF Distance LSB | uint16 | | 21 | TOF Distance MSB | | | 22 | Motor 1 Current XLSB | float | | 23 | Motor 1 Current LSB | | | 24 | Motor 1 Current MSB | | | 25 | Motor 1 Current XMSB | | | 26 | Motor 2 Current XLSB | float | | 27 | Motor 2 Current LSB | | | 28 | Motor 2 Current MSB | | | 29 | Motor 2 Current XMSB | | | 30 | Motor 3 Current XLSB | float | | 31 | Motor 3 Current LSB | | | 32 | Motor 3 Current MSB | | | 33 | Motor 3 Current XMSB | | | 34 | Motor 4 Current XLSB | float | | 35 | Motor 4 Current LSB | | | 36 | Motor 4 Current MSB | | | 37 | Motor 4 Current XMSB | | | 38 | 8-bit CRC | | ### CRC Generation The CRC appended to the *Command* and *Command Response* frames is an 8-bit XOR CRC: {% code lineNumbers="true" %} ```c static uint8_t calculate_xor_crc(uint8 *data, int length) { uint8_t crc = 0; for (int i = 0; i < length; i++) { crc ^= data[i]; } return crc; }// calculate_xor_crc ``` {% endcode %} The CRC is computed across the payload data of the frame, **EXCLUDING** the preamble. For example: Bytes 4 to 25 of the *Command* Frame and bytes 4 to 21 of the *Command Response* Frame. ### UART Interface Debug [RealTerm overview from Sparkfun.](https://learn.sparkfun.com/tutorials/terminal-basics/real-term-windows) Can be downloaded [here.](https://flex-controller-se.mantismc.com/flex-controller-se-edition/broken-reference)

Configure UART connection via *Port* tab. Click *Change* to apply.

Ensure *Hex* radio button is selected under *Display As*.

Paste hex data in either of drop-downs and click corresponding *Send Numbers* button.

#### Set Motor 1 and Motor 2 Throttles (Command 0x0005) Example * Motor 1 Throttle: 50 % * Motor 2 Throttle: -100% {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x05 0x00 0x32 0x9C 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0xAB ``` {% endcode %} #### Set All Motor Throttles (Command 0x0013) Example Sets motors 1-4 to 100 % throttle. {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x13 0x00 0x64 0x64 0x64 0x64 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x13 ``` {% endcode %} #### Kill All Motors (Command 0x0007) Example {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x07 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x07 ``` {% endcode %} #### Set Motor 1 Throttle (Command 0x0003) Example Sets motor 1 to 100 % throttle. {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x03 0x00 0x64 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x67 ``` {% endcode %} #### Set All Motor Throttles (Finite) (Command 0x0014) Example * Motor 1: Unchanged * Motor 2 : 100 % throttle for 5 seconds * Motor 3: 50 % throttle, indefinately * Motor 4: -25 % throttle for 10 seconds {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x14 0x00 0x00 0xFF 0xFF 0xFF 0xFF 0x64 0x88 0x13 0x00 0x00 0x32 0x00 0x00 0x00 0x00 0xE7 0x10 0x27 0x00 0x00 0x09 ``` {% endcode %} #### System Reset (Command 0x0015) Example {% code overflow="wrap" %} ``` 0xEF 0xBE 0xAD 0xDE 0x15 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x15 ``` {% endcode %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://flex-controller-se.mantismc.com/flex-controller-se-edition/user-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.