SAFETY NOTE: This is an educational prototype dealing with physical robotics and moving parts. Always place the UGV on blocks (wheels off the ground) during initial testing to prevent runaway scenarios. Ensure your motor power supply has a hardware kill switch or can be quickly disconnected.
Objective and use case
What you’ll build: A fail-safe teleoperated Unmanned Ground Vehicle (UGV) prototype that accepts directional commands but automatically halts forward motion if a physical front bumper switch detects an obstacle.
Why it matters / Use cases
- Warehouse Robotics: Hardware bumper overrides prevent collisions if the network lags or the human operator makes an error during remote teleoperation.
- Remote Inspection Vehicles: Provides an immediate, fail-safe tactile stop mechanism when navigating tight spaces (pipes, crawlspaces) where camera depth perception is limited.
- Redundant Safety Systems: Demonstrates how high-level software commands must be subordinated to local, low-level hardware sensors for robust, low-latency (< 5ms) system design.
Expected outcome
- A Python-based control loop running consistently at 20Hz.
- Non-blocking ingestion of keyboard teleop commands (W/A/S/D/X) with near-zero latency.
- Real-time GPIO polling of a front bumper switch that instantly overrides forward drive commands upon contact.
Audience: Robotics Developers, Students; Level: Intermediate
Architecture/flow: Non-blocking Keyboard Input → Python Control Node (20Hz) → Motor Driver (Subordinated to Hardware GPIO Interrupts)
Educational validation note
Before publication, this case passed the Prometeo automated validation gate with status PASS. The validator checked the code blocks, article structure, copy/paste-safe commands and consistency with the supported device catalog.
Published validation evidence
- Automatic result: PASS.
- Parsed structure: 3 sections, 3 tables and 3 code blocks detected before publication.
- Checked code: 2 Python/py_compile.
- Supported catalog: the article text was checked against Prometeo’s validation-capable device profiles, and unsupported stacks block publication.
- Report findings: no blocking findings.
This validation confirms syntax and tool compatibility for the published material, but it does not replace physical testing on your exact hardware, wiring and runtime environment.
Educational safety note
This project is an educational prototype, not a certified product. Before powering the setup, verify the pinout of your exact ULX3S board revision, keep FPGA I/O signals at 3.3 V, never connect 5 V directly to I/O pins, disconnect power before changing wiring, and use suitable external supplies for loads, motors or servos while sharing ground only when the wiring requires it.
Conceptual block diagram
High-level view: what enters the system, what each block processes, and what comes out.
Functional architecture
Conceptual control flow: button input, mode selection, PWM timing and servo motion.
Validation path
The automated validation checks syntax, simulation/lint and compatibility with the ULX3S/ECP5 toolchain.
Prerequisites
- Operating System: Raspberry Pi OS Bookworm (64-bit) installed on a Raspberry Pi 5.
- Environment: Python 3.11+.
- System Configuration: I2C interface enabled via
sudo raspi-config(Interfacing Options -> I2C). - Libraries:
smbus2(for I2C communication) andgpiozero(for standard GPIO control). Install via:pip install smbus2 gpiozero.
Materials
To build this practical case, you must use EXACTLY this device model:
* Raspberry Pi 5 + PCA9685 PWM HAT + TB6612FNG dual motor driver + bumper switch UGV chassis
* Power Supply: 5V/5A USB-C power supply for the Raspberry Pi 5.
* Motor Power: 6V to 9V battery pack (e.g., 4x or 6x AA, or a 2S LiPo) dedicated to the TB6612FNG VMOT pin to power the DC motors.
* Wiring: Female-to-female and male-to-female jumper wires.
Setup/Connection
The hardware architecture splits responsibilities: The Pi 5 handles logic, the PCA9685 generates precise hardware PWM signals (offloading timing from the Pi’s CPU), and the TB6612FNG handles the high-current switching for the motors. The bumper switch acts as a simple digital input.
1. Raspberry Pi 5 to PCA9685 PWM HAT
The PCA9685 communicates over I2C.
| Pi 5 Pin | Pi 5 Function | PCA9685 Pin | Description |
|---|---|---|---|
| Pin 1 | 3.3V | VCC | Logic power for the PCA9685 chip. |
| Pin 6 | GND | GND | Common ground. |
| Pin 3 | GPIO 2 (SDA) | SDA | I2C Data line. |
| Pin 5 | GPIO 3 (SCL) | SCL | I2C Clock line. |
2. PCA9685 and Pi 5 to TB6612FNG Motor Driver
The TB6612FNG requires PWM signals for speed and standard logic high/low signals for direction. We use the PCA9685 for speed and Pi GPIOs for direction.
| Source | Source Pin | TB6612FNG Pin | Description |
|---|---|---|---|
| PCA9685 | PWM Channel 0 | PWMA | Speed control for Motor A (Left). |
| PCA9685 | PWM Channel 1 | PWMB | Speed control for Motor B (Right). |
| Pi 5 | Pin 15 (GPIO 22) | AIN1 | Direction control 1 for Motor A. |
| Pi 5 | Pin 16 (GPIO 23) | AIN2 | Direction control 2 for Motor A. |
| Pi 5 | Pin 18 (GPIO 24) | BIN1 | Direction control 1 for Motor B. |
| Pi 5 | Pin 22 (GPIO 25) | BIN2 | Direction control 2 for Motor B. |
| Pi 5 | Pin 1 | VCC | Logic power (3.3V). |
| Battery | Positive Terminal | VMOT | Motor power (6V – 9V). |
| Battery | Negative Terminal | GND | Common ground (tie to Pi GND). |
3. Bumper Switch to Raspberry Pi 5
The bumper is a simple microswitch configured as normally open (NO). We will use the Pi’s internal pull-up resistor. With the internal pull-up enabled: unpressed = True (High), pressed = False (Low). The gpiozero library automatically abstracts this logic so the is_active property returns True when the button is pressed (pulled low).
| Pi 5 Pin | Switch Terminal | Description |
|---|---|---|
| Pin 11 (GPIO 17) | COM (Common) | Digital input for the bumper. |
| Pin 14 (GND) | NO (Normally Open) | Pulls GPIO 17 low when pressed. |
Validated Code
The software is divided into two modules. The first module (ugv_hardware.py) abstracts the hardware and provides a robust mock implementation for dry-run testing. The second module (ugv_teleop.py) contains the non-blocking keyboard listener and the core safety override logic.
File 1: ugv_hardware.py
Create this file to handle low-level device interactions.
Public preview of the validated file. The complete source is shown to members and in PDF/Print.
#!/usr/bin/env python3
"""
ugv_hardware.py
Hardware abstraction layer for UGV Chassis.
Supports dry-run mocking for validation on standard PCs.
"""
import logging
class MockBumper:
def __init__(self):
self._is_pressed = False
logging.info("[MOCK] Bumper initialized.")
@property
def is_pressed(self):
return self._is_pressed
def simulate_press(self, state: bool):
self._is_pressed = state
class RealBumper:
def __init__(self, pin: int):
from gpiozero import Button
# Internal pull-up: unpressed = True (High), pressed = False (Low)
self.button = Button(pin, pull_up=True)
logging.info(f"[HARDWARE] Bumper initialized on GPIO {pin}.")
@property
def is_pressed(self):
return self.button.is_active
class MockMotorController:
def __init__(self):
self.left_speed = 0.0
self.right_speed = 0.0
logging.info("[MOCK] Motor controller initialized.")
def set_motors(self, left_speed: float, right_speed: float):
self.left_speed = max(-1.0, min(1.0, left_speed))
self.right_speed = max(-1.0, min(1.0, right_speed))
logging.debug(f"[MOCK] Motors set -> Left: {self.left_speed:.2f}, Right: {self.right_speed:.2f}")
class RealMotorController:
# ... continues for members in the complete validated source ...#!/usr/bin/env python3
"""
ugv_hardware.py
Hardware abstraction layer for UGV Chassis.
Supports dry-run mocking for validation on standard PCs.
"""
import logging
class MockBumper:
def __init__(self):
self._is_pressed = False
logging.info("[MOCK] Bumper initialized.")
@property
def is_pressed(self):
return self._is_pressed
def simulate_press(self, state: bool):
self._is_pressed = state
class RealBumper:
def __init__(self, pin: int):
from gpiozero import Button
# Internal pull-up: unpressed = True (High), pressed = False (Low)
self.button = Button(pin, pull_up=True)
logging.info(f"[HARDWARE] Bumper initialized on GPIO {pin}.")
@property
def is_pressed(self):
return self.button.is_active
class MockMotorController:
def __init__(self):
self.left_speed = 0.0
self.right_speed = 0.0
logging.info("[MOCK] Motor controller initialized.")
def set_motors(self, left_speed: float, right_speed: float):
self.left_speed = max(-1.0, min(1.0, left_speed))
self.right_speed = max(-1.0, min(1.0, right_speed))
logging.debug(f"[MOCK] Motors set -> Left: {self.left_speed:.2f}, Right: {self.right_speed:.2f}")
class RealMotorController:
def __init__(self, i2c_bus=1, pca_addr=0x40):
import smbus2
from gpiozero import DigitalOutputDevice
self.bus = smbus2.SMBus(i2c_bus)
self.pca_addr = pca_addr
# Initialize PCA9685
self.bus.write_byte_data(self.pca_addr, 0x00, 0x10) # Sleep
self.bus.write_byte_data(self.pca_addr, 0xFE, 0x79) # Set prescaler for ~50Hz
self.bus.write_byte_data(self.pca_addr, 0x00, 0x20) # Auto-increment
# Initialize TB6612FNG Direction Pins
self.ain1 = DigitalOutputDevice(22)
self.ain2 = DigitalOutputDevice(23)
self.bin1 = DigitalOutputDevice(24)
self.bin2 = DigitalOutputDevice(25)
logging.info("[HARDWARE] Motor controller initialized via PCA9685 and GPIO.")
def _set_pwm(self, channel: int, duty_cycle: float):
# Duty cycle from 0.0 to 1.0 mapped to 0-4095
val = int(duty_cycle * 4095)
self.bus.write_byte_data(self.pca_addr, 0x06 + 4*channel, 0)
self.bus.write_byte_data(self.pca_addr, 0x07 + 4*channel, 0)
self.bus.write_byte_data(self.pca_addr, 0x08 + 4*channel, val & 0xFF)
self.bus.write_byte_data(self.pca_addr, 0x09 + 4*channel, val >> 8)
def set_motors(self, left_speed: float, right_speed: float):
# Constrain speeds
left_speed = max(-1.0, min(1.0, left_speed))
right_speed = max(-1.0, min(1.0, right_speed))
# Left Motor (Motor A)
if left_speed >= 0:
self.ain1.on()
self.ain2.off()
self._set_pwm(0, left_speed)
else:
self.ain1.off()
self.ain2.on()
self._set_pwm(0, -left_speed)
# Right Motor (Motor B)
if right_speed >= 0:
self.bin1.on()
self.bin2.off()
self._set_pwm(1, right_speed)
else:
self.bin1.off()
self.bin2.on()
self._set_pwm(1, -right_speed)
class UGVChassis:
def __init__(self, dry_run: bool):
self.dry_run = dry_run
if dry_run:
self.bumper = MockBumper()
self.motors = MockMotorController()
else:
self.bumper = RealBumper(pin=17)
self.motors = RealMotorController()
def halt(self):
self.motors.set_motors(0.0, 0.0)
File 2: ugv_teleop.py
Create this file to handle the control logic and safety overrides. Ensure both files are in the same directory.
Public preview of the validated file. The complete source is shown to members and in PDF/Print.
#!/usr/bin/env python3
"""
ugv_teleop.py
Main teleoperation node with bumper safety override.
"""
import argparse
import logging
import time
import sys
import select
import termios
import tty
from ugv_hardware import UGVChassis
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
class TeleopController:
def __init__(self, chassis: UGVChassis):
self.chassis = chassis
self.current_cmd = 'x'
self.running = True
def process_command(self, cmd: str):
speed_forward = 0.8
speed_turn = 0.5
left_cmd = 0.0
right_cmd = 0.0
if cmd == 'w':
left_cmd, right_cmd = speed_forward, speed_forward
elif cmd == 's':
left_cmd, right_cmd = -speed_forward, -speed_forward
elif cmd == 'a':
left_cmd, right_cmd = -speed_turn, speed_turn
elif cmd == 'd':
left_cmd, right_cmd = speed_turn, -speed_turn
elif cmd == 'x':
left_cmd, right_cmd = 0.0, 0.0
elif cmd == 'q':
self.running = False
return
# --- SAFETY OVERRIDE LOGIC ---
# If bumper is pressed, prevent ANY forward motion commands
if self.chassis.bumper.is_pressed:
if left_cmd > 0: left_cmd = 0.0
if right_cmd > 0: right_cmd = 0.0
logging.warning("BUMPER PRESSED! Forward motion disabled.")
self.chassis.motors.set_motors(left_cmd, right_cmd)
def get_key_non_blocking():
"""Reads a single character from stdin without blocking."""
if select.select([sys.stdin], [], [], 0.0)[0]:
return sys.stdin.read(1)
return None
# ... continues for members in the complete validated source ...#!/usr/bin/env python3
"""
ugv_teleop.py
Main teleoperation node with bumper safety override.
"""
import argparse
import logging
import time
import sys
import select
import termios
import tty
from ugv_hardware import UGVChassis
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
class TeleopController:
def __init__(self, chassis: UGVChassis):
self.chassis = chassis
self.current_cmd = 'x'
self.running = True
def process_command(self, cmd: str):
speed_forward = 0.8
speed_turn = 0.5
left_cmd = 0.0
right_cmd = 0.0
if cmd == 'w':
left_cmd, right_cmd = speed_forward, speed_forward
elif cmd == 's':
left_cmd, right_cmd = -speed_forward, -speed_forward
elif cmd == 'a':
left_cmd, right_cmd = -speed_turn, speed_turn
elif cmd == 'd':
left_cmd, right_cmd = speed_turn, -speed_turn
elif cmd == 'x':
left_cmd, right_cmd = 0.0, 0.0
elif cmd == 'q':
self.running = False
return
# --- SAFETY OVERRIDE LOGIC ---
# If bumper is pressed, prevent ANY forward motion commands
if self.chassis.bumper.is_pressed:
if left_cmd > 0: left_cmd = 0.0
if right_cmd > 0: right_cmd = 0.0
logging.warning("BUMPER PRESSED! Forward motion disabled.")
self.chassis.motors.set_motors(left_cmd, right_cmd)
def get_key_non_blocking():
"""Reads a single character from stdin without blocking."""
if select.select([sys.stdin], [], [], 0.0)[0]:
return sys.stdin.read(1)
return None
def run_self_test(controller: TeleopController):
"""Automated dry-run test sequence proving the safety logic."""
logging.info("Starting automated self-test sequence...")
# Test 1: Forward motion logic
controller.process_command('w')
assert controller.chassis.motors.left_speed == 0.8, "Left motor failed forward command."
assert controller.chassis.motors.right_speed == 0.8, "Right motor failed forward command."
logging.info("Test 1 Passed: Forward command executed correctly.")
# Test 2: Bumper override
controller.chassis.bumper.simulate_press(True)
controller.process_command('w')
assert controller.chassis.motors.left_speed == 0.0, "Safety override failed on left motor!"
assert controller.chassis.motors.right_speed == 0.0, "Safety override failed on right motor!"
logging.info("Test 2 Passed: Bumper successfully halted forward motion.")
# Test 3: Reverse motion while bumper pressed
controller.process_command('s')
assert controller.chassis.motors.left_speed == -0.8, "Reverse failed during bumper press."
assert controller.chassis.motors.right_speed == -0.8, "Reverse failed during bumper press."
logging.info("Test 3 Passed: Reverse escape maneuvers remain active.")
logging.info("All self-tests passed successfully.")
def main():
parser = argparse.ArgumentParser(description="UGV Teleop Node")
parser.add_argument('--dry-run', action='store_true', help="Run without hardware")
parser.add_argument('--self-test', action='store_true', help="Run automated safety validation")
args = parser.parse_args()
chassis = UGVChassis(dry_run=args.dry_run or args.self_test)
controller = TeleopController(chassis)
if args.self_test:
run_self_test(controller)
return
print("UGV Teleop Started. Keys: W (fwd), S (rev), A (left), D (right), X (stop), Q (quit)")
old_settings = termios.tcgetattr(sys.stdin)
try:
tty.setcbreak(sys.stdin.fileno())
while controller.running:
cmd = get_key_non_blocking()
if cmd:
controller.current_cmd = cmd.lower()
controller.process_command(controller.current_cmd)
time.sleep(0.05) # 20Hz loop
finally:
termios.tcsetattr(sys.stdin, termios.TCSADRAIN, old_settings)
chassis.halt()
print("\nUGV Teleop Stopped.")
if __name__ == "__main__":
main()
Validation Method and Expected Evidence
To guarantee the fail-safe logic functions perfectly before deploying to live, high-current hardware, validate the system using the built-in self-test mode.
Validation Steps:
1. Open a terminal and run the self-test parameter: python3 ugv_teleop.py --self-test
2. Run the interactive simulation: python3 ugv_teleop.py --dry-run
Expected Evidence:
When running the --self-test, the application utilizes Python’s assert statements to mathematically verify that the final PWM variable sent to the motors drops strictly to 0.0 when a forward command is issued concurrently with a bumper press. The console output must print:
Test 1 Passed: Forward command executed correctly.
Test 2 Passed: Bumper successfully halted forward motion.
Test 3 Passed: Reverse escape maneuvers remain active.
All self-tests passed successfully.
If the output succeeds, the core logic is sound, and you can remove the --dry-run flag to execute the 20Hz control loop on the physical hardware. When the physical bumper is pressed on the live chassis, forward motor rotation will immediately cease.
Find this product and/or books on this topic on Amazon
As an Amazon Associate, I earn from qualifying purchases. If you buy through this link, you help keep this project running.
Quick Quiz
Telecommunications Electronics Engineer and Computer Engineer (official degrees in Spain).
