Reference
Protocol v0
Every topic, rule and unit that bots, the station and the position service use. MQTT carries it today, and the
protocol is written so another transport could: what it needs from one, and how MQTT gives it, is in
What it needs from its transport. Zenoh is the next one: how it would, and
what’s still to be shown, is On Zenoh. The message layouts are
JSON Schema files in protocol/schemas/. scripts/check-protocol tests them against protocol/examples/: every file
in good/ must pass, and every file in bad/ must fail. Why it’s shaped this way, and what’s not in it yet, is in
Concepts: the protocol’s design.
What it needs from its transport
The protocol is JSON messages on topics. A fleet’s transport is chosen when the fleet is set up, and every program on that fleet uses it. A transport can carry a fleet only if it gives all seven of these.
- Topics in levels, read by pattern. A topic is levels split by
/. A reader can ask for one level of anything (+, as inestop/+) or everything below a level (#). - Last value kept. A topic marked kept holds its last message, and anyone who starts reading it gets that first. An empty message takes the value away. The e-stop depends on this (rule 3).
- Presence. A program can leave a message to be published for it if its connection is lost without a goodbye. A
bot’s and the station’s is
{"state":"offline"}on their status topic, kept. - Two kinds of delivery. At most once may be lost but is never repeated: commands, telemetry and poses, where a newer one follows anyway. At least once is sent again until it arrives, so it may come twice: hello, status, events and e-stops. Messages from one sender on one topic arrive in the order they were sent.
- One connection per name. Each connection has a name nothing else on the transport is using, so two programs never run as one name at once. A second connection with the same name either takes the first one’s place or is refused until the first is gone: a transport may do either.
- Logins, and who may do what. Each program proves who it is with a certificate of its own, over an encrypted link, and the transport refuses any topic that login may not read or write. The list is in How it’s secured. A transport that can’t enforce it, per login and per topic, can’t carry a fleet people share.
- Stops before commands. A bot can tell that every e-stop in force has reached it before it takes its first command (rule 1). Being told the transport has taken its subscription isn’t enough: the e-stops may still be on their way, behind or overtaken by commands.
On MQTT
| What it needs | How MQTT gives it |
|---|---|
| Topics and patterns | MQTT topics, with its + and # wildcards. |
| Last value kept | Retained messages. An empty retained message clears one. |
| Presence | The last will, set when connecting, retained. |
| At most once, at least once | QoS 0 and QoS 1. MQTT keeps order within one topic. |
| One connection per name | The client ID: the broker allows one connection per ID. Real bots use their bot ID, from their MAC address. The simulator uses <fleet>-<bot>, so two fleets’ sim-1s don’t collide. The cluster’s broker names a connection by its login, so there one login is one connection. |
| Logins | TLS with a client certificate for each login, and broker/acl. |
| Stops before commands | A marker. A bot subscribes to estop/+ and its own sync (QoS 1). Once the broker has acknowledged that, it publishes a marker to sync (QoS 1), and it subscribes to cmd only when the marker comes back. Mosquitto queues a subscription’s retained messages while it handles the subscribe, so they’re queued ahead of the marker, and it sends QoS 1 messages to a connection in the order it queued them. The acknowledgement alone isn’t enough: Mosquitto sends only about 20 QoS 1 messages before waiting for the client to acknowledge them, and QoS 0 messages (cmd) go out past the ones waiting. With 300 e-stops kept, a bot that subscribed to cmd on the acknowledgement got its first command after 26 of them. The MQTT standard promises order only within one topic, so this rests on the broker: the end-to-end test checks it (300 e-stops kept, cmd sent every millisecond), and another broker needs the same check. Mosquitto queues only so many messages for one connection (the cluster’s broker and bench mode 200, the development broker 1000). Past that it drops the rest, and the marker with them: tested with 1200 e-stops kept on the development broker, the marker never came back, so the bot took no commands, which the simulator warns about after 10 s. A fleet keeps far fewer e-stops than that. |
The simulator and the firmware both do this.
On Zenoh
No bot runs on Zenoh yet: the firmware speaks MQTT only. The simulator, the station and the scenarios do, on a
development router (scripts/zenoh up, below). The Zenoh link (transport/gunklink/zenoh.py) is built, and the tests
every link has to pass (transport/tests/test_contract.py, and tests/zenoh/test_router.py for what only Zenoh has)
run on it against a real router, zenohd 1.10.2 with mutual TLS and access rules, in CI (tests/zenoh/run.sh). The
in-memory link and MQTT pass the same tests. So does the end to end test (tests/e2e/), simulator and station and all,
but for two parts: the recorder, which has no Zenoh option yet, and MQTT’s takeover of a name, which Zenoh refuses. Rows say tested where those tests
show it, measured where it was timed by hand, and not yet run where nothing has shown it. Zenoh has no kept
messages, no last will and no takeover of a name, so the link makes up the difference, and the programs above it see
what MQTT gives them.
| What it needs | How Zenoh gives it |
|---|---|
| Topics and patterns | Key expressions: the same topics, with * for one level (MQTT’s +) and ** for everything below (#). The link turns one into the other. Tested. |
| Last value kept | No kept flag. The router’s storage plugin keeps the last value of each kept topic: every topic marked kept on this page, and the presences. The link writes that list into the router’s config, and its tests check the list against this page. A reader’s link subscribes, then asks the storages with a get, and hands the program the kept values first. Clearing one is a Zenoh delete, handed over as an empty message, as on MQTT. One sent just as a reader subscribes |
| can reach it twice, live and from the storage: the link compares the router’s timestamps on the two and hands it over | |
once. One can also miss it both ways: a storage takes in what’s sent and answers gets in no set order, so a get can be answered while messages that reached the router before the subscription are still waiting to go in. So before its get, the link puts a marker of its own in each storage it reads, under a fleet no fleet has (_mark-<its name>, which no program hears and every login may write), and waits until a get returns it: a storage takes messages in the order they came, so then every earlier one is in. Tested, 300 of them five times over while commands flow, and 40 times over on one CPU: none missed, none twice. Before, the same 300 came twice (up to 74 of them), and on one CPU some went missing every run (1 to 29). Also fixed then: a reader’s get that never ended on one CPU, so it heard nothing at all. The link takes a get’s answers through a callback now, not the binding’s bounded channel. A router that restarts loses what it kept unless its storage is on disk. Every link finds it again by itself, and its program’s on_up puts back what’s its own, as on MQTT: tested, a TLS router stopped and started, and the station’s kept e-stop reached the bot again. |
|
| Presence | Nothing is published for a program after it’s gone. Instead a program’s link keeps its presence at <topic>/@presence and holds a liveliness token there while it’s connected. When a token goes without a goodbye, a reader’s link hands the program the presence on that topic, and a reader that starts later gets it as kept. A goodbye takes the kept presence away first. @presence is a chunk no * or ** takes in, so no pattern ever reads it, and the router’s access rules have to name it. Tested. A program killed with no goodbye goes at once, since its computer closes the connection. One that freezes, or loses power or Wi-Fi, goes when the router’s lease runs out: 9.0 s, measured. |
| At most once, at least once | At most once is a plain put. Zenoh never resends one: in its own words, “reliability does not trigger any data retransmission on the wire”, so a message in flight when a connection drops is lost. For kept topics (hello, status and e-stops) the storages make up for that: a reader that comes back asks for the last values again. Events have nothing yet. The way to give them at least once is the advanced publisher and subscriber: the publisher keeps its recent messages, and the subscriber notices a gap in their numbers and asks for what it missed. Both are in zenoh-python and zenoh-pico 1.10.2 (not yet run). Messages from one connection on one topic arrive all and in order: tested, 200 of them. |
| One connection per name | The session ID. The link makes the ID from the name it would use on MQTT, so a name always gives the same ID, and the router refuses a second session with an ID it already has, until the first is gone. Tested. A bot that restarts after losing power, before the router has noticed, waits for the lease to run out, up to 9 s, and can’t move while it waits. Unlike the cluster’s broker, the router doesn’t tie the ID to the login: a program holding a login’s certificate could connect under another ID beside the real one, and nothing would say so. |
| Logins | TLS with a client certificate for each login, and the router’s access control: rules by certificate name, for each kind of message (put, delete, subscribe, get, liveliness) and key expression. Anything not allowed is refused. A connection with no certificate is refused. Tested. Refusals are silent. A subscription, get or put the rules refuse gives no error, just nothing: a refused get looks like one with no replies. There’s nothing like %u in broker/acl, so each login gets its own rules, written out from broker/acl and the list of logins (access() in the link): a user block’s lines are that login’s, a pattern line every login’s with its own name for %u, and on Zenoh the station may also send estop/station. Tested on a real router. A change needs the router restarted, and so does a renewed certificate: zenohd reads both only at start. As a cluster runs it (broker/zenoh/start.py --tls: TLS only, no rule for plain tcp), its --check is a liveness probe that fails once the certificate or the rules have changed, so the router starts again with them. Tested. The router reads no revocation list: a revoked certificate still connects, but its name gets no rules once it has no valid certificate left. If the same name has another valid one, the revoked certificate keeps that name’s rules until it runs out. zenoh-pico has a TLS option, but no source says it runs on an ESP32: it has to be shown on a bare board, logins and all, before any bot uses Zenoh. |
| Stops before commands | A bot subscribes to estop/*, and its link asks the storages for the kept ones and hands them over before saying the subscription is in. The bot subscribes to cmd only then. That takes the marker’s place. Tested: 300 kept e-stops, a cmd every millisecond, and the first cmd came after the last e-stop. Because refusals are silent, a bot refused its e-stops would see none and think none were set. So on Zenoh the station keeps its own e-stop, estop/station, set to {"stop":false}, and a bot takes commands only once it has heard it (subscribe(..., proof=) in the link). Tested: a login that may not read e-stops never got that far. The station keeps it for each fleet it runs, and takes it away when a site comes off the lab’s list. It stays when the station goes down: it says the rules let a bot read e-stops, not that a station is there. The simulator waits for it. Tested end to end: a simulated bot that starts during an e-stop stays stopped after the stop is cleared, until the station’s own comes. |
The development router
scripts/zenoh up runs zenohd in a container, as scripts/broker up does mosquitto. On port 7447, on this machine only,
it takes any program with no login and lets it use every fleet topic, as the development broker does. With
TRANSPORT=zenoh in front, scripts/sim, scripts/station, scripts/scenario watch and scripts/e2e use it in place
of the broker. scripts/zenoh up --lan adds TLS on this machine’s network address, port 7448, for programs on other
machines: certificates from bench mode’s CA (scripts/login NAME, the same as the broker’s), each held to the rules from
broker/acl above. scripts/zenoh revoke NAME revokes a login and starts the router again without it. What the router
keeps is in memory, and goes when it stops.
Topics
Everything sits under gunkslab/v0/<fleet>/.
| Topic | From → to | Kept | Delivery | Schema |
|---|---|---|---|---|
gunkslab/v0/<fleet>/<bot>/hello |
bot → station | yes | at least once | hello |
gunkslab/v0/<fleet>/<bot>/status |
bot → station (its presence says offline) |
yes | at least once | status |
gunkslab/v0/<fleet>/<bot>/cmd |
station → bot | no | at most once | cmd |
gunkslab/v0/<fleet>/<bot>/telemetry |
bot → station, 10 Hz | no | at most once | telemetry |
gunkslab/v0/<fleet>/<bot>/event |
bot → station, when something happens | no | at least once | event |
gunkslab/v0/<fleet>/<bot>/pose |
position service → station | no | at most once | pose |
gunkslab/v0/<fleet>/<bot>/sync |
bot → itself: the marker that says its e-stops are in (rule 1) | no | at least once | sync |
gunkslab/v0/<fleet>/estop/<name> |
anyone → every bot in the fleet: each person’s own | yes | at least once | estop |
v0is the protocol version. A new version gets new topics, so bots on two versions can share one transport while they’re updated.<fleet>is a fleet ID, set in each bot’s config. It keeps fleets apart on one transport. The examples usedesk.<bot>is the bot’s own ID. Real bots name themselves from their MAC address,bot-a4cf12(the firmware does this today). Simulated bots aresim-1,sim-2and so on.- Every connection needs a name nothing else on the transport is using (above). On MQTT a second one with the same name throws the first off, and two of them keep doing it to each other. On Zenoh the second is refused.
- IDs are lower case, digits and hyphens, 1 to 32 characters.
station,estopandsimcan’t be bot IDs. They’re topics of their own under the fleet.
Rules
- On connect, a bot:
- Leaves
{"state":"offline"}as its presence on its status topic, kept. - Publishes
hello, then{"state":"online"}. - Reads everyone’s e-stop,
estop/+, and its ownsync. Once those are in place it sends a new marker tosync, and only when the marker comes back does it read its owncmdtopic: every e-stop in force reached it first. It obeys nocmdbefore then, and none at all if it may not read the e-stops.
- Leaves
- Dead-man. A bot stops 500 ms after the last
cmd. A station that’s driving sendscmdat least every 250 ms, repeating the same values if nothing has changed. Today’s firmware already does this. - E-stop. Everyone has an e-stop of their own, kept on
estop/<their name>. While anyone’s says{"stop":true}, every bot stays stopped and ignorescmd. It drives again only once every one is off ({"stop":false}, or the kept message taken away with an empty one) and a freshcmdcomes. Because they’re kept and read before any command (rule 1), a bot that connects during an e-stop stops straight away. On the cluster a driver may set or clear only their own, and an admin anyone’s. A bot keeps track of up to eight at once. If there are ever more, it stays stopped until it restarts. An e-stop may name bots,{"stop":true,"bots":["bot-a4cf12", ...]}(a group’s stop in the lab): then only those stop, and for any other bot it counts as off. A bot that understands this says"estop_bots": truein itshello; one that doesn’t refuses the whole message, so it wouldn’t stop. A sender names bots only when every bot it names saidestop_bots, and otherwise sends a stop for every bot. - Bots don’t know where they are. Position comes from the position service: the overhead camera, or the
simulator. It publishes
poseon the bot’s behalf. A bot that can measure itself still reports that throughtelemetry, notpose. A bot withimuin itshellosendsheading: which way it points by its own gyro, 0 where it pointed when it was first still after booting. That drifts, and its 0 isn’t the field’s +x. A bot with encoders sendsodo_l_mandodo_r_m, how far each side’s wheels have turned since boot, in metres, forward positive. These are wheel turns, so a wheel that slips still counts. A bot with both may do its own dead reckoning and sendodo_x_mandodo_y_m: where its wheels and gyro put it, in its own frame, 0,0 where its heading started and +x the way heading 0 points. It’s still not where it is on the field: the station lines it up. With no camera, nothing publishespose: the station works out where each bot is from that telemetry, by its own estimate or the bot’s dead reckoning, from its last pose or where a person places it (“Where a bot is without a camera” and “Steering without a camera”, under the station, below). Those stay estimates, in the station’sstation/fleetwith how far off each may be, and never become apose. - Numbered commands. The station may put an increasing
seqon eachcmd, and the bot reports the last one it obeyed asseqin its telemetry. That shows the bot is obeying, gives the round-trip time, and catches commands that arrive out of order. While commands keep coming, the bot ignores aseqlower than the last one it obeyed. Once it has stopped for a timeout, it accepts anyseqagain, so a restarted station can start counting from 0. A restart takes longer than the 500 ms timeout, so the bot has always stopped first. - Events say why. Telemetry repeats the state. An
eventis sent once, when something happens:boot, with the reason the bot last restarted (a brownout, a crash, power-on).timeout_stop.estop_onandestop_off.wifi_reconnectandmqtt_reconnect.obstacle_stopandedge_stop(rule 9).stall_stop,battery_lowandbattery_empty(rule 10).
- Identify.
{"identify":true}makes the bot show which physical bot it is: a short wiggle of the wheels or a blink of the board’s LED, under 2 s, then stopped. During an e-stop it must not move the wheels. - Unknown fields are refused. Every layout says which fields it allows, so a typo or a newer field shows up as an error instead of being silently ignored.
- The reflex. A bot with a front distance sensor (
tofin itshello’ssensors) won’t drive forward into what it sees, whatever it’s told. On an empty desk, the part of the sensor’s view aimed down reads the surface some way ahead. gl_zero’s sensor is read as five regions of interest, one after another, and its bottom region reads about 14 cm. That reading longer, or nothing back at all, means the desk ends ahead. Any region reading shorter than that is an obstacle. A region has to read it twice running, so one odd reading doesn’t count. Either way it drops the forward part of its wheel commands. It can still turn on the spot or back off. It lets go once the readings have been normal for a moment (100 ms in the simulator). It sendsobstacle_stoporedge_stopwhen the reflex first holds back a forward drive, with the reading that did it, and while it’s holding, its telemetry carriesreflex. Telemetry carries the bottom region’s reading (or the only one’s) asrange_m,nullfor nothing back, and with several regions, each one’s last reading asranges:bottom,middleandtopstraight ahead (aimed down, level and up),leftandrightlevel to each side.ranges_age_mssays how long before the message each was read, in milliseconds: the regions take turns, so a reading can be a sixth of a second old. This is decided on the bot, so it works with the station down. A bot with a rear sensor too (tof-rear) does the same backwards: it won’t reverse into what that one sees, but may turn or drive forward away from it. Its events carry"end":"rear", and its telemetryreflex_rearandrange_rear_m. A sensor that stops answering counts as the desk ending. - The bot’s own hardware stops. A bot that watches its motors and battery stops on its own, whatever it’s told,
and says why. A motor that’s driven but doesn’t turn is switched off and stays off until its side is asked for
nothing, or for the other way:
stall_stop, with whichmotor. A low battery is a warning,battery_low. An empty one stops the motors until the battery is charged,battery_empty. Both carry the voltage asbatt_vwhen the bot measures it, and its telemetry carries the battery’s state asbattery(ok,low,empty) for as long as it lasts. Itslandrare the power actually going out, so a stalled side or an empty battery reads 0. Pirate Stage does this. gl_zero’s firmware judges its battery the same way. It counts its encoders but doesn’t use them yet, so it can’t tell a motor that doesn’t turn, but its motor driver says when it cuts out on overcurrent or overheating, one line for all four motors: it sends that asstall_stopwithmotordrv. Its IMU listens for the motors turning, and when they’re driven but not heard it switches all four off:stall_stopwithmotorimu(the firmware). The simulator acts both out when told to (below). The station won’t drive a bot whose battery is empty (“The station”, below).
The station
The station is the program that runs the fleet. It keeps track of every bot, and it’s the only thing that sends a bot
cmd. Anything that wants to drive (the driving tool, the driving page) asks the station, and the station drives.
That gives one place for the command numbering, power caps, and who is driving which bot.
| Topic | From → to | Kept | Delivery | Schema |
|---|---|---|---|---|
gunkslab/v0/<fleet>/station/status |
station → anyone (its presence says offline) |
yes | at least once | status |
gunkslab/v0/<fleet>/station/fleet |
station → anyone, when something changes | yes | at least once | station-fleet |
gunkslab/v0/<fleet>/station/drive/<client> |
a client → station | no | at most once | station-drive |
gunkslab/v0/<fleet>/station/notice |
station → clients | no | at least once | station-notice |
gunkslab/v0/<fleet>/station/desk |
the lab → station: the desk’s size | yes | at least once | station-desk |
gunkslab/v0/<fleet>/sites |
the lab → station and simulator: the other sites they run | yes | at least once | sites |
- A client is anything that asks the station to drive. It names itself in the topic it drives on
(
station/drive/drive-4821), with the same ID rules as a bot. On the cluster that name is the client’s login, and the transport lets it publish under no other, so one driver can’t speak as another. - One driver per bot. The first client to drive a bot holds it. Another client’s requests for that bot are refused
with a
noticeuntil the holder releases it, or goes quiet for 1 s. - The station’s dead-man. A client driving a bot sends
station/driveat least every 250 ms. If it goes quiet for 500 ms, the station sends the bot{"stop":true}itself, rather than waiting for the bot’s own timeout. - The station streams. While a bot is being driven, the station sends it
cmdevery 100 ms with its ownseq, capped at the station’s power limit. It times eachseq’s echo in telemetry, and reports it instation/fleet. - The e-stop doesn’t go through the station. Anyone can set their own
estop/<name>, and the bots obey it directly, so stopping never depends on the station running. During an e-stop the station refuses drive requests with anotice. - No battery, no driving. A bot whose telemetry says its battery is
empty, or that sendsbattery_empty(rule 10), is refused with abattery_emptynotice until its telemetry says otherwise. If it was being driven when the battery went, the station sends it a stop and stops streaming. A goto under way ends withbattery_empty. Astoporreleaseis still taken. A low battery is only a warning: the station drives on. - Go to a point.
{"goto":{"x":0.9,"y":0.2}}asks the station to drive a bot to a point on the field and stop there. It’s sent once. The station steers the bot from itsposeitself, so the client’s dead-man doesn’t apply. The client holds the bot while it travels. Astoporreleasefrom the holder, the holder driving by hand, or the e-stop cancels it. The station sends the holder anoticewhen it ends:arrived(within 3 cm),lost(no pose for 2 s on the way, or an estimate more than 30 cm off, below),timeout(not there after 30 s, not counting time the station held it to give way), orestop,offlineorbattery_emptyif those cut it short, orblockedif the bot’s reflex (rule 9) held it back for 3 s. Time the reflex spends on a bot the station knows is close doesn’t count. Getting round other bots is avoidance’s job, and the station turns the bot away from it. Nor does time spent going round something the bot’s sensor found (below), up to 9 s of being held. A goal inside such a thing, or one with no way round it, endsblockedonce the bot has looked round (below). It refuses withno_poseif it has no recent pose for the bot to start from, nor an estimate within 30 cm, and withedgeif the point is too near the desk’s edge for the bot to end at (below). While a goto is under way, the bot’s row instation/fleetcarries itsgoal. - Which poses it believes. A bot’s
poseonly once it has saidhello: a pose for a name the station doesn’t know adds nothing. And not one further from the last than a bot could have gone since (1 m/s, and 5 cm of jitter), nor one more than 10 cm off the desk when--deskgives its size. A refused jump is believed once enough time has passed for the bot to have made it (one picked up and put down elsewhere). While the station steers a bot by an estimate (below), it measures the jump from there, with as much more room as the estimate may be off, so a pose where a person said they put a bot down is believed at once. A bot that has only ever been placed, never seen, has its first pose refused if it’s further than that. Each change is logged once. - Where a bot is without a camera. The station also keeps its own estimate of where each bot is, by the bot’s
wheel counts and gyro (
odo_l_m,odo_r_mandheadingin its telemetry, rule 4): the distance from the two sides’ mean, the direction from the gyro, since a skid steer turns less than its wheels say. It starts from the last pose it believed, or from where a person says they put the bot down:{"place":{"x":0.4,"y":0.3,"theta":1.57}}, refused withno_odometryif the bot doesn’t send all three yet, and held to the one-driver rule but taking no hold. While the bot has no fresh pose, its row instation/fleetcarries theestimate, witherr_m, how far off it might be by now: 2 cm from a placing (and 5° of heading), 1 cm from a pose; then 3 % of the straight line from there, as a wheel that reads long reads long the whole way; 4 % of the turn since, for every metre driven at that turn, and 0.09° a second the same way; and 0.5 % of every metre driven, for what doesn’t add up like that. That’s a worst case, every error adding the same way. Over a gap of a quarter second or more between two messages (one lost) it counts the whole step, as it can’t tell the way the bot went. In the simulator, 300 runs of 2.2 m each, a Pirate Stage ended 6 cm off on average and 16 at most, against a radius of 24 to 28; a gl_zero 2 and 6, against 10 or 11. It was inside the radius the whole way, every run. A reboot loses it, and the log says so. - The bot’s own estimate. For a bot that sends
odo_x_mandodo_y_m, the station keeps a second one beside it, its row’sonboard: the bot’s own steps, worked out as often as it reads its gyro, turned into the desk’s frame from the same start. On a link that loses nothing the two come out the same, as the errors are the wheels’ and the gyro’s either way. Through lost telemetry the bot’s holds: in the simulator, with a second’s outage at 15 % of messages, the radius of a Pirate Stage’s own stayed 17 to 26 cm, the station’s grew to 81 to 220: honest, but too wide to steer by. Both run at once. - Steering without a camera. While a bot has a pose from the camera less than half a second old, the station steers
by that. Otherwise it steers by an estimate: by default the bot’s own if it sends one, else the station’s.
A person can choose which, per bot:
{"bot":"sim-1","steer_by":"estimate"}(or"onboard") onstation/drive/<client>. Nothing is sent to the bot. It’s refused withno_odometryif the bot doesn’t send its wheel counts, orno_reckoningforonboardif it doesn’t do its own; it takes no hold and doesn’t stop a goto. The row instation/fleetsays which insteer_by. On an estimate, every room the station keeps round the bot grows by itserr_m: from other bots, from the desk’s edge, and the size it’s planned round things by. What its sensor finds is kept as much bigger, and isn’t forgotten when a later reading misses it, as that reading can’t say where. An estimate more than 30 cm off is no use to steer by on a desk this size: a goto endslost, a new one is refused withno_pose, until a camera’s pose or a new placing. - Keeping out of the way. On a goto, the station keeps the bot clear of every other bot it has a pose for. A bot
that set off later gives way to one that set off earlier, and a bot being driven by hand always has the right of way.
Bots that are parked, or waiting, are passed on a path planned round all of them at once. Meanwhile the bot’s row in
station/fleetcarriesavoid:wait(held still to give way) ordetour(going round), and when going round,via, the waypoint it’s heading for first. Under that, a guard: no bot on a goto drives at another within 3 cm of touching. A wait that lasts 10 s turns into going round. A parked bot is its outline, a rectangle at its pose; any other bot, and anything a sensor found, is kept clear of by the circles round the bots’ corners. Driving by hand is not steered. A driver can still run into things. The station’s--desk WIDTHxDEPTHkeeps detours on the desk, and for a bot with a distance sensor, avoids detours it would arrive at facing an edge its reflex would stop it at. - A goal near the desk’s edge. With
--desk, the station judges how a goto can come in to its goal. A bot facing an edge is stopped by its own reflex with its middle about 21 cm from it, less the 3 cm short of a goal a goto stops. Driving straight in from where it is, it must arrive with the desk going on that far past the goal, and 1 cm more. If it can’t, the station first sends it to a point it lines up at: at least 19 cm in from every edge, where its sensor stays on the desk whichever way it faces, and 20 to 60 cm back from the goal. From there it drives in at a slant or along the edge, arriving with its sensor 2 cm onto the desk. It picks the point that makes the shortest trip, with neither the point nor the run in from it near a bot that’s stopped, where another goto will stop, or something a sensor found; and picks again if one of those comes into the way. Meanwhile the bot’s row instation/fleetcarriesapproach, that point. If every way in is taken, it waits (avoidiswait), and after 10 s endsblocked. Going round something on the way, it judges again from where it comes out. A point with no way in ends at once with anedgenotice, before the bot moves: nearer an edge than the circle round the bot’s corners (about 9 cm for a gl_zero), or deep in a corner, where no slant keeps its sensor on the desk. A goto that can’t come in any more for the same reason endsedge. Each bot’s row carriesedge, the numbers that decide where a goto can end, so a page can shade where it can’t. A bot without a distance sensor is only kept the circle round its corners from the edge. Without--desk, the station judges none of this. - A desk that changes.
station/desk(station-desk, kept), such as{"w": 3, "d": 2}, gives the desk’s size in place of--desk. The station takes it only once no bot is on a goto or being driven, so a desk never changes under a moving bot: one heard while something moves waits until nothing does. Cleared, it goes back to--desk.station/fleetcarriesdesk, the size it plans on now, so whoever sent one can see it taken. - Several sites. A lab running robots in more than one place gives each place its own fleet ID, a site, and one
station runs them all. Started with
--sites, the station readssites(sites, kept) on its own fleet, such as{"sites": [{"id": "house", "desk": {"w": 5, "d": 4}}]}, and runs each site listed as a fleet of its own: everything above, ongunkslab/v0/house/, with that desk in place of--desk. They share the station’s one connection (a transport that names connections by login, as the cluster’s broker does, takes one per login), so only the station’s own fleet has a presence: a site’s station is down whenever the station’s own fleet’sstation/statusisoffline, whatever the site’s says. A clean stop saysofflineon every site. Sites come and go as the list changes, 8 at most. Each site may say itstransport,linkandcamera, chosen when the site is made.camerais whether the site has a position service saying its bots’ poses: left out,true. The transport and link left out aremqttandconnected(always reachable while it runs), the only ones a station or simulator runs today. Sharing the station’s connection, a site can only be on the transport the station is on; one listed on any other, or on another link, is skipped and the rest of the list runs. One taken off has its driven bots stopped and itsstation/statusandstation/fleetcleared. A new desk for a running site is taken as a clearedstation/deskwould be: never under a moving bot, and not while astation/deskis in effect. Its own fleet, or a site listed twice, is skipped too. - What bots’ sensors find. The station can’t see a box on the desk, but a bot’s front distance sensor can. A
region of the sensor reading nearer than the desk it should see has found something. The reading is the nearest
thing anywhere in that region’s view, so the station remembers 4 cm discs right across the view at that distance,
except where another region looked, could have seen something that tall, and saw further. It doesn’t for a reading
that may be a bot it knows of, or one more than 60 cm out (a small turn moves those a lot). Each disc keeps how tall
the thing must at least be, since it reached up into the region’s view. A reading counts where the bot was facing
when it was taken (by
ranges_age_ms, give or take 50 ms for the network): turning on the spot, a sixth of a second is 10°. Withoutranges_age_ms, it counts at every heading the bot may have had since. Go-tos go round the discs like parked bots, with 3 cm more room. Beside one, a bot about to turn on the spot backs straight off first, if what the station knows of behind it leaves room: turning sweeps its corners round. Looking round: finding no way to the goal, the station first turns the bot about 40° each way and back, holding still half a second at each heading, so its regions see past what they saw, and plans again. Still no way, it endsblocked. It looks once for every 10 cm the bot moves. A disc is forgotten when a region that could have seen something that tall there reads at least 3 cm past it (a reading short of the desk rules out only what’s nearer than it), when a bot drives through it, or after 5 minutes. 60 at most, the oldest going first. The limit: a region’s view is 15° wide, so what’s remembered runs past a box’s ends until a turn shows otherwise. And from 33 mm up, the level regions meet the desk 25 cm out, so they can only rule out something low nearer than that. A gap beside a wall can endblockeduntil the bot gets closer. station/fleetis a summary of every bot the station knows: type, online or offline, whether its reports have gone quiet, who’s driving it, and the echo time. While a bot looks round, itsavoidislook. It also carriesseen, the discs above, when there are any. With--desk, each bot’s row carriesedge, and while it lines up for a goal,approach(above). It’s kept, so a page that opens late has the whole picture at once.
The simulator’s desk
The simulator’s bots aren’t perfect, unless it’s started with --ideal. Each bot draws its own errors at boot, up
to its type’s, so what it reports of itself comes apart from where it really is, as a real one’s would. Its wheels
on each side are a little bigger or smaller than the firmware takes them to be (within 1 %), so the same power on both
sides curves and the wheel counts are off. The ground goes by a little less than the wheels turn (1 %, and more on a
ramp or a bump). As a skid steer, it turns 30 % less than its wheels’ difference says. Its gyro reads within 3 % of
the real turn, with an offset left over from the still second (up to 0.05°/s) that wanders as the board warms, and a
little noise on each reading. The gyro numbers are the MPU-6050’s as best recalled, not re-checked; the rest are
guesses until a car drives. They’re in sim/gunksim/types.py, one place for each robot type.
Started with --no-camera, the simulator says no poses for its own desk, as a site without an overhead camera; a
site’s camera is the sites list’s to say (above). Its bots’ telemetry goes out as before. Its bots are on the map
once a person places them, and the station steers them by their estimates (above).
The simulator publishes the boxes on its desk on gunkslab/v0/<fleet>/sim/boxes, kept, as sim-boxes, so a
page can draw them. It’s the simulator’s, not part of what bots and the station speak. Nothing has to read it, and
the station doesn’t. A real desk has no such topic.
On a desk with no camera it publishes where each bot really is on gunkslab/v0/<fleet>/sim/truth, not kept, ten
times a second, as sim-truth: {"t_ms":..., "bots":[{"id":"sim-1","x":0.42,"y":0.31,"theta":1.57}]}. It’s for a
page to draw beside the station’s estimate, so a person can see how far the estimate has drifted. Like sim/boxes
it’s the simulator’s: the station never reads it, so it can’t steer by it, and a real desk has no such topic.
It also listens on gunkslab/v0/<fleet>/sim/<bot>/fault (sim-fault), so a simulated bot can act out what a real
one’s hardware stops (rule 10): {"battery": "low"}, "empty" or "ok" (charged again), or {"stall": "L"} (or
"R") to stall a motor while its side is driven. scripts/sim fault sends them. A real bot has no such topic.
Started with --manage, the simulator runs the bots listed on gunkslab/v0/<fleet>/sim/robots (sim-robots,
kept), such as {"robots": [{"id": "sim-1"}, {"id": "sim-2", "type": "pirate-stage"}]}, and adds and removes bots
while it runs as the list changes. A bot added goes where the desk is clearest. A bot removed clears its kept
hello and status, so the station forgets it. A type left out is the simulator’s --type, and an ID it has no
certificate for is skipped. Until a list comes (5 seconds), it runs --bots of its own.
With --manage it also follows the lab’s map on gunkslab/v0/<fleet>/sim/map (sim-map, kept), such as
{"desk": {"w": 3, "d": 2}, "boxes": [{"id": "wall", "x": 1.5, "y": 1, "w": 0.1, "d": 0.6, "h": 0.1}]}: the desk’s
size and the boxes on it, in place of its --desk and --box. Every bot has the new desk at once, and the boxes go
out again on sim/boxes. Cleared, it goes back to its own. The lab sends station/desk with it, and changes it only
when nothing is moving.
With --sites as well, the simulator follows the same sites list as the station and runs a desk for each site:
its own size, its own bots from that site’s sim/robots, its own map from that site’s sim/map, and its own
sim/boxes. A site’s desk starts with no bots until its list comes. A bot ID runs on one site at a time: one listed
on two runs where it already was, and moves once it’s taken off there. A site taken off the list has its bots
removed, as above, and its sim/boxes cleared.
A box can be a zone instead, a flat patch of the desk with a kind and no height: boost (a bot goes 1.5 times as
fast over it), slow (half), bump (0.3, and its heading gets a small knock as it rolls on) or ramp (0.6 going
up, 1.4 coming down, the same across), a ramp with its way up in radians, as a pose’s theta:
{"id": "hill", "x": 2.4, "y": 1.4, "w": 0.3, "d": 0.6, "kind": "ramp", "up": 1.5708}. Where zones overlap, each one
counts. A zone works from where a bot’s middle is. Its sensors don’t see zones, and the station doesn’t know them: a
bot’s power and its pose come apart over one, as they would on a real floor that isn’t all the same. They’re for
games and for testing what a driver does about that.
Units and frames
- Distance in metres, angles in radians, time in milliseconds. That’s the convention research tools (ROS among them) expect.
- The field frame is set by the position service: x and y on the desk, z up. Heading (
theta) is anticlockwise from +x, from -π to π. - Wheel commands (
l,r) are power, -1 to 1, not speed. gl_zero’s firmware doesn’t use its encoders, so the same number gives different speeds on different bots and on a flat or a full battery. v0 has no speed commands in metres a second. They need encoders. - A bot’s own
headingis anticlockwise too, -π to π, but from where the bot pointed when it was first still after booting, not from the field’s +x. - A bot’s own odometer (
odo_l_m,odo_r_m) starts at 0 at boot and counts back down when a side drives backwards. A bot leaves it out until it knows its encoders’ counts a wheel turn. Its own dead reckoning (odo_x_m,odo_y_m) is in metres in the frame of itsheading, from where that started. - Bot time is
up_ms, milliseconds since boot. The station stamps what it receives. v0 has no clock sync between bots.