# zap

**Repository Path**: zhuliu2122/zap

## Basic Information

- **Project Name**: zap
- **Description**: Zap —— 中小学信息科技教学虚拟仿真平台。拖拽搭电路、Python编程、即时仿真。Zap一下，创意立刻实现。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-06-17
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zap — 虚拟仿真实验板

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](pyproject.toml)

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

软件包下载地址：[Zap](https://www.wcqxxkj.cn/zap.html)
## 功能特性

- 🧩 **拖拽搭建** — 从组件库拖拽元件到画布，点击连线，搭建电路一目了然
- 🐍 **Python 编程** — 内置代码编辑器，Tab 自动补全，真实 Python 语法
- ⚡ **实时仿真** — 60fps 状态更新，传感器滑块/执行器状态面板实时交互
- 🔌 **插件体系** — 无需修改程序，新增元件即插即用
- 🌐 **物联网** — 内置 MQTT 支持，对接 SIoT 等教学平台
- 📁 **项目文件** — 一键保存/加载，附带 10 个教学示例

## 截图

![主界面](docs/screenshot.png)

## 环境要求

- Python ≥ 3.10
- 支持 Windows / macOS / Linux

## 安装运行

```bash
pip install .
python -m zap
```

## 打包为桌面应用

```bash
pip install pyinstaller
pyinstaller Zap.spec
# Windows → dist/Zap.exe
# macOS   → dist/Zap.app
# Linux   → dist/Zap
```

## 界面操作

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

### 编程与仿真
- 切换到**代码编辑**页，编写 Python 代码
- 点击 **▶ 运行** 开始仿真，**■ 停止** 结束
- 底部 **传感器数值** 面板可拖拽滑块/点击按钮调节传感器数值
- 底部 **仿真状态** 面板实时显示执行器状态
- 底部 **环境变量** 复选框开启后，执行器自动影响传感器（加热→温度↑、LED→光照↑）

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

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

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

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

```
plugins/你的元件/
├── descriptor.yaml    # 元件描述（必填）
└── module.py          # 仿真 API 类 + 图标绘制 + 状态处理（必填）
```

### descriptor.yaml 字段说明

```yaml
id: dht11                        # 唯一标识，与文件夹名保持一致
name: 温湿度传感器                # 显示在组件库的名称
var: dht                         # 代码生成时的变量名缩写（如 dht.read_temperature()）
category: sensor                 # sensor / actuator / input
connect_type: ADC                # ADC / IN / OUT / PWM 决定可接的主控板端口范围
connector:
  label: DATA                    # 元件上接口的标签文字
simulation:
  parameters:                    # 仿真参数定义，传感器和执行器都用到
    temperature:                 # 参数键名，传感器用 get_sensor(pin)["temperature"] 读取
      label: "温度(°C)"          # 在传感器面板和执行器状态面板中显示的名称
      type: float                # bool / int / float
      range: [-20, 60]           # 取值范围（仅传感器滑块使用）
      default: 25                # 默认值
      unit: °C                   # 单位（可选，显示在数值后）
library:
  class_name: DHT11              # 对应 module.py 中 SimClass 的类名
  methods:                       # API 方法描述，用于代码补全和右键生成代码
    read_temperature:
      returns: float
env_effect:                      # 可选，环境变量配置（仅执行器）
  state:                         # 触发参数名
    target: temperature          # 影响的传感器参数
    mode: accumulate             # accumulate(累积) / immediate(即时)
    rate: 0.1                    # 累积型：每帧变化量
```

### 传感器示例

`plugins/dht11/descriptor.yaml`：
```yaml
id: dht11
name: 温湿度传感器
var: dht
category: sensor
connect_type: ADC
connector:
  label: DATA
simulation:
  parameters:
    temperature:
      label: "温度(°C)"
      type: float
      range: [-20, 60]
      default: 25
      unit: °C
    humidity:
      label: "湿度(%)"
      type: float
      range: [0, 100]
      default: 50
      unit: "%"
library:
  class_name: DHT11
  methods:
    read_temperature:
      returns: float
    read_humidity:
      returns: float
```

`plugins/dht11/module.py`：
```python
from zap.simulation.engine import SimBoard

class DHT11:
    def __init__(self, pin: str):
        self._pin = pin

    def read_temperature(self) -> float:
        vals = SimBoard._state.get_sensor(self._pin)
        return float(vals.get("temperature", 25))

    def read_humidity(self) -> float:
        vals = SimBoard._state.get_sensor(self._pin)
        return float(vals.get("humidity", 50))

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

# draw_icon(painter, rect, item) — 可选，绘制画布上的图标
def draw_icon(painter, rect, item):
    from PySide6.QtGui import QBrush, QColor
    from PySide6.QtCore import Qt
    painter.setBrush(QBrush(QColor(100, 160, 220)))
    painter.drawRoundedRect(rect.adjusted(2, 2, -2, -2), 4, 4)
    painter.drawText(rect, Qt.AlignCenter, "温湿度")
```

### 执行器示例

`plugins/fan/descriptor.yaml`：
```yaml
id: fan
name: 风扇模块
var: fan
category: actuator
connect_type: OUT
connector:
  label: SIG
simulation:
  parameters:
    state:                      # 键名必须和 set_actuator() 关键字参数名一致
      label: "开/关"            # 状态面板显示的文字
      type: bool                # bool 自动显示 ON/OFF，其他显示数值+单位
      default: false
library:
  class_name: Fan
  methods:
    "on":
      returns: None
    "off":
      returns: None
env_effect:                     # 风扇开启后，每帧降低温度 0.1°C
  state:
    target: temperature
    mode: accumulate
    rate: -0.1
```

`plugins/fan/module.py`：
```python
from zap.simulation.engine import SimBoard

class Fan:
    def __init__(self, pin): self._pin = pin
    def on(self):
        SimBoard._state._check_running()
        SimBoard._state.set_actuator(self._pin, state=True)  # state 键名与 YAML 一致
    def off(self):
        SimBoard._state._check_running()
        SimBoard._state.set_actuator(self._pin, state=False)

SimClass = Fan

# draw_icon — 根据状态切换图标颜色
def draw_icon(p, r, item):
    from PySide6.QtGui import QBrush, QColor
    from PySide6.QtCore import QPointF
    cx, cy = r.center().x(), r.center().y()
    if getattr(item, '_sim_on', False):
        p.setBrush(QBrush(QColor(100, 180, 255)))  # 运行中
    else:
        p.setBrush(QBrush(QColor(200, 200, 200)))  # 停止
    p.drawEllipse(QPointF(cx, cy), 14, 14)

# on_state(item, state) — 状态更新时自动调用，更新图标内存属性
def on_state(item, state):
    item._sim_on = state.get("state", False)
```

### 规范要点

- `SimClass` 必须导出，构造函数接受 `pin: str` 参数
- 传感器用 `SimBoard._state.get_sensor(pin)` 读取值，YAML parameters 键名与之对应
- 执行器用 `SimBoard._state.set_actuator(pin, **values)` 设置状态，**YAML parameters 键名必须和关键字参数名一致**
- 执行器方法调用前需先调用 `SimBoard._state._check_running()` 以支持仿真停止
- 图标绘制函数：`draw_icon(painter, rect, item)`，函数名固定
- 状态处理函数：`on_state(item, state)`，函数名固定，插件加载时自动注册
- `var` 字段定义在 descriptor.yaml 中，用于生成代码时的变量名
- 执行器可选 `env_effect` 字段，配置环境变量自动影响（accumulate 累积 / immediate 即时）
- 蜂鸣器可加 `set_volume(n)` 方法，音量范围 0-100

### 自动生效的功能

重启应用后：
- 新元件自动出现在左侧**组件库**
- 代码编辑器 **Tab 补全**自动包含新方法和属性
- 右键元件 → **查看代码**自动使用 `var` 定义的变量名
- 底部**仿真状态**面板自动按 YAML 的 `parameters` 显示执行器状态
- 图标动画通过 `draw_icon` + `on_state` 联动，新增元件无需修改程序

## 物联网

已测试支持 SIoT v1/v2、中小学信息科技物联数据中台，其他平台请自行测试。

## API 参考

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

## 许可证

Apache 2.0 — 详见 [LICENSE](LICENSE)

## 贡献

欢迎提交 Issue 和 Pull Request！

- 🐛 发现 Bug → [新建 Issue](https://gitee.com/zhuliu2122/Zap/issues)
- 💡 功能建议 → 提交 Issue 讨论后再动手
- 🔧 开发环境：`pip install -e .` 可编辑模式安装
- 提交前请确保现有示例项目能正常加载

## 作者

逐流 — [Gitee](https://gitee.com/zhuliu2122/Zap)