This project is a virtual reality (VR) setup that allows a rat to play the classic video game DOOM. The system uses a combination of hardware and software to track the rat's movement on a ball, translate it into in-game actions, and provide rewards for completing objectives.

The project is divided into several modules, each responsible for a specific part of the system. The main components are:

• Hardware Control: A set of scripts for controlling the various hardware components, including the omnidirectional drive, motion sensors, and reward system.
• Game Integration: A module for integrating the hardware with the DOOM game engine using the ViZDoom library.
• Training: A framework for training the rat to play the game, with different training scenarios and reward structures.
• Distributed Architecture: A client-server architecture that allows the main PC to control the hardware connected to a Raspberry Pi.

For a more detailed breakdown of each script's content, interface, and function, please see the Technical Overview.

This module controls a linear actuator using Raspberry Pi GPIO pins. It provides a LinActuator class to manage the actuator's movements (up, down, stop).

Usage:

from actuator import LinActuator

lin_act_pins = {'up': 22, 'down': 4, 'enable': 27}
lin_act = LinActuator(lin_act_pins)
lin_act.setup()

# Drive the actuator up for 2 seconds
lin_act.drive('up', t=2, blocking=True)

This is the main entry point for running the "rat playing DOOM" experiment. It initializes and coordinates all the necessary components.

This guide provides step-by-step instructions for running the full experiment. This setup involves a Windows PC (tested on Windows 10/11) that runs the main simulation and a Raspberry Pi that controls the physical hardware (omnidirectional platform, sensors, reward system).

The Raspberry Pi acts as a server, listening for commands from the PC. You need to start the pi_receiver.py script on it.

1. Find the Raspberry Pi's IP Address: Connect your Raspberry Pi to the same local network as your PC. Open a terminal on the Pi and run the following command to find its IP address:

   hostname -I

   Note this IP address (e.g., 192.168.1.74).

2. SSH into the Raspberry Pi: Open a Command Prompt or PowerShell on your Windows PC and connect to your Raspberry Pi using SSH. You will need the username and IP address of your Pi.

   ssh your_username@<raspberry_pi_ip>

   For example: ssh pi@192.168.1.74

3. Start the Receiver Script: Once logged in, navigate to the project directory. You need to run pi_receiver.py and provide the IP address of your PC as an argument. This allows the Pi to send data back to the correct device.

   • To find your PC's IP address, open a Command Prompt on Windows and type ipconfig. Look for the "IPv4 Address" under your active network adapter.

   Now, run the script on the Raspberry Pi:

   python pi_receiver.py <your_pc_ip> <port>

   For example: python pi_receiver.py 192.168.1.50 4444

   The Raspberry Pi is now ready and waiting for a connection from the PC.

With the Raspberry Pi running, you can now start the main experiment script on your PC.

1. Open a Command Prompt: Navigate to the project directory on your PC.

2. Run arena_scenario.py: Execute the script with the Raspberry Pi's IP address, the port number (which should match the one used on the Pi), and the serial port for the reward circuit.

   python arena_scenario.py <raspberry_ip> <port> <reward_circuit_serial_port>

   For example:

   python arena_scenario.py 192.168.1.74 4444 /dev/ttyACM0

   The experiment should now begin. The DOOM window will open, and the system will start processing the rat's movements.

You can modify the following parameters directly within the arena_scenario.py script to customize the experiment:

• smooth_flo (Line 37): Configures the motion smoothing.

  • smooth_dt: Time window for smoothing velocity calculations. A larger value results in smoother but more delayed motion data.
  • hist_size: The number of historical data points to use for smoothing.

• calibration_path (Line 41): The file path for the omnidirectional drive's calibration data (omni_calib.pckl).

• reward_circuit (Line 46):

  • auto_mixing_at_every: Interval in seconds to automatically run the reward mixer.
  • init_pressure_setpoint: Initial pressure for the reward system.

• cfg_update (Line 53): A dictionary for DOOM game settings.

  • fullscreen: Set to True for fullscreen mode.
  • win_visible: Set to False to run the game in the background.
  • res: Screen resolution (e.g., vizdoom.ScreenResolution.RES_1024X576).
  • fov: Field of view for the player.
  • repos_win: Repositions the game window on the screen (x, y).

• trainer (ManualTrainer, Line 60): Parameters for the manual training mode.

  • move_r_per_sec: Reward granted per second of movement.
  • kill_r: Reward for killing a monster.
  • man_r: Manual reward amount triggered by a key press.
  • omni_speed: The movement speed of the omnidirectional platform during manual control.
  • no_reward: Set to True to disable all rewards.

This module contains a collection of shared, dependency-free classes and functions, including a ServerSocket class for creating a server socket.

This module defines configuration parameters for the various hardware components used in the project.

This is a utility for processing and resizing textures for the DOOM environment.

This module provides a DOOM class that wraps the vizdoom library, creating a gym.Env compatible environment.

Usage:

from DOOM import DOOM

doom = DOOM('doom/scenarios/arena_lowered.wad', 'map01')

# Get the initial state
state, info = doom.reset()

# Take a step in the environment
action = ([0, 0, 0], 0)
state, reward, terminated, truncated, info = doom.step(action)

This module provides a LiveLinePlot class for real-time data visualization.

Usage:

from live_testing import LiveLinePlot

# Create a live plot with 3 subplots
mov_live_plot = LiveLinePlot(nplots=3, ylim=(-1200, 1200))

# Update the plot with new data
mov_live_plot.update(time.time(), [x, y, z])

This module is responsible for handling the motion sensors. It provides MotionSensor, MotionSensors, and SmoothMotion classes.

Usage:

from motion import MotionSensor, SmoothMotion

# Create a motion sensor object
flo = MotionSensor(spi_port=0, spi_cs=1, spi_slot=0)

# Create a smoothed motion object
smooth_flo = SmoothMotion(flo, smooth_dt=0.1)

# Get the smoothed velocity
vel = smooth_flo.get_vel()

This module controls the omnidirectional drive system. It provides the OmniDrive class for managing the three-wheeled platform.

Usage:

from omni_drive import OmniDrive

# Create an omni-drive object
omni_drive = OmniDrive()
omni_drive.setup()

# Drive the platform forward for 2 seconds
omni_drive.simple_drive('forward', t=2, blocking=True)

This module defines a torch.nn.Module for optimizing the transfer matrix of the omnidirectional drive.

This is the server-side component that runs on the Raspberry Pi. It listens for commands from the main PC and executes them on the hardware.

Usage:

python pi_receiver.py <server_ip> <server_port>

This module provides a set of wrapper classes that allow the main PC to interact with the hardware on the Raspberry Pi as if it were a local object.

This module defines classes for tracking the player's in-game movement and providing feedback for the control system.

This module defines the RewardCircuit class for controlling the reward system.

Usage:

from reward import RewardCircuit

# Create a reward circuit object
reward_circuit = RewardCircuit('/dev/ttyACM0')

# Open the water valve for 500ms
reward_circuit.open_valve(ms=500)

This is a simple test script for the RewardCircuit class.

This module defines a set of classes for training the rat to play DOOM.

This is a utility for washing the tubes of the reward system.

Contributions to this project are welcome! If you are interested in improving the code, enhancing the documentation, or adding new features, please feel free to reach out.

You can send your suggestions, questions, or contributions to: chickenhun [at] gmail.com