RaspRover Hackathon Project

RaspRover is a lightweight maze-navigation prototype that combines a C-based maze solver, a browser-based visualization UI, and a Python bridge for simulation and testing.

What this repository contains

• C maze-solving core for wall mapping, cost propagation, and motion planning
• A browser-based maze UI for visualizing the environment and testing controls
• A Python WebSocket/serial bridge for local simulation and hardware integration experiments

Actual way to run the demo

Follow this flow for the real demo experience:

1. Open the website and build the maze

   • Open the maze UI in your browser.
   • Use the wall tool to add walls, the erase tool to remove them, and the start/goal tools to place the start and target cells.
   • Finalize the maze layout before you start the run.

2. Connect the RatRocket bot

   • Make sure the RatRocket bot is powered on and connected to the system that will act as the bridge between the website, the Python server, and the bot.
   • The bot is the component that runs the actual maze-solving logic and decision-making.

3. Start the Python server on port 8765

   • Run the Python WebSocket server so the website and the bridge client can communicate.
   • The server acts as the communication hub between the browser UI and the bot-side bridge.

4. Start the client that connects everything together

   • Launch the client application that talks to:
     • the Python server,
     • the RatRocket bot,
     • and the website.
   • This client is responsible for relaying information between the display UI and the bot.

5. Enter the webserver URL in the website and connect

   • In the browser UI, enter the WebSocket URL for the Python server (for example, ws://localhost:8765).
   • Click Connect so the website begins receiving live updates from the system.

6. Let UART data flow and start solving

   • Once the communication path is established, data starts flowing over UART between the bridge/client and the bot.
   • The bot receives the maze state and begins solving the maze on its own.

7. Play around with the maze

   • You can change the start and goal points in the website at any time.
   • The bot will recompute and solve the maze based on the updated configuration.

8. Important note

   • The algorithm and decision-making run on the bot itself.
   • The website is only a display and interaction layer for setting up the maze and visualizing the run.

Documentation

The project documentation set now includes:

• docs/ARCHITECTURE.md — high-level architecture overview
• docs/USER_GUIDE.md — setup and runtime guide
• docs/API_PROTOCOL.md — WebSocket and message protocol reference

The rest of this file preserves the older usage notes and examples for reference while the newer docs above provide a cleaner project overview.

What I changed

• Restored and cleaned the static maze UI in web/maze-vue/maze_static.html:
  • Removed the broken custom GRID_ELEMENT/manual input feature.
  • Added subtle in-cell row/column labels (e.g. 00 01 ..., 10 11 ...).
  • Added a small JSON command/test panel so you can craft and send messages from the browser.
• Replaced the old GUI-based simulator with a minimal WebSocket simulator at UISimulation/SimulationUI.py:
  • An asyncio + websockets client that sends example JSON commands to a WebSocket server.
  • Lightweight and easy to customize for your maze protocol.

Files of interest

• web/maze-vue/maze_static.html
• UISimulation/SimulationUI.py

Quick start — run the Web UI (recommended via simple static server)

1. From the repository root, run a static HTTP server so the browser can load files correctly:

# from workspace root (w:\\FreelanceProjects\\RaspRover_Hackathon)
python -m http.server 8000
# then open http://localhost:8000/web/maze-vue/maze_static.html

2. Open the URL in your browser. The UI includes:

• The maze canvas (with subtle row/col labels).
• Wall editing tools and toolbar modes.
• A JSON test panel for crafting messages to send via the UI's WebSocket connection.

Run the WebSocket simulator (Python)

1. Install the dependency (if not already installed):

python -m pip install --user websockets

2. Run the simulator (default connects to ws://localhost:8765):

python UISimulation/SimulationUI.py
# or point it at your server:
python UISimulation/SimulationUI.py ws://your-server:8765

3. The simulator will connect and send a short sequence of example JSON messages:

• {"type": "ping"}
• {"type": "maze_request"}
• {"type": "robot_init", "r": 0, "c": 0, "dir": 0}
• {"type": "robot_move", "action": "forward"}

Customize or extend the commands list in UISimulation/SimulationUI.py to match your exact UI/hardware protocol.

How the browser UI and simulator interact

• The browser UI opens a WebSocket connection (when you use the connect button in the UI) and sends/receives JSON messages. Use the JSON test panel to exercise message formats manually.
• The simulator acts as a client that can also connect to a WebSocket server to exercise the server-side handling of these messages, or you can run the simulator against a server and connect the UI to the same server depending on your test setup.

Notes & troubleshooting

• If websockets is not found, ensure you installed it into the Python you run with python.
• If you prefer to test without a server, you can run a simple Python WebSocket echo/server for debugging — let me know if you want a one-file server example.
• If the UI does not update after simulator messages, confirm both the UI and simulator are connected to the same WebSocket endpoint and that message formats match.

Next steps I can do for you (optional)

• Add a tiny WebSocket test server that both the UI and simulator can connect to for end-to-end testing.
• Extend UISimulation/SimulationUI.py to replay recorded command sequences or accept a JSON file of commands.
• Add automated UI test steps or a browser-run script to exercise the maze controls.

If you want any of those, tell me which and I will implement it next.

---

Generated: 2026-06-24 End-to-end demo

Follow these steps to run the full demo (server + UI + simulator) locally.

1. Install Python deps (recommended inside a virtualenv):

python -m pip install --user -r requirements.txt

2. Start the WebSocket test server (broadcast/echo server):

python UISimulation/ws_test_server.py

3. Start a static HTTP server to serve the web UI (from repo root):

python -m http.server 8000

4. Open the browser to the UI page:

http://localhost:8000/web/maze-vue/maze_static.html

5. In the UI, enter the WebSocket URL ws://localhost:8765 and click Connect.

6. Run the simulator in another terminal to send example commands to the server (which will echo them back to the UI):

python UISimulation/SimulationUI.py ws://localhost:8765

7. Observe messages in the server terminal and UI. You can also type JSON in the WS server's server> prompt to broadcast messages to the UI.

Troubleshooting

• If the UI does not connect, verify the server is running on port 8765 and no firewall is blocking connections.
• Confirm Python's websockets package is installed into the Python interpreter you are invoking.

That's it — this flow demonstrates the UI, the test server, and the simulator interacting end-to-end. Modify UISimulation/SimulationUI.py to exercise specific sequences or load recorded command lists.

Maze UI — Web static demo and hardware bridge

Overview

This repository contains a lightweight, single-file, no-build web demo for a Maze UI and bot simulation located at web/maze-vue/maze_static.html. The page renders a maze, lets you place/remove obstacles, set start/goal, and animate a bot. It also includes a simple WebSocket-based protocol so an external device (e.g., your STM bot) can send movement commands to the page and receive the current UI state.

Goals

• Provide an immediately runnable, no-install web UI for testing and demos.
• Allow interactive editing of the maze (wall/goal/start) from the browser.
• Provide a WebSocket API so hardware or a bridge program can control the on-screen bot and read maze state.
• Keep documentation up-to-date: this README is updated whenever the UI or protocol is changed.

Files of interest

• web/maze-vue/maze_static.html — single-file demo (open in a browser).
• README.md — this file.

Quick start

1. Open the file in your browser (double-click or open the file). Modern browsers (Chrome, Edge, Firefox) recommended.
2. Use the left toolbar to switch modes:

• Wall: click a cell edge to add/remove a wall on that side (click near the top/right/bottom/left edge of a cell).
• Erase: click a cell edge to remove a wall on that side.
• Goal: click a cell to set the goal (the bot's current position becomes the start).
• Start: click a cell to move the bot and set the start.
• Pointer: default; clicking sets start and moves the bot.

3. Use arrow keys to control the bot: Up = forward, Left/Right = turn, U = U-turn.
4. To integrate hardware, enter your WebSocket URL in the WS field (e.g., ws://192.168.1.5:8080) and click Connect.

WebSocket protocol (JSON)

The demo uses a small JSON protocol. When connected, the page will send its state periodically on relevant changes using sendState().

Outgoing (page → server)

• Message type: state
• Example payload: { "type":"state", "bot": { "r": 2, "c": 3, "dir": "N" }, "start": [0,0], "goal": [4,4], "walls": [[0,0,1,1,1,1],[0,1,1,0,1,1], ...] } Notes:
• walls is an array where each item is: [r, c, wN, wE, wS, wW] (each w is 0 or 1). This represents the four edge walls of every cell. The page sends the full grid on state changes.

Incoming (server → page)

• Move commands: { "cmd": "move", "action": "forward" } { "cmd": "move", "action": "left" } { "cmd": "move", "action": "right" } { "cmd": "move", "action": "uturn" }
• Set bot position: { "cmd": "set", "r": 3, "c": 2, "dir": "E" }
• Set walls from hardware (replace current walls): { "cmd": "walls", "walls": [[r,c,wN,wE,wS,wW], ...] } Example: { "cmd": "walls", "walls": [[0,0,1,1,1,1],[0,1,1,0,1,1]] }

Notes on integration

• If your STM device can open a WebSocket connection directly, implement the above messaging formats and send/receive JSON strings.
• If your STM communicates over serial (USB/UART), create a small bridge on a PC or Raspberry Pi that reads serial messages and translates them to WebSocket messages for the UI. Example Python bridge snippet is below.

Python test WebSocket server (example)

This small example uses the websockets package to accept UI connections and send test commands. Install:

python -m pip install websockets

Server example (save as ws_test_server.py):

import asyncio
import websockets
import json

clients = set()

async def handler(ws, path):
    clients.add(ws)
    try:
        async for msg in ws:
            print('RX:', msg)
            # echo received messages to all clients for testing
            for c in list(clients):
                if c.open:
                    await c.send(msg)
    finally:
        clients.remove(ws)

async def main():
    async with websockets.serve(handler, '0.0.0.0', 8080):
        print('WS server listening on 0.0.0.0:8080')
        await asyncio.Future()

if __name__ == '__main__':
    asyncio.run(main())

Run:

python ws_test_server.py

Then open web/maze-vue/maze_static.html and connect to ws://localhost:8080. The server will echo messages — useful for inspecting what the page sends. You can also send JSON strings from the server console to drive the page.

Serial-to-WebSocket bridge (idea)

If your STM sends compact serial messages (e.g., movement notifications or sensor readings), run a bridge on a small computer that:

• Reads serial lines (pyserial) from the STM.
• Translates them into the JSON messages defined above.
• Sends them to the UI WebSocket server or directly to the browser WebSocket if it connects to the bridge.

Maintenance and updates

• I will update this README.md each time I change web/maze-vue/maze_static.html in ways that affect features, UI flow, or the WebSocket protocol.
• Please keep the examples here synchronized with any protocol changes. If you need a different JSON shape for your STM firmware, tell me the format and I'll adapt the UI bridge code and README accordingly.

Contributing

• Report bugs or feature requests in the repo.
• If you modify the WebSocket format, update the WebSocket protocol section in this README.

Changelog

• 2026-06-24: Added WebSocket integration and interactive toolbar (Wall/Goal/Start/Pointer). Documented protocol and provided example test server.
• 2026-06-24: Added edge-level wall editing, Erase tool, on-screen arrow controls, and extended the WS state to include per-cell walls (walls array). Updated UI and README.

Contact

If you'd like, I can also:

• Add a serial-to-WS bridge script in this repo.
• Add edge-level wall editing (click specific wall edges) instead of full-cell obstacles.
• Implement authentication / reconnect / status indicator features for production deployment.