Skip to content
gunkslab

Tutorial 09 · 20 min

Keeping out of the way

When the station drives bots to points, it keeps them from running into each other. It does this with the positions it already has, not the bots’ sensors. This tutorial shows the rules, how to watch them work, and where they stop.

Do 08. Scenarios first.

1. The rules

On every step of a go-to, the station looks a short way (35 cm) along the bot’s path for another bot’s body. Then:

  • Someone set off first: the one that set off later gives way. It stops and holds its place until the way is clear. A bot someone is driving by hand always has the right of way.
  • Their paths are about to meet: the one giving way stops before they meet, not when they’re already nose to nose.
  • Something’s parked, or waiting: the moving bot goes round it, and round every other stopped bot on the way. The station plans a path round them all on a 2 cm grid, keeping clear of each, and the bot heads for the farthest point on it that it can see straight: its waypoint. Two parked bots too close together to pass between are passed on the outside. The path is planned again twice a second, as things move. A waypoint it would reach facing the desk’s edge is a last resort. Its distance sensor would stop it short (10).
  • A wait that lasts 10 seconds turns into going round, so two bots can’t hold each other up for ever. With no way round, and no other bot on a go-to or being driven that might open one, the go-to ends blocked.

Under all of that is a guard. A bot on a go-to that’s within 3 cm of touching another may turn on the spot, or drive past it, but not drive at it. If its way runs at the other bot, it turns to go round instead. Each bot only ever opens the gap, so two can’t close on each other. The worst that happens is a wait, not a knock.

How much room a bot needs depends on what’s near it. gl_zero is 14.75 cm long and 10.75 cm wide.

  • A parked bot, with no go-to and nobody driving it, won’t move or turn. It takes only its outline, a rectangle at its pose. A bot going round it keeps its own rectangle clear, facing the way it drives, and turns on the spot only where its corners have room to swing round. So the path is planned on positions and headings, not positions alone.
  • Anything that may move or turn, a bot on its way somewhere or waiting its turn, is kept clear by the circles round both bots’ corners: 18.3 cm across for gl_zero. That’s cautious, and the same in every direction.

2. Run the scenarios

scripts/scenario run crossing head-on parked-in-the-way three-way four-corners between-two-parked
crossing               PASS  (15.1 s simulated in 0.14 s)
    closest sim-1 / sim-2: 0.300 m between centres
head-on                PASS  (15.6 s simulated in 0.24 s)
    closest sim-1 / sim-2: 0.215 m between centres
parked-in-the-way      PASS  (13.4 s simulated in 0.12 s)
    closest sim-1 / sim-2: 0.154 m between centres
three-way              PASS  (20.6 s simulated in 0.33 s)
    closest sim-1 / sim-2: 0.214 m between centres
    closest sim-1 / sim-3: 0.227 m between centres
    closest sim-2 / sim-3: 0.177 m between centres
four-corners           PASS  (33.0 s simulated in 5.18 s)
    closest sim-1 / sim-2: 0.211 m between centres
    closest sim-1 / sim-3: 0.249 m between centres
    closest sim-1 / sim-4: 0.403 m between centres
    closest sim-2 / sim-3: 0.282 m between centres
    closest sim-2 / sim-4: 0.269 m between centres
    closest sim-3 / sim-4: 0.216 m between centres
between-two-parked     PASS  (11.5 s simulated in 0.21 s)
    closest sim-1 / sim-2: 0.320 m between centres
    closest sim-1 / sim-3: 0.160 m between centres
    closest sim-2 / sim-3: 0.160 m between centres
  • Two bots both on the move come to about 21 cm between centres. Their circles would touch at 18.3 cm. The gap is the margin the station keeps, plus the guard.
  • Passing a parked bot, they come closer: 15.4 cm in parked-in-the-way, 16 cm either side in between-two-parked. There, the bot keeps its rectangle clear of the parked one’s, not the circles round them. Two circles couldn’t pass between two parked bots 32 cm apart. They’d need 46.6 cm.
  • It costs time. one-bot, about the same trip with nobody in the way, takes 12.6 s. head-on takes 15.6 s. four-corners takes 33 s: four bots taking turns through the middle.

3. Watch it

scripts/broker up
scripts/viewer up
scripts/scenario watch head-on
watching head-on: open http://127.0.0.1:8080/?fleet=scenario&desk=1.2x0.8
PASS after 15.3 s

On the page:

  • The bot that set off second (sim-2) is labelled waiting, and stays put.
  • The first (sim-1) is labelled going round. Its dashed line bends through a small ring, the waypoint it’s heading for to get round sim-2, then on to its goal cross.
  • Once sim-1 is past, sim-2 sets off.

The same thing is in the station’s summary. In a second terminal, before you start the scenario:

scripts/broker sub -t 'gunkslab/v0/scenario/station/fleet' -v

A message from the middle of the run (wrapped here to fit):

gunkslab/v0/scenario/station/fleet {"estop":false,"bots":[
  {"id":"sim-1","state":"online","quiet":false,"type":"gl-zero","driver":"scenario","echo_ms":20,
   "goal":{"x":1.0,"y":0.4},"avoid":"detour","via":{"x":0.591,"y":0.211}},
  {"id":"sim-2","state":"online","quiet":false,"type":"gl-zero","driver":"scenario","echo_ms":20,
   "goal":{"x":0.2,"y":0.4},"avoid":"wait"}]}

avoid is wait or detour. via is the waypoint, there only while going round. Both disappear when the bot is back on its way.

4. Tell the station where the desk ends

The station doesn’t know how big the desk is unless it’s told. Without that, a detour can put the waypoint off the edge. In the simulator the bot presses against the wall. On a real desk it falls off.

scripts/station options
  --desk DESK      desk size in metres, WIDTHxDEPTH, origin at a corner:
                   detours stay on it (default: unknown)

So with the simulator’s default desk:

scripts/station up --desk 1.2x0.8

With --desk, a detour never picks a side that’s off the desk. If neither side fits, the bot waits instead, for as long as another bot is on a go-to or being driven, since that might open the way. If none is, waiting won’t help: after 10 seconds the go-to ends blocked. Scenarios always pass the station their desk.

5. Where it stops

  • Driving by hand isn’t steered. The rules apply to go-tos. A driver on the page can still drive into a bot. A bot being driven by hand does count as moving, so go-tos give way to it.
  • It goes by positions, not sensors. It only sees bots the station has a recent pose for. A box on the desk, or a bot that’s gone quiet, is invisible to it. The bot’s own distance sensor catches what’s close in front: 10. The distance sensor.
  • Crowds can still jam. scripts/scenario stress (08) runs 200 random layouts of two to four bots on every change. None collide and none reach the desk’s edge. About 1 bot in 57 doesn’t finish. When this was written, all but one were the last of three bots, the other two parked where they left it no way round, so it ended blocked. The other ran out of time 2 cm from its goal, after a long way round. Either way the station stops the bot and says why, as in 07.
  • Time spent giving way doesn’t count towards a go-to’s 30 seconds. Time spent going round does.

How it’s built: the codebase.

Check yourself

  1. Two bots are sent towards each other, one a second after the other. Which waits? (1. The rules)
  2. A bot is parked just left of another’s path. Which side does the moving one pass on, and why that one? (1)
  3. Why do two moving bots never get nearer than about 21 cm, when a bot can pass a parked one at 15 cm? (1, 2)
  4. What does the page draw for a bot going round another? (3. Watch it)
  5. Why does a real desk need --desk, when the simulator only needs it to be tidy? (4)
  6. You drive a bot by hand straight at a bot on a go-to. What happens? (5. Where it stops)

Stuck?

  • Run ./gunkslab doctor. It checks the container runtime and the ports, and prints FIX with what to do.
  • Troubleshooting has the common problems and their fixes.
  • Known issues says what’s untested or doesn’t work yet.
  • Still stuck? Open an issue in desk-issues with what you typed, what you saw, and the output of ./gunkslab doctor.