PoloFlie_GridRunner — Setup & Bring-Up Guide

Coordinate Crazyflie drones and Pololu 3pi+ ground robots to metric waypoints on a shared grid, using a central hub with MQTT and Crazyflie PA (Positioning Anchors).

0) System picture (what talks to what)

• Hub (PC): Runs craziepololu_hub_script.py.

  • Publishes metric waypoints to each Pololu (x_m, y_m).

  • Sends drone waypoints via Crazyflie PA (x_m, y_m, z_m).

  • Subscribes to status/telemetry from all agents.

• ESP32 bridge (per robot): Runs esp32_MQTT.ino.

  • Forwards MQTT ⇄ UART frames between the hub and Pololu.

• Pololu 3pi+ 2040: Runs pololu_robot_code.py.

  • Receives waypoints in meters, converts to grid cells using its configured cell size/origin, plans a path locally, and drives to the target.

• Crazyflie 2.1 + PA: Uses Crazyflie’s indoor positioning to fly to (x, y, z).

1) Hardware you’ll need

• 1× Crazyflie 2.1 + Positioning Anchor (PA/LPS) set

• 1× (or more) Pololu 3pi+ 2040 OLED

• 1× ESP32-WROOM-32U for each Pololu

• Wi-Fi router (LAN)

• Cables: USB-C (Pololu), Micro-USB (ESP32)

• Wiring (per robot):

  • Pololu UART0: TX=GP28, RX=GP29

  • ESP32 power from Pololu 3.3 V (share GND)

  • Cross RX↔TX between ESP32 and Pololu (ESP32-TX → GP29, ESP32-RX ← GP28)

Tip: Keep your grid intersections evenly spaced and measured (e.g., 0.30 m per cell). You’ll set this value in your Pololu code so it can convert meters→cells.

2) Software you’ll need

• MQTT broker on your LAN (e.g., Mosquitto)

• Arduino IDE with:

  • ESP32MQTTClient, WiFi

• Python 3.x on the hub PC:

  • paho-mqtt

  • cflib (Crazyflie Python lib)

(If you prefer your ROS2 bridge variant, you can still run that; the guide below assumes you’re using the single-hub script listed in the new README.)

3) Flash the ESP32 bridge (esp32_MQTT.ino)

1. Open esp32_MQTT.ino in Arduino IDE.

2. Set Wi-Fi SSID/password and MQTT broker IP (your LAN broker, e.g., 192.168.1.10).

3. Upload to each ESP32.

4. Wire ESP32↔Pololu as above and power the ESP32 from the Pololu 3.3 V pin.

What it does: subscribes to your robot’s command topic, forwards commands line-by-line over UART to the Pololu; forwards Pololu status back up to MQTT.

4) Load the Pololu robot code (pololu_robot_code.py)

1. Copy pololu_robot_code.py to the 3pi+ 2040 (MicroPython).

2. In the code, set these calibration constants to match your arena:

   • CELL_SIZE_M (meters per grid cell; e.g., 0.30)

   • ORIGIN_X_M, ORIGIN_Y_M (where the grid’s (0,0) sits in the room)

   • Heading convention (0°/+x, left-hand/right-hand frame; keep consistent with your hub)

3. Confirm UART pins for ESP32 link: GP28/GP29.

4. Confirm the waypoint input schema is metric (e.g., a JSON frame containing { "cmd":"goto", "x_m":..., "y_m":... }).

5. The robot should:

   • Convert (x_m, y_m) → nearest intersection(s) using CELL_SIZE_M and ORIGIN_*.

   • Plan a path (grid moves/turns) locally.

   • Drive it with line following.

   • Publish status (pose, arrived, clue/object events).

Sanity check: send a waypoint at a known intersection (e.g., 0.60 m, 0.90 m if your cells are 0.30 m) and verify the Pololu computes exactly 2×3 cells of travel.

5) Configure the Crazyflie PA

1. Install and anchor the PA beacons per Crazyflie/LPS docs.

2. Ensure the drone’s coordinate frame aligns with (or is transformable to) the ground-grid frame:

   • Place the drone at two measured intersections on the floor grid and record PA (x, y).

   • Compute a rigid 2D transform (rotation θ and translation) so PA coords map to your ground grid.

   • Apply this transform in the hub before sending drone waypoints.

Quick alignment method:

• Pick grid points G₁, G₂ (meters) and measure PA points P₁, P₂.
  
• θ = atan2(Δy_G, Δx_G) − atan2(Δy_P, Δx_P).
  
• T = G₁ − R(θ)·P₁.
  
• For any PA point P, use G ≈ R(θ)·P + T so both drone and Pololu share the same (x, y) world.
  

6) Run the hub (craziepololu_hub_script.py)

1. Start your MQTT broker.

2. Run craziepololu_hub_script.py on the hub PC.

3. Make sure it:

   • Connects to the broker.

   • Publishes metric waypoints to each Pololu’s command topic.

   • Connects to your Crazyflie via cflib and sends (x, y, z) targets (z in meters).

   • Subscribes to robot/drone status topics and logs arrivals/clues/objects.

Suggested MQTT topic shapes (example)

• Robot command: robots/00/cmd → {"cmd":"goto","x_m":0.90,"y_m":0.60}

• Robot status: robots/00/status → {"x_m":0.90,"y_m":0.60,"state":"arrived"}

• Drone command: handled inside hub via cflib (no MQTT needed unless you externalize it)

• Drone status: (optional) publish telemetry to drones/cf01/status

Keep topic names consistent across ESP32, Pololu, and hub. If you already have a schema, keep it—just ensure metrics in meters end up at the Pololu intact.

7) First-run checklist

• Same Wi-Fi: hub, ESP32s, and broker all on the same LAN.

• Frame alignment: the (x, y) you send means the same physical point to both drone and Pololu.

• Cell size: measure a few cells with a tape; update CELL_SIZE_M.

• Origin: mark the physical (0,0) and confirm both agents agree.

• UART sanity: TX/RX crossed, common GND, 3.3 V only.

• One waypoint test (robot): send (x_m, y_m) to a nearby intersection and watch it plan & drive.

• One waypoint test (drone): send (x_m, y_m, z_m) hovering above that same intersection.

8) Multi-agent use

• Send distinct metric waypoints to each robot and the drone.

• Your Pololu code already does local path planning from meters→cells; the hub can stay simple (no per-cell scripts needed).

• If multiple agents might converge, keep your “intent reservation” mechanism on the Pololu side (or add it to the hub) so robots don’t target the same cell at the same time.

9) Troubleshooting quick wins

• Robot ignores waypoints → Check that the incoming JSON uses x_m/y_m (not cell indices) and that your parser keys match.

• Robot path is offset/diagonal → Wrong ORIGIN_* or CELL_SIZE_M or heading convention.

• Drone misses the point → Frame alignment off; re-compute rotation/translation.

• ESP32 silent → SSID/password/broker IP, or RX/TX swapped, or missing common ground.

• Everything chatters → Two publishers to the same robot topic; disable the extra sender.

10) Usage pattern (day-to-day)

1. Power PA anchors → power Crazyflie → verify PA lock.

2. Power Pololus → ESP32 bridges (via Pololu 3.3 V).

3. Start MQTT broker.

4. Run craziepololu_hub_script.py.

5. Send metric waypoints:

   • Drone: (x_m, y_m, z_m)

   • Robot(s): (x_m, y_m)

6. Watch status topics/logs for arrived, clue, object.