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.

To build and flash the ESP32:

# 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:

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:

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:

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:

   mkdir -p ~/.config/containers/systemd/
   cp deploy/wiji-web.container ~/.config/containers/systemd/
   

2. Reload systemd and start the service:

   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.