JackBot/README.md

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)

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)

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:

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

Run

From the repository root:

python main.py

or on Linux/macOS:

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.