Project Requirement Document Turret Controller - SergeGit/rc-tank-platform GitHub Wiki
RC Tank Hull Controller - Product Requirements Document (PRD)
1. Overview
The Hull Controller is the low-level embedded control subsystem of the RC Tank platform. It is implemented using an Arduino Nano and functions as an I²C slave to the Raspberry Pi–based Turret Controller. The Hull Controller manages all physical actuation and sensing on the tank’s chassis, including propulsion, lighting, weapon systems, and battery monitoring.
This PRD defines the engineering requirements for the design, implementation, and validation of the Hull Controller subsystem.
2. Purpose and Scope
Purpose
To define the technical specifications, control logic, safety mechanisms, and interface protocols of the RC Tank Hull Controller, ensuring reliable operation and deterministic control of physical components.
Scope
- Covers all firmware running on the Arduino Nano
- Defines electrical interfaces, I²C protocol, and subsystem behaviors
- Includes hardware pin configuration and safety requirements
- Specifies validation and test requirements
- Includes provisions for future feature extensions
3. System Context
System Architecture Role
The Hull Controller operates as the I²C slave in a hierarchical control architecture:
PS3/Web Interface → Raspberry Pi Turret Controller (I²C Master) → Arduino Nano Hull Controller (I²C Slave) → Motors/Lights/Weapons
Interfaces
| Interface |
Type |
Description |
| I²C Bus |
Master-Slave |
Receives control commands from Raspberry Pi and sends back telemetry |
| Digital/PWM Outputs |
GPIO |
Controls motors, lights, and weapons |
| Analog Inputs |
ADC |
Monitors battery voltage |
| Interrupt Input |
Digital |
Detects cannon fire feedback |
4. Hardware Configuration
4.1 Hardware Components
- Arduino Nano (ATmega328P)
- Dual Cytron motor drivers for track propulsion
- L293D motor driver for turret rotation/elevation
- Laser, IR emitter, and cannon firing circuit
- Front and rear LED lighting
- Battery management system (voltage divider, relay)
4.2 Pin Assignments
| Function |
Arduino Pin |
Description |
| Battery Management |
A0 |
Battery Voltage Input |
|
A1 |
Battery Relay Control |
| Lights |
A2 |
Front Lights |
|
A7 |
Rear Lights |
| Weapons |
D13 |
Cannon Fire Control |
|
A3 |
Laser Module |
|
D6 |
IR Light |
|
D2 |
Cannon Fired Interrupt |
| Tracks (Cytron) |
D3 |
Left Track PWM1 |
|
D9 |
Left Track PWM2 |
|
D10 |
Right Track PWM1 |
|
D11 |
Right Track PWM2 |
| Turret (L293D) |
D5 |
Rotation Enable (PWM) |
|
D8 |
Rotation Input 1 |
|
D7 |
Rotation Input 2 |
|
D6 |
Elevation Enable (PWM) |
|
D4 |
Elevation Input 1 |
|
D12 |
Elevation Input 2 |
| I²C |
A4 |
SDA |
|
A5 |
SCL |
5. Communication Protocol
5.1 I²C Configuration
- Role: Slave
- Address:
0x08
- Bus Speed: 100 kHz (default)
- Master: Raspberry Pi Turret Controller
5.2 Command Format
| Byte |
Description |
| 1 |
Command code |
| 2 |
Data value (parameter) |
5.3 Command Codes
| Command |
Hex |
Description |
Data Range |
| Turret Rotate |
0x10 |
Control turret rotation motor |
0–200 (maps to -100–100%) |
| Turret Elevate |
0x11 |
Control turret elevation |
0–200 |
| Tracks Move |
0x20 |
Control forward/backward speed |
0–200 |
| Tracks Turn |
0x21 |
Control left/right turning |
0–200 |
| Laser Toggle |
0x30 |
Toggle laser |
0/1 |
| IR Toggle |
0x31 |
Toggle IR emitter |
0/1 |
| Cannon Fire |
0x32 |
Trigger cannon fire |
Duration (ms) |
| Front Lights |
0x40 |
Control front lights |
0=Off,1=On,2=Blink |
| Rear Lights |
0x41 |
Control rear lights |
0=Off,1=On,2=Blink |
| Get Battery |
0xE0 |
Request battery data |
N/A |
| Get Position |
0xE1 |
Request position data |
N/A |
| Get Cannon Status |
0xE2 |
Request cannon ready state |
N/A |
| Get GPS |
0xE3 |
Request GPS data |
N/A |
| Get All Sensors |
0xEF |
Request all sensor data |
N/A |
| Get Status |
0xF0 |
Request system status |
N/A |
| Emergency Stop |
0xFF |
Stop/resume all systems |
0=Stop,1=Resume |
5.4 Response Format
| Command |
Bytes |
Description |
| Get Battery |
5 |
Voltage, type, relay state |
| Get Position |
4 |
X/Y coordinates |
| Get Cannon Status |
1 |
Ready (0/1) |
| Get GPS |
8 |
Lat/Long data |
| Get All Sensors |
16 |
Composite telemetry packet |
| Get Status |
1 |
Status flags |
Status Flags
- Bit 0: Cannon Ready
- Bit 1: Laser Active
- Bit 2: IR Active
- Bit 3: Front Lights On/Blink
- Bit 4: Rear Lights On/Blink
- Bit 5: Battery Relay Enabled
- Bit 6: Error State
- Bit 7: Emergency Stop Active
6. Functional Requirements
| Subsystem |
Requirement ID |
Description |
| Battery Management |
BMS-01 |
Continuously monitor voltage using ADC A0 |
|
BMS-02 |
Detect battery type based on voltage thresholds |
|
BMS-03 |
Control battery relay (A1) for power switching |
|
BMS-04 |
Provide battery voltage in 0.01V increments via I²C |
| Track Control |
MOT-01 |
Independent PWM control of left/right track motors |
|
MOT-02 |
Implement speed ramping for smooth acceleration |
|
MOT-03 |
Allow full stop on Emergency Stop command |
| Turret Control |
TUR-01 |
Control rotation/elevation motors via L293D |
|
TUR-02 |
Maintain min speed threshold for motion start |
| Weapons Control |
WPN-01 |
Fire cannon for specified duration |
|
WPN-02 |
Prevent firing during cooldown |
|
WPN-03 |
Toggle laser and IR independently |
| Lighting System |
LGT-01 |
Support ON/OFF/BLINK modes |
|
LGT-02 |
Blink rate configurable at 500ms |
| I²C Handling |
I2C-01 |
Respond to all master requests within 20ms |
|
I2C-02 |
Provide telemetry updates when polled |
| System States |
SYS-01 |
Support Normal, Error, and Emergency Stop states |
7. Non-Functional Requirements
| Category |
Requirement |
| Performance |
Response latency < 25ms for command execution |
| Reliability |
Watchdog timer (1s) resets system on hang |
| Safety |
Motor cutoff on E-Stop or loss of communication |
| Power |
Operate within 7–12V supply range |
| Maintainability |
All pin/command definitions centralized in config.h |
| Scalability |
Must support additional I²C commands without conflict |
8. Safety and Fault Handling
- Emergency Stop: Immediately disables all motors and weapons
- Battery Protection: Disable outputs below voltage threshold
- Watchdog Timer: Resets system if no loop execution for >1s
- Communication Loss: Failsafe stop if no I²C command in 2s
- Overcurrent Handling: Motor ramping and thresholds prevent surge
9. Testing and Validation
| Test ID |
Description |
Expected Result |
| TST-01 |
Command 0x20 (Tracks Move) |
Tracks move smoothly per speed input |
| TST-02 |
Command 0x32 (Cannon Fire) |
Cannon fires once, cooldown enforced |
| TST-03 |
Command 0x40/0x41 (Lights) |
Lights toggle and blink correctly |
| TST-04 |
Command 0xE0 (Get Battery) |
Returns valid voltage bytes |
| TST-05 |
Emergency Stop (0xFF) |
Motors stop immediately |
| TST-06 |
Watchdog Timeout |
System resets after 1s hang |
10. Future Enhancements
- Integration with GPS-based telemetry
- Addition of current sensing for motor load monitoring
- CAN or UART interface for future external modules
- Improved fault logging via serial output
- PID control loops for smoother track/turret motion
- OTA firmware updates via Raspberry Pi master
11. Acceptance Criteria
- All functional commands execute deterministically
- Safety features verified under failure simulation
- I²C communication stable over 10,000 command cycles
- No critical watchdog resets under normal operation
- Battery readings accurate within ±0.05V