Going live

Before your robots work in a building, its owner runs a go-live with your company: your robots use their route under the owner's rules, the building's own record counts how they do, and the owner accepts them. This page says what to build first, what's recommended and what's optional, what a building's go-live checks, and where the test kit's conformance check fits.

What to build

The robot API covers twelve essentials for robots in buildings. Build the first column before any site visit. The second is what buildings ask for and what their go-live record shows. The third you may use where a building offers it.

Essential	Must build	Should build	May build
1. Identity	Sign every call with each robot's own secret; keep clocks on NTP; verify the gateway's certificate by pin or by the site's CA. Where the building asks, a certificate of insurance on file (your people, no code)	Keep secrets out of logs and command lines, and plan for replacing one	A read-only key for dashboards
2. Capability		The profile: size, weight and payload, and the capability sheet, sent whole each time	The data-center fields
3. Purpose		`payload_class` and `deadline` on trips; `purpose` and `to_area` at doors where a person approves robots	`ref`, your own delivery number
4. Permission	Act on `reason_code`, `retry` and `retry_after`; treat an unknown code as a refusal; no answer within your timeout means no. As a visitor company, a pass before each trip	Read `GET /v1/places` at the start of each shift
5. Passage	A new `passage_id` per trip, resent unchanged when unsure; follow each passage to its end; report `passed`, `boarded` and `exited`; cancel calls your robot no longer needs; pick up after a restart	Check in every second or two in a car or a doorway; `wait_in_line` at busy elevators	`ride_alone`
6. Awareness	Follow the notices (on the stream, or by polling); keep clear of doors and elevators under a `fire alarm`	Plan around closures, keep-out zones and no-robot windows	Booking ahead
7. Location and health		A position every 1 to 5 seconds while moving; a heartbeat with battery, state and software version	Positions in your own map
8. Help		Ask for help when stuck (`POST /v1/help`); report `assisted` when a person helped
9. Life safety	Stop when held; keep to every notice's `never` list	Confirm each `emergency` notice and go where it sends your robot; `"emergency": true` in the profile
10. Charging and home			Charger slots
11. Record and conformance	Pass the conformance check on the sandbox and in the building; rerun it after each software change	Run its drills with `--robot-answers`
12. Wayfinding			Directions, trip packages and ROS 2 files

At a data center, add its own musts: work_order on hall and cage passages, a tenant's permit for each cage, and no robot at the people's mantrap. See Data centers.

The guide explains each of these. The gateway works with robots that haven't built the second and third columns: a robot that doesn't confirm emergencies is still told, and held at every door and elevator, and the owner's screen says it doesn't confirm.

How a building brings your robots live

The building is connected, once. Its doors, elevators and badge system are connected to the gateway, with the owner's authorizations (the developer designation with the elevator maker, the elevator alterations, IT and security approval, and site access). Four life-safety rules are witnessed on site, usually by the elevator partner: fire service recall ends every robot call, and nothing a robot does can delay it; fire and egress doors keep their code function; a lost connection or power returns the equipment to normal, with no held doors or stuck calls; and there's no network link to an elevator controller, only the maker's cloud API or a relay. The first robot company waits on this; later ones don't.
Your go-live starts. The owner chooses the rule, or route, your robots will use (its doors, elevators, hours and days) and agrees targets with your company for three measures.
Your robots work the route. The building's own record counts the measures, and the tests it can see, from your robots' trips on that route since your go-live started. The site's people witness the tests on site and sign each one off.
Your company and the owner sign the in-passage agreement.
The owner accepts. Accepting switches your route on. The owner confirms go-live, not Plynth.

Your company's page shows your go-live as it goes: its measures, and each test, witnessed or seen in the record.

The measures

Measure	What counts
Unassisted Trips	Trips on your route that your robot's own report completed (`PASSED` or `RELEASED`) with no one's help. A command acknowledgement never counts as a trip
Full Days Counted	Days since your go-live started. The clock pauses only for documented delays by the owner, the elevator maker or an authority
Interventions per 100 Trips	Trips someone helped through (your robot reported `assisted`, or the building's people recorded it), plus trips that fell back: ended `FAILED` for anything but the owner's own rules and limits. Per 100 trips

To accept, the owner wants every measure at its target and the in-passage agreement signed. The owner may accept anyway, and the test report then says what wasn't met. Once accepted, the measures as they stood are kept in the report.

The tests

Fourteen tests, in five groups. "In the record" means the building's record can show the test from your robots' own trips; the others are shown by a witness on site. Either way, the site's people sign each one off with the witness's name, and the witnessed tests are in the report for the owner to weigh.

Test	What it shows	In the record	Your robot's part
Through a Door, Unassisted	The robot reports it got through	Yes	Ask, go through, report `passed`
An Elevator Ride, Unassisted	Called, boarded, rode and got out, on the robot's own reports	Yes	Report `boarded` and `exited`
Badge Revoked	The badge system refuses a revoked robot at a secured door	Yes	Take the refusal (`badge_inactive`) and fall back
Elevator Timeout	The car doesn't come, or the robot doesn't board in time	Yes	Once its passage has `FAILED` (`timeout`), don't board: fall back
Connection Lost	A door or elevator stops answering	Yes	Take `FAILED` (`device_refused`) and fall back
Fire Service Recall	Run in the elevator partner's test mode	Yes	Stay out of the car (`fire_recall`)
Access Revoked, in a doorway	While the robot is in the doorway	No	Finish clearing the doorway; its next requests are refused
Fire Alarm, in a doorway	While the robot is in the doorway	No	Clear the doorway and hold; never hold the door
Connection Lost, in a doorway	While the robot is in the doorway	No	Clear the doorway; the door works on its own
Access Revoked, in a car	While the robot is inside the car	No	Ride on, get out and report `exited`
Fire Service Recall, in a car	While the robot is inside the car	Yes	Get out when the doors open, and report `exited`
Connection Lost, in a car	While the robot is inside the car	Yes	Get out when it can, and report `exited`, late if need be
Told Where to Go, and Confirmed	In an emergency, the robot answered within its deadline	Yes	Confirm `going` or `holding` by `confirm_by`
At Its Holding Zone	Sent to a holding zone in its own smoke compartment, it said it arrived	Yes	Go to `target`, then confirm `arrived`

The two emergency tests come from emergencies and fire drills in the building, with your robots there. A building runs its own drills: ask the site to run one with your robot on site.

The in-passage agreement

Before the owner accepts, your company and the owner agree in writing what happens with your robot in a doorway or a car when its access is revoked, the fire alarm sounds, or a connection is lost. The tests above "in a doorway" and "in a car" are the same situations, shown on site.

The conformance check

The test kit's conformance check runs as your robot, against the sandbox or a building's gateway, and checks what your software must handle before any site visit:

HTTPS, with the gateway's certificate verified (plain HTTP passes only on loopback);
health, a bad signature refused and an old timestamp refused as a replay;
a door passage, and an exact retry repeating the answer while other contents get 409;
a full elevator ride followed on the stream, with its car, a check-in aboard, and exited;
cancel before boarding, and cancelling again;
reason codes on every refusal, the notices, and the places listing the door and elevator;
the stream, and picking up after a reconnect: who it is, the steps missed, its passages;
on the sandbox only: a fire alarm drill, a go-to-zone drill, a pre-discharge drill, an emergency power off drill, a doorway dwell, and a help request.

It prints PASS, SKIP or FAIL for each, writes a JSON report with the evidence when you add --report, and exits non-zero on any failure. On the sandbox it uses the sandbox's door door and elevator lift, riding from 1 to 2, unless you name others:

python3 -m plynth.conformance --env ../plynth-sandbox.env --report conformance.json

Get the kit, and your robot's plynth-sandbox.env, from the sandbox.

In a building

In a building, name the door, the elevator and the ride, and verify the gateway. The address, robot ID and secret come from GATEWAY_URL, GATEWAY_ROBOT_ID and GATEWAY_ROBOT_SECRET:

python3 -m plynth.conformance --door <door ID> --elevator <elevator ID> --from 1 --to 2 \
  --pin sha256:<the building's fingerprint> --report conformance.json

Use --cafile site-ca.pem instead of --pin where the site has its own certificate authority (or set GATEWAY_TLS_PIN). --secret still works, but a flag shows in ps and your shell history, so keep the secret in GATEWAY_ROBOT_SECRET.

In a building, the check really opens the door and calls the car, and it reports boarded and exited for your robot. Run it with your robot at the door and at the elevator lobby, and someone from the site watching. Its trips go into the building's record like any others, marked as a test: the kit sends X-Test-Run: conformance on each call. Your own software can mark its test runs the same way (Marking a test). The building runs its own drills, and a request for help there calls a person, so those checks show SKIP there, not FAIL.

The report

{"gateway": "https://sandbox.plynth.build", "robot": "<robot ID>", "time": "2026-10-21T09:12:03-04:00", "kit": "0.2.2",
 "gateway_release": "<the gateway's release>", "api": "1", "door": "door", "elevator": "lift", "ride": ["1", "2"],
 "passed": true,
 "checks": [{"check": "health", "passed": true, "evidence": {"ok": true}}]}

Each check has its name, whether it passed, and its evidence; a skipped check says why. The report records the kit's version, the gateway's release and the API version. Send it to the building: it's the robot side of the go-live record.

The report is written on your own computer and isn't signed, so it's your evidence, not the building's. What the owner's go-live counts is the building's own record of your robots' trips, and the tests its people witness. Before you go to a building, the sandbox can grade your own software and give it a signed certificate: Getting certified.

Your own software answers the drills

By default, the kit answers each drill for your robot, to show you the flow. That shows the gateway works, not your robot: the report says "answered_by": "the kit".

Add --robot-answers with your own software running as the same robot. The kit then starts each drill and waits for your software to confirm within the notice's deadline, and, when it's sent to a zone, to say it arrived within a further minute. The report then says "answered_by": "the robot's own software". That's the result a building wants.

While it runs, the kit holds one stream for the robot, and a robot may hold two, so keep your software to one. The kit places the robot itself for each drill (in the middle of the ride's --from floor, floor 1 by default, or inside the server room on floor 2), so keep your software from sending other positions meanwhile.

With a visitor key

A visitor key rides and uses the doors only, so the drills, the doorway dwell and the help request show SKIP, saying why. The rest runs as usual. Use your company's own keys for the full check.

After go-live

A software change. Send your robot's version in its heartbeat (software). When it changes, the owner is asked to rerun its conformance test, and the re-test is due until the building records it. An update can't quietly change how your robot behaves at a door.
A new secret. On your company's page, Rotate keeps the old secret working for 24 hours while you install the new one, and Revoke Old stops it at once. When the building replaces a secret, the old one stops at once.
Insurance. You're told 30 days before your certificate ends, on your company's page. Without a valid one where the building asks, every request is refused insurance_expired.
A new gateway certificate. The building sends you the new fingerprint before it switches: pin both until then (verifying the gateway).