
# JackBot — Hexapod Control & Simulation

**Purpose**
- **Overview**: JackBot is a Python project for controlling and simulating a six-legged (hexapod) robot. It computes foot trajectories, runs inverse kinematics against a URDF model, and sends joint commands to either a hardware controller (ESP32 / Arduino) or a PyBullet simulation.

**Setup Dependencies and Virtual Enviroment**
- **Python packages**: At minimum the project uses `numpy`, `pygame`, `ikpy`, `pybullet`, `pyserial`, and `matplotlib`.
- **Install** (recommended inside a venv):

Linux / macOS (Bash):

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

Windows (PowerShell):

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

If PowerShell blocks activation, run:

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

**Quick Start**
- **Simulation**: enable the simulator in `config.py` by setting `sim = True`, then run:

```bash
python3 main.py
```
- **Hardware**: set `sim = False` in `config.py` and choose `arduinoConnection = True` or provide your ESP32 settings. Verify `port`, `baudrate`, `esp32_ip`, and `esp32_port` in `config.py`.

**Project structure (key files)**
- **Entry point**: [main.py](main.py) — starts the controller and state loop.
- **Controller**: [Controller.py](Controller.py) — joystick input and `ControlIntent` updates.
- **Kinematics**: [kinematics.py](kinematics.py) — URDF-based forward/inverse kinematics using IKPy.
- **Simulation**: [simulation.py](simulation.py) — PyBullet visualization and joint control.
- **Hardware comms**: [EspCommunication.py](EspCommunication.py) and [ArduinoCommunication.py](ArduinoCommunication.py) — send commands to ESP32 or Arduino.
- **Runtime globals**: [GlobalVariables.py](GlobalVariables.py) — central runtime objects and flags.
- **Types**: [DataTypes.py](DataTypes.py) — `PosArray`, `DegArray`, `RadArray`, `ControlIntent`.
- **States**: [RobotState/idle.py](RobotState/idle.py) and [RobotState/walking.py](RobotState/walking.py) — state machine implementations.
- **Config**: [config.py](config.py) — ports, flags (`sim`, `arduinoConnection`), URDF path, timing values.

**How it works**
- `main.py` creates a `ControlIntent` and `RobotContext`, starts the controller thread, and runs a state loop. The `WalkingState` computes per-leg foot paths (Bezier/linear), converts positions to joint angles with `kinematics.ikpyInverse()`, then sends commands to hardware or updates the simulator.

**Configuration notes**
- **URDF**: the robot description file is `JackBotUrdf.urdf`; ensure the path in `config.py` (`urdf_path`) is correct.
- **Timing**: step timing and tick rate are configured in `config.py` (`standard_duration`, `standard_tickpersec`).

**Suggested next steps**
- Add a `requirements.txt` or `pyproject.toml` for reproducible installs.
- Document hardware wiring and expected serial/ESP packet formats if you plan to use hardware.
- Provide an example `config.py` for common setups (sim vs hardware).

**License & Contributing**
- No license file included. Add `LICENSE` if you want to publish or share.
- Contributions: open an issue or PR with improvements; add tests for kinematics if possible.