📝 docs: 添加文档，使用pnpm

.github/workflows/docs.yml → .github/workflows/docs.pnpm.yml

@@ -14,13 +14,13 @@ jobs:
       - name: Checkout this
         # @see https://github.com/actions/checkout
         uses: actions/checkout@v3
-        with:
-          ssh-key: ${{ secrets.ID_MOBILE_ROBOT_CORE }}
-          submodules: true  # Fetch private submodules
+        # with:
+        #   ssh-key: ${{ secrets.ID_MOBILE_ROBOT_CORE }}
+        #   submodules: true  # Fetch private submodules
 
 
-      - name: remove core docs
-        run: rm -rf core/docs/core
+      # - name: remove core docs
+      #   run: rm -rf core/docs/core
 
       - name: Contribute List 
         # @see https://github.com/marketplace/actions/contribute-list
@@ -36,12 +36,14 @@ jobs:
           node-version: 16.x
 
       - name: Run install
-        uses: borales/actions-yarn@v4
+        # @see https://github.com/marketplace/actions/setup-pnpm
+        uses: pnpm/action-setup@v2
         with:
-          cmd: install # will run `yarn install` command
-
-      - name: Build VuePress site
-        run: yarn docs:build
+          version: 8
+          run_install: |
+            - recursive: true
+              args: [--frozen-lockfile, --strict-peer-dependencies]
+            - args: [--global, gulp, prettier, typescript]
 
       - name: Deploy to GitHub Pages
         # @see https://github.com/crazy-max/ghaction-github-pages
@@ -50,7 +52,7 @@ jobs:
           # 部署到 docs 分支
           target_branch: docs
           # 部署目录为 VuePress 的默认输出目录
-          build_dir: core/docs/.vuepress/dist
+          build_dir: docs/.vuepress/dist
         env:
           # @see https://docs.github.com/cn/actions/reference/authentication-in-a-workflow#about-the-github_token-secret
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/.gitignore

@@ -0,0 +1,3 @@
+.temp
+.cache
+dist/

docs/.vuepress/client.ts

@@ -0,0 +1,7 @@
+import { defineClientConfig } from '@vuepress/client'
+
+export default defineClientConfig({
+  enhance({ app, router, siteData }) {},
+  setup() {},
+  rootComponents: [],
+})

docs/.vuepress/config.ts

@@ -0,0 +1,34 @@
+import { defineUserConfig } from 'vuepress'
+import { DefaultThemeOptions, defaultTheme } from '@vuepress/theme-default'
+import { MarkdownOptions } from '@vuepress/markdown'
+
+// set markdown options
+const markdownOptions: MarkdownOptions = {
+  headers: {
+    level: [2, 3, 4, 5],
+  },
+}
+
+// set theme config
+const themeOptions: DefaultThemeOptions = {
+  // 在这里进行配置
+  repo: 'https://github.com/HenryZhuHR/mobile_robot-ros2',
+  sidebarDepth: 3, // 设置根据页面标题自动生成的侧边栏的最大深度
+}
+
+export default defineUserConfig({
+  title: 'ROS2移动机器人',
+  description: '开发文档',
+
+  // set site base to default value
+  base: "/mobile_robot-ros2/",
+
+  // site-level locales config
+  lang: 'zh-CN',
+
+  // configure default theme
+  theme: defaultTheme(themeOptions),
+
+  // configure markdown
+  markdown: markdownOptions,
+})

docs/.vuepress/styles/palette.scss

@@ -0,0 +1,142 @@
+// responsive breakpoints
+$MQNarrow: 1280px !default;
+$MQMobile: 1080px !default;
+$MQMobileNarrow: 419px !default;
+
+
+// code languages
+$codeLang: 'c' 'cpp' 'cs' 'css' 'dart' 'docker' 'fs' 'go' 'html' 'java' 'js'
+  'json' 'kt' 'less' 'makefile' 'md' 'php' 'py' 'rb' 'rs' 'sass' 'scss' 'sh'
+  'styl' 'ts' 'toml' 'vue' 'yml' !default;
+
+// Light mode
+:root {
+  // brand colors
+  //   --c-brand: #3eaf7c;
+  --c-brand: #1188cd; // 11A8CD
+  --c-brand-light: #4abf8a;
+
+  // background colors
+  --c-bg: #ffffff;
+  --c-bg-light: #f3f4f5;
+  --c-bg-lighter: #eeeeee;
+  --c-bg-navbar: var(--c-bg);
+  --c-bg-sidebar: var(--c-bg);
+  --c-bg-arrow: #cccccc;
+
+  // text colors
+  --c-text: #2c3e50;
+  --c-text-accent: var(--c-brand);
+  --c-text-light: #3a5169;
+  --c-text-lighter: #4e6e8e;
+  --c-text-lightest: #6a8bad;
+  --c-text-quote: #7a7a7a;
+
+  // border colors
+  --c-border: #eaecef;
+  --c-border-dark: #dfe2e5;
+
+  // custom container colors
+  --c-tip: #42b983;
+  --c-tip-bg: var(--c-bg-light);
+  --c-tip-title: var(--c-text);
+  --c-tip-text: var(--c-text);
+  --c-tip-text-accent: var(--c-text-accent);
+  --c-warning: #e7c000;
+  --c-warning-bg: #fffae3;
+  --c-warning-title: #ad9000;
+  --c-warning-text: #746000;
+  --c-warning-text-accent: var(--c-text);
+  --c-danger: #cc0000;
+  --c-danger-bg: #ffe0e0;
+  --c-danger-title: #990000;
+  --c-danger-text: #660000;
+  --c-danger-text-accent: var(--c-text);
+  --c-details-bg: #eeeeee;
+
+  // badge component colors
+  --c-badge-tip: var(--c-tip);
+  --c-badge-warning: var(--c-warning);
+  --c-badge-danger: var(--c-danger);
+
+  // transition vars
+  --t-color: 0.3s ease;
+  --t-transform: 0.3s ease;
+
+  // code blocks vars
+  --code-bg-color: #282c34;
+  --code-hl-bg-color: rgba(0, 0, 0, 0.66);
+  --code-ln-color: #9e9e9e;
+  --code-ln-wrapper-width: 3.5rem;
+
+  // font vars
+  --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
+    Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  --font-family-code: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
+
+  // layout vars
+  --navbar-height: 3.6rem;
+  --navbar-padding-v: 0.7rem;
+  --navbar-padding-h: 1.5rem;
+  --sidebar-width: 20rem;
+  --sidebar-width-mobile: calc(var(--sidebar-width) * 0.82);
+  --content-width: 1080px;
+  --homepage-width: 1080px;
+}
+
+// Dark mode
+html.dark {
+  // brand colors
+  --c-brand: #42aaff;
+  --c-brand-light: #349469;
+
+  // background colors
+  --c-bg: #22272e;
+  --c-bg-light: #2b313a;
+  --c-bg-lighter: #262c34;
+
+  // text colors
+  --c-text: #d6dde4;
+  --c-text-light: #96a7b7;
+  --c-text-lighter: #8b9eb0;
+  --c-text-lightest: #8094a8;
+  --c-text-quote: #a5a5a5;
+
+  // border colors
+  --c-border: #3e4c5a;
+  --c-border-dark: #34404c;
+
+  // custom container colors
+  --c-tip: #318a62;
+  --c-warning: #ceab00;
+  --c-warning-bg: #7e755b;
+  --c-warning-title: #ceac03;
+  --c-warning-text: #362e00;
+  --c-danger: #940000;
+  --c-danger-bg: #806161;
+  --c-danger-title: #610000;
+  --c-danger-text: #3a0000;
+  --c-details-bg: #323843;
+
+  // code blocks vars
+  --code-hl-bg-color: #363b46;
+}
+
+
+.sidebar-item {
+  font-weight: 800 !important;
+  font-size: 1.08rem !important;
+  padding: 1rem 1rem 0.35rem 1rem !important;
+}
+
+.sidebar-item-children .sidebar-item-children .sidebar-item {
+  font-weight: 400 !important;
+  font-size: 1rem !important;
+  padding: 0.35rem 1rem 0.35rem 2rem !important;
+  list-style-type: circle !important;
+
+  &::before {
+    content: '»';
+    position: relative;
+  }
+}

docs/README.md

@@ -0,0 +1,98 @@
+# 移动机器人开发文档
+
+## 项目简介
+
+涉及技术栈: 
+- 语言层: Python3, C++
+- 框架: ROS2, PyTorch,  TensorRT
+- 库: OpenCV, TensorRT, MQTT, RTMP
+- 软件包管理: CMake
+- 软件开发相关: Git, Github Actions, VSCode, Docker
+
+## 项目结构
+
+![系统架构](./images/system-architecture.jpg)
+
+该项目的 ROS2 工作空间包括 `core` 和 `modules` 
+
+`core` 中包含功能包如下:
+
+- **controller**: 系统控制模块。包括底盘控制、机械臂控制等
+  - 🔄 [motion_controller](./core/controller/motion_controller.md): 运动控制模块
+  - 💠 arm_controller: 机械臂控制模块
+
+- **manager**: 系统管理模块。包括系统状态管理、任务管理等
+  - **launch**: ROS2 启动文件
+  - ✅ [system_manager](./core/manager/system_manager.md): 系统状态管理模块
+  - 🔄 [task_manager](./core/manager/system_manager.md): 任务管理模块
+
+- **base**: 基础模块。包括系统中的基础功能，如基本节点、基本传感器、基本深度学习模型等，便于统一开发
+  - ✅ [base_node](./core/base/base_node.md): 为系统中功能节点的开发提供基础，包括节点的初始化、参数的读取、心跳包的发送等。 提供一个参考模板 [node_template](./modules/common/base_node.md)
+
+
+`modules` 中包含功能包如下:
+- **common**: 通用功能模块。包括全局的系统状态码定义、通用的工具函数等
+  - ✅ system_state: 系统状态码、错误码的全局定义，模块的注册序号，话题、服务、参数的全局定义
+  - 💠 utils: 通用工具函数
+
+- **interfaces**: 数据接口。 包括各个模块之间的数据接口、消息结构定义
+  - ✅ state_interfaces: 系统状态接口和服务接口
+
+- **data_transmission**: 数据传输模块
+  - 🔄 [dt_mqtt](./modules/data_transmission/dt_mqtt.md): MQTT 通信模块
+  - 🚧 [dt_rtmp](./modules/data_transmission/dt_rtmp.md): 视频推流模块，RTMP 协议
+
+
+- **sensors**: 传感器模块。包括各种传感器的驱动、数据处理等
+  - ✅ [sensor_joy](./modules/sensors/sensor_joy.md): 手柄
+  - 🔄 sensor_uwb: UWB 定位
+
+- **vision**: 视觉算法模块。包括各种视觉算法的实现
+  - ✅ vision_lanedet: 车道线检测算法
+  - 🚧 vision_objdet: 目标检测算法
+  - 💠 vision_objtrack: 目标检测算法
+
+- **navigation**: 导航模块 (未开发)
+
+- **app**: 应用程序
+  - 💠 app_web: web 端控制面板 (Vue3 + flask)
+
+
+功能开发流程: 
+```shell
+💠 计划开发 → 🚧 开发中 → 🔄 测试中 → ✅ 开发完成 → ⛔️ 下线
+                        ⬆︎        ↙︎ 
+                        🐛 修复中
+                        🚀 升级中         
+```
+             
+
+
+## 分支管理
+
+项目使用 git 进行版本控制，每个功能模块都应该新建一个分支进行开发，开发完成后合并到 `dev` 分支，`dev` 分支的代码经过测试后 PR 到 `main` 分支。**功能模块命名规则**:
+
+其他子模块的开发和测试是完全可以独立的，因此，其他功能包的分支应该为 `pkg-<group>__<package_name>` 结构，`<group>` 为功能分组，`<package_name>` 为功能包名，中间用双下划线 `__` 分隔。
+
+例如，传感器 (sensors) 中摄像头 (camera) 的分支应该为 `pkg-sensors__camera` 
+
+
+## 项目文档
+
+拥有开发权限的开发者可以查看完整文档: 
+```shell
+yarn
+yarn docs:dev
+```
+
+## 项目规范
+
+- C++ 代码规范: [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) | [C++ 风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents/)
+- Python 代码规范: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) | [Python 风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/contents/)
+- Shell 代码规范: [Shell Style Guide](https://google.github.io/styleguide/shellguide.html) | [Shell 风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-shell-styleguide/contents/)
+
+## 开发贡献
+<br>
+<a href="https://github.com/HenryZhuHR/mobile_robot-ros2/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=HenryZhuHR/mobile_robot-ros2" />
+</a>

docs/core/base/base_node.md

@@ -0,0 +1,30 @@
+# 基本节点 (base_node)
+
+基本节点 `BaseNode` 是所有节点的基类，提供了节点的基本功能，包括：
+- 节点定义
+- 心跳机制
+
+
+
+## 基本节点的功能
+
+### 节点定义
+
+节点定义包括节点的初始化、节点设置、心跳设置
+
+节点设置指的是设置注册序号，包括分组 (state_group) 和序号 (state_group) ，分组用于区分不同的功能模块，序号用于区分不同的节点。
+分组参考 `SystemStateGroup` ，序号参考 `SystemStateCode` 。
+
+### 心跳机制
+
+为了能够监测各个节点的运行状态，基本节点提供了心跳机制。
+
+
+![心跳机制](./images/heartbeat-mechanism.svg)
+
+- 在节点启动时，「当前节点」会向「系统状态管理器」注册自己的心跳包，「系统状态管理器」会为「当前节点」分配一个注册序号，「当前节点」会使用这个注册序号来标识自己，如果节点的注册序号为 `0`，则不会继续运行节点相关功能
+- 在节点运行时，「当前节点」定时向「系统状态管理器」发送心跳包，以表明「当前节点」的运行状态。「系统状态管理器」会不断广播系统的运行状态，以便其他节点能够获取到系统的运行状态。
+
+**异常监测**：「系统状态管理器」根据收到的心跳包判断节点是否正常运行，如果节点长时间没有发送心跳包，则认为节点已经停止运行，将节点的状态码设置为 `OFFLINE`，则其他依赖于「当前节点」数据的节点则不再执行相关操作，同时也便于检查哪些节点已经停止运行。
+
+总的来说，心跳机制，是为了让系统状态管理器获取到各个节点的运行状态，以便于快速定位到系统中的异常节点，从而提高系统的可靠性。