# VirtCtrlBoard

**Repository Path**: sjxun/virt-ctrl-board

## Basic Information

- **Project Name**: VirtCtrlBoard
- **Description**: No description available
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# virt-ctrl-board — 虚拟仿真实验板

面向中小学信息科技教学的桌面虚拟仿真软件。拖拽搭建电路、Python 编程、实时仿真运行。

## 安装运行

```bash
pip install pyside6 pyyaml pydantic jedi paho-mqtt
python -m virt_ctrl_board
```

## 界面操作

### 电路搭建
- 从左侧**组件库**拖拽元件到画布
- **左键点击**主控板端口 → 再点元件端口 → 完成连线
- **右键**元件 → 断开连接 / 删除元件
- Ctrl+Z 撤销 / Ctrl+Y 重做

### 编程与仿真
- 切换到**代码编辑**页，编写 Python 代码
- 点击 **▶ 运行** 开始仿真，**■ 停止** 结束
- 底部 **传感器数值** 面板可拖拽滑块/点击按钮调节传感器数值
- 底部 **仿真状态** 面板实时显示执行器状态

### 快捷键
| 操作 | 快捷键 |
|------|--------|
| 运行 / 停止 | F5 / Shift+F5 |
| 缩放画布 | Ctrl+滚轮 |
| 平移画布 | 中键拖拽 |
| 新建项目 | Ctrl+N |
| 打开项目 | Ctrl+O |
| 保存项目 | Ctrl+S |
| 代码补全 | Tab |

### 项目文件
- Ctrl+O 打开 `.vcb` 项目文件（预连线 + 预写代码）
- Ctrl+S 保存当前项目
- `examples/` 目录下有 8 个预置示例项目

## 新增元件（插件系统）

无需修改程序代码。在 `plugins/` 目录下新建文件夹，放入 2 个文件即可：

```
plugins/你的元件/
├── descriptor.yaml    # 元件描述（参数、端口类型、方法签名）
└── module.py          # 仿真 API 类 + 图标绘制（可选）+ 动画状态（执行器可选）
```

**示例：新增一个超声波传感器**

`plugins/ultrasonic/descriptor.yaml`：
```yaml
id: ultrasonic
name: 超声波测距传感器
category: sensor
connect_type: IN          # 决定连接 P4~P7
connector:
  label: SIG
simulation:
  parameters:
    distance:
      label: "距离(cm)"
      type: float
      range: [2, 400]
      default: 100
      unit: cm
library:
  class_name: Ultrasonic
  methods:
    measure:
      returns: float
```

`plugins/ultrasonic/module.py`：
```python
from virt_ctrl_board.simulation.engine import _sim_state

class Ultrasonic:
    def __init__(self, pin: str):
        self._pin = pin
    def measure(self) -> float:
        vals = _sim_state.get_sensor(self._pin)
        return float(vals.get("distance", 100))

SimClass = Ultrasonic      # 必须导出！挂载到 board.Ultrasonic

# 图标绘制函数（可选，不写则用默认图标）
def draw_icon(painter, rect, item):
    from PySide6.QtGui import QPen, QColor, QBrush
    from PySide6.QtCore import Qt, QRectF
    cx, cy = rect.center().x(), rect.center().y()
    painter.setBrush(QBrush(QColor(140, 140, 180)))
    painter.drawRoundedRect(QRectF(cx - 8, cy - 12, 16, 24), 6, 6)

# 执行器还需要状态处理函数
# def on_state(item, state): item._sim_on = state.get("state", False)
```

**规范要点**：
- `SimClass` 必须导出，构造函数接受 `pin: str` 参数
- 读取传感器值用 `_sim_state.get_sensor(pin)`，设置执行器用 `_sim_state.set_actuator(pin, **values)`
- 执行器 API 方法需先调用 `_sim_state._check_running()` 以支持停止
- 图标函数签名：`draw_icon(painter, rect, item)`，函数名固定
- 状态函数签名：`on_state(item, state)`，函数名固定

重启应用后新元件自动出现在组件库，Tab 代码补全也自动包含新方法。

## 物联网

MQTT 服务器建议使用 DFRobot 的 SIoT（v1 支持 Windows/Linux/macOS，v2 支持 Windows）。仿真软件已完整适配 SIoT v1/v2 通讯协议。

## API 参考

完整 API 文档见 `docs/board_api_reference.md`，包含：
- 所有 18 个元件的函数和用法
- OLED / MQTT / 时间控制
- 组合示例（光控灯、自动浇灌、IoT 远程控制等）

## 作者

逐流 — [Gitee](https://gitee.com/zhuliu2122/virt-ctrl-board)