Skip to content
gunkslab

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.

  1. Topics in levels, read by pattern. A topic is levels split by /. A reader can ask for one level of anything (+, as in estop/+) or everything below a level (#).
  2. 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).
  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.
  4. 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.
  5. 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.
  6. 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.
  7. 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
  • v0 is 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 use desk.
  • <bot> is the bot’s own ID. Real bots name themselves from their MAC address, bot-a4cf12 (the firmware does this today). Simulated bots are sim-1, sim-2 and 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, estop and sim can’t be bot IDs. They’re topics of their own under the fleet.

Rules

  1. 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 own sync. Once those are in place it sends a new marker to sync, and only when the marker comes back does it read its own cmd topic: every e-stop in force reached it first. It obeys no cmd before then, and none at all if it may not read the e-stops.
  2. Dead-man. A bot stops 500 ms after the last cmd. A station that’s driving sends cmd at least every 250 ms, repeating the same values if nothing has changed. Today’s firmware already does this.
  3. 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 ignores cmd. It drives again only once every one is off ({"stop":false}, or the kept message taken away with an empty one) and a fresh cmd comes. 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": true in its hello; one that doesn’t refuses the whole message, so it wouldn’t stop. A sender names bots only when every bot it names said estop_bots, and otherwise sends a stop for every bot.
  4. Bots don’t know where they are. Position comes from the position service: the overhead camera, or the simulator. It publishes pose on the bot’s behalf. A bot that can measure itself still reports that through telemetry, not pose. A bot with imu in its hello sends heading: 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 sends odo_l_m and odo_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 send odo_x_m and odo_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 publishes pose: 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’s station/fleet with how far off each may be, and never become a pose.
  5. Numbered commands. The station may put an increasing seq on each cmd, and the bot reports the last one it obeyed as seq in 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 a seq lower than the last one it obeyed. Once it has stopped for a timeout, it accepts any seq again, 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.
  6. Events say why. Telemetry repeats the state. An event is sent once, when something happens:
    • boot, with the reason the bot last restarted (a brownout, a crash, power-on).
    • timeout_stop.
    • estop_on and estop_off.
    • wifi_reconnect and mqtt_reconnect.
    • obstacle_stop and edge_stop (rule 9).
    • stall_stop, battery_low and battery_empty (rule 10).
  7. 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.
  8. 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.
  9. The reflex. A bot with a front distance sensor (tof in its hello’s sensors) 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 sends obstacle_stop or edge_stop when the reflex first holds back a forward drive, with the reading that did it, and while it’s holding, its telemetry carries reflex. Telemetry carries the bottom region’s reading (or the only one’s) as range_m, null for nothing back, and with several regions, each one’s last reading as ranges: bottom, middle and top straight ahead (aimed down, level and up), left and right level to each side. ranges_age_ms says 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 telemetry reflex_rear and range_rear_m. A sensor that stops answering counts as the desk ending.
  10. 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 which motor. 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 as batt_v when the bot measures it, and its telemetry carries the battery’s state as battery (ok, low, empty) for as long as it lasts. Its l and r are 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 as stall_stop with motor drv. Its IMU listens for the motors turning, and when they’re driven but not heard it switches all four off: stall_stop with motor imu (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 notice until the holder releases it, or goes quiet for 1 s.
  • The station’s dead-man. A client driving a bot sends station/drive at 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 cmd every 100 ms with its own seq, capped at the station’s power limit. It times each seq’s echo in telemetry, and reports it in station/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 a notice.
  • No battery, no driving. A bot whose telemetry says its battery is empty, or that sends battery_empty (rule 10), is refused with a battery_empty notice 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 with battery_empty. A stop or release is 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 its pose itself, so the client’s dead-man doesn’t apply. The client holds the bot while it travels. A stop or release from the holder, the holder driving by hand, or the e-stop cancels it. The station sends the holder a notice when 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), or estop, offline or battery_empty if those cut it short, or blocked if 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, ends blocked once the bot has looked round (below). It refuses with no_pose if it has no recent pose for the bot to start from, nor an estimate within 30 cm, and with edge if 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 in station/fleet carries its goal.
  • Which poses it believes. A bot’s pose only once it has said hello: 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 --desk gives 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_m and heading in 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 with no_odometry if 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 in station/fleet carries the estimate, with err_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_m and odo_y_m, the station keeps a second one beside it, its row’s onboard: 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") on station/drive/<client>. Nothing is sent to the bot. It’s refused with no_odometry if the bot doesn’t send its wheel counts, or no_reckoning for onboard if it doesn’t do its own; it takes no hold and doesn’t stop a goto. The row in station/fleet says which in steer_by. On an estimate, every room the station keeps round the bot grows by its err_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 ends lost, a new one is refused with no_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/fleet carries avoid: wait (held still to give way) or detour (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 WIDTHxDEPTH keeps 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 in station/fleet carries approach, that point. If every way in is taken, it waits (avoid is wait), and after 10 s ends blocked. Going round something on the way, it judges again from where it comes out. A point with no way in ends at once with an edge notice, 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 ends edge. Each bot’s row carries edge, 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/fleet carries desk, 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 reads sites (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, on gunkslab/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’s station/status is offline, whatever the site’s says. A clean stop says offline on every site. Sites come and go as the list changes, 8 at most. Each site may say its transport, link and camera, chosen when the site is made. camera is whether the site has a position service saying its bots’ poses: left out, true. The transport and link left out are mqtt and connected (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 its station/status and station/fleet cleared. A new desk for a running site is taken as a cleared station/desk would be: never under a moving bot, and not while a station/desk is 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°. Without ranges_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 ends blocked. 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 end blocked until the bot gets closer.
  • station/fleet is 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, its avoid is look. It also carries seen, the discs above, when there are any. With --desk, each bot’s row carries edge, 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 heading is 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 its heading, 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.