diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md index d7203100bc..95902257a0 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md @@ -10,10 +10,9 @@ cascade: who_is_this_for: This is an introductory topic for developers wiring up heterogeneous edge fleets, where devices need a shared way to find each other and a shared way to be controlled by agents. Device Connect provides this communication protocol between agents and devices, and standardizes how devices from different vendors advertise themselves and exchange structured messages, so both peer devices and AI agents can discover and invoke them through the same driver model. You'll use it to stand up peer-to-peer communication between two devices, with no broker or cloud service in between. learning_objectives: - - Understand Device Connect Edge SDK primitives and use them to build a device driver that exposes capabilities like discovery, RPC, events, and status to other peers on the mesh + - Understand Device Connect Edge SDK primitives - Set up a Python environment for Device Connect with no hardware required - - Build two cooperating drivers, a simulated sensor that exposes an RPC method and emits readings on a schedule, and a threshold monitor that subscribes to those events with `@on` and emits its own alerts in response - - Run both devices as independent runtimes and watch them discover and invoke each other on the same network + - Build two simulated devices - Use the Device Connect agent tools to discover both devices on the mesh and invoke their RPCs prerequisites: @@ -31,6 +30,7 @@ armips: operatingsystems: - Linux - macOS + - Windows tools_software_languages: - Python diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md index 60fc1678de..a6b5a38893 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md @@ -51,13 +51,4 @@ In D2D mode, every participant is a peer. Each device runtime joins the same pub No central server sits between the sensor and the monitor. They advertise themselves, find each other by event name, and exchange typed payloads directly. -## What you'll learn - -By the end of this Learning Path you will: - -- set up a Python project with uv, the Device Connect runtime, and the agent tools -- write two cooperating drivers: a simulated sensor and a threshold monitor that reacts to it -- run both as independent device runtimes on one machine -- use the Device Connect agent tools to discover both peers and invoke their RPCs - -The next section covers the developer model. +Move on to the next section to have a look at the developer model. diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md index 605d0454a7..f4d65df37e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md @@ -17,17 +17,14 @@ This mirrors a real edge scenario, a room supervisor watching environmental sens This walkthrough uses [uv](https://docs.astral.sh/uv/) to manage the project and its Python dependencies. uv will resolve a compatible Python interpreter, create a virtual environment, and install packages for you, so no manual `venv` or `pip` steps are needed. -If you do not already have uv installed, run the official installer for your platform: - -```bash -# macOS or Linux +{{< tabpane code=true >}} + {{< tab header="macOS or Linux" language="shell">}} curl -LsSf https://astral.sh/uv/install.sh | sh -``` - -```powershell -# Windows PowerShell + {{< /tab >}} + {{< tab header="Windows" language="powershell">}} powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` + {{< /tab >}} +{{< /tabpane >}} Alternative install methods (Homebrew, pipx, and others) are listed in the [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/). Verify the install with: @@ -244,7 +241,15 @@ print("recent alerts:", invoke_device(monitor_id, "get_recent_alerts")) PY ``` -The script discovers both devices, invokes `get_reading` on the sensor, and invokes `get_recent_alerts` on the monitor. The alert list should contain every breach the monitor has observed since it started. +The script discovers both devices, invokes `get_reading` on the sensor, and invokes `get_recent_alerts` on the monitor. The alert list should contain every breach the monitor has observed since it started: + +``` +Found 2 device(s) + monitor-001 (threshold_monitor) + sensor-001 (simulated_sensor) +latest reading: {'success': True, 'result': {'temperature': 27.5, 'humidity': 53.5}} +recent alerts: {'success': True, 'result': [{'device_id': 'sensor-001', 'temperature': 27.9}, {'device_id': 'sensor-001', 'temperature': 28.7}, {'device_id': 'sensor-001', 'temperature': 28.2}, {'device_id': 'sensor-001', 'temperature': 28.1}, {'device_id': 'sensor-001', 'temperature': 29.2}, {'device_id': 'sensor-001', 'temperature': 28.6}, {'device_id': 'sensor-001', 'temperature': 27.7}, {'device_id': 'sensor-001', 'temperature': 28.9}, {'device_id': 'sensor-001', 'temperature': 29.0}, {'device_id': 'sensor-001', 'temperature': 27.5}]} +``` ## What happened diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md index 00e6496381..f1d2d845db 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md @@ -1,14 +1,12 @@ --- -title: The developer model +title: Device Connect developer model weight: 3 # FIXED, DO NOT MODIFY layout: learningpathall --- -## Device Connect developer model - -### Device Connect Edge SDK +## Device Connect Edge SDK The [`device-connect-edge`](https://pypi.org/project/device-connect-edge/) package is the Python SDK you install on every device that joins a Device Connect network. It provides the building blocks for creating a device runtime: the `DeviceDriver` base class you subclass to describe a device, the decorators used to expose its capabilities to peers and agents, and the `DeviceRuntime` that brings a driver online on the network. @@ -16,25 +14,25 @@ You describe a device by subclassing `DeviceDriver` from `device_connect_edge.dr In this Learning Path you'll use these primitives to write two cooperating drivers: a **sensor** runtime that publishes temperature and humidity readings on a schedule, and a **threshold monitor** runtime that reacts to those readings and raises alerts when a threshold is crossed. The subsections below walk through the identity, decorators, and runtime you'll use to build them, and the agent tools package you'll use to invoke them from a separate client. -#### Identity and status +### Identity and status Every driver declares who it is and how it is doing. These are properties, not decorators: - `identity` returns a `DeviceIdentity` (device type, manufacturer, model, description). This is what peers see during discovery. - `status` returns a `DeviceStatus` (availability, location, optional health fields). This is the live signal other peers use to decide if the device is reachable and usable. -#### Behavior decorators +### Behavior decorators - `@rpc()`: exposes a method as a remote procedure. Other peers or agents call it by device ID and method name; the return value is serialized back to the caller. - `@emit()`: declares that the method is an event publisher. Calling it inside the driver emits the event to any peer subscribed to it. - `@periodic(interval=)`: runs the method on a fixed schedule once the runtime starts. Useful for sampling, heartbeats, or housekeeping. - `@on(event_name=, device_type=)`: subscribes the method to events emitted by other devices. The runtime delivers matching events as method calls with the source device id, event name, and a payload dict. -#### Runtime +### Runtime `DeviceRuntime(driver=..., device_id=..., allow_insecure=...)` wraps your driver in a process that joins the pub/sub transport, advertises identity and status, and dispatches incoming RPCs and events to the decorated methods. You call `await runtime.run()` to keep it alive. -### Device Connect Agent tools +## Device Connect Agent tools The [`device-connect-agent-tools`](https://pypi.org/project/device-connect-agent-tools/) package is the companion SDK for the client side of a Device Connect network: anything that wants to interact with devices on the mesh, from a short script or REPL to a full AI agent. It exposes a small set of functions that mirror the core capabilities of the protocol: @@ -46,7 +44,7 @@ Any Python process that imports this package can find and drive devices without ## What you'll build -In this Learning Path you will build two cooperating simulated devices on the same local network: +In the next section you will create two cooperating simulated devices on the same local network: - a **sensor** driver that publishes temperature and humidity readings on a schedule using `@rpc`, `@emit`, and `@periodic` - a **threshold monitor** driver that uses `@on` to subscribe to the sensor's readings, emits its own `alert_raised` event when a reading crosses a threshold, and exposes the alert history through an `@rpc` method