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