[Builders & Makers] Example Runtime for Educational GoPiGo3 Robot

[slowrunner]

Which are you?

Evaluating, not building yet

Substrate or product

GoPiGo3 Educational Robot with Raspberry Pi 4 (Basic and ROS2)

What do you want to discuss?

Your offer for an example runtime for the basic GoPiGo3 robot is very welcome. I usually start with someone else's code and adapt for the GoPiGo3 - Basic OpenCV object recognition tutorial, TurtleBot3_Cartographer, TurtleBot4 Nav2_Bringup, etc. but getting a specific headstart is great.

[slowrunner]

Front End Success - Looks like I need a runtime:

Test 1:

(.venv) ubuntu@u26llpi5:~/U26LLPi5/systests/urml/gopigo3$ more gopigo3_t1_remote.sh 
#!/bin/bash

# optional:      --envelope envelope.yaml \

urml translate "Announce 'Driving forward 1 meter' and then execute the action" \
    --manifest gopigo3.manifest.yaml \
    --profile educational \
    --no-policy \
    --provider openai \
    --model "qwen3.5:4b" \
    --out remote.qwen3.5_4b.gopigo3_t1.program.urml.yaml

(.venv) ubuntu@u26llpi5:~/U26LLPi5/systests/urml/gopigo3$ ./gopigo3_t1_remote.sh 
wrote remote.qwen3.5_4b.gopigo3_t1.program.urml.yaml
Translation accepted after 0 revision(s); profile(s)=educational

(.venv) ubuntu@u26llpi5:~/U26LLPi5/systests/urml/gopigo3$ more remote.qwen3.5_4b.gopigo3_t1.program.urml.yaml 
profile:
- educational
behavior:
  type: sequence
  on_error: abort_and_report
  steps:
  - speak:
      utterance: Driving forward one meter
      style: conversational
  - drive:
      distance: 1.0

[slowrunner]

Yes, please provide an example (native platform, non-ROS) GoPiGo3-URML-Runtime

[idoco2003]

Done, and thank you for the nudge.
There is now a native, non-ROS GoPiGo3 example runtime in the repo: examples/gopigo3/ (landing in PR #532).

It has three pieces:
a basic GoPiGo3 manifest (differential, relative-motion, a distance sensor, an espeak output),
a GoPiGo3Adapter that drives the wheels through easygopigo3 (drive_cm, turn_degrees, orbit) and speaks through espeak,
and a runner that validates a program and then executes it through the adapter.

The headline case is the exact command you translated: announce "Driving forward 1 meter", then drive 1 m.
It validates, then calls easygopigo3.drive_cm(100.0) on the wheels.
A short patrol (turn, drive, turn, drive, announce, report) is in there too.

It runs here against a fake easygopigo3 so CI stays hermetic, and unchanged on your Pi once you pip install gopigo3 easygopigo3 and delete the fake block.
drive and turn map to your encoders; "announce" maps to speak, which the Pi backs with espeak.
A basic GoPiGo3 has no arm or camera, so grasp / detect / capture come back as not-supported rather than faked; you extend the adapter to add them.

If you send your gopigo3.manifest.yaml I will tune the example to match your exact distances and speeds.

Thanks,
Ido

[slowrunner]

GoPiGo3 Runtime Example Scratch Pad

(Collecting thoughts - submitted as an issue

• gopigo3_adapter.py: if even desired to discuss installation of real gopigo3 api outside of the README, (all install statements should link Installation_FAQ - (code and comments have invalid installation instructions)
• run_gopigo3.py: same -explaining install of real GoPiGo3 API is not responsibility of URML project. Link to DexterInd/GoPiGo3/InstallationFAQ.
• README, code and report instruct for real robot, “delete fake”. Is it possible to attempt import easygogopi3 in a try block, and instantiate the fake on the import exception- so no user induced code errors and the non-user created code can be read and execute permissioned?
• Sorry, the run_gopigo3.py render_report() installs the fake_easygopigo3 and I don't know how to use the real easygopigo3 here.

[slowrunner]

Thank you for supporting the GoPiGo3 educational robot platform.

For over 10 years the GoPiGo3 has maintained relevance in a very competitive market, which is important to me as a user. Having the GoPiGo3 as one possible platform to learn about URML and exercise these concepts is exciting.

[idoco2003]

That means a lot, thank you.
Ten years of staying relevant in this market is exactly why the GoPiGo3 is a good platform to learn URML on: simple enough to understand end to end, and real enough that validate-before-actuate actually matters.

One update: the example is merged and live now (examples/gopigo3/), not just landing.
The offer still stands. Send your gopigo3.manifest.yaml whenever you like and I will tune the example to your exact distances, speeds, and sensor.

Enjoy exercising it.

Thanks,
Ido

[slowrunner]

FYI: "URML.dev in the news"

I published small mentions of urml.dev and URML for the GopiGo3

on the GoPiGo3 forum

and on Fosstodon (Mastodon federated)

[idoco2003]

Thank you for spreading the word on both the GoPiGo3 forum and Fosstodon. Word-of-mouth from someone who has actually run it is the signal that matters most at this stage.
If anyone coming from those posts has questions, examples/gopigo3/ plus its README covers the full end-to-end on a Pi.
The manifest tuning offer stands.

[slowrunner]

@idoco2003 Thank you for creating the example GoPiGo3 runtime. It was very exciting (well "heart stopping") to hear Dave really executing the URML we have been discussing.

Reviewing the run_gopigo3.py program, I realized how I want to use my_run_gopigo3_urml.py program:

#!/usr/bin/env python3
"""Run validated URML programs on a basic GoPiGo3, hermetically (Discussion #523).

FILE:  my_run_gopigo3_urml.py

USAGE:  ./my_run_gopigo3_urml.py [-f urml_file_name] [-m] [-h]

PARAMETERS:
- -f urml_file_name  - run the file passed
- -m                           - force mock EasyGoPiGo3 class
- -h                            - prints this help info

PURPOSE:
- Runs a URML program if passed
- Runs two demo programs if no program file is specified
- CAUTION:  If executed on a real GoPiGo3 robot without the -m option, the robot will move!
- Can be used to simulate "running a GoPiGo3 URML program" before running for real

EXAMPLE:
./my_run_gopigo3_urml.py -f "remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml" -m

Looks like I needed to improve my gopigo3_t1_remote.sh to clean the model="qwen3.5:9b" when inserting it into the --out parameter to "urml translate ..."

#!/bin/bash

# optional:      --envelope envelope.yaml \

model="qwen3.5:9b"
fn="${model//:/_}"

urml translate "Announce 'Driving forward 10 centimeters' and then execute the action" \
    --manifest gopigo3.manifest.yaml \
    --profile educational \
    --no-policy \
    --provider openai \
    --model $model \
    --save-rejected remote.$fn.gopigo3_t1.rejected.out \
    --out remote.$fn.gopigo3_t1.program.urml.yaml

[idoco2003]

This is exactly the right shape, and I built most of it (PR #544).

run_gopigo3.py now takes -f:

./run_gopigo3.py -f remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml

It validates your file against the GoPiGo3 manifest and runs it; the two demos only run when you do not pass -f. So your my_run_gopigo3_urml.py is now the stock runner with a flag.

On the mock-vs-real default I went the other way from your sketch, on purpose. After Dave's unplanned trip across the room, the default is now a dry run: -f, or a bare run, validates and prints the planned wheel and speech calls and moves nothing. To actually drive you add --execute. And I kept your -m: it forces the fake even with --execute, so you can preview a program on Dave's Pi without Dave moving.

./run_gopigo3.py -f prog.yaml                # simulate, safe
./run_gopigo3.py -f prog.yaml --execute      # let Dave loose
./run_gopigo3.py -f prog.yaml --execute -m   # still just a simulation

The reason for flipping the default is the lesson Dave taught us: in a validate-before-actuate project, running the tool should not be able to surprise you into motion. The gate goes in front of the motor.

Nice catch on the filename, too. The colon in qwen3.5:9b makes a messy --out path; sanitizing it to qwen3.5_9b is the right move. That part is yours to do, since the model name is yours to pass, but it is a good tip for anyone using a model tag as a filename.

Thanks for designing this out loud. It made the feature obvious.

Thanks,
Ido

[slowrunner]

You beat me to it - wow.

This is as far as I got:

[slowrunner]

btw - I saw your discussion point on versions - having runtimes print "GoPiGo3 Runtime v0.1" would provide a traceable workflow. ( I hate having to remember to update version strings when I edit things. Surely the software world has a solution for this?)

[idoco2003]

Ha, glad I beat you to it, and your draft is what told me what to build.

On the version string: you put your finger on a real annoyance, and there is a clean answer. Do not hand-maintain it, read it from the installed package. The example ships inside URML, so its version is just the versions of the URML packages running it, which pip already records. So I had it report those instead of a string someone has to remember to bump (PR #545):

$ run_gopigo3.py --version
gopigo3 example, running on urml-validator 0.2.0, urml-ros2-runtime 0.2.0

Every run prints that line, and a -f run also stamps it into the report header, so a saved report says which versions produced it. Nothing to edit when the code changes: pip records the version, the example reports it.

For your own scripts the same trick works: importlib.metadata.version("some-package") reads whatever pip installed. And if you want the version derived straight from git, setuptools-scm computes it from your tags so you never type a number at all. The principle you were reaching for is: derive the version, do not store it by hand.

Thanks,
Ido

[slowrunner]

COOL! GoPiGo3 Executed URML Translated By (remote Ollama) LLM

Full circle robot action:

1. urml translate "Announce 'Driving forward 10 centimeters' and then execute the action"
2. resubmit translate "LLM timed out" - output "urml_from_LLM"
3. run_gopigo3 -f urml_from_LLM

1. Translate request timed out:

(gopigo3) ubuntu@U26LDave:~/LyricalDave/systests/urml/mygopigo3$ ./gopigo3_t1_remote.sh 
urml: provider error: provider raised: APITimeoutError: Request timed out.

2. Resubmitted - successful translate:

(gopigo3) ubuntu@U26LDave:~/LyricalDave/systests/urml/mygopigo3$ ./gopigo3_t1_remote.sh 
wrote remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml
Translation accepted after 0 revision(s); profile(s)=educational

3a) Test latest run_gopigo3.py is "safe" on a real GoPiGo3

(gopigo3) ubuntu@U26LDave:~/LyricalDave/systests/urml/mygopigo3$ ./run_gopigo3.py 
[gopigo3 example] backend: fake (dry run, no movement)
wrote /home/ubuntu/LyricalDave/systests/urml/mygopigo3/gopigo3-report.txt

3b) Test latest run_gopigo3.py defaults to "safe run" with real URML file

(gopigo3) ubuntu@U26LDave:~/LyricalDave/systests/urml/mygopigo3$ ./run_gopigo3.py -f remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml
[gopigo3 example] backend: fake (dry run, no movement)
URML on a basic GoPiGo3 - running remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml (Discussion #523).
robot: gopigo3_basic   drive_type: differential   max drive: 2.0 m

[VALID] program file: remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml
   executed 2 steps, success=True
   wheel + speech calls, in order:
     emit_speech  -> espeak 'Driving forward 10 centimeters'
     drive_by     -> easygopigo3.drive_cm(10.0)

Dry run: validated and planned, not actuated. Pass --execute (without -m) to drive the robot.

3c) "Go For Gold": Test run_gopigo3.py with real urml from LLM and execute the validated program on Lyrical-Dave:

(gopigo3) ubuntu@U26LDave:~/LyricalDave/systests/urml/mygopigo3$ ./run_gopigo3.py -f remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml --execute
[gopigo3 example] --execute: this WILL move a connected GoPiGo3. Clear space around the robot.
[gopigo3 example] backend: real (executing on hardware)
URML on a basic GoPiGo3 - running remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml (Discussion #523).
robot: gopigo3_basic   drive_type: differential   max drive: 2.0 m

[VALID] program file: remote.qwen3.5_9b.gopigo3_t1.program.urml.yaml
   executed 2 steps, success=True
   wheel + speech calls, in order:
     emit_speech  -> espeak 'Driving forward 10 centimeters'
     drive_by     -> easygopigo3.drive_cm(10.0)

Dave moved 10cm relative to his then position:

Have to track down why I'm not hearing the emit_speech actions (probably needs "espeak-ng" the next generation of espeak text-to-speech current in the community)

[idoco2003]

This is the whole thing, end to end, on your own robot with a model running on your own hardware. English, to a remote local LLM, to a validated program, to Dave actually moving. There is no cloud anywhere in that loop. That is exactly the picture URML exists to make real, and you got there first.

The full circle: you typed a sentence, an Ollama model turned it into URML, the validator checked it against Dave's declared capabilities, and -f ran it on the wheels. Sentence to motion, offline, on a Pi-class robot.

On the timeout: that one is a cold start, not a real failure. The first call to Ollama has to load the multi-GB model into memory, which can blow past the default request timeout; your warm retry worked because the model was already resident. I shipped a small fix so you do not have to lean on the retry (PR #546): the OpenAI provider now honors URML_OPENAI_TIMEOUT, so

export URML_OPENAI_TIMEOUT=600

gives a cold load room to finish. Keeping the model warm with OLLAMA_KEEP_ALIVE helps too. Tutorial 3 now notes both.

Congratulations. This is the demo I would put in front of anyone who asks what URML is for.

Thanks,
Ido