device-connect-server 0.1.0__tar.gz

device_connect_server-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+Copyright 2024-2026 Arm Limited
+PROPRIETARY AND CONFIDENTIAL
+All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Arm Limited. The Software is
+provided under a separate Non-Disclosure Agreement (NDA) and may not be
+used, copied, modified, merged, published, distributed, sublicensed, or
+sold except as expressly permitted by that agreement.
+
+Unauthorized copying, distribution, or use of this Software is strictly
+prohibited and may result in civil and criminal penalties.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL ARM
+LIMITED BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM
+THE USE OF THE SOFTWARE.
+
+---
+
+NOTE: This software is intended for future release under the Apache License,
+Version 2.0. The open-source license will become effective upon public release.

device_connect_server-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: device-connect-server
+Version: 0.1.0
+Summary: Device Connect — edge device runtime with Zenoh/NATS messaging, D2D communication, and IoT orchestration
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: device-connect-sdk>=0.1.0
+Provides-Extra: security
+Requires-Dist: bcrypt>=4.0.0; extra == "security"
+Requires-Dist: aiohttp>=3.9.0; extra == "security"
+Requires-Dist: zeroconf>=0.131.0; extra == "security"
+Requires-Dist: qrcode[pil]>=7.4.2; extra == "security"
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.30.0; extra == "telemetry"
+Requires-Dist: opentelemetry-sdk>=1.30.0; extra == "telemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.30.0; extra == "telemetry"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.30.0; extra == "telemetry"
+Provides-Extra: state
+Requires-Dist: etcd3gw<3,>=2.4.0; extra == "state"
+Provides-Extra: logging
+Requires-Dist: pymongo; extra == "logging"
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt; extra == "mqtt"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: device-connect-server[dev,logging,mqtt,security,state,telemetry]; extra == "all"
+Dynamic: license-file

device_connect_server-0.1.0/README.md

@@ -0,0 +1,301 @@
+<p align="center">
+  <img src="../../logo.svg" alt="Device Connect" width="400">
+</p>
+
+# device-connect-server
+
+Server-side runtime for the Device Connect framework. Extends [device-connect-sdk](../device-connect-sdk/) with device registry, security (commissioning, ACLs), distributed state, audit logging, and CLI tools.
+
+## Contents
+
+- [Where This Fits](#where-this-fits)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [CLI Tools](#cli-tools)
+- [Device Commissioning Flow](#device-commissioning-flow)
+- [Testing](#testing)
+- [Contributing](#contributing)
+
+## Where This Fits
+
+```
+  device-connect-sdk          device-connect-server           device-connect-agent-tools
+  (Device Connect SDK)    (server runtime — this)   (agent SDK)
+        │                         │                         │
+        └──────────────── Mesh ─────────────────────────────┘
+```
+
+- **device-connect-sdk** — runs on physical devices (Raspberry Pi, robots, cameras, sensors)
+- **device-connect-server** — runs on servers. Adds registry, security, state, and CLIs
+- **device-connect-agent-tools** — connects AI agents (Strands, LangChain, MCP) to the device mesh
+
+## Install
+
+> Not yet on PyPI. Install from Git:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e "../device-connect-sdk"
+pip install -e ".[all]"
+```
+
+This pulls in `device-connect-sdk` automatically. Optional extras:
+
+| Extra | Adds |
+|-------|------|
+| `[security]` | bcrypt, aiohttp, zeroconf, qrcode (commissioning + ACLs) |
+| `[telemetry]` | OpenTelemetry SDK + OTLP exporters |
+| `[state]` | etcd3gw (distributed state store) |
+| `[logging]` | pymongo (audit logging to MongoDB) |
+| `[mqtt]` | aiomqtt (MQTT messaging backend) |
+| `[all]` | All of the above + dev tools |
+
+> **Note:** Zenoh is now a core dependency of `device-connect-sdk` and is included automatically.
+
+## Quick Start
+
+> **Prerequisites:** Complete the [Install](#install) steps first (venv active, packages installed). You also need Docker. For JWT auth you additionally need [nsc](https://github.com/nats-io/nsc) (`brew install nsc`).
+
+### 1. Start infrastructure
+
+Choose a deployment mode:
+
+<details open>
+<summary><b>Zenoh (dev mode, no auth)</b></summary>
+
+```bash
+docker compose -f infra/docker-compose-dev.yml up -d
+```
+
+</details>
+
+<details>
+<summary><b>Secure — Zenoh (TLS)</b></summary>
+
+```bash
+# 1. Generate CA + Zenoh router + registry client certificates
+./security_infra/generate_tls_certs.sh zenoh
+
+# 2. Generate a client certificate for each device
+./security_infra/generate_tls_certs.sh --client rng-001
+
+# 3. Start infrastructure with TLS
+docker compose -f infra/docker-compose.yml up -d
+```
+
+</details>
+
+<details>
+<summary><b>NATS (dev mode, no auth)</b></summary>
+
+```bash
+docker compose -f infra/docker-compose-nats-dev.yml up -d
+```
+
+</details>
+
+<details>
+<summary><b>Authenticated — NATS (JWT auth)</b></summary>
+
+```bash
+# 1. Generate NATS JWT config
+./security_infra/setup_jwt_auth.sh dev
+
+# 2. Generate credentials for built-in roles (registry, devctl)
+./security_infra/gen_creds.sh --all --force
+
+# 3. Generate credentials for each device and agent
+./security_infra/gen_creds.sh --user rng-001
+./security_infra/gen_creds.sh --user my-agent
+
+# 4. Start infrastructure with JWT auth
+docker compose -f infra/docker-compose-nats.yml up -d
+```
+
+</details>
+
+| Service | Port | Purpose |
+|---------|------|---------|
+| zenoh | 7447 | Zenoh messaging |
+| nats / nats-jwt | 4222 | NATS messaging |
+| etcd | 2379 | Distributed state store |
+| device-registry-service | 8080 | Device registration and discovery |
+
+### 2. Connect a simulated device
+
+The number generator simulator connects to the messaging backend, registers itself with the device registry, and emits `number_generated` events every 5 seconds.
+
+```bash
+cd ../device-connect-sdk  # sibling package in the monorepo
+
+# Zenoh (dev mode, no auth)
+DEVICE_CONNECT_ALLOW_INSECURE=true ZENOH_CONNECT=tcp/localhost:7447 \
+  python examples/number_generator/device_simulator.py
+
+# Secure — Zenoh (TLS)
+# ZENOH_CONNECT=tls/localhost:7447 \
+#   MESSAGING_TLS_CA_FILE=../device-connect-server/security_infra/ca.pem \
+#   MESSAGING_TLS_CERT_FILE=../device-connect-server/security_infra/rng-001-cert.pem \
+#   MESSAGING_TLS_KEY_FILE=../device-connect-server/security_infra/rng-001-key.pem \
+#   python examples/number_generator/device_simulator.py
+
+# Insecure — NATS (no auth)
+# DEVICE_CONNECT_ALLOW_INSECURE=true python examples/number_generator/device_simulator.py
+
+# Authenticated — NATS (JWT auth)
+# NATS_CREDENTIALS_FILE=~/.device-connect/credentials/rng-001.creds.json \
+#   NATS_URL=nats://localhost:4222 python examples/number_generator/device_simulator.py
+```
+
+### 3. Verify the device registered
+
+`devctl list` queries the registry service and returns all connected devices with their capabilities, identity, and status. `statectl` reads the same data directly from etcd.
+
+```bash
+# Zenoh (dev mode, no auth)
+ZENOH_CONNECT=tcp/localhost:7447 devctl list
+statectl --raw list /device-connect/default/devices/
+
+# Secure — Zenoh (TLS)
+# ZENOH_CONNECT=tls/localhost:7447 \
+#   MESSAGING_TLS_CA_FILE=security_infra/ca.pem \
+#   MESSAGING_TLS_CERT_FILE=security_infra/rng-001-cert.pem \
+#   MESSAGING_TLS_KEY_FILE=security_infra/rng-001-key.pem \
+#   devctl list
+
+# Insecure — NATS (no auth)
+# devctl list
+
+# Authenticated — NATS (JWT auth)
+# NATS_CREDENTIALS_FILE=~/.device-connect/credentials/devctl.creds.json \
+#   NATS_URL=nats://localhost:4222 devctl list
+```
+
+### 4. Connect an AI agent
+
+The Strands Agent subscribes to all device events on the mesh (`device-connect.default.*.event.>`), batches them over a time window, and sends them to Claude for analysis. Claude can call back into devices using `invoke_device()` and `get_device_status()` tools.
+
+```bash
+git clone https://github.com/arm/strands-device-connect-example.git
+cd strands-device-connect-example
+pip install -r requirements.txt
+
+# Insecure — Zenoh (no auth)
+ZENOH_CONNECT=tcp/localhost:7447 \
+  ANTHROPIC_API_KEY="sk-ant-..." python strands_agent.py
+
+# Secure — Zenoh (TLS)
+# ZENOH_CONNECT=tls/localhost:7447 \
+#   MESSAGING_TLS_CA_FILE=../device-connect-server/security_infra/ca.pem \
+#   MESSAGING_TLS_CERT_FILE=../device-connect-server/security_infra/my-agent-cert.pem \
+#   MESSAGING_TLS_KEY_FILE=../device-connect-server/security_infra/my-agent-key.pem \
+#   ANTHROPIC_API_KEY="sk-ant-..." python strands_agent.py
+
+# Insecure — NATS (no auth)
+# ANTHROPIC_API_KEY="sk-ant-..." python strands_agent.py
+
+# Authenticated — NATS (JWT auth)
+# ANTHROPIC_API_KEY="sk-ant-..." \
+#   NATS_CREDENTIALS_FILE=~/.device-connect/credentials/my-agent.creds.json \
+#   NATS_URL=nats://localhost:4222 python strands_agent.py
+```
+
+> Get an API key at [console.anthropic.com](https://console.anthropic.com/).
+
+### 5. Tear down
+
+```bash
+# Insecure — Zenoh (no auth)
+docker compose -f infra/docker-compose-dev.yml down
+
+# Secure — Zenoh (TLS)
+# docker compose -f infra/docker-compose.yml down
+
+# Insecure — NATS (no auth)
+# docker compose -f infra/docker-compose-nats-dev.yml down
+
+# Authenticated — NATS (JWT auth)
+# docker compose -f infra/docker-compose-nats.yml down
+```
+
+To clean up everything:
+
+```bash
+rm -rf .venv
+rm -rf ~/.device-connect/credentials
+rm -rf security_infra/.nsc security_infra/nats-jwt-generated.conf
+rm -f security_infra/*.pem security_infra/*.srl
+```
+
+See [device-connect-sdk — Credentials](../device-connect-sdk/README.md#credentials) for the credentials file format.
+
+## CLI Tools
+
+```bash
+# Device control
+devctl list                                # list registered devices
+devctl list --compact                      # compact output
+devctl register --id myDevice --keepalive  # register a test device
+devctl discover --timeout 5               # find uncommissioned devices (mDNS)
+devctl commission cam-001 --pin 1234-5678  # commission a device
+devctl interactive                         # REPL for device operations
+
+# State management
+statectl get experiments/EXP-001           # read a key
+statectl list experiments/                 # list keys under prefix
+statectl set experiments/EXP-001 '{"status": "done"}' --ttl 3600
+statectl delete experiments/EXP-001        # delete a key
+statectl watch experiments/ --prefix       # watch for changes
+statectl locks                             # list held locks
+statectl stats                             # key counts by namespace
+```
+
+## Device Commissioning Flow
+
+New devices must be provisioned and commissioned before joining the mesh. The mechanism depends on your messaging backend:
+
+- **Zenoh** — uses mTLS (mutual TLS). Each device gets a client certificate signed by the shared CA. Generate one with `./security_infra/generate_tls_certs.sh --client <device-id>`.
+- **NATS** — uses JWT credentials. Each device gets a JWT + NKey pair. Generate one with `./security_infra/gen_creds.sh --user <device-id>`.
+
+### NATS JWT commissioning (detailed)
+
+Using `camera-001` as an example:
+
+1. **Provision** (factory): generate an identity with NKey keypair + factory PIN
+2. **Generate credentials** (admin): `./security_infra/gen_creds.sh --user camera-001`
+3. **Commission** (admin): `devctl commission camera-001 --pin 1234-5678`
+   - Delivers credentials to the device's commissioning HTTP server
+   - Device saves credentials and connects to NATS
+4. **Operate** (every boot): device loads credentials from disk, connects, registers, starts heartbeats
+
+Each device becomes a user under the shared DEVICE-CONNECT account — all users in the same account can communicate over `device-connect.*` subjects:
+
+```
+Operator: dc-operator              (trust root)
+  └─ Account: DEVICE-CONNECT       (shared namespace)
+       ├─ User: registry            (registry service)
+       ├─ User: devctl              (CLI tools)
+       ├─ User: orchestrator        (server coordination)
+       ├─ User: camera-001          (per-device, via --user)
+       └─ User: my-agent            (AI agent, via --user)
+```
+
+See [device-connect-sdk — Credentials](../device-connect-sdk/README.md#credentials) for how devices consume credentials at runtime.
+
+AI agents connecting via [device-connect-agent-tools](../device-connect-agent-tools/) also need their own credentials: `./security_infra/gen_creds.sh --user my-agent` (NATS) or `./security_infra/generate_tls_certs.sh --client my-agent` (Zenoh).
+
+## Testing
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[all]"
+pytest tests/ -v --timeout=30
+```
+
+Unit tests run without external services. Integration tests are in [tests/](../../tests/).
+
+## Contributing
+
+We welcome contributions! Please open an [issue](https://github.com/arm/device-connect/issues) to report bugs or suggest features, or submit a [pull request](https://github.com/arm/device-connect/pulls) directly.

device_connect_server-0.1.0/device_connect_server/__init__.py

@@ -0,0 +1,81 @@
+"""Device Connect - Edge device orchestration framework.
+
+This package re-exports everything from device_connect_sdk (the lightweight
+device SDK) and adds core extensions: registry, security, state, logging,
+CapabilityLoader, devctl, and statectl.
+
+Core Components:
+    - DeviceRuntime: Runtime that hosts a DeviceDriver (handles messaging, registration, heartbeats)
+    - DeviceDriver: Abstract base for device-specific logic
+    - DeviceCapabilities, DeviceIdentity, DeviceStatus: Type definitions
+
+Submodules:
+    - device_connect_server.drivers: Device driver framework with decorators
+    - device_connect_server.messaging: Pluggable messaging (NATS, MQTT)
+    - device_connect_server.security: ACLs, commissioning, credentials
+    - device_connect_server.state: State store abstractions
+    - device_connect_server.registry: Registry client and service
+    - device_connect_server.telemetry: OpenTelemetry distributed tracing
+    - device_connect_server.logging: Audit logging framework
+    - device_connect_server.devctl: Device control CLI
+    - device_connect_server.statectl: State management CLI
+
+Example:
+    from device_connect_server import DeviceRuntime
+    from device_connect_server.drivers import DeviceDriver, rpc
+    from device_connect_server.types import DeviceCapabilities
+
+    class CameraDriver(DeviceDriver):
+        device_type = "camera"
+
+        @rpc()
+        async def capture_image(self, resolution: str = "1080p") -> dict:
+            '''Capture an image.'''
+            return {"image_b64": "..."}
+
+    device = DeviceRuntime(
+        driver=CameraDriver(),
+        device_id="camera-001",
+        messaging_urls=["nats://localhost:4222"]
+    )
+    await device.run()
+"""
+# Re-export everything from device_connect_sdk
+from device_connect_sdk import (  # noqa: F401
+    DeviceRuntime,
+    build_rpc_error,
+    build_rpc_response,
+    DeviceState,
+    DeviceCapabilities,
+    DeviceIdentity,
+    DeviceStatus,
+    FunctionDef,
+    EventDef,
+    DeviceConnectError,
+    DeviceError,
+    RegistrationError,
+    FunctionInvocationError,
+    ValidationError,
+    CommissioningError,
+)
+
+__all__ = [
+    # Device runtime
+    "DeviceRuntime",
+    "build_rpc_error",
+    "build_rpc_response",
+    # Types
+    "DeviceState",
+    "DeviceCapabilities",
+    "DeviceIdentity",
+    "DeviceStatus",
+    "FunctionDef",
+    "EventDef",
+    # Errors
+    "DeviceConnectError",
+    "DeviceError",
+    "RegistrationError",
+    "FunctionInvocationError",
+    "ValidationError",
+    "CommissioningError",
+]

device_connect_server-0.1.0/device_connect_server/devctl/__init__.py

@@ -0,0 +1,16 @@
+"""Device control CLI for Device Connect.
+
+This module provides a command-line interface for interacting with
+the device registry, commissioning devices, and performing device operations.
+
+CLI Usage:
+    python -m device_connect_server.devctl list [--compact]
+    python -m device_connect_server.devctl register --id myDevice [--keepalive]
+    python -m device_connect_server.devctl discover [--timeout 5]
+    python -m device_connect_server.devctl commission <device_id> --pin 1234-5678
+    python -m device_connect_server.devctl interactive
+"""
+
+from device_connect_server.devctl.cli import main
+
+__all__ = ["main"]

device_connect_server-0.1.0/device_connect_server/devctl/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point for running devctl as a module.
+
+Usage:
+    python -m device_connect_server.devctl list
+    python -m device_connect_server.devctl register --id myDevice
+    python -m device_connect_server.devctl discover
+    python -m device_connect_server.devctl commission <device_id> --pin 1234-5678
+    python -m device_connect_server.devctl interactive
+    python -m device_connect_server.devctl --help
+"""
+
+from device_connect_server.devctl.cli import main
+
+if __name__ == "__main__":
+    main()