Tutorial 10 · 20 min
The distance sensor
Each simulated gl_zero has one distance sensor in its nose: a VL53L1X time-of-flight sensor, held level, its lens 33 mm above the desk. It keeps the bot out of trouble without the station. The bot won’t drive forward into something close in front, or off the edge of the desk. This tutorial puts a box on the simulated desk, drives into it, backs off, and sends a bot somewhere it can’t get to.
Do 09. Keeping out of the way first, and have the broker, the station and the page up.
1. How one sensor sees both
The sensor sends out light and times how long the nearest return takes. The chip sees a cone 27° across, through a grid of 16 x 16 light cells. It can be read from a patch of those cells, a region of interest, which narrows the cone to about 15° and aims it. The bot reads five regions, one after another, each 20 ms:
| Region | Aimed | On an empty desk |
|---|---|---|
bottom |
6° down | meets the desk about 14 cm ahead. Read every other time, so every 40 ms |
middle |
level | meets the desk about 25 cm ahead |
top |
6° up | doesn’t meet a 1.2 m desk at all |
left, right |
level, 6° to each side | about 25 cm ahead, like the middle |
The bottom region is the reflex’s:
- Longer than normal, or nothing back at all: the desk has ended under it. An edge.
- Any region shorter than the bottom’s normal: something is in front, close. An obstacle.
Each region has to read it twice running, so one odd reading doesn’t stop the bot.
When either happens while the bot is driving forward, its reflex drops the forward part of the wheel commands. It
can still turn on the spot or back off. It lets go once the readings have been normal again for a moment. It sends an
obstacle_stop or edge_stop event when it first holds back a forward drive. This is decided on the bot, so it
works with the station down. (Protocol rule 9.)
The other regions see further: things up to about 25 cm ahead, and across the desk for tall ones. That’s for the station, which uses them to find its way round things (step 5).
The simulator models this. For each region it traces a fan of rays across the cone against the desk, the boxes and the other bots, and reports the nearest hit.
2. Put a box on the desk
scripts/sim options
--box X,Y,W,D a box on the desk, centre and size in metres, 5 cm tall;
give it more than once for more
Restart the simulator with one bot, and a 10 cm box 32 cm in front of where it starts:
scripts/sim down
scripts/sim up 1 --seed 1 --box 0.6,0.72,0.1,0.1
The page draws the box as a grey square, and a short grey line ahead of the bot: the bottom region’s reading. The bot’s card shows it too, as distance (about 14 cm: the desk).
3. Drive into it
In Terminal B, watch the bot’s events and telemetry:
scripts/broker sub -t 'gunkslab/v0/desk/sim-1/event' -t 'gunkslab/v0/desk/sim-1/telemetry' -v
In Terminal A, drive it forward at half power for 5 seconds, straight at the box:
scripts/broker stream 5 gunkslab/v0/desk/sim-1/cmd '{"l":0.5,"r":0.5}'
Terminal B, picking out the lines that matter:
gunkslab/v0/desk/sim-1/telemetry {"up_ms":4402,"rssi":-54,"l":0.5,"r":0.5,"stopped":false,"heading":0.0,"range_m":0.144,"ranges":{"bottom":0.144,"middle":0.205,"left":0.2,"top":0.209,"right":0.204},"ranges_age_ms":{"bottom":0,"middle":61,"left":21,"top":140,"right":101}}
gunkslab/v0/desk/sim-1/event {"up_ms":5603,"kind":"obstacle_stop","range_m":0.111}
gunkslab/v0/desk/sim-1/telemetry {"up_ms":5603,"rssi":-52,"l":0.0,"r":0.0,"stopped":false,"heading":0.0,"range_m":0.111,"ranges":{"bottom":0.111,"middle":0.125,"left":0.122,"top":0.116,"right":0.116},"ranges_age_ms":{"bottom":0,"middle":138,"left":101,"top":61,"right":19},"reflex":"obstacle"}
gunkslab/v0/desk/sim-1/telemetry {"up_ms":6105,"rssi":-52,"l":0.0,"r":0.0,"stopped":false,"heading":0.0,"range_m":0.105,"ranges":{"bottom":0.105,"middle":0.105,"left":0.103,"top":0.105,"right":0.103},"ranges_age_ms":{"bottom":24,"middle":0,"left":121,"top":84,"right":41},"reflex":"obstacle"}
gunkslab/v0/desk/sim-1/event {"up_ms":9604,"kind":"timeout_stop"}
range_m0.144 while it drives: the bottom region, reading the desk about 14 cm ahead.rangeshas every region’s. The four that look level or up already read the box, about 20 cm away: nearer than the desk they’d see, but further than the bottom’s, so the reflex lets the bot drive on. The station hears them.ranges_age_mssays how long ago each was read. The regions take turns, so some readings are a sixth of a second old. The station needs that when the bot is turning, to put each reading where the bot was facing when it was taken.- The box comes nearer than the bottom’s desk. At 11.1 cm the reflex trips and says so:
obstacle_stop, with the nearest reading. The bot coasts a little further while its wheels slow, so the readings settle near 10 cm. landrgo to 0.0 although it’s still being told 0.5.stoppedstays false. Nothing told it to stop.reflexsays why it isn’t moving.timeout_stopwhen the stream ends: the ordinary dead-man, nothing to do with the sensor.
On the page, the line ahead of the bot turns red and the bot’s label says obstacle.
4. Back off
scripts/broker stream 2 gunkslab/v0/desk/sim-1/cmd '{"l":-0.4,"r":-0.4}'
gunkslab/v0/desk/sim-1/telemetry {"up_ms":13504,"rssi":-52,"l":-0.4,"r":-0.4,"stopped":false,"heading":0.0,"range_m":0.101,"ranges":{"bottom":0.101,"middle":0.104,"left":0.102,"top":0.105,"right":0.098},"ranges_age_ms":{"bottom":22,"middle":41,"left":0,"top":123,"right":83},"reflex":"obstacle"}
gunkslab/v0/desk/sim-1/telemetry {"up_ms":14203,"rssi":-55,"l":-0.4,"r":-0.4,"stopped":false,"heading":0.0,"range_m":0.135,"ranges":{"bottom":0.135,"middle":0.134,"left":0.131,"top":0.136,"right":0.128},"ranges_age_ms":{"bottom":0,"middle":98,"left":59,"top":18,"right":142}}
gunkslab/v0/desk/sim-1/telemetry {"up_ms":15004,"rssi":-53,"l":-0.4,"r":-0.4,"stopped":false,"heading":0.0,"range_m":0.138,"ranges":{"bottom":0.138,"middle":0.179,"left":0.185,"top":0.183,"right":0.174},"ranges_age_ms":{"bottom":0,"middle":100,"left":62,"top":19,"right":142}}
Backwards is allowed straight away. As the box gets further than the bottom region’s desk, reflex disappears, and
the bottom region reads the desk again. Forward works again. The other regions still read the box, further off.
Try the edge as well: turn the bot to face an edge with nothing in the way, and stream it forward. It stops with its
front about 12 cm short of the edge, range_m goes to null (nothing comes back), and the event is edge_stop.
5. Send it somewhere it can’t go
Point the bot at the box again (or start over: scripts/sim down, then the up from step 2). In Terminal B:
scripts/broker sub -t 'gunkslab/v0/desk/station/notice' -t 'gunkslab/v0/desk/sim-1/event' -v
In Terminal A, ask the station for a point 5 cm short of the box, nearer than the sensor will let the bot go.
scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","goto":{"x":0.6,"y":0.62}}'
gunkslab/v0/desk/station/notice {"client":"me","bot":"sim-1","kind":"blocked"}
The station can’t see the box, but it knows it’s there: the bot’s level regions read it from where the bot started,
nearer than the desk they’d see, and the bot’s telemetry carries those readings. It remembers what they found as
small discs. A region’s reading is the nearest thing anywhere in its 15° view, so the discs go right across it,
except where another region saw further. The point asked for is inside them. Before giving up, the bot turns about
40° each way and back, the page’s card saying looking round, so its regions see what’s either side. Still no way
there, it ends blocked. The station’s log (scripts/station logs) says what it found:
00:29:44 station sim-1's sensor found something the station can't see, at x 0.53, y 0.70: go-tos go round it
00:29:44 station sim-1's sensor found something the station can't see, at x 0.61, y 0.71: go-tos go round it
00:29:47 station sim-1's sensor sees past 2 thing(s) found near x 0.53, y 0.70: forgotten
00:29:47 station sim-1's sensor found something the station can't see, at x 0.49, y 0.70: go-tos go round it
00:29:47 station sim-1's sensor sees past 1 thing(s) found near x 0.49, y 0.70: forgotten
00:29:49 station sim-1's sensor found something the station can't see, at x 0.49, y 0.69: go-tos go round it
00:29:49 station sim-1's sensor found something the station can't see, at x 0.67, y 0.70: go-tos go round it
00:29:49 station sim-1's sensor sees past 1 thing(s) found near x 0.67, y 0.70: forgotten
00:29:49 station sim-1's sensor found something the station can't see, at x 0.65, y 0.70: go-tos go round it
00:29:51 station sim-1's sensor sees past 2 thing(s) found near x 0.52, y 0.71: forgotten
00:29:51 station sim-1's sensor found something the station can't see, at x 0.48, y 0.69: go-tos go round it
00:29:51 station goto sim-1 for me: blocked
The lines come while it looks round. It holds still half a second at each heading, so every region reads from there. Turned, a region sees the desk where the station had placed discs past the box’s end, so it forgets those, and one aimed at the box’s end finds a little more. Then it’s quiet: standing still, the bot keeps reading the box, and the station keeps what it found.
Send it somewhere past the box instead, and it goes round: the box-in-the-way and round-a-wall scenarios do just
that (scripts/scenario watch round-a-wall, 08). Held back with nothing found, it ends blocked
after 3 seconds. The desk’s edge is different, because the station knows where it is (section 6). If what the sensor
sees is another bot the station knows is close, none of this applies: getting round bots is avoidance’s job. The
station turns the bot away from it and keeps going.
The station forgets what it found when a region that could have seen it looks there and sees past it, when a bot drives through it, or after 5 minutes.
6. Near the desk’s edge
The reflex stops a bot facing an edge with its middle about 21 cm from it. So a point nearer an edge than that can’t
be reached head on. It can be reached at a slant, or along the edge, with the patch of desk the bottom region watches
staying on the desk all the way in. The station works that out itself when it knows the desk’s size, as tutorial 09
left it (scripts/station up --desk 1.2x0.8).
Start a bot with no box:
scripts/sim down
scripts/sim up 1 --seed 1
In Terminal B, watch the notices and the bot’s events:
scripts/broker sub -t 'gunkslab/v0/desk/station/notice' -t 'gunkslab/v0/desk/sim-1/event' -v
In Terminal A, ask for a point 6 cm from the edge, then one 12 cm from it:
scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","goto":{"x":1.14,"y":0.4}}'
scripts/broker send gunkslab/v0/desk/station/drive/me '{"bot":"sim-1","goto":{"x":1.08,"y":0.4}}'
gunkslab/v0/desk/station/notice {"client":"me","bot":"sim-1","kind":"edge"}
gunkslab/v0/desk/station/notice {"client":"me","bot":"sim-1","kind":"arrived"}
- 6 cm: refused,
edge. Before the bot moves. Its middle can’t come nearer an edge than the circle round its corners, about 9 cm for a gl_zero, or it couldn’t turn there. Nor deep in a corner: within about 15 cm of both edges, no slant keeps the sensor on the desk. - 12 cm: lined up, then in. Driving straight there, it would arrive facing the edge, and the sensor would see
the desk end first. So the station sends the bot to a
point well in from the edges first, 20 cm or more back from the goal and lined up with it, and it drives in at a
slant from there. On the page its card says lining up, and the dashed line bends through a ring at that point.
No
edge_stopevent: the reflex never needed to stop it.
Select the bot in the page’s drive panel and the desk is shaded where a go-to for it can’t end. Click in the shading, and the page says why it was refused. The station’s log has both:
07:27:05 station refused sim-1 for me: edge
07:27:19 station goto sim-1 for me: arrived
The at-the-edge and too-near-the-edge scenarios (08) play the same two. Without --desk, the
station knows nothing about the edge: the bot drives at it, the reflex stops it, and after 3 seconds the go-to ends
blocked.
7. What the sensor can’t do
These come from the geometry, and they apply to the real bot as much as the simulated one:
- Low things are only seen close. The level regions meet the desk about 25 cm ahead, so anything lower than the lens is hidden behind the desk further out than that. The top region sees across the desk, but only things taller than 2 to 4 cm.
- Each region is 15° wide. It says how far the nearest thing is, not where in its view. So what the station
remembers runs past a box’s ends until the bot turns and sees otherwise. Gaps beside boxes can still end
blocked, for a different reason: how the station stores what it found, and keeps the bot clear (known issues). - Nothing beside the nose. The full 27° is only as wide as gl_zero about 22 cm ahead of the lens, and out there
its edges look level, 33 mm up. So something low at the very edge of the bot’s path is never seen: nearer, it’s
outside the view. For a 2 cm box that’s the outer few millimetres, at the tyres. The bot drives into it and stays
there, pressed against it, since nothing on it feels the bump (
low-box-beside-the-path, which is expected to fail). Right beside the front, the station goes by what it saw on the way there. - A bot can’t drive right up to an edge it’s facing. Its middle stops about 20 cm from it. At a slant or side-on, it can get closer, which is how the station reaches points near an edge (section 6). Nothing watches the sides, though: along an edge, the station’s idea of where the bot is keeps it on the desk, so a real desk needs the camera’s positions to be good to a couple of centimetres.
- Nothing at the back. Reversing is never held back, so a bot can still back off the desk. The simulated desk has walls. A real one doesn’t.
- Very low things, a cable say, are seen late if at all. Even the bottom region passes over them until they’re almost under the front. The simulator’s boxes are 5 cm tall unless a scenario says otherwise.
The numbers are gl_zero’s nose pod, as its CAD has it: the lens 33 mm above the desk and 72.45 mm ahead of the bot’s middle, 1.3 mm behind its nose.
8. Tidy up
Put the simulator back to two bots and no box:
scripts/sim down
scripts/sim up 2
How it’s built: the codebase.
Check yourself
- With nothing in front, what is the bottom region measuring? And the top one? (1. How one sensor sees both)
- Why does a bottom reading longer than normal mean an edge? (1)
- While the reflex holds a bot, its commands say 0.5 and its telemetry says 0.0. Which is it doing, and what in the telemetry says why? (3. Drive into it)
- Why is backing off allowed straight away? (4. Back off)
- A go-to runs up behind another bot and the reflex trips. Does the station end it
blocked? What does it do instead? And for a box? What does the bot do before the station gives up? (5) - Why can’t a bot reach a point 12 cm from the edge, facing it? How does the station get it there anyway? (6. Near the desk’s edge)
- Why is a point 6 cm from the edge refused, when the sensor isn’t the problem there? And why do a desk’s corners have more shading than the middle of its edges? (6)
Stuck?
- Run
./gunkslab doctor. It checks the container runtime and the ports, and printsFIXwith 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.