Ver0.1

README.md

@@ -1,199 +1,111 @@
-# SwarmPlug
+# SwarmPlug ver0.1
 
-**SwarmPlug** is a plug-and-play connectivity layer for **ROS1-based multi-agent systems**,  
-designed to enable decentralized **association, introspection, and coordination** across heterogeneous robotic swarms.
-
-> 🚩 This repository is a **public demo & timestamp anchor** for **SwarmPlug ver0.1**.  
-> It demonstrates core capabilities and interfaces, **without exposing the commercial core implementation**.
-![MyVideo_1](https://github.com/user-attachments/assets/b9444de8-d616-4299-8397-fcf16fdf4df1)
-
----
-
-## 1. What does SwarmPlug do?
-
-SwarmPlug focuses on one fundamental problem in swarm robotics:
-
-> **How can multiple ROS-based agents, running independent ROS masters on different devices, discover each other and share selected ROS interfaces in a decentralized way?**
-
-SwarmPlug provides:
-
-- A lightweight **association layer** between devices
-
-- Unified **introspection** of swarm-wide ROS entities
-
-- A simple **CLI interface** to inspect swarm state
-
-
-No cloud, no central server, no monolithic ROS master.
+**Host Attachment Specification**
 
 ---
 
-## 2. What ver0.1 proves
+## Statement
 
-This ver0.1 demo validates the following capabilities:
+SwarmPlug ver0.1 defines a deterministic host attachment specification  
+between SwarmPlug and a ROS runtime environment.
 
-- ✅ Cross-device association between multiple ROS1 nodes
-
-- ✅ Swarm-wide discovery of:
-
-    - ROS nodes
-
-    - ROS topics
-
-    - ROS parameters
-
-- ✅ Command-line introspection of swarm state
-
-- ✅ End-to-end “hello world” topic exchange across devices
-
+It does not normalize.  
+It does not snapshot.  
+It does not coordinate.  
 
-This version focuses on **connectivity and observability**, not on control or task logic.
+**It attaches.**
 
 ---
 
-## 3. Repository scope
+## Problem
 
-### Included in this repository
+Before semantic abstraction or coordination can occur,  
+a reliable host attachment layer must exist.
 
-- 📄 Documentation and usage examples
-
-- 🧩 High-level architecture description
-
-- 🖥 CLI command demonstrations
-
-- 🕒 Public release timestamp (ver0.1)
-
+A ROS runtime exposes its operational surface through:
 
-### Not included in this repository
+- ROS Master (XMLRPC)
+- Topics
+- Services
+- Parameters
 
-- ❌ Core synchronization algorithms
-
-- ❌ Commercial SwarmPlug implementation
-
-- ❌ Protocol adapters and internal optimizations
-
-- ❌ Appliance / firmware images
-
-
-> This separation is intentional and aligns with the commercial roadmap.
+**A sidecar infrastructure must attach and discover these interfaces consistently.**
 
 ---
 
-## 4. Architecture overview (high level)
-
-SwarmPlug runs **locally on each device**, alongside the local ROS master.
+## Position
 
-Each instance:
+SwarmPlug ver0.1 defines the host attachment boundary.
 
-- Interfaces with its local ROS graph
-
-- Participates in a decentralized association process
-
-- Exposes a unified swarm view through a CLI
-
+`ROS Runtime → SwarmPlug Attachment`
 
-```
-ROS Nodes  →  Local ROS Master
-                │
-                ▼
-           SwarmPlug Module
-                │
-      ── Association Layer ──
-                │
-           Swarm-wide View
-                │
-                ▼
-           swarmplug CLI
+**ver0.1 completes the connection and discovery layer.**
 
-```
 ---
 
-## 5. CLI demo (ver0.1)
-
-The following commands illustrate the ver0.1 demo behavior.
-
-### List swarm members
-
-```
-swarmplug nodes
-```
-
-### List visible ROS topics across the swarm
+## Architecture (Conceptual)
 
-```
-swarmplug topics
-```
+```mermaid
+flowchart TB
 
-### Echo a topic from the swarm
-```
-swarmplug echo /topic1
-```
+  subgraph L1["Host Runtime"]
+    A1["ROS Master"]
+    A2["Topics / Services / Params"]
+  end
 
-### List ROS parameters discovered in the swarm
+  subgraph L2["SwarmPlug ver0.1"]
+    B1["Connection Layer"]
+    B2["Discovery Interface"]
+  end
 
+  A1 --> B1
+  A2 --> B2
 ```
-swarmplug parameters
 
-```
+## Determinism
 
-### Read a specific parameter
+Given a reachable ROS master,
+ver0.1 deterministically discovers:
 
-```
-swarmplug echo /turtlesim/background_b
-```
+- Topics
+- Nodes
+- Services
+- Parameters
 
-These commands allow developers to **inspect swarm state without manually logging into each device**.
+**No transformation, mutation, or interception is performed.**
 
----
-
-## 6. Typical demo scenario
-
-A minimal demonstration setup may include:
-
-- Device A: ROS1 node publishing `/topic1`
-
-- Device B: SwarmPlug-enabled node associated with A
-
-- Device C: Another ROS1 node joining later
-
+## Scope Limitation
 
-After association:
+SwarmPlug ver0.1 does not include:
 
-- All participating devices can observe selected ROS entities
-
-- CLI commands return a **swarm-consistent view**
-
+- Canonical naming
+- Semantic abstraction
+- Snapshot generation
+- Communication transport
+- Coordination logic
 
-This validates decentralized discovery and visibility.
+## Version Context
+| Version | Responsibility        |
+|---------|----------------------|
+| ver0.1  | Host attachment      |
+| ver0.2  | Canonical naming     |
+| ver0.3  | Semantic snapshot    |
 
----
-
-## 7. Current status
+## Principle
 
-- **Public demo release:** ver0.1
-
-- **Focus:** association & introspection
-
-- **Next milestone:** ver0.2 (feature expansion & stability improvements)
-
+Attachment precedes abstraction.
+Discovery precedes normalization.
 
-The roadmap prioritizes robustness, modularity, and compatibility with heterogeneous robotic platforms.
+ver0.1 establishes the attachment layer.
 
----
 
-## 8. License & usage
+## License
 
-This repository is provided **for demonstration and evaluation purposes only**.
+This version specification is part of the SwarmPlug documentation.
 
-- Commercial use of SwarmPlug core requires authorization
-
-- Internal implementations are not open-sourced in this repository
-
+Licensed under the **SwarmPlug Documentation License v1.0**.
 
----
+See the **main LICENSE** file for details.
 
-## 9. Contact
 
-For collaboration, evaluation, or commercial inquiries:
 
-📧 **qyswarm@163.com**