From f909c232d8f753fc78814ec257f787ef259575f3 Mon Sep 17 00:00:00 2001 From: Kavya Chennoju Date: Mon, 11 May 2026 00:05:19 -0700 Subject: [PATCH 1/2] Add device-connect-server learning path (draft) Introduces a new Learning Path covering Device Connect's server tier on top of the edge SDK. Uses the hosted Device Connect Fabric portal (fabric.deviceconnect.dev) to mint NATS JWT credentials, then walks through running two simulated robot-arm devices and one orchestrating agent against the tenant. Devices and the agent talk through the shared server (NATS, Zenoh, or MQTT backend). Marked as draft (cascade: draft: true) until reviewed. Video asset is hosted externally at https://github.com/kavya-chennoju/arm-learning-path-assets and referenced via raw.githubusercontent.com, matching the pattern already in use by the tinkerblox_ultraedge Learning Path. --- .../device-connect-server/_index.md | 56 ++++ .../device-connect-server/_next-steps.md | 17 ++ .../device-connect-server/background.md | 74 ++++++ .../device-connect-server/server-setup.md | 246 ++++++++++++++++++ 4 files changed, 393 insertions(+) create mode 100644 content/learning-paths/embedded-and-microcontrollers/device-connect-server/_index.md create mode 100644 content/learning-paths/embedded-and-microcontrollers/device-connect-server/_next-steps.md create mode 100644 content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md create mode 100644 content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_index.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_index.md new file mode 100644 index 0000000000..e0cd3a1673 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_index.md @@ -0,0 +1,56 @@ +--- +title: Connect Devices and AI agents through Device Connect Server + +draft: true +cascade: + draft: true + +minutes_to_complete: 30 + +who_is_this_for: This is a follow-on topic for developers who have a working Device Connect mesh and want to add a server layer on top. The server gives you a persistent device registry, distributed state, and security primitives (commissioning, ACLs) so you can operate a multi-network fleet from one place. + +learning_objectives: + - Understand what the Device Connect server adds on top of the edge SDK and when you'd reach for it + - Provision a hosted tenant on the Device Connect portal and download per-device NATS credentials + - Commission two simulated devices against your tenant using the credentials the portal issues + - Discover and invoke commissioned devices from a Python client using `device-connect-agent-tools` + - Connect a Strands AI agent to the same tenant + +prerequisites: + - Familiarity with the Device Connect edge SDK (the [device-to-device Learning Path](/learning-paths/embedded-and-microcontrollers/device-connect-d2d/) is a good starting point) + - An account on the [Device Connect portal](https://portal.deviceconnect.dev/) + - Basic familiarity with Python and the command line + +author: + - Kavya Sri Chennoju + - Annie Tallund + +### Tags +skilllevels: Introductory +subjects: Libraries +armips: + - Cortex-A + - Neoverse +operatingsystems: + - Linux + - macOS +tools_software_languages: + - Python + - Docker + +further_reading: + - resource: + title: Device Connect + link: https://deviceconnect.dev/ + type: website + - resource: + title: device-connect-server package + link: https://github.com/arm/device-connect/tree/main/packages/device-connect-server + type: documentation + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 +layout: "learningpathall" +learning_path_main_page: "yes" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_next-steps.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_next-steps.md new file mode 100644 index 0000000000..cfca5cb4ea --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/_next-steps.md @@ -0,0 +1,17 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 +title: "Next Steps" +layout: "learningpathall" +--- + +## Where to go next + +From this baseline you can extend the deployment in a few directions: + +- swap Zenoh dev mode for [Zenoh with TLS](https://github.com/arm/device-connect/tree/main/packages/device-connect-server#secure--zenoh-tls) using the `generate_tls_certs.sh` script in `security_infra/` +- swap to a NATS backend with [JWT authentication](https://github.com/arm/device-connect/tree/main/packages/device-connect-server#authenticated--nats-jwt-auth) for per-device credentials +- explore the [multi-tenant deployment](https://github.com/arm/device-connect/tree/main/packages/device-connect-server#multi-tenant-deployment) flow when several teams or workshops share the same infrastructure +- replace the simulated number-generator with a real sensor or robot driver using the same `DeviceDriver` pattern from the edge SDK diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md new file mode 100644 index 0000000000..54b4c09e7b --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md @@ -0,0 +1,74 @@ +--- +title: Why add a Device Connect server +weight: 2 + +# FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## What D2D mode gives you, and where it stops + +In device-to-device (D2D) mode, every Device Connect runtime is a peer on the same local network. Devices find each other through the messaging backend's local discovery (Zenoh's multicast scouting, or NATS running in a peer-to-peer configuration), exchange typed events, and call each other's RPCs directly. There is no central process to provision or maintain. + +That is a great fit for prototyping, for small fleets on a shared LAN, and for time-sensitive applications where a cloud round-trip would be wasteful. It stops being a great fit when you need any of the following: + +- a **persistent registry** that survives device reboots and lets a new client list every device that has ever connected, not just the ones online right this second +- **distributed state** shared between devices and agents, with leases and watches (for example, "which experiment is each device currently running?") +- **multi-network reach** for devices and agents on different LANs, behind NAT, or in the cloud +- **fleet-wide operations** like commissioning new devices, rotating credentials, or auditing every RPC that has ever been issued +- **security guarantees** beyond TLS on the wire, including per-device cryptographic identity, PIN-based onboarding, role-based ACLs, and audit logs + +The [`device-connect-server`](https://github.com/arm/device-connect/tree/main/packages/device-connect-server) package is the layer that adds those capabilities on top of the edge SDK you already know. + +## What the server adds + +The server runtime ships as a small set of services you run alongside (or instead of) raw D2D scouting: + +- a **messaging router** (Zenoh by default; NATS or MQTT as alternatives) so devices on different networks can reach the same mesh +- a **device registry service** that records every device, its identity, capabilities, and last-known status, in a persistent store +- an **etcd-backed distributed state store** that any device or agent can read and write through the Python API +- a **device commissioning flow** with PIN-based onboarding and per-device cryptographic identity (covered later in this Learning Path) +- optional **security infrastructure**: TLS/mTLS for Zenoh, JWT auth for NATS, role-based access control, audit logging + +You can adopt these incrementally: run the dev-mode Docker Compose to get a router and registry running locally with no auth, then layer in TLS or JWT once you have the basics working. + +## A note on commissioning + +In a serious deployment, no device joins the mesh until it has been **commissioned**, meaning it has been given a cryptographic identity that the server trusts. The shape of that identity depends on the messaging backend: + +- with **Zenoh**, commissioning means issuing the device a client TLS certificate signed by a shared CA +- with **NATS**, commissioning means issuing the device a JWT credential bound to its tenant + +In both cases, the credential answers the question "is this device allowed on this tenant's mesh?" and prevents anyone else from impersonating it. In this Learning Path you will use the [Device Connect portal](https://portal.deviceconnect.dev/) to mint NATS credentials for your devices and your agent, then point each runtime at the tenant's NATS server. That replaces the local Docker setup with a hosted server you do not need to operate yourself. + +## Where this sits in the architecture + +``` +┌──────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ +│ Devices │ │ Device Connect │ │ AI agents │ +│ (edge SDK) │ │ server │ │ (agent-tools) │ +│ DeviceDriver │◄───►│ Pub/sub · Registry│◄───►│ discover_devices() │ +│ @rpc @emit │ │ KV · Security│ │ invoke_device() │ +│ @periodic @on │ │ │ │ Strands / LC / MCP │ +└──────────────────┘ └──────────────────────┘ └─────────────────────┘ +``` + +Devices and agents still talk to each other through the same primitives (`@rpc`, `@emit`, `discover_devices`, `invoke_device`). The Device Connect server runs the pub/sub messaging, the persistent registry, the shared key-value store, and the security layer in one place. + +The animation below shows the same idea end to end: a Device Connect server runs in Berlin (with Zenoh, NATS, or MQTT as the messaging backend), robots in San Francisco and Tokyo install `device-connect-edge` and register with it, and an AI agent in Bangalore installs `device-connect-agent-tools` and drives both robots through the server. Every `invoke_device` call and every event flows through Berlin. + + + +## What you'll do in this Learning Path + +In the rest of this Learning Path you will: + +- start the server stack locally with Docker Compose +- connect a simulated number-generator device to it +- discover the registered device from a short Python client using `device-connect-agent-tools` +- attach a Strands AI agent that subscribes to events on the mesh + +The next section walks through the setup. diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md new file mode 100644 index 0000000000..20f04fadfe --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md @@ -0,0 +1,246 @@ +--- +title: Run devices and an orchestrating agent on a Device Connect server +weight: 3 + +# FIXED, DO NOT MODIFY +layout: learningpathall +--- + +In this section you will use the hosted Device Connect service to provision a tenant, commission a simulated device with NATS JWT credentials, and verify it from a Python client. The hosted service runs the messaging router (NATS) and the registry for you, so the only thing you operate is the device itself and the agent that talks to it. + +## Mint device and agent credentials from the Device Connect portal + +The Device Connect portal is operated by Arm as a hosted developer service for the open-source [Device Connect](https://github.com/arm/device-connect) framework. Sign-in provisions a private **tenant** for your account, an isolated namespace on a hosted NATS messaging server, and lets you mint per-device and per-agent JWT credentials so your devices and AI agents can discover and invoke one another across networks. Only your account email and the cryptographic identities (device IDs, JWTs, public keys) you create on the portal are stored; the contents of messages your devices exchange are not stored, seen, or proxied. Treat each `.creds.json` you download like a private key, and do not put secrets, API keys, or personal data into device names or descriptions. For questions or issues, open one at [`arm/device-connect`](https://github.com/arm/device-connect/issues). + +1. Open [`https://portal.deviceconnect.dev/`](https://portal.deviceconnect.dev/) and sign in. Signing in gives you a **tenant** — an isolated namespace on the shared Device Connect server that only the devices and agents you commission against it can join. Nothing from another tenant can see, publish to, or invoke anything in yours. +2. Open the **My Devices** section. The page header reads `Manage device credentials for tenant ` — the value of `` is your **tenant slug** (for example, `beta`). The portal uses it to namespace every identity you create, so `sf-robot` on the `beta` tenant becomes `beta-sf-robot`. The NATS server URL is the same for every tenant: `nats://portal.deviceconnect.dev:4222`. +3. From the same **My Devices** page, add three identities. Type the short names below and the portal prefixes each one with your tenant slug automatically: + - `sf-robot`: the San Francisco robot arm + - `tokyo-robot`: the Tokyo robot arm + - `bangalore-agent`: the orchestrating agent + +For each identity, the portal exposes a **Download** button that gives you a NATS JWT credentials file named `.creds.json`. Treat each `.creds.json` file like a private key: anyone who has it can act as that identity on your tenant. + +Export the tenant settings so the rest of the walkthrough can reuse them. + +```bash +export TENANT= +export NATS_URL=nats://portal.deviceconnect.dev:4222 +export MESSAGING_BACKEND=nats +``` + +Now save the downloaded credentials to a stable directory: + +```bash +mkdir -p ~/.device-connect/credentials +mv ~/Downloads/${TENANT}-sf-robot.creds.json ~/.device-connect/credentials/ +mv ~/Downloads/${TENANT}-tokyo-robot.creds.json ~/.device-connect/credentials/ +mv ~/Downloads/${TENANT}-bangalore-agent.creds.json ~/.device-connect/credentials/ +chmod 600 ~/.device-connect/credentials/*.creds.json +``` + +The agent-tools `connect()` function reads `TENANT` only when its `zone` argument is left unset, so always call it as `connect(zone=os.environ["TENANT"])` in the Python snippets below. + +The portal also exposes a **Coding Agents** tab that can drive this whole step for you — pointing a coding agent (such as Claude Code or Codex) at it will provision identities and download the credentials on your behalf. The manual flow above is what the agent automates, and is useful to walk through once so you understand what the agent is doing. + +## Install the SDKs + +Create a virtual environment and install the edge runtime and the agent tools: + +```bash +mkdir -p ~/device-connect-fabric && cd ~/device-connect-fabric +python3 -m venv .venv +source .venv/bin/activate +pip install device-connect-edge device-connect-agent-tools +``` + +You do not need `device-connect-server` locally; Fabric runs that for you in this case. If you would rather self-host, you can install it with `pip install device-connect-server` and run the router and registry yourself; see the [device-connect-server README](https://github.com/arm/device-connect/tree/main/packages/device-connect-server) for the Docker Compose deployment options. + +## Write a simulated robot-arm driver + +Create a file called `robot_arm.py`. The driver pretends to be a 6-DOF robot arm: it exposes RPCs for moving to a target pose and homing, tracks its current position, and emits a `motion_completed` event after every move. + +```python +import argparse +import asyncio +import random + +from device_connect_edge import DeviceRuntime +from device_connect_edge.drivers import DeviceDriver, emit, rpc +from device_connect_edge.types import DeviceIdentity, DeviceStatus + + +class RobotArmDriver(DeviceDriver): + device_type = "robot_arm" + + def __init__(self): + super().__init__() + self._position = {"x": 0.0, "y": 0.0, "z": 0.0} + + @property + def identity(self) -> DeviceIdentity: + return DeviceIdentity( + device_type="robot_arm", + manufacturer="Device Connect", + model="SIM-ARM-6DOF", + description="Simulated 6-DOF robot arm", + ) + + @property + def status(self) -> DeviceStatus: + return DeviceStatus(availability="available", location="simulator") + + @rpc() + async def move_to(self, x: float, y: float, z: float) -> dict: + # pretend to physically traverse to the target + await asyncio.sleep(random.uniform(0.2, 0.6)) + self._position = {"x": x, "y": y, "z": z} + await self.motion_completed(target=self._position) + return {"position": self._position} + + @rpc() + async def home(self) -> dict: + return await self.move_to(0.0, 0.0, 0.0) + + @rpc() + async def get_position(self) -> dict: + return self._position + + @emit() + async def motion_completed(self, target: dict): + return None + + +async def main(): + parser = argparse.ArgumentParser() + parser.add_argument("--device-id", required=True) + args = parser.parse_args() + + runtime = DeviceRuntime(driver=RobotArmDriver(), device_id=args.device_id) + await runtime.run() + + +if __name__ == "__main__": + asyncio.run(main()) +``` + +Note that there is no `allow_insecure=True` on the runtime. The runtime will only join the mesh if it has valid credentials, which is what makes commissioning meaningful. + +## Connect the device to the server + +Point the runtime at the Fabric NATS server and at the device's `.creds.json` file. The combination of `NATS_URL` and `NATS_CREDENTIALS_FILE` is what turns the device from "an unauthenticated process" into "a commissioned member of your tenant": + +```bash +NATS_URL=$NATS_URL \ + NATS_CREDENTIALS_FILE=~/.device-connect/credentials/${TENANT}-sf-robot.creds.json \ + python robot_arm.py --device-id ${TENANT}-sf-robot +``` + +On startup, the runtime presents its JWT to NATS, NATS verifies it against your tenant's signing key, and the device is allowed to publish, subscribe, and register itself. From this moment it shows up in the portal under your tenant, with its identity, capabilities, and live status. + +The `--device-id` you pass on the command line must match the identity inside the credentials file (so `${TENANT}-sf-robot.creds.json` requires `--device-id ${TENANT}-sf-robot`). + +In a second terminal, do the same for the Tokyo arm: + +```bash +source ~/device-connect-fabric/.venv/bin/activate +NATS_URL=$NATS_URL \ + NATS_CREDENTIALS_FILE=~/.device-connect/credentials/${TENANT}-tokyo-robot.creds.json \ + python robot_arm.py --device-id ${TENANT}-tokyo-robot +``` + +You now have two commissioned devices on your tenant. + +## Discover and invoke from Python + +Open a third terminal and run a short client using the agent's credentials. This is the same `device-connect-agent-tools` API you would use from a Strands or LangChain agent. Agents authenticate to the same tenant in the same way devices do, just with a different `.creds.json` file: + +```bash +source ~/device-connect-fabric/.venv/bin/activate +NATS_URL=$NATS_URL \ + MESSAGING_BACKEND=nats \ + TENANT=$TENANT \ + NATS_CREDENTIALS_FILE=~/.device-connect/credentials/${TENANT}-bangalore-agent.creds.json \ + python - <<'PY' +import os +from device_connect_agent_tools import connect, discover_devices, invoke_device + +tenant = os.environ["TENANT"] +connect(zone=tenant) + +devices = discover_devices() +print(f"Found {len(devices)} device(s) on tenant") +for d in devices: + print(f" {d['device_id']:24} {d['device_type']:20} {d.get('status', {}).get('availability', '?')}") + +# Drive both arms through the server. The server routes each call to the right device. +for d in devices: + print(f"\nhome on {d['device_id']}:") + print(invoke_device(d['device_id'], 'home')) + +print(f"\nmove {tenant}-sf-robot to (0.2, 0.1, 0.3):") +print(invoke_device(f'{tenant}-sf-robot', 'move_to', x=0.2, y=0.1, z=0.3)) + +print(f"\nposition of {tenant}-tokyo-robot:") +print(invoke_device(f'{tenant}-tokyo-robot', 'get_position')) +PY +``` + +You should see both `sf-robot` and `tokyo-robot` listed, then each one home, then the SF arm move, then Tokyo's position read. The agent never needs to know which network the arms are on; it only needs the tenant's NATS URL and its own credentials. + +## (Optional) Attach a Strands AI agent + +`device-connect-agent-tools` ships an adapter that turns the same Device Connect mesh into a Strands tool surface: + +```bash +pip install "device-connect-agent-tools[strands]" +``` + +```python +import asyncio +from device_connect_agent_tools.adapters.strands_agent import StrandsDeviceConnectAgent + +async def main(): + agent = StrandsDeviceConnectAgent( + goal="Coordinate the two robot arms: home them, then plan and execute moves on user request", + model_id="claude-sonnet-4-20250514", + ) + async with agent: + await agent.run() + +asyncio.run(main()) +``` + +Run it with the agent's credentials and an Anthropic API key: + +```bash +NATS_URL=$NATS_URL \ + NATS_CREDENTIALS_FILE=~/.device-connect/credentials/${TENANT}-bangalore-agent.creds.json \ + TENANT=$TENANT \ + ANTHROPIC_API_KEY="sk-ant-..." \ + python my_agent.py +``` + +The agent subscribes to events on your tenant, batches them over a short window, and prompts Claude to react. Claude can call back into devices using `invoke_device()` and `get_device_status()`. + +## Tear down + +Stop the running terminals with `Ctrl-C`. Your tenant and credentials remain valid until you revoke them from the portal, so there is nothing on your machine to clean up beyond the virtual environment: + +```bash +deactivate +rm -rf ~/device-connect-fabric/.venv +``` + +To rotate credentials, regenerate them from the portal and replace the `.creds.json` files. Old credentials are revoked the moment new ones are issued. + +## What you've built + +You now have a working Device Connect deployment with a hosted server in the loop: + +- a hosted NATS router and persistent registry on your tenant +- two commissioned simulated robot arms, each authenticated by its own JWT credential +- a Python client using `device-connect-agent-tools` to discover the arms and drive them through the server +- (optionally) a Strands agent coordinating both arms over the same mesh + +This is the same shape of deployment you would use to put real robot arms, conveyors, cameras, or actuators on the mesh; only the driver code and the credential names change. From bca1abbbbfb7b5aaaa3c59a59e10ee1d223948b5 Mon Sep 17 00:00:00 2001 From: Annie Tallund Date: Tue, 12 May 2026 15:18:04 -0700 Subject: [PATCH 2/2] Technical review of Device Connect Server LP --- .../device-connect-server/background.md | 63 ++++---- .../device-connect-server/server-setup.md | 134 ++++++++++++------ 2 files changed, 127 insertions(+), 70 deletions(-) diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md index 54b4c09e7b..13a1fcec62 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md @@ -6,43 +6,57 @@ weight: 2 layout: learningpathall --- -## What D2D mode gives you, and where it stops +## From device-to-device (D2D) to server -In device-to-device (D2D) mode, every Device Connect runtime is a peer on the same local network. Devices find each other through the messaging backend's local discovery (Zenoh's multicast scouting, or NATS running in a peer-to-peer configuration), exchange typed events, and call each other's RPCs directly. There is no central process to provision or maintain. +The [device-to-device Learning Path](/learning-paths/embedded-and-microcontrollers/device-connect-d2d/) showed Device Connect in its simplest shape. Each runtime is a peer on the same local network. Devices find each other automatically, exchange typed events, and call each other's remote procedure calls (RPCs) directly. There is no broker, registry, or cloud service to run. -That is a great fit for prototyping, for small fleets on a shared LAN, and for time-sensitive applications where a cloud round-trip would be wasteful. It stops being a great fit when you need any of the following: +That model is useful when everything is close together. It works well for prototypes, lab demos, and small fleets on one local area network (LAN). It is also a good fit when a cloud round-trip would add unnecessary delay. -- a **persistent registry** that survives device reboots and lets a new client list every device that has ever connected, not just the ones online right this second -- **distributed state** shared between devices and agents, with leases and watches (for example, "which experiment is each device currently running?") -- **multi-network reach** for devices and agents on different LANs, behind NAT, or in the cloud -- **fleet-wide operations** like commissioning new devices, rotating credentials, or auditing every RPC that has ever been issued -- **security guarantees** beyond TLS on the wire, including per-device cryptographic identity, PIN-based onboarding, role-based ACLs, and audit logs +As soon as the fleet grows, D2D mode starts to run out of road. You may need devices on different networks to talk to each other. You may need a registry that remembers devices after they disconnect. You may also need stronger identity, credential rotation, or audit logs. -The [`device-connect-server`](https://github.com/arm/device-connect/tree/main/packages/device-connect-server) package is the layer that adds those capabilities on top of the edge SDK you already know. +Use a Device Connect server when you need: + +- a **persistent registry** that survives device reboots and lets new clients list known devices +- **distributed state** shared between devices and agents, with leases and watches +- **multi-network reach** for devices and agents on different LANs, behind network address translation (NAT), or in the cloud +- **fleet-wide operations** such as commissioning devices and rotating credentials +- **stronger security controls** such as per-device identity, JSON Web Token (JWT) credentials, role-based access control lists (ACLs), and audit logs + +The [`device-connect-server`](https://github.com/arm/device-connect/tree/main/packages/device-connect-server) package is the layer that adds those capabilities on top of the edge software development kit (SDK) you already know. ## What the server adds -The server runtime ships as a small set of services you run alongside (or instead of) raw D2D scouting: +The server does not change how you write device code. Devices still use `DeviceDriver`, `@rpc`, `@emit`, `@periodic`, and `@on`. Clients and artificial intelligence (AI) agents still use `discover_devices()` and `invoke_device()`. + +The server changes how devices find and trust each other. In D2D mode, each runtime discovers nearby peers directly. With a server, every device and agent connects to a shared service. + +That shared service gives you a few fleet-level building blocks: -- a **messaging router** (Zenoh by default; NATS or MQTT as alternatives) so devices on different networks can reach the same mesh -- a **device registry service** that records every device, its identity, capabilities, and last-known status, in a persistent store -- an **etcd-backed distributed state store** that any device or agent can read and write through the Python API -- a **device commissioning flow** with PIN-based onboarding and per-device cryptographic identity (covered later in this Learning Path) -- optional **security infrastructure**: TLS/mTLS for Zenoh, JWT auth for NATS, role-based access control, audit logging +- **routing** so devices on different networks can join the same mesh +- **registry** so clients can see known devices, their capabilities, and their last-known status +- **shared state** so devices and agents can coordinate through a common store +- **commissioning** so each device gets its own trusted credential +- **security controls** such as Transport Layer Security (TLS), mutual TLS (mTLS), JSON Web Token (JWT) authentication, role-based access control, and audit logging -You can adopt these incrementally: run the dev-mode Docker Compose to get a router and registry running locally with no auth, then layer in TLS or JWT once you have the basics working. +Device Connect supports different messaging backends, including Zenoh, NATS, and Message Queuing Telemetry Transport (MQTT). In this Learning Path, you will use the hosted portal with NATS credentials. That lets you focus on the device and agent code instead of running the server yourself. ## A note on commissioning -In a serious deployment, no device joins the mesh until it has been **commissioned**, meaning it has been given a cryptographic identity that the server trusts. The shape of that identity depends on the messaging backend: +Commissioning means giving a device or agent a trusted identity before it joins the mesh. Without commissioning, a process is just code trying to connect. With commissioning, the server can decide whether that process is allowed to publish, subscribe, register itself, or call an RPC. -- with **Zenoh**, commissioning means issuing the device a client TLS certificate signed by a shared CA +The credential format depends on the messaging backend: + +- with **Zenoh**, commissioning means issuing the device a client TLS certificate signed by a shared certificate authority (CA) - with **NATS**, commissioning means issuing the device a JWT credential bound to its tenant -In both cases, the credential answers the question "is this device allowed on this tenant's mesh?" and prevents anyone else from impersonating it. In this Learning Path you will use the [Device Connect portal](https://portal.deviceconnect.dev/) to mint NATS credentials for your devices and your agent, then point each runtime at the tenant's NATS server. That replaces the local Docker setup with a hosted server you do not need to operate yourself. +In both cases, the credential answers the same question: is this identity allowed on this mesh? + +In this Learning Path, you will use the [Device Connect portal](https://portal.deviceconnect.dev/) to download NATS credentials for three default identities on your tenant. Two identities will run simulated robot arms. The third identity will run the Python client or agent. ## Where this sits in the architecture +In the diagram, pub/sub means publish/subscribe, KV means key-value, LC means LangChain, and MCP means Model Context Protocol. + ``` ┌──────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐ │ Devices │ │ Device Connect │ │ AI agents │ @@ -55,7 +69,7 @@ In both cases, the credential answers the question "is this device allowed on th Devices and agents still talk to each other through the same primitives (`@rpc`, `@emit`, `discover_devices`, `invoke_device`). The Device Connect server runs the pub/sub messaging, the persistent registry, the shared key-value store, and the security layer in one place. -The animation below shows the same idea end to end: a Device Connect server runs in Berlin (with Zenoh, NATS, or MQTT as the messaging backend), robots in San Francisco and Tokyo install `device-connect-edge` and register with it, and an AI agent in Bangalore installs `device-connect-agent-tools` and drives both robots through the server. Every `invoke_device` call and every event flows through Berlin. +The animation below shows the same idea end to end. A Device Connect server runs in Berlin. Robots in San Francisco and Tokyo install `device-connect-edge` and register with it. An AI agent in Bangalore installs `device-connect-agent-tools` and drives both robots through the server. Every `invoke_device` call and every event flows through the server.