Skip to content

Commit f909c23

Browse files
kavya-chennojukavya-chennoju
committed
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.
1 parent 0154cab commit f909c23

4 files changed

Lines changed: 393 additions & 0 deletions

File tree

‎content/learning-paths/embedded-and-microcontrollers/device-connect-server/_index.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Connect Devices and AI agents through Device Connect Server
3+
4+
draft: true
5+
cascade:
6+
draft: true
7+
8+
minutes_to_complete: 30
9+
10+
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.
11+
12+
learning_objectives:
13+
- Understand what the Device Connect server adds on top of the edge SDK and when you'd reach for it
14+
- Provision a hosted tenant on the Device Connect portal and download per-device NATS credentials
15+
- Commission two simulated devices against your tenant using the credentials the portal issues
16+
- Discover and invoke commissioned devices from a Python client using `device-connect-agent-tools`
17+
- Connect a Strands AI agent to the same tenant
18+
19+
prerequisites:
20+
- 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)
21+
- An account on the [Device Connect portal](https://portal.deviceconnect.dev/)
22+
- Basic familiarity with Python and the command line
23+
24+
author:
25+
- Kavya Sri Chennoju
26+
- Annie Tallund
27+
28+
### Tags
29+
skilllevels: Introductory
30+
subjects: Libraries
31+
armips:
32+
- Cortex-A
33+
- Neoverse
34+
operatingsystems:
35+
- Linux
36+
- macOS
37+
tools_software_languages:
38+
- Python
39+
- Docker
40+
41+
further_reading:
42+
- resource:
43+
title: Device Connect
44+
link: https://deviceconnect.dev/
45+
type: website
46+
- resource:
47+
title: device-connect-server package
48+
link: https://github.com/arm/device-connect/tree/main/packages/device-connect-server
49+
type: documentation
50+
51+
### FIXED, DO NOT MODIFY
52+
# ================================================================================
53+
weight: 1
54+
layout: "learningpathall"
55+
learning_path_main_page: "yes"
56+
---

‎content/learning-paths/embedded-and-microcontrollers/device-connect-server/_next-steps.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
# ================================================================================
3+
# FIXED, DO NOT MODIFY THIS FILE
4+
# ================================================================================
5+
weight: 21
6+
title: "Next Steps"
7+
layout: "learningpathall"
8+
---
9+
10+
## Where to go next
11+
12+
From this baseline you can extend the deployment in a few directions:
13+
14+
- 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/`
15+
- 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
16+
- 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
17+
- replace the simulated number-generator with a real sensor or robot driver using the same `DeviceDriver` pattern from the edge SDK

‎content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Why add a Device Connect server
3+
weight: 2
4+
5+
# FIXED, DO NOT MODIFY
6+
layout: learningpathall
7+
---
8+
9+
## What D2D mode gives you, and where it stops
10+
11+
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.
12+
13+
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:
14+
15+
- 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
16+
- **distributed state** shared between devices and agents, with leases and watches (for example, "which experiment is each device currently running?")
17+
- **multi-network reach** for devices and agents on different LANs, behind NAT, or in the cloud
18+
- **fleet-wide operations** like commissioning new devices, rotating credentials, or auditing every RPC that has ever been issued
19+
- **security guarantees** beyond TLS on the wire, including per-device cryptographic identity, PIN-based onboarding, role-based ACLs, and audit logs
20+
21+
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.
22+
23+
## What the server adds
24+
25+
The server runtime ships as a small set of services you run alongside (or instead of) raw D2D scouting:
26+
27+
- a **messaging router** (Zenoh by default; NATS or MQTT as alternatives) so devices on different networks can reach the same mesh
28+
- a **device registry service** that records every device, its identity, capabilities, and last-known status, in a persistent store
29+
- an **etcd-backed distributed state store** that any device or agent can read and write through the Python API
30+
- a **device commissioning flow** with PIN-based onboarding and per-device cryptographic identity (covered later in this Learning Path)
31+
- optional **security infrastructure**: TLS/mTLS for Zenoh, JWT auth for NATS, role-based access control, audit logging
32+
33+
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.
34+
35+
## A note on commissioning
36+
37+
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:
38+
39+
- with **Zenoh**, commissioning means issuing the device a client TLS certificate signed by a shared CA
40+
- with **NATS**, commissioning means issuing the device a JWT credential bound to its tenant
41+
42+
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.
43+
44+
## Where this sits in the architecture
45+
46+
```
47+
┌──────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐
48+
│ Devices │ │ Device Connect │ │ AI agents │
49+
│ (edge SDK) │ │ server │ │ (agent-tools) │
50+
│ DeviceDriver │◄───►│ Pub/sub · Registry│◄───►│ discover_devices() │
51+
│ @rpc @emit │ │ KV · Security│ │ invoke_device() │
52+
│ @periodic @on │ │ │ │ Strands / LC / MCP │
53+
└──────────────────┘ └──────────────────────┘ └─────────────────────┘
54+
```
55+
56+
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.
57+
58+
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.
59+
60+
<video width="100%" controls muted playsinline>
61+
<source src="https://raw.githubusercontent.com/kavya-chennoju/arm-learning-path-assets/main/videos/device-connect-server-overview.mp4" type="video/mp4">
62+
Your browser does not support the video tag.
63+
</video>
64+
65+
## What you'll do in this Learning Path
66+
67+
In the rest of this Learning Path you will:
68+
69+
- start the server stack locally with Docker Compose
70+
- connect a simulated number-generator device to it
71+
- discover the registered device from a short Python client using `device-connect-agent-tools`
72+
- attach a Strands AI agent that subscribes to events on the mesh
73+
74+
The next section walks through the setup.

0 commit comments

Comments
 (0)