Documentation Hull Controller - SergeGit/rc-tank-platform GitHub Wiki

RC Tank Hull Controller — Documentation Package

1. Overview

The Hull Controller is the Arduino Nano–based subsystem responsible for all low-level actuation and sensing functions of the RC Tank. It operates as an I²C slave to the Raspberry Pi–based Turret Controller, which manages high-level logic, computer vision, and user interfaces.

Responsibilities

  • Drive left and right tank tracks (propulsion)
  • Control turret rotation and elevation motors
  • Operate weapon systems (cannon, laser, IR)
  • Control lighting systems (front, rear)
  • Supervise and report battery voltage
  • Execute commands received via I²C

The controller performs all real-time hardware actions; high-level decisions and user inputs are managed externally.

2. System Architecture

2.1 Role in System

User Input (PS3/Web) → Turret Controller (Raspberry Pi) → I2C Bus → Hull Controller (Arduino Nano) → Motors, Lights, Weapons

2.2 Communication

Interface Direction Description
I²C Master: Raspberry Pi → Slave: Arduino Command + Telemetry exchange
GPIO Outputs Motor drivers, lights, cannon, laser
Analog Inputs Battery voltage sensing

2.3 Operation Cycle

  1. Receives commands from the Raspberry Pi via I²C.
  2. Decodes and applies commands to actuators.
  3. Periodically measures battery voltage and prepares telemetry.
  4. Responds to I²C read requests with status or measurement data.

3. Hardware Interface

3.1 Arduino Nano Pin Mapping

Pin Function Notes
A0 Battery Voltage Divider Analog read
A1 Battery Relay Control Digital out
A2 Front Lights Digital out
A3 Laser Control Digital out
A7 Rear Lights Digital out
D2 Cannon Fired Interrupt Optional input
D3, D9 Left Track (Cytron) PWM outputs
D10, D11 Right Track (Cytron) PWM outputs
D5, D7, D8 Turret Rotation (L293D) Enable + IN1 + IN2
D6, D4, D12 Turret Elevation (L293D) Enable + IN1 + IN2
D13 Cannon Firing Digital out
A4, A5 I²C SDA, SCL Communication bus

4. I²C Command Reference

4.1 Command Codes

Command Code Description Data
CMD_TURRET_ROTATE 0x10 Rotate turret 0–200 (→ -100…+100%)
CMD_TURRET_ELEVATE 0x11 Elevate turret 0–200 (→ -100…+100%)
CMD_TRACKS_MOVE 0x20 Move forward/backward 0–200
CMD_TRACKS_TURN 0x21 Turn left/right 0–200
CMD_LASER_TOGGLE 0x30 Toggle laser 0=off, 1=on
CMD_IR_TOGGLE 0x31 Toggle IR emitter 0=off, 1=on
CMD_CANNON_FIRE 0x32 Fire cannon Duration (0–255)
CMD_FRONT_LIGHTS 0x40 Front lights 0=off,1=on,2=blink
CMD_REAR_LIGHTS 0x41 Rear lights 0=off,1=on,2=blink
CMD_GET_BATTERY 0xE0 Get battery info —
CMD_GET_STATUS 0xF0 Get system status —
CMD_EMERGENCY_STOP 0xFF Stop or resume all systems 0=stop,1=resume

4.2 Response Format

Request Bytes Format
Battery 5 Voltage (uint16, hundredths of volts), type, relay state, reserved
Status 1 Bit flags: cannon, laser, IR, lights, battery, errors

Status Flags:

Bit 0 – Cannon ready
Bit 1 – Laser active
Bit 2 – IR active
Bit 3 – Front lights on/blinking
Bit 4 – Rear lights on/blinking
Bit 5 – Battery relay enabled
Bit 6 – Error
Bit 7 – Emergency stop

5. Subsystems

5.1 Tracks Control

  • Controls two Cytron motor drivers for left/right propulsion.
  • Input mapping: 0–200 → -100…+100 speed range.
  • Functions: forward, reverse, turn, and emergency stop.

5.2 Turret Control

  • Two L293D motors (rotation and elevation).
  • Smooth speed control with ramping.

5.3 Weapons System

  • Cannon firing with cooldown.
  • Laser and IR toggle outputs.
  • Safety lockout between firings.

5.4 Lighting System

  • Front and rear lights (on/off/blink modes).
  • Shared blink timer for synchronization.

5.5 Battery Management System

  • Voltage sensing via divider (A0).
  • Relay enable/disable (A1).
  • Provides battery data for telemetry.

6. Timing Parameters

Parameter Default Notes
Motor update interval 20 ms PWM ramp update rate
Battery check interval 2000 ms ADC sample rate
Light blink interval 500 ms Blink toggle period
Cannon cooldown 2000 ms Safety delay after fire

7. Safety Features

  • Emergency stop (I²C command 0xFF).
  • Input validation on all command bytes.
  • Battery voltage monitoring.
  • Built-in watchdog compatibility.
  • Hardware isolation via transistors or MOSFETs.

8. Simplified Control Diagram

flowchart LR
    subgraph RPI["Turret Controller (Raspberry Pi)"]
        I2CM[I²C Master]
    end
    subgraph ARD["Hull Controller (Arduino Nano)"]
        I2CS[I²C Slave]
        TRK[Track Control]
        TRT[Turret Control]
        WPN[Weapons System]
        LGT[Light Control]
        BMS[Battery Supervision]
    end
    subgraph PHY["Physical Systems"]
        MTRS[Tracks]
        TROT[Turret Motors]
        CANN[Cannon]
        LIGHTS[Lights]
        LASER[Laser]
        IR[IR Emitter]
        BAT[Battery]
    end

    I2CM -- I²C Bus --> I2CS
    I2CS --> TRK & TRT & WPN & LGT & BMS
    TRK --> MTRS
    TRT --> TROT
    WPN --> CANN & LASER & IR
    LGT --> LIGHTS
    BMS --> BAT

9. Quick Reference Table

Subsystem Functions Pins
Tracks Move, turn D3, D9, D10, D11
Turret Rotate, elevate D4–D8, D12
Weapons Cannon, laser, IR D13, A3, D6
Lights Front/rear, blink A2, A7
Battery Measure & relay A0, A1

10. Extension Guidelines

To extend or modify the system:

  1. Define new command in config.h.
  2. Add a handler in processCommand() (in i2c_comm.cpp).
  3. Implement subsystem logic in the respective module.
  4. Update telemetry or status bits as needed.

End of Hull Controller Documentation Package