67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
|
|
# 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. |