Deployment Process (new robot → ready to use)¶

This is the binding process for putting URG software on a uMe and keeping it up to date. It is the single source of truth; if any other page contradicts it, this page wins.


Target	Perception Board of the robot (user `booster`)
Service	`ume-gateway.service` (user-level systemd, autostart)
Port	`8765` (WebSocket, LAN only)
Files	`gateway_v2.py` + `install.sh`
Repo	`robotics-group-app` → `gateway/`

Which board — and why

The robot has two on-board computers. Everything of ours is installed on the Perception Board (Jetson AGX Orin): the camera and the conversational agent are physically attached there, and the motion commands reach the Motion Board from there over DDS anyway. So there is one place to deploy and one IP for the app. Nothing of ours runs on the Motion Board.

App ──► Perception Board IP ──► Gateway + SDK ──(DDS)──► Motion Board ──► motors

Board	User	Office IP	Internal IP	Runs
Perception (Jetson AGX Orin)	`booster`	`192.168.1.131`	`192.168.10.102`	Gateway, SDK, camera, chat agent
Motion	`master`	`192.168.1.195`	`192.168.10.101`	Motion control (nothing of ours)

The app always connects to the Perception Board address.

A. Commissioning a new robot (once per robot)¶

Plan about 30 minutes. You need: the robot, a PC on the same network, the tablet, and the two files gateway_v2.py + install.sh from the robotics-group-app repository (folder gateway/).

Part 1 — Prepare¶

Power up the robot and connect it to the network (cable to the router is the most reliable). Make sure the RealSense camera is plugged in.
Find the Perception Board IP. Ask IT/the router, or check the robot's network settings. Write it down — you will need it three more times.
Test the connection from the PC:
```
ssh booster@<ROBOT-IP> "python3 --version && echo OK"
```
Expected: a Python 3.10+ version and OK. Confirm the host key with yes the first time. If this fails, nothing else will work — fix it first.

Part 2 — Install the Gateway on the robot¶

Copy the two files from the PC:

scp gateway_v2.py install.sh booster@<ROBOT-IP>:~/

Run the installer — in a normal login shell, not a stripped-down one:
```
ssh booster@<ROBOT-IP>
bash ~/install.sh
```
Check the output. The installer prints the service status at the end. It must read active (running). If not, see Troubleshooting.

Why the login shell matters

install.sh copies the DDS/ROS environment variables of the current shell into the service. In a stripped-down shell the service starts but the motors will not respond.

From now on the Gateway starts automatically every time the robot boots — no manual start, ever.

Part 3 — Install the app on the tablet¶

Get the APK. Either the current build from the team, or build it yourself from the robotics-group-app repository:
```
flutter pub get
flutter gen-l10n
flutter build apk --release
```
The file lands in build/app/outputs/flutter-apk/.
Transfer it to the tablet (USB cable, OneDrive, or any share — note that some chat tools block .apk attachments).
Install it: tap the file on the tablet. On first install Android asks to allow "install from unknown sources" for that app — confirm once.
Connect the tablet to the same network as the robot.

iOS

On iPhone/iPad the app is distributed via TestFlight instead — App Store and Google Play follow later (see Roadmap).

Part 4 — Verify (do this every time)¶

Open the app → Connect to Robot → Connect via IP → enter the Perception Board IP → Connect.
Check, in this order:
- Live camera image appears
- Battery and mode are shown
- PREP (slide to confirm) → robot stands up
- WALK → both joysticks move the robot
- One gesture (e.g. wave)
- Stop → robot damps immediately
Reboot the robot once and connect again — this proves the autostart works.

Safety

Steps 12–13 move a full-size humanoid. Clear 2 m of space, keep the physical stop in reach, and have a second person present. See Safety.

Part 5 — Record it¶

Add the robot to the fleet list (fleet/robots.md in the ume-sdk repository): serial/name, both board IPs, Gateway version, runtime version, date, who commissioned it. Commit the change.
Change the default password on the board (passwd) and, ideally, install an SSH key.

Handover to the operator¶

The operator only ever needs: robot on → app open → connect. No SSH, no scripts, no manual start. Point them at Daily Operation.

B. Everyday operation¶

Robot on → app open → connect. The Gateway starts automatically on boot; no manual start is needed. Logs: journalctl --user -u ume-gateway -f.

C. Shipping a new Gateway version¶

Change and test gateway_v2.py locally (mock: python3 gateway_v2.py --mock).
Test on one robot first, with a responsible person present.
Roll out to the remaining robots: copy the file, run bash ~/install.sh again (or systemctl --user restart ume-gateway.service).
Record the new version in the fleet list and in the Changelog.

D. Versioning¶

Item	Scheme	Where
Gateway	`vMAJOR.MINOR` in the file header + startup log line	`gateway_v2.py`
App	`x.y.z+build`	`pubspec.yaml`
SDK / docs	`x.y.z`	Changelog
Per robot	gateway version + install date	fleet list

Rule: the app and the Gateway are released as a pair. Any change to the message contract (new command, changed field) increases the MINOR version on both sides, and both are tested together before rollout.

E. Handling platform (vendor) updates¶

The robot's underlying platform runtime is supplied by the hardware vendor and can receive updates. URG software is deliberately insulated from that:

Only one file touches the runtime. In the Gateway it is the single backend class; in the Python SDK it is ume_sdk/_backend.py. Nothing else — not the app, not the WebSocket contract, not external clients, not this documentation — depends on the vendor package.
We pin, we do not float. A robot keeps the runtime version it was commissioned with. Vendor updates are never applied automatically.

Process when a vendor update arrives:

Assess — read the release notes for changes to the interfaces we use (mode switching, locomotion, actions, battery, camera topics).
Test on one robot — apply the update on a single test robot, run the full checklist below.
Adapt if needed — if a signature changed, update only the backend class / _backend.py. The API contract towards the app stays identical.
Release as a pair — new Gateway version + tested runtime version become one "robot software set" with a version number.
Roll out to the fleet (section C) and record it in the fleet list.
Never update a customer robot without running steps 1–3 first.

Post-update checklist: connect from the app · live camera image · mode change DAMP → PREP → WALK · both joysticks · one gesture and one whole-body dance · emergency stop · battery value plausible · persona save · autostart survives a reboot.

F. Roles¶

Who	Does
URG development	Gateway/app changes, vendor-update assessment, release
Commissioning	Steps A1–A4 on each new robot
Operator (customer, education)	Uses the app only — no SSH, no scripts