The RC Tank Hull Controller is an Arduino Nano-based system that acts as an I2C slave to a Raspberry Pi Turret Controller. The system provides comprehensive control over a model tank's movement, weapons systems, and lighting.

The controller architecture is modular, separating functionality into distinct systems:

• BMS (Battery Management System): Monitors and controls battery voltage
• Tracks: Controls tank forward/backward movement and turning
• Turret: Controls turret rotation and elevation
• Weapons: Controls cannon, laser, and IR emitters
• Lights: Controls front and rear lighting systems
• Motor Control: Unified system for multiple motor types with speed ramping

• Arduino Nano microcontroller
• Motor drivers:
  • Cytron motor drivers for tracks
  • L293D motor drivers for turret controls
• Voltage divider for battery monitoring
• Relay for battery control (optional)
• LED lights for front/rear indicators
• Cannon, laser, and IR emitter components
• Appropriate wiring and power supply

All pin assignments are centralized in config.h for easy modification. Key pin assignments include:

• Battery Voltage: A0
• Battery Relay: A1

• Front Lights: A2
• Rear Lights: A7

• Cannon: 13 (also built-in LED)
• Laser: A3
• IR Light: 6
• Cannon Fired Interrupt: 2

• Left Track PWM1: 3
• Left Track PWM2: 9
• Right Track PWM1: 10
• Right Track PWM2: 11

• Rotation Enable: 5
• Rotation Input 1: 8
• Rotation Input 2: 7
• Elevation Enable: 6
• Elevation Input 1: 4
• Elevation Input 2: 12

The controller operates as an I2C slave at address 0x08 (configurable in config.h). It responds to commands from the Raspberry Pi master.

Commands typically consist of two bytes:

1. Command byte (identifies the action)
2. Data byte (parameter for the action)

The controller responds with varying amounts of data depending on the command:

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

The BMS monitors battery voltage through a voltage divider connected to analog pin A0. It can:

• Detect battery type
• Enable/disable a battery relay
• Provide battery status information
• Implement voltage compensation for motors

Key functions:

• setupBatteryManagement(): Initialize the BMS
• updateBatteryManagement(): Regularly update battery readings
• updateBatteryVoltage(): Get current battery voltage
• detectBatteryType(): Auto-detect the battery type
• enableRelay(): Control the battery relay

The unified motor control system handles both track and turret motors. It features:

• Support for multiple motor types (L293D, Cytron)
• Smooth speed ramping
• Voltage compensation based on battery level
• Minimum speed thresholds to overcome inertia

Key functions:

• registerL293DMotor(): Add an L293D motor to the control system
• registerCytronMotor(): Add a Cytron motor to the control system
• setMotorSpeed(): Set target speed (-100 to 100)
• stopMotor(): Immediately stop a specific motor
• stopAllMotors(): Emergency stop all motors
• updateMotors(): Update motor speeds (call in main loop)

Controls the tank's movement using two track motors in a differential drive configuration.

Key functions:

• handleTracksMove(): Process forward/backward movement commands
• handleTracksTurn(): Process turning commands
• setArcadeDriveInput(): Direct joystick-style control
• trackdrive(): Set left and right track speeds directly
• emergencyStopTracks(): Immediately stop both tracks

Controls the turret's rotation and elevation motors.

Key functions:

• handleTurretRotate(): Process turret rotation commands
• handleTurretElevate(): Process turret elevation commands
• stopTurret(): Stop all turret motors

Controls the tank's weapons systems including cannon, laser, and IR emitter.

Key functions:

• handleCannonFire(): Fire the cannon for a specified duration
• handleLaserToggle(): Toggle the laser on/off
• handleIrToggle(): Toggle the IR emitter on/off
• getIsCannonReady(): Check if cannon is ready to fire

Controls the tank's front and rear lights with support for blinking.

Key functions:

• handleFrontLights(): Control front lights
• handleRearLights(): Control rear lights
• getFrontLightState(): Get current front light state
• getRearLightState(): Get current rear light state

The controller can be in one of three states:

1. STATE_NORMAL: Normal operation
2. STATE_ERROR: Error detected
3. STATE_EMERGENCY_STOP: Emergency stop activated

The system includes several safety features:

• Watchdog timer (1-second timeout)
• Emergency stop command
• Input validation for all commands
• Battery voltage monitoring
• LED indicators for system state

All configurable parameters are centralized in config.h:

• Battery check interval: 2000ms
• Light blink interval: 500ms
• Motor update interval: 20ms
• Cannon cooldown period: 2000ms

• Default ramp step: 5 PWM units per update
• Track motor minimum threshold: 20 PWM units
• Turret motor minimum threshold: 25 PWM units

• Voltage divider values: R1=100kΩ, R2=22kΩ
• Reference voltage: 5.0V
• Readings for moving average: 10

#include "main.h"

void setup() {
  // All subsystems are initialized in main.cpp's setup()
  // No additional setup required
}

void loop() {
  // All subsystem updates are handled in main.cpp's loop()
  // No additional loop code required
}

import smbus
import time

# Create I2C bus
bus = smbus.SMBus(1)  # Use 0 for older Raspberry Pi models

# I2C address of the Arduino
ARDUINO_ADDRESS = 0x08

# Command codes
CMD_TRACKS_MOVE = 0x20
CMD_CANNON_FIRE = 0x32
CMD_FRONT_LIGHTS = 0x40

# Move forward at half speed
bus.write_byte_data(ARDUINO_ADDRESS, CMD_TRACKS_MOVE, 150)  # 150 maps to +50 speed

# Fire cannon with medium duration
bus.write_byte_data(ARDUINO_ADDRESS, CMD_CANNON_FIRE, 128)  # ~half max duration

# Turn on front lights
bus.write_byte_data(ARDUINO_ADDRESS, CMD_FRONT_LIGHTS, 1)  # 1 = on

# Request battery data
bus.write_byte(ARDUINO_ADDRESS, 0xE0)
battery_data = bus.read_i2c_block_data(ARDUINO_ADDRESS, 0, 5)
voltage = (battery_data[0] | (battery_data[1] << 8)) / 100.0  # Convert to voltage
print(f"Battery: {voltage}V")

1. Motors not responding:

   • Check motor driver connections
   • Verify battery voltage is sufficient
   • Ensure motor speed exceeds minimum threshold

2. I2C communication errors:

   • Verify I2C address matches in both devices
   • Check SDA/SCL connections
   • Reduce I2C speed if experiencing issues
   • Use pull-up resistors on SDA/SCL lines

3. Erratic behavior:

   • Check for adequate power supply
   • Verify no pin conflicts exist
   • Check for proper grounding
   • Isolate motor power from logic power if possible

4. System repeatedly resets:

   • Watchdog timer may be triggering
   • Ensure loop() executes quickly enough
   • Add wdt_reset() calls if needed in long operations

// In your setup function:
byte newMotorIndex = registerL293DMotor(
  9,    // Enable pin (PWM)
  10,   // Input 1 pin
  11,   // Input 2 pin
  "New Motor",  // Name for diagnostics
  25    // Minimum threshold
);

// In your command handler:
void handleNewMotorCommand(byte data) {
  // Convert data (0-200) to speed (-100 to 100)
  int speed = data - 100;
  setMotorSpeed(newMotorIndex, speed);
}

1. Add new command code in main.h:

#define CMD_NEW_FEATURE 0x50

2. Add command handler in processCommand() in main.cpp:

case CMD_NEW_FEATURE:
  handleNewFeature(data);
  break;

3. Create the handler function:

void handleNewFeature(byte data) {
  // Your implementation here
}

This section provides a complete reference to the API functions available in each module of the tank controller system.

• float batteryVoltage - Current battery voltage
• int batteryType - Detected battery type
• bool isRelayEnabled - Current relay state

#include <Wire.h>

// Command codes
#define CMD_TRACKS_MOVE 0x20
#define CMD_TRACKS_TURN 0x21
#define CMD_FRONT_LIGHTS 0x40
#define CMD_EMERGENCY_STOP 0xFF

// I2C address of the tank controller
#define TANK_ADDRESS 0x08

void setup() {
  Wire.begin(); // Initialize as master
  Serial.begin(115200);
  delay(1000); // Give slave time to initialize
  
  // Turn on front lights
  sendCommand(CMD_FRONT_LIGHTS, 1);
}

void loop() {
  // Move forward at half speed
  sendCommand(CMD_TRACKS_MOVE, 150); // 150 = +50 speed
  delay(2000);
  
  // Turn right at half rate
  sendCommand(CMD_TRACKS_TURN, 150); // 150 = 50% right turn
  delay(1000);
  
  // Stop
  sendCommand(CMD_TRACKS_MOVE, 100); // 100 = 0 speed
  sendCommand(CMD_TRACKS_TURN, 100); // 100 = 0 turn
  delay(2000);
}

void sendCommand(byte command, byte data) {
  Wire.beginTransmission(TANK_ADDRESS);
  Wire.write(command);
  Wire.write(data);
  byte error = Wire.endTransmission();
  
  if (error) {
    Serial.print("I2C error: ");
    Serial.println(error);
  }
}

#include <Wire.h>

#define TANK_ADDRESS 0x08
#define CMD_GET_BATTERY 0xE0

void setup() {
  Wire.begin();
  Serial.begin(115200);
}

void loop() {
  // Request battery data
  Wire.beginTransmission(TANK_ADDRESS);
  Wire.write(CMD_GET_BATTERY);
  Wire.endTransmission();
  
  // Read response (5 bytes)
  Wire.requestFrom(TANK_ADDRESS, 5);
  
  if (Wire.available() >= 5) {
    // First two bytes are voltage (uint16, hundredths of volts)
    uint16_t rawVoltage = Wire.read() | (Wire.read() << 8);
    float voltage = rawVoltage / 100.0;
    
    // Third byte is battery type
    byte batteryType = Wire.read();
    
    // Fourth byte is relay state
    bool relayEnabled = Wire.read() > 0;
    
    // Fifth byte is reserved/status
    byte status = Wire.read();
    
    // Print battery info
    Serial.print("Battery: ");
    Serial.print(voltage);
    Serial.print("V, Type: ");
    Serial.print(batteryType);
    Serial.print(", Relay: ");
    Serial.println(relayEnabled ? "ON" : "OFF");
  }
  
  delay(2000);
}

To add a new command to the system, follow these steps:

1. Define the command code in main.h:

#define CMD_CUSTOM_FEATURE 0x60

2. Add command handler in the processCommand function in main.cpp:

case CMD_CUSTOM_FEATURE:
  handleCustomFeature(data);
  break;

3. Implement the handler function:

void handleCustomFeature(byte data) {
  // Implement your custom functionality
  // For example, controlling a new accessory
  digitalWrite(PIN_CUSTOM_FEATURE, data > 0 ? HIGH : LOW);
}

This table provides a complete reference for connecting all components to the Arduino Nano.

• Logic Power: Arduino Nano requires 7-12V DC input via VIN or USB
• Motor Power: Motors may require separate power supply to prevent voltage drops affecting logic
• Power Isolation: Consider using optoisolators or separate regulators to isolate motor noise from logic circuits
• Current Requirements:
  • Arduino Nano: ~50mA
  • Track Motors: ~1-3A per motor
  • Turret Motors: ~500mA per motor
  • Lights: ~100-200mA total
  • Weapons: ~50-500mA depending on components

1. Ground Connections: All grounds (Arduino, motors, sensors, power supplies) must be connected together
2. Signal Isolation: Use transistors or MOSFETs between Arduino pins and higher power components
3. PWM Pins: Use only designated PWM pins (3, 5, 6, 9, 10, 11) for motor speed control
4. Noise Reduction: Add 100nF ceramic capacitors across motor terminals to reduce EMI
5. Wire Gauge: Use appropriate wire gauge for current requirements:
   • 22-24 AWG for signals and low current
   • 18-20 AWG for moderate current (lights, small motors)
   • 16 AWG or larger for high current (main track motors)

This controller software was designed for Arduino Nano to control an RC tank.

Note: This documentation covers the functionality shown in the provided code files. Additional functionality may require updates to this documentation.