Skip to main content
Version: v0.1.x

Upgrading to v0.1.x

These steps take a 0.0.x setup (CLI through v0.0.36, Python SDK through 0.0.16) to 0.1.x. This snapshot is CLI v0.1.0 (Python SDK 0.0.17). You do not need to land on v0.0.36 first.

See the v0.1.0 release notes.

Here's what's updated in 0.1.x:

  • Agents get better machine context: @command allowlists, class descriptions on puda machine list / ping, a structured command catalog, and @safety so they see what a machine is, what it can do, and what needs confirmation.
  • Livestreams join the fleet. puda livestream registers feeds and attaches machines, so agents retrieve livestream context from PUDA instead of copy-pasted URLs.
  • CLI output is JSON by default. Protocols get a client-side wait, --yes to skip confirms, and validate against live catalog types.
  • Scaling support for up to 1,000,000 machines/edges: shared MACHINE_STATE / MACHINE_COMMANDS KV, ping/pong discovery, throttled heartbeat/position, 10s immediate timeouts, and single-node or three-node NATS.
  • Optional clock sync so timestamps from many hosts stay in order.

Upgrade in this order: CLI, NATS, every edge, skills, livestreams, then clock sync. Do not mix a 0.1.x CLI with a 0.0.16 edge, or the reverse: puda machine commands and protocol validate will fail.

1. Install the new CLI​

Install a 0.1.x CLI from PUDA releases, or run puda update if the CLI is already installed, and confirm the version is 0.1.x:

puda update
puda --version

CLI machine commands now print JSON by default (list, ping, state, commands). Pass --human for the old text output.

puda machine list discovers live edges from ping/pong and reports machine_id, description, and livestream_count. puda machine ping <machine_id> probes specific IDs and includes sdk_version, run_status, and registered livestream URLs.

0.1.x adds puda livestream for agents (add, list, attach, detach, rm). Agents register camera streams in the fleet registry instead of relying on pasted URLs.

Optional: puda healthcheck probes each configured NATS URL, cluster membership, and JetStream.

puda machine and puda protocol run accept --yes / -y to skip safety confirmation prompts.

A protocol command named wait is handled by the CLI: it sleeps for params.seconds and is not sent to a machine.

2. Redeploy the NATS server​

JetStream stream and KV definitions changed in 0.1.x. Shared buckets MACHINE_STATE and MACHINE_COMMANDS replace the old per-machine buckets, and LIVESTREAMS is new. The 0.0.x hand-written Compose file is not enough. Redeploy from infra/nats rather than patching the old instance.

Pick one layout from NATS Server:

  • Single-node — one NATS server on one computer.
  • Three-node — one NATS server on each of three computers on the same network.

After the server is running, apply JetStream once with REPLICAS=1 (single-node) or REPLICAS=3 (three-node). Old per-machine KV buckets are unused.

3. Upgrade every edge to SDK 0.0.17 or later​

On each edge, set the puda dependency in pyproject.toml to 0.0.17 or later:

pyproject.toml
dependencies = [
    "puda>=0.0.17",
]

Keep your other dependencies. Then lock and install:

uv lock
uv sync

If the edge is managed with puda machine update, deploy after the driver changes below.

Heartbeat is now published at most every 5s and position at most every 3s. Dashboards that expected 1 Hz on those subjects will look quieter.

Mark remote commands with @command​

0.0.x advertised every public driver method. 0.1.x advertises only methods decorated with @command. A driver with none of those methods fails at startup with Update SDK to 0.0.17.

driver.py
from puda import command

class Driver:
    """One-sentence summary of what this machine does."""

    @command
    def move_to(self, x_mm: float, y_mm: float, z_mm: float) -> bool:
        """Move the machine head to an absolute position."""
        ...

Keep helpers private (_name). Inherited serial APIs and other undecorated public methods stay local.

Put a one-sentence summary in the class docstring. puda machine list and puda machine ping show that first paragraph as description.

Raise on failure​

Command handlers must raise to fail. Returning False is still a successful PUDA response ({"result": false}), which might confuse the AI agent.

Optional: @safety​

Attach @safety to commands that can cause harm so agents check preconditions and optionally confirm with the operator. It is published in the catalog; it does not block edge dispatch. See @safety decorator.

Optional: lifecycle methods​

shutdown, home, and reset are optional.

  • shutdown, if defined, runs before the edge stops.
  • home, if defined, is triggered by puda machine home.
  • puda machine reset always clears the active run ID, then calls reset if present. A missing reset is a successful no-op.

MACHINE_COMMANDS now includes a structured catalog (name, signature, doc, safety) next to the command text. A 0.0.16 edge that only published {"commands": "..."} is incompatible with this CLI.

Protocol validate reads parameter types from that catalog as JSON primitives (str, int, float, bool, dict, list, bytes, any, and nullable/unions of those). Annotate @command parameters with those kinds so puda protocol validate can check protocol params. Nested dict/list, typing aliases, and Any catalogs are accepted. Validate only parses commands named in the protocol; unused catalog signatures are ignored. Unannotated parameters, *args, and **kwargs skip the type check.

4. Refresh skills​

On the agent host:

puda skills update

The updated skills cover livestream, clock sync, and the special client-side protocol wait command:

  • puda
    • Livestream — given the camera source, stream name, description, host, and machine IDs, the agent brings up MediaMTX and ffmpeg and registers the stream with puda livestream.
    • Clock sync — given the site NTP server IP, the agent runs scripts/sync-clock.sh or scripts/sync-clock.ps1 from the puda skill on the edge host (Chrony on Linux, Windows Time on Windows).
  • puda-protocol — agents can insert a special client-side wait command (params.seconds) to pause a protocol or a single machine in a parallel step. The CLI sleeps locally; wait is not sent to a machine.

5. Livestreams​

0.0.x ran cameras as a standalone MediaMTX stack, separate from PUDA. You had to give the agent the URLs and machine context yourself.

0.1.x keeps that stack and adds the puda livestream subcommand plus a fleet registry in NATS KV (LIVESTREAMS). You do not register streams by hand. After puda skills are updated, give the agent the camera source (USB /dev/video* path or rtsp:// URL), livestream name, a short description, the MediaMTX host (MagicDNS, Tailscale IP, or the machine IP if there is no Tailscale), and the machine IDs that are using the feed. The skill starts MediaMTX and ffmpeg if they are not already running, then registers with puda livestream add.

If MediaMTX is already running from 0.0.x, leave it up. The skill still registers the existing streams so puda machine list and puda machine ping can see them.

See Livestream.

6. Clock sync​

Clock sync is not required to finish the upgrade. It is still important in a distributed system: timestamps come from many machines, and those clocks must agree. Follow Clock Sync if you want that accuracy.

7. Re-validate protocols​

Protocol validate and run read safety and parameter types from the live command catalog. After the edge is on 0.0.17, run puda protocol validate again. Only commands named in the protocol are parsed; unused catalog signatures cannot fail the file. Unannotated parameters skip the type check.

Commands with safety.confirm=true will make the AI agent prompt you for a manual confirmation unless you pass --yes.

Immediate commands now time out at 10s (was 120s). Queue commands stay at 120s.

If a protocol needs a pause, use the special client-side wait command (params.seconds). The CLI sleeps locally; the command is not sent to a machine.

8. PUDA Logger and database​

Command and response payloads did not change, so keep the PUDA Logger and the database server running. The local SQLite database (puda.db) is unchanged. If you changed NATS URLs in step 2, point the logger's NATS_SERVERS at the new servers.

9. Confirm the fleet​

puda machine list
puda machine ping <machine_id>
puda machine commands <machine_id>
puda livestream list --machines <machine_id>

puda machine list should show description and livestream_count. puda machine ping should show sdk_version 0.0.17 or later and any registered livestream URLs. puda machine commands should list only @command methods.

More driver detail: Integrating a New Machine. SDK notes: Python SDK 0.0.17.