# Motor Control Implementation Summary

## Overview
Implemented complete 2-byte motor control commands for all control buttons in the JoyStick screen. All button presses now send proper values to the BLE Module via the JOYSTICK_BUTTONS_CHARACTERISTIC, which forwards them to the SPI interface.

## Implementation Details

### 1. BluetoothService.kt
**Added Function:** `sendMotorCommand(value: Int)`
- Sends 2-byte values (16-bit unsigned integers) to the BLE Module
- Uses little-endian byte order (LSB first)
- Communicates via `JOYSTICK_BUTTONS_CHARACTERISTIC_UUID` (0x0230bc9a...)
- Located in `MOTOR_SERVICE_UUID` (0x0030bc9a...)

**How it works:**
```kotlin
// Converts integer to 2 bytes
val lowByte = (value and 0xFF).toByte()
val highByte = ((value shr 8) and 0xFF).toByte()
val commandBytes = byteArrayOf(lowByte, highByte)
```

**Expected BLE Module behavior:**
The firmware should:
1. Receive the 2 bytes via BLE characteristic write
2. Set NSS (chip select) pin LOW
3. Send the 2 bytes over SPI interface
4. Set NSS pin HIGH

### 2. JoyStickViewModel.kt
**Added Constants:** All button value mappings as defined in CONTROL_BUTTON_VALUES.md

**Implemented Functions:**
- `sendDirectionCommand(direction: String)` - Arrow buttons (UP, DOWN, LEFT, RIGHT)
- `sendActionCommand(action: String)` - Shape buttons (TRIANGLE, SQUARE, CIRCLE, CROSS)
- `sendModeCommand(mode: String)` - Radio buttons (Mode 1, 2, 3)
- `onButtonAClick/B/C/D(isPressed: Boolean)` - Toggle buttons with ON/OFF states
- `sendJoystickAngle(angle: Float)` - Joystick rotation (0-360°)
- `sendMotorCommand(value: Int, description: String)` - Helper function

### 3. JoyStickScreen.kt
**Connected All Buttons:**
- ✅ Arrow buttons (Up, Down, Left, Right) - Call `sendDirectionCommand()`
- ✅ Shape buttons (Triangle, Square, Circle, X) - Call `sendActionCommand()`
- ✅ Radio buttons (Mode 1, 2, 3) - Call `sendModeCommand()` via onClick handlers
- ✅ Toggle buttons (A, B, C, D) - Call `onButtonXClick()` with proper ON/OFF states
- ✅ Joystick - Sends angle updates with throttling (100ms delay)

**Joystick Implementation:**
```kotlin
LaunchedEffect(viewModel.currentAngle.value) {
    viewModel.sendJoystickAngle(viewModel.currentAngle.value)
    delay(100) // Throttle to avoid flooding BLE connection
}
```

## Value Mapping Reference

### Arrow Buttons
| Button | Value  | Hex    |
|--------|--------|--------|
| UP     | 257    | 0x0101 |
| DOWN   | 258    | 0x0102 |
| LEFT   | 259    | 0x0103 |
| RIGHT  | 260    | 0x0104 |

### Shape Buttons
| Button   | Value | Hex    |
|----------|-------|--------|
| TRIANGLE | 513   | 0x0201 |
| SQUARE   | 514   | 0x0202 |
| CIRCLE   | 515   | 0x0203 |
| CROSS    | 516   | 0x0204 |

### Mode/Radio Buttons
| Button | Value | Hex    |
|--------|-------|--------|
| MODE_1 | 769   | 0x0301 |
| MODE_2 | 770   | 0x0302 |
| MODE_3 | 771   | 0x0303 |

### Toggle Buttons (ON States)
| Button | Value | Hex    |
|--------|-------|--------|
| A ON   | 1025  | 0x0401 |
| B ON   | 1026  | 0x0402 |
| C ON   | 1027  | 0x0403 |
| D ON   | 1028  | 0x0404 |

### Toggle Buttons (OFF States)
| Button | Value | Hex    |
|--------|-------|--------|
| A OFF  | 1281  | 0x0501 |
| B OFF  | 1282  | 0x0502 |
| C OFF  | 1283  | 0x0503 |
| D OFF  | 1284  | 0x0504 |

### Joystick (360° Rotation)
- **Formula:** `0x1000 + angle` (where angle is 0-360)
- **Range:** 4096 (0x1000) to 4456 (0x1168)
- **Examples:**
  - 0° = 4096 (0x1000)
  - 45° = 4141 (0x102D)
  - 90° = 4186 (0x105A)
  - 180° = 4276 (0x10B4)
  - 270° = 4366 (0x110E)
  - 360° = 4456 (0x1168)

## Testing Checklist

### Android App Testing
- [ ] Arrow buttons send correct values (check logs)
- [ ] Shape buttons send correct values
- [ ] Radio buttons send mode commands when selected
- [ ] Toggle buttons send ON value when pressed
- [ ] Toggle buttons send OFF value when released
- [ ] Joystick sends angle updates continuously (throttled)
- [ ] All buttons work when BLE is connected
- [ ] Reconnection works if connection is lost

### Firmware Testing (BLE Module)
- [ ] Firmware receives 2-byte values correctly
- [ ] NSS pin goes LOW before SPI transmission
- [ ] Both bytes are sent over SPI in correct order (LSB first)
- [ ] NSS pin goes HIGH after transmission
- [ ] SPI slave device receives values correctly
- [ ] Values match the button pressed

## Log Messages
The implementation includes comprehensive logging:

```
Motor command sent: Direction: UP (0x0101)
Motor command sent: Action: TRIANGLE (0x0201)
Motor command sent: Mode: 1 (0x0301)
Motor command sent: Toggle A ON (0x0401)
Motor command sent: Joystick: 45° (0x102D)
```

Check Android Logcat with filter "JoyStickViewModel" or "BLE" to monitor commands.

## Byte Order Clarification
**Little-Endian Format (Used):**
- Value 0x0101 = [0x01, 0x01]
- Value 0x0201 = [0x01, 0x02]
- Value 0x102D = [0x2D, 0x10] (45° joystick)

The low byte is sent first, then the high byte.

## Firmware Requirements
The BLE firmware must:
1. Implement the JOYSTICK_BUTTONS_CHARACTERISTIC (UUID: 0x0230bc9a-7856-3412-7856-341278563412)
2. Handle BLE characteristic write events
3. Forward received 2-byte values to SPI:
   - Assert NSS LOW
   - Send byte[0] (low byte)
   - Send byte[1] (high byte)  
   - Assert NSS HIGH
4. Ensure SPI is configured with compatible settings (clock, mode, etc.)

## Next Steps
1. Test all buttons with actual BLE Module hardware
2. Verify SPI communication with logic analyzer if available
3. Adjust throttling delay for joystick if needed (currently 100ms)
4. Fine-tune angle precision if required
5. Add visual feedback for button presses (if desired)

## Version History
- **v1.0** (2025-12-25): Initial implementation with all control buttons