From 5bfaf46a8bbd9451e5bff2470699e7ee0239a2eb Mon Sep 17 00:00:00 2001 From: MayaTheShy Date: Thu, 19 Feb 2026 23:28:12 -0500 Subject: [PATCH] feat: Implement WebBridge communication improvements with command retention, acknowledgment, and reduced polling frequency --- WEBBRIDGE_FIX.md | 290 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 WEBBRIDGE_FIX.md diff --git a/WEBBRIDGE_FIX.md b/WEBBRIDGE_FIX.md new file mode 100644 index 0000000..225972f --- /dev/null +++ b/WEBBRIDGE_FIX.md @@ -0,0 +1,290 @@ +# WebBridge Communication Fix + +## Problem +The webbridge communication was unreliable, requiring frequent restarts. Commands would get lost between the server → webbridge → turtle chain. + +## Root Causes Identified + +### 1. **Race Condition on Command Clearing** +- Server would immediately clear commands when polled +- If turtle wasn't listening at that exact moment, commands were lost forever +- No retry mechanism + +### 2. **Too Frequent Polling** +- Polling every 1 second was too aggressive +- Created more opportunities for timing issues +- Increased network overhead + +### 3. **Single Transmission** +- Commands were transmitted only once over wireless modem +- If turtle was busy or signal was weak, command was lost +- No acknowledgment system + +## Solutions Implemented + +### 1. **Server-Side: Smart Command Management** (`server/server.js`) + +**Added timing-based command retention:** +```javascript +// Don't clear commands immediately +if (!turtle.lastCommandPollTime || (Date.now() - turtle.lastCommandPollTime) > 5000) { + // First poll or > 5 seconds since last poll - send commands + turtle.lastCommandPollTime = Date.now(); + res.json({ commands }); +} else { + // Recent poll - assume previous commands were received, clear them + turtle.pendingCommands = []; + res.json({ commands: [] }); +} +``` + +**Benefits:** +- Commands stay available for multiple poll cycles +- Automatic clearing after 5 seconds (prevents stale commands) +- Webbridge can retry if first attempt fails + +**Added explicit acknowledgment endpoint:** +```javascript +POST /api/turtle/:id/commands/ack +``` +- Webbridge can explicitly confirm commands were sent +- Server clears commands only after confirmation +- Better tracking and logging + +### 2. **Webbridge: Improved Reliability** (`webbridge.lua`) + +**Reduced polling frequency:** +```lua +local POLL_INTERVAL = 2 -- Changed from 1 to 2 seconds +``` +- Less aggressive polling reduces race conditions +- Gives turtle more time to process +- Reduces server load + +**Multiple transmissions per command:** +```lua +-- Send command 3 times for reliability +for i = 1, 3 do + modem.transmit(COMMAND_CHANNEL, CHANNEL_RECEIVE, commandPacket) + os.sleep(0.05) -- Small delay between retransmissions +end +``` +- Increases chance of turtle receiving command +- 50ms delay prevents message collision +- Triple redundancy + +**Explicit acknowledgment:** +```lua +-- After sending all commands +os.sleep(0.5) -- Give turtle time to receive +if acknowledgeCommands(turtleID) then + addLog(" ACK: Commands acknowledged", colors.lime) +end +``` +- Waits 500ms for turtle to receive +- Sends acknowledgment to server +- Server can safely clear commands + +**Better logging:** +```lua +addLog("Received " .. #commands .. " command(s) for Turtle #" .. turtleID, colors.cyan) +addLog(" CMD: " .. cmd.command .. " -> Turtle #" .. turtleID, colors.yellow) +addLog(" ACK: Commands acknowledged", colors.lime) +``` +- Clearer status tracking +- Easier debugging +- Visual feedback on monitor + +### 3. **Docker Fix** (`server/Dockerfile`) + +**Added missing database.js:** +```dockerfile +COPY server.js ./ +COPY database.js ./ # <-- ADDED +``` +- Server was crashing in Docker because database.js wasn't copied +- This was causing the "module not found" errors + +## Communication Flow (New) + +### Before Fix: +``` +1. Web UI sends command → Server adds to queue +2. Webbridge polls → Server sends commands → Server CLEARS immediately +3. Webbridge transmits ONCE to turtle +4. If turtle missed it → COMMAND LOST FOREVER +``` + +### After Fix: +``` +1. Web UI sends command → Server adds to queue +2. Webbridge polls → Server sends commands → Server KEEPS for 5s +3. Webbridge transmits 3 TIMES to turtle (redundancy) +4. Wait 500ms for turtle to receive +5. Webbridge sends ACK → Server clears commands +6. If ACK fails → Commands still in queue for next poll +``` + +## Expected Improvements + +### ✅ **No More Lost Commands** +- Commands are retried automatically +- Multiple transmissions increase success rate +- 5-second window allows for retries + +### ✅ **Better Reliability** +- Explicit acknowledgment system +- Commands don't disappear prematurely +- Graceful handling of network issues + +### ✅ **Less Restart Required** +- System self-heals from temporary issues +- No need to restart webbridge after missed commands +- More robust against timing problems + +### ✅ **Better Observability** +- Enhanced logging shows command flow +- Monitor displays acknowledgment status +- Easier to debug issues + +## Testing Recommendations + +1. **Send Multiple Commands Rapidly** + - Commands should all arrive + - No commands should be lost + - Check webbridge monitor for ACK messages + +2. **Test With Busy Turtle** + - Send command while turtle is exploring + - Command should still arrive + - Multiple transmissions help + +3. **Test Network Issues** + - Move turtle far away (weak signal) + - Commands should still arrive (3 tries) + - If all fail, they retry on next poll + +4. **Monitor Logs** + - Server shows command sends and ACKs + - Webbridge shows transmission and ACK + - Turtle shows command receipt + +## Deployment Steps + +1. **Update Docker Container:** + ```bash + cd /home/mayatheshy/remoteturtle + docker compose down + docker compose build + docker compose up -d + ``` + +2. **Update Webbridge (In Minecraft):** + - Stop current webbridge (Ctrl+T) + - Upload new webbridge.lua + - Restart: `webbridge` + +3. **Turtle Code (No Changes Needed)** + - Existing turtle.lua works with new system + - No updates required + +## Configuration + +### Tunable Parameters + +**Server (server.js):** +- `lastCommandPollTime` threshold: `5000ms` (5 seconds) + - Increase for slower networks + - Decrease for faster response + +**Webbridge (webbridge.lua):** +- `POLL_INTERVAL`: `2` seconds + - Increase for slower networks + - Decrease for faster response (but more overhead) + +- Transmission retries: `3` times + - Increase for very weak signals + - Decrease to reduce spam + +- ACK delay: `0.5` seconds + - Increase if turtles are very busy + - Decrease for faster acknowledgment + +## Monitoring + +### Server Console Output: +``` +📤 Sending 1 command(s) to turtle 42 + - forward +✅ Turtle 42 acknowledged 1 command(s) +``` + +### Webbridge Monitor: +``` +[10:30:15] Received 1 command(s) for Turtle #42 +[10:30:15] CMD: forward -> Turtle #42 +[10:30:16] ACK: Commands acknowledged +``` + +### Turtle Output: +``` +Modem message on channel 100 + Target: 42 + My ID: 42 + Command: forward + Executing command... +``` + +## Troubleshooting + +### Commands Still Not Arriving? + +1. **Check Server Logs:** + - Is server sending commands? + - Are ACKs being received? + +2. **Check Webbridge Monitor:** + - Is it polling? + - Is it transmitting? + - Are ACKs succeeding? + +3. **Check Turtle:** + - Is modem open on channel 100? + - Is command processing loop running? + - Check for error messages + +4. **Check Network:** + - Are turtles within wireless modem range? + - Is webbridge computer within range? + - Try moving closer + +### High Failure Rate? + +1. **Increase Transmissions:** + - Change `for i = 1, 3` to `for i = 1, 5` + - More redundancy + +2. **Increase Poll Interval:** + - Change `POLL_INTERVAL = 2` to `POLL_INTERVAL = 3` + - More time between attempts + +3. **Check Signal Strength:** + - Use ender modems for unlimited range + - Add more webbridge relays + +## Performance Impact + +- **Server:** Minimal (one extra endpoint) +- **Webbridge:** Slightly higher (3x transmissions, but 2s polling) +- **Turtle:** No change (same command processing) +- **Network:** Higher wireless traffic (3x per command), but more reliable + +## Version History + +- **v1.0** - Original implementation (1s polling, single transmission) +- **v2.0** - Current fix (2s polling, 3x transmission, acknowledgment) + +--- + +**Last Updated:** February 20, 2026 +**Status:** ✅ Ready for Testing