Initial commit

docs/user_guide/configuration.md

@@ -0,0 +1,120 @@
+# Uni-Lab 配置指南
+
+Uni-Lab支持通过Python配置文件进行灵活的系统配置。本指南将帮助您理解配置选项并设置您的Uni-Lab环境。
+
+## 配置文件格式
+
+Uni-Lab支持Python格式的配置文件，它比YAML或JSON提供更多的灵活性，包括支持注释、条件逻辑和复杂数据结构。
+
+### 基本配置示例
+
+一个典型的配置文件包含以下部分：
+
+```python
+#!/usr/bin/env python
+# coding=utf-8
+"""Uni-Lab 配置文件"""
+
+from dataclasses import dataclass
+
+# 配置类定义
+@dataclass
+class MQConfig:
+    """MQTT 配置类"""
+    lab_id: str = "YOUR_LAB_ID"
+    # 更多配置...
+
+# 其他配置类...
+```
+
+## 配置选项说明
+
+### MQTT配置 (MQConfig)
+
+MQTT配置用于连接消息队列服务，是Uni-Lab与云端通信的主要方式。
+
+```python
+@dataclass
+class MQConfig:
+    """MQTT 配置类"""
+    lab_id: str = "7AAEDBEA"  # 实验室唯一标识
+    instance_id: str = "mqtt-cn-instance"
+    access_key: str = "your-access-key"
+    secret_key: str = "your-secret-key"
+    group_id: str = "GID_labs"
+    broker_url: str = "mqtt-cn-instance.mqtt.aliyuncs.com"
+    port: int = 8883
+    
+    # 可以直接提供证书文件路径
+    ca_file: str = "/path/to/ca.pem"
+    cert_file: str = "/path/to/cert.pem"
+    key_file: str = "/path/to/key.pem"
+    
+    # 或者直接提供证书内容
+    ca_content: str = ""
+    cert_content: str = ""
+    key_content: str = ""
+```
+
+#### 证书配置
+
+MQTT连接支持两种方式配置证书：
+
+1. **文件路径方式**（推荐）：指定证书文件的路径，系统会自动读取文件内容
+2. **直接内容方式**：直接在配置中提供证书内容
+
+推荐使用文件路径方式，便于证书的更新和管理。
+
+### HTTP客户端配置 (HTTPConfig)
+
+即将开放 Uni-Lab 云端实验室。
+
+### ROS模块配置 (ROSConfig)
+
+配置ROS消息转换器需要加载的模块：
+
+```python
+@dataclass
+class ROSConfig:
+    """ROS模块配置"""
+    modules: list = None
+    
+    def __post_init__(self):
+        if self.modules is None:
+            self.modules = [
+                "std_msgs.msg",
+                "geometry_msgs.msg",
+                "control_msgs.msg",
+                "control_msgs.action",
+                "nav2_msgs.action",
+                "unilabos_msgs.msg",
+                "unilabos_msgs.action",
+            ]
+```
+
+您可以根据需要添加其他ROS模块。
+
+### 其他配置选项
+
+- **OSSUploadConfig**: 对象存储上传配置
+
+## 如何使用配置文件
+
+启动Uni-Lab时通过`--config`参数指定配置文件路径：
+
+```bash
+unilab --config path/to/your/config.py
+```
+
+## 环境变量覆盖
+
+某些配置项可以通过环境变量进行覆盖，这在不同环境部署时特别有用：
+
+```bash
+# 设置环境变量覆盖配置
+export UNILAB_LAB_ID="YOUR_LAB_ID"
+export UNILAB_MQTT_BROKER="mqtt-broker-address"
+
+# 启动Uni-Lab
+python -m unilabos.app.main --config path/to/your/config.py
+```

docs/user_guide/installation.md

@@ -0,0 +1,24 @@
+# **Uni-Lab 安装**
+
+请先 `git clone` 本仓库，随后按照以下步骤安装项目：
+
+`Uni-Lab` 建议您采用 `mamba` 管理环境。若需从头建立 `Uni-Lab` 的运行依赖环境，请执行
+
+```shell
+mamba env create -f unilabos-<YOUR_OS>.yaml
+mamba activate ilab
+```
+
+其中 `YOUR_OS` 是您的操作系统，可选值 `win64`, `linux-64`, `osx-64`, `osx-arm64`
+
+若需将依赖安装进当前环境，请执行
+
+```shell
+conda env update --file unilabos-<YOUR_OS>.yml
+```
+
+随后，可在本仓库安装 `unilabos` 的开发版：
+
+```shell
+pip install .
+```

docs/user_guide/launch.md

@@ -0,0 +1,77 @@
+# Uni-Lab 启动
+
+安装完毕后，可以通过 `unilab` 命令行启动：
+
+```bash
+Start Uni-Lab Edge server.
+
+options:
+  -h, --help            show this help message and exit
+  -g GRAPH, --graph GRAPH
+                        Physical setup graph.
+  -d DEVICES, --devices DEVICES
+                        Devices config file.
+  -r RESOURCES, --resources RESOURCES
+                        Resources config file.
+  -c CONTROLLERS, --controllers CONTROLLERS
+                        Controllers config file.
+  --registry_path REGISTRY_PATH
+                        Path to the registry
+  --backend {ros,simple,automancer}
+                        Choose the backend to run with: 'ros', 'simple', or 'automancer'.
+  --app_bridges APP_BRIDGES [APP_BRIDGES ...]
+                        Bridges to connect to. Now support 'mqtt' and 'fastapi'.
+  --without_host        Run the backend as slave (without host).
+  --config CONFIG       Configuration file path for system settings
+```
+
+## 使用配置文件
+
+Uni-Lab支持使用Python格式的配置文件进行系统设置。通过 `--config` 参数指定配置文件路径：
+
+```bash
+# 使用配置文件启动
+unilab --config path/to/your/config.py
+```
+
+配置文件包含MQTT、HTTP、ROS等系统设置。有关配置文件的详细信息，请参阅[配置指南](configuration.md)。
+
+## 初始化信息来源
+
+启动 Uni-Lab 时，可以选用两种方式之一配置实验室设备、耗材、通信、控制逻辑：
+
+### 1. 组态&拓扑图
+
+使用 `-g` 时，组态&拓扑图应包含实验室所有信息，详见{ref}`graph`。目前支持 graphml 和 node-link json 两种格式。格式可参照 `tests/experiments` 下的启动文件。
+
+### 2. 分别指定设备、耗材、控制逻辑
+
+分别使用 `-d, -r, -c` 依次传入设备组态配置、耗材列表、控制逻辑。
+
+可参照 `devices.json` 和 `resources.json`。
+
+不管使用哪一种初始化方式，设备/物料字典均需包含 `class` 属性，用于查找注册表信息。默认查找范围都是 Uni-Lab 内部注册表 `unilabos/registry/{devices,device_comms,resources}`。要添加额外的注册表路径，可以使用 `--registry` 加入 `<your-registry-path>/{devices,device_comms,resources}`。
+
+## 通信中间件 `--backend`
+
+目前 Uni-Lab 仅支持 ros2 作为通信中间件。
+
+## 端云桥接 `--app_bridges`
+
+目前 Uni-Lab 提供 FastAPI (http), MQTT 两种端云通信方式。其中默认 MQTT 负责端对云状态同步和云对端任务下发，FastAPI 负责端对云物料更新。
+
+## 分布式组网
+
+启动 Uni-Lab 时，加入 `--without_host` 将作为从站，不加将作为主站，主站 (host) 持有物料修改权以及对云端的通信。局域网内分别启动的 Uni-Lab 主站/从站将自动组网，互相能访问所有设备状态、传感器信息并发送指令。
+
+## 完整启动示例
+
+以下是一些常用的启动命令示例：
+
+```bash
+# 使用配置文件和组态图启动
+unilab -g path/to/graph.json
+
+# 使用配置文件和分离的设备/资源文件启动
+unilab -d devices.json -r resources.json
+```