# JackBot — Hexapod Control & Simulation

JackBot is a Python project for controlling and simulating a six-legged hexapod robot.
It uses IKPy for inverse kinematics, PyBullet for optional simulation, and can send joint commands to ESP32 or Arduino hardware.

## Requirements

- Python 3.12 recommended on Windows
- Python 3.11 / 3.12 is safest for `pygame` compatibility
- Required Python packages:
	- `numpy`
	- `pygame`
	- `ikpy`
	- `pybullet`
	- `pyserial`
	- `matplotlib`

## Setup

### Linux / macOS (Bash)

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install numpy pygame ikpy pybullet pyserial matplotlib
```

### Windows (PowerShell)

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
pip install numpy pygame ikpy pybullet pyserial matplotlib
```

If PowerShell blocks activation:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1
```

## Run

From the repository root:

```powershell
python main.py
```

or on Linux/macOS:

```bash
python3 main.py
```

## Configuration

Edit `config.py` before running:

- `sim = True` to enable PyBullet simulation
- `sim = False` to use hardware control
- `arduinoConnection = True` to use Arduino
- `arduinoConnection = False` to use ESP32
- `port` and `baudrate` for Arduino
- `esp32_ip` and `esp32_port` for ESP32
- `urdf_path = "JackBotUrdf.urdf"`

## Project structure

- `main.py` — main application entry point
- `Controller.py` — Pygame-based controller and input display
- `kinematics.py` — IKPy forward/inverse kinematics
- `simulation.py` — PyBullet simulation wrapper
- `GlobalVariables.py` — shared runtime state and comms
- `DataTypes.py` — typed arrays and control intent
- `RobotState/idle.py` — idle robot state
- `RobotState/walking.py` — walking robot state
- `EspCommunication.py` — ESP32 communication
- `ArduinoCommunication.py` — Arduino communication
- `JackBotUrdf.urdf` — robot model file

## Notes

- `GlobalVariables.py` initializes either `Simulation()` or the selected hardware comm class.
- `DataTypes.py` declares `PosArray`, `DegArray`, `RadArray`, `RobotCommand`, and `ControlIntent`.
- `Controller.py` updates `gv.vector_dirmov` and `gv.robot_state` from joystick input.
- `kinematics.py` loads leg chains from `JackBotUrdf.urdf` and computes IK.

## Troubleshooting

- If `pygame` installation fails on Windows, use Python 3.12 and upgrade `pip setuptools wheel` first.
- If `python` is not found on Windows, install Python and enable "Add Python to PATH".
- If the program crashes on startup, verify `JackBotUrdf.urdf` path and `config.py` settings.

## Suggested improvements

- Add a `requirements.txt` or `pyproject.toml`.
- Add a `LICENSE` file before sharing the project.
- Document hardware wiring and packet formats for ESP32/Arduino.