Stretch4 Nav Webapp

Getting a robot to drive itself around a building normally means terminals, a stack of launch files, and someone who remembers which ones to run in which order. We replace that with a webapp.

This blog walks through the app in the order you’d use it: getting it running, the top bar that stays on every page, and then its three steps — mapping, editing the map, navigating — with a screenshot of each screen along the way. If you’d rather start with the code, it’s on GitHub at hello-robot/stretch4_nav_webapp, and if you’d rather watch than read, jump to the video at the end.

If it isn’t installed yet, on the robot:

pip3 install --user hello-robot-stretch4-nav-webapp

Start it once, on the robot:

stretch4-nav-webapp

Then open http://<robot-ip>:8080 from any laptop or tablet on the same network. There is nothing to install on the machine you’re browsing from.

The whole app is three steps:

1. Mapping — Drive the robot around with the gamepad; it builds a map as it goes.
2. Edit Map (optional) — Clean up the map and paint zones on it — no-go areas, slow areas, room names.
3. Navigation — Tell the robot where it is, then click to send it places.

Already have a map? Skip straight to Navigation.

Two more buttons sit next to them in the top bar: Overview returns you to this page, and Stop mode shuts down whichever mode is currently running. Only one mode runs at a time, which is what keeps you out of half-started states.

The top bar is always there

Whatever page you’re on, the strip along the top stays put. It’s worth learning first, because it answers most of the “why isn’t it moving?” questions before you ask them.

Runstop

The red RUNSTOP button halts the robot immediately, from any page. When pressed it changes to ROBOT STOPPED, press it again to release.

While Mapping or Navigation is running and the runstop is on, a banner sits over the map — “The robot is runstopped — it will not move” — with a Release runstop button right next to it. You can click that button directly or use the button in the top bar.

Robot status

The pill on the right shows battery and readiness at a glance. Click it for the detail.

It tells you whether the robot is ready to move, why not if it isn’t, the battery percentage and whether it’s charging, and when the reading was last refreshed with a Check again button. Further right, small indicators show the rosbridge connection, the gamepad dongle, and the current mode.

Actions

Actions exists because these aren’t setup steps. You might want to home the robot, stow the arm, or start the gamepad at any point and for quite unrelated reasons. So they sit in a menu you can open from any page at any time, instead of being locked into a sequence you run once at the start.

Nothing here is blocked by a mode that’s already running: you can home, stow, or start teleop mid-mapping or mid-navigation. An item only greys out if the robot isn’t answering or another action is still finishing. They also fire the moment you click them, with no confirmation step.

• Home robot — Moves every joint to find its zero. Takes about a minute.
• Stow — Moves the arm into its stow position, tucked within the base footprint.
• Gamepad — Starts teleop so you can drive with the controller.
• Check robot again — Re-reads the robot’s state.

Each item carries a line underneath saying what it’s about to do, or why it can’t — “No dongle detected — plug it in first, then start.” Below them, a Status list gives a live readout of Homed / Arm stowed / Gamepad dongle / Gamepad teleop, each with a coloured dot.

Step 1 — Mapping

Press Mapping. Before anything starts, the app checks the robot for you.

Three checks, each with a button to fix it on the spot:

• Homed — otherwise the robot doesn’t know where its joints are.
• Arm stowed — otherwise watch the arm while you drive.
• Gamepad dongle connected — otherwise you can’t drive.

Start mapping lights up once all three pass. If you know what you’re doing and want past them anyway, Start anyway without the checks is always available underneath.

Driving the map

Now drive the robot around the whole space with the gamepad, and make sure you come back through somewhere you’ve already mapped so it can close the loop and fix the drift. The map draws itself on screen as the lidar sees the obstacles.

The Camera button in the top-right corner opens a live view from the robot’s head camera. It is off by default, click to turn it on. You can minimize it later to a small corner pill to free up screen space while keeping the feed active.

The Layers checkboxes on the left choose what you see: Map, Robot, Laser scan. They only change your view, nothing there is sent to the robot.

Saving it

When the space looks complete, type a name and press Save map.

The map is now available to every other part of the app. Stop mapping at the bottom ends the session. Maps live in the folder printed on the home page (/home/hello-robot/stretch_user/maps by default).

Step 2 — Edit Map

Designed for anyone using Nav2, this paint-style map editor lets you clean up scans, add obstacles, set restricted zones, define speed limits, label rooms, and rotate or crop your map.

Start by picking a saved map.

Maps marked — needs setup haven’t had their Nav2 filter files generated yet; a Set up this map button appears for those.

The five layers

Once a map is loaded, you pick a layer to paint. Every layer is a separate image stacked over the same map, and each card tells you whether it’s been painted yet.

• Occupancy — The walls and free space Nav2 plans around. Editing this changes the map itself.
• Keepout — Areas the robot must never enter.
• Speed — Areas where the robot slows down, by an amount you choose.
• Rooms — Names the areas — “kitchen”, “bedroom”, “Bay 2”.
• Binary filter — Marks areas for a binary costmap filter.

Keepout, Speed and Binary filter each show a badge — Painted or Empty, so you can tell without clicking in whether anything has been drawn on that layer yet. Rooms shows a count instead (2 named in the shot above, because this map has two). Occupancy has no badge: it is the map, so there’s nothing to be empty of.

The toolbar

The same toolbar sits above the canvas on every layer.

• Brush — Paint free-hand. Drag to draw.
• Erase — Rub the layer back out. Drag to erase.
• Circle — Click the centre, then click again to set the radius.
• Rectangle — Click one corner, then click the opposite corner.
• Polygon — Click each corner, then close the outline to fill it.
• Pan — Move the map: drag to pan, scroll to zoom. Paints nothing.

Plus Undo, a Brush size slider, and a one-line hint under the toolbar that always says what the current tool is about to do.

Circles, rectangles and polygons stay objects, not just strokes. They look painted the moment you place them, but they remain clickable afterwards — even after saving. So you can drag one to move it, drag a handle to resize it, or hit Delete shape to remove it.

Occupancy — fix the map itself

Brush paints wall; Erase clears back to free space. This is where you erase the stray marks a lidar picks up through a glass door, close a wall that didn’t quite scan, or remove a table that has since moved.

The Crop & rotate lets you cut away the parts of a map the robot can never use, or straighten a map that came out at an angle.

To crop, press Draw crop box and click two opposite corners on the map. The panel reports the selection in cells — “Selection: 640 × 480 cells, kept on Apply” — and you can drag the box edges to adjust it. Then choose what the box means:

• Keep inside throws away everything outside the box. Use it to cut a map down to the floor you care about; the map gets smaller.
• Remove inside wipes everything inside the box and leaves the map the same size. Use it to delete a room or a junk area without reshaping the map around it.

To rotate, drag the slider to any angle from 0 to 359°, or nudge with the six buttons: ±1° for fine alignment, ±5° to close in, ±90° for a map that came out on its side. Positive turns counter-clockwise, negative clockwise. They add up, so +5° twice is 10°; the current angle shows next to them and Reset returns it to 0.

Nothing is committed while you work, the map previews the crop and the rotation live, and a rotation tells you the size it would produce. Apply to all layers commits it, and Undo last apply restores the version from before.

The name is literal: every layer is transformed together, so your keepout, speed and room paint stays lined up with the walls. Saved locations move with the map too, and the panel says how many it moved, plus a warning if any of them ended up outside the new map or inside an area you cleared, so a spot at the kitchen door either stays at the kitchen door or gets flagged for review.

Keepout — where the robot may never go

Paint an area and the robot simply won’t enter it: the top of a staircase, a delicate equipment corner, a private space. Switch on the Keepout filter when you start Navigation for it to take effect.

Speed — where the robot slows down

Same tools, plus a Zone speed slider.

The slider is the share of full speed the robot keeps inside the zone where 15% means it crawls through at 15% of normal. Good for narrow hallways and busy rooms. Set the value before you paint. Switch on the Speed filter when you start Navigation.

Rooms — give the space names

Add a room name, pick it, then paint the area it covers. Clicking a room’s colour dot cycles it through the palette; double-clicking its name renames it. Deleting a room clears its paint too. The robot’s world stops being a grey blob and starts having places in it.

Saving

Nothing is written to disk until you press Save [layer] layer in the top-right. An Unsaved changes marker appears next to it while you have work in progress.

Step 3 — Navigation

Press Navigation and pick the map for the room you’re actually standing in.

This screen checks that the robot is Homed, then offers the two filters you painted back in Edit Map:

• Keepout filter — keep the robot out of the areas you painted.
• Speed filter — slow the robot down in the areas you painted.

A line under the map picker tells you which of them this map actually has (“This map has painted keepout and speed zones”), so you’re never guessing. Leave both off and you get plain MPPI navigation. Press Start navigation.

First: tell the robot where it is

The map and the real robot aren’t linked yet. A card walks you through connecting them the first time.

Press the button, click the map where the robot really stands, then drag toward where it’s facing and release. The Localized chip at the top of the panel turns green when it’s taken. If the robot ever looks lost later, Set pose is always there under Map tools.

Then: send it places

The left panel is deliberately split by consequence — a Map tools section labelled “Nothing here moves the robot”, and a Goal section labelled “These move the robot”.

• Pan — Left-drag to move the map, scroll to zoom. Moves nothing but your view.
• Set pose — Tell the robot where it actually is.
• Set goal — Arms the map, click-drag a destination and the robot drives there. The drag sets which way it ends up facing.
• Cancel goal — Stops the robot and drops the current goal.
• Undock — Backs the robot off its charging dock. Do this before sending it anywhere if the robot is docked.

A status line under the Goal buttons narrates what’s happening — Driving to the goal…, Cancelling — the robot is stopping…, Goal reached.

Three health chips at the top of the panel — Driver, Lidar, Localized — tell you the robot body is answering, laser scans are flowing, and the robot knows where it is.

Places

Places are named spots you can return to with one click.

• + Robot’s spot saves wherever the robot is standing right now.
• + Place on map lets you click-drag a pin anywhere on the map and name it.

Saved places show up as labels on the map itself, and clicking one in the list sends the robot there. The × deletes one.

Layers

The Layers section at the bottom is the same set of overlays RViz calls displays — nine of them, and toggling any of them only changes what you see:

• Map — The saved occupancy map you started with.
• Robot — The 3D Stretch model at its current pose.
• Laser scan — Live lidar hits — what the robot can see right now.
• Global costmap — Where Nav2 thinks it’s expensive or unsafe to drive, across the whole map.
• Local costmap — Obstacles right around the robot, updated live.
• Keepout zones — The no-go zones navigation is actually enforcing.
• Speed zones — The slow-down zones navigation is actually enforcing.
• Planned path — The route Nav2 intends to drive to the current goal.
• Footprint — The outline the robot’s base occupies.

Stop navigation shuts down Nav2 and returns you to the setup screen.

Who this is for

First-time and non-technical users — drive a Stretch around a building without learning the launch-file stack underneath. Open a page, press a button, watch the camera, click a destination.

Researchers — set the robot up quickly through the GUI and spend your time on the research instead.

Experienced users — you’ll get the most out of Edit Map: an intuitive way to modify and add the layers you hand to Nav2, without editing masks by hand or hunting through config.

Video

Prefer to watch? This video walks through the whole app in under three minutes, from mapping a building to sending the robot across it.

For a source install, CLI flags, the config/default.yaml settings, the REST API underneath, and anything else developer-facing, see the project on GitHub.