ver0.2

README.md

@@ -1,199 +1,126 @@
-# SwarmPlug
+# SwarmPlug ver0.2
 
-**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)
+**Canonical Identity Specification**
 
 ---
 
-## 1. What does SwarmPlug do?
+## Statement
 
-SwarmPlug focuses on one fundamental problem in swarm robotics:
+SwarmPlug ver0.2 defines a canonical identity specification layer  
+above host attachment.
 
-> **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?**
+It does not snapshot.  
+It does not transmit.  
+It does not coordinate.
 
-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.
+**It standardizes identity.**
 
 ---
 
-## 2. What ver0.1 proves
+## Problem
 
-This ver0.1 demo validates the following capabilities:
+ROS deployments often exhibit inconsistent naming patterns across:
 
-- ✅ 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
+- Devices
+- Networks    
+- Deployments
 
 
-This version focuses on **connectivity and observability**, not on control or task logic.
+Without canonical identity,  
+cross-system semantic alignment becomes ambiguous.
 
 ---
 
-## 3. Repository scope
+## Position
 
-### Included in this repository
+SwarmPlug ver0.2 defines a stable identity anchor  
+independent of host runtime naming.
 
-- 📄 Documentation and usage examples
-
-- 🧩 High-level architecture description
-
-- 🖥 CLI command demonstrations
-
-- 🕒 Public release timestamp (ver0.1)
-
+`ROS Runtime → Host Attachment → Canonical Identity`
 
-### Not included in this repository
+**ver0.2 completes the identity normalization layer.**
 
-- ❌ Core synchronization algorithms
-
-- ❌ Commercial SwarmPlug implementation
-
-- ❌ Protocol adapters and internal optimizations
-
-- ❌ Appliance / firmware images
-
+---
 
-> This separation is intentional and aligns with the commercial roadmap.
+## Architecture (Conceptual)
 
----
+```mermaid
+flowchart TB
 
-## 4. Architecture overview (high level)
+  subgraph L1["Host Runtime"]
+    A1["ROS Topics / Nodes"]
+  end
 
-SwarmPlug runs **locally on each device**, alongside the local ROS master.
+  subgraph L2["Host Attachment (ver0.1)"]
+    B1["Discovery Layer"]
+  end
 
-Each instance:
+  subgraph L3["Canonical Identity (ver0.2)"]
+    C1["host_id"]
+    C2["node_id"]
+    C3["Canonical Naming Rules"]
+  end
 
-- Interfaces with its local ROS graph
-
-- Participates in a decentralized association process
-
-- Exposes a unified swarm view through a CLI
-
+  A1 --> B1 --> C1
+  B1 --> C2
+  C1 --> C3
 
 ```
-ROS Nodes  →  Local ROS Master
-                │
-                ▼
-           SwarmPlug Module
-                │
-      ── Association Layer ──
-                │
-           Swarm-wide View
-                │
-                ▼
-           swarmplug CLI
 
-```
 ---
 
-## 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
+## Determinism
 
-```
-swarmplug topics
-```
+Given identical host configuration,  
+ver0.2 produces identical canonical identity anchors.
 
-### Echo a topic from the swarm
-```
-swarmplug echo /topic1
-```
+Identity remains invariant across:
 
-### List ROS parameters discovered in the swarm
+- System reboots
+- Network reconfiguration
+- Deployment relocation
 
-```
-swarmplug parameters
+---
 
-```
+## Scope Limitation
 
-### Read a specific parameter
+SwarmPlug ver0.2 does not include:
 
-```
-swarmplug echo /turtlesim/background_b
-```
+- State abstraction    
+- Snapshot schema   
+- Communication layers    
+- Blockchain anchoring    
+- Decision mechanisms
 
-These commands allow developers to **inspect swarm state without manually logging into each device**.
+**ver0.2 does not modify host runtime behavior.**
 
 ---
 
-## 6. Typical demo scenario
+## Version Context
 
-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
-
-
-After association:
-
-- All participating devices can observe selected ROS entities
-
-- CLI commands return a **swarm-consistent view**
-
-
-This validates decentralized discovery and visibility.
+| Version | Responsibility        |
+|---------|----------------------|
+| ver0.1  | Host attachment      |
+| ver0.2  | Canonical identity   |
+| ver0.3  | Semantic snapshot    |
 
 ---
 
-## 7. Current status
+## Principle
 
-- **Public demo release:** ver0.1
-
-- **Focus:** association & introspection
-
-- **Next milestone:** ver0.2 (feature expansion & stability improvements)
-
+Identity precedes semantics.  
+Normalization precedes distribution.
 
-The roadmap prioritizes robustness, modularity, and compatibility with heterogeneous robotic platforms.
+ver0.2 establishes the identity layer.
 
 ---
+## License
 
-## 8. License & usage
-
-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**