From 63388d96b81e9775917db76b53b2ca1da64b28ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?PROFERIS=20-=20Mi=C2=B3osz=20Stocki?=
 <milosz.stocki@proferis.pl>
Date: Tue, 7 Jul 2026 12:17:18 +0200
Subject: [PATCH] add README.md

---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bbae86c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# 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.