PROFERIS - Mi³osz Stocki
106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
# WijiBoard 👻
|
||
|
||
WijiBoard is a **5-bar parallel linkage SCARA robot** designed as a spirit-board / planchette mover, controlled wirelessly from a browser via **Web Bluetooth**.
|
||
|
||
There is **no mobile app, no WiFi, and no server backend** needed for operation. The ESP32 firmware communicates directly with a local web Single Page Application (SPA) using BLE.
|
||
|
||
## Features
|
||
|
||
- **Kinematics Engine**: Custom Inverse and Forward Kinematics for a 5-bar linkage SCARA arm.
|
||
- **Web Bluetooth**: Direct browser-to-hardware communication, eliminating complex networking.
|
||
- **Interactive UI**:
|
||
- **Stepper Test**: Interactive SVG arm visualiser with jog controls and IK movement.
|
||
- **Board Control**: Clickable points of interest on various board layouts.
|
||
- **Input Text**: Keyboard-to-board automatic spelling.
|
||
- **Sequence Editor**: Record, playback, and export custom movement sequences.
|
||
- **Serverless**: The Web SPA operates purely on client-side JS (requires a Chromium-based browser).
|
||
|
||
## Hardware Overview
|
||
|
||
- **MCU**: ESP32-C3 / ESP32-S3 (PlatformIO + Arduino core)
|
||
- **Motors**: 2× 28BYJ-48 stepper motors with ULN2003 drivers
|
||
- **Mechanism**: 5-bar parallel SCARA linkage
|
||
|
||
## How to Use
|
||
|
||
1. **Power up the board**: Plug in the ESP32.
|
||
2. **Open the App**: Navigate to the hosted web application or serve it locally (e.g., `python -m http.server 8080`).
|
||
3. **Connect**: Click the Bluetooth icon in the UI to pair with `WijiBoard`.
|
||
- *Note: Web Bluetooth requires a Chromium-based browser (Chrome, Edge, Opera, etc.) and does not work in Firefox.*
|
||
4. **Home the Arm**: The robot must be homed before precise movements. You can trigger homing from the "Stepper Test" section.
|
||
5. **Control**: Use the interactive maps, test section, or text inputs to control the planchette.
|
||
|
||
## Development & Building
|
||
|
||
### 1. Building the MCU Firmware (PlatformIO)
|
||
|
||
The firmware is located in the `src/` directory and is built using [PlatformIO](https://platformio.org/).
|
||
|
||
To build and flash the ESP32:
|
||
|
||
```bash
|
||
# Navigate to the project root
|
||
cd esp32s3-wiji
|
||
|
||
# Compile the firmware
|
||
pio run
|
||
|
||
# Flash the firmware to the ESP32 via USB
|
||
pio run --target upload
|
||
|
||
# Open serial monitor for debugging (115200 baud)
|
||
pio device monitor
|
||
```
|
||
|
||
### 2. Serving the Web App (Local Development)
|
||
|
||
For quick local development, serve the files from the root directory:
|
||
|
||
```bash
|
||
python -m http.server 8080
|
||
```
|
||
Then open `http://localhost:8080` in your browser.
|
||
|
||
### 3. Containerized Deployment (Production)
|
||
|
||
The project includes a complete containerized setup to serve the static web application in a production-like environment using Docker or Podman. The configuration is found in the `deploy/` directory.
|
||
|
||
#### Building the Image
|
||
|
||
To build the Docker image using the provided `Dockerfile`:
|
||
```bash
|
||
cd deploy
|
||
docker build -t wiji-web:latest .
|
||
```
|
||
*(This uses a multi-stage build: first generating any dynamic assets using Python, then serving the static files via Nginx).*
|
||
|
||
#### Running with Docker Compose
|
||
|
||
To start the application using `docker-compose`:
|
||
|
||
```bash
|
||
cd deploy
|
||
docker-compose up -d
|
||
```
|
||
The application will be served by Nginx on the configured port.
|
||
|
||
#### Running with Podman (Quadlet)
|
||
|
||
If you are using Podman, you can deploy the container using the provided systemd quadlet file:
|
||
|
||
1. Copy the quadlet file to your user's systemd directory:
|
||
```bash
|
||
mkdir -p ~/.config/containers/systemd/
|
||
cp deploy/wiji-web.container ~/.config/containers/systemd/
|
||
```
|
||
2. Reload systemd and start the service:
|
||
```bash
|
||
systemctl --user daemon-reload
|
||
systemctl --user start wiji-web.service
|
||
systemctl --user enable wiji-web.service
|
||
```
|
||
|
||
## Acknowledgments
|
||
|
||
The initial 5-bar IK mechanism and lookup tables were inspired by `nerd-sniped/WijiBoard`. The firmware, sequence architecture, UI, and BLE protocol were built from scratch.
|