一、这是什么

Python 小程序是 VSAR 里的一种可编程自动化工具：在软件内直接编写 Python 脚本，保存到当前工程，一键运行后由软件在后台启动独立 Python 进程。脚本可控制测量启停、写日志、发送/等待 CAN 报文等，适合快速验证、批量发报文、简单联调。

软件自带 Python 3.13 运行环境，一般无需单独安装 Python。

与 C 语言小程序相比：不用编译，改完保存即可运行；语法更接近日常脚本；适合逻辑不复杂、迭代快的场景。

---

二、如何创建与打开

1. 菜单进入：程序 → Python 小程序（或子菜单「添加 Python 小程序」）。

2. 新建时可选择：

• 空模板：空白代码；
• 发送一帧 CAN 报文、千帧递增、千帧正弦 等内置示例（便于照着改）。

3. 每个小程序对应工程目录：{工程}/PythonApplet/PApp_{编号}/PApp.py。保存工程后，下次打开会自动恢复已创建的小程序窗口。

4. 工具栏可导入/导出 .py 文件，或打开所在文件夹（用外部编辑器改完后，在 VSAR 中保存或重新加载）。

注意：删除小程序窗口前须先停止运行，否则会提示无法删除。

---

三、编辑界面怎么用

窗口大致分为：代码区、内部 API 树（通用 / 日志 / 测量 / CAN）、示例与说明、运行日志。

操作	快捷键 / 入口	说明
保存	Ctrl+S / 保存按钮	写入当前工程的 PApp.py；设置里可勾选「执行前自动保存」
静态检查	Ctrl+F9	内置 pylint 检查语法与严重错误，结果在下方日志区
运行	F9	先检查，通过后再启动；运行中代码区只读
停止	停止按钮	结束当前脚本进程

在左侧 API 树中点击函数名（如 can_send），右侧会显示说明和示例片段，可复制到代码区。运行时资源目录下还提供 VSAR_API.json（与树节点对应，供界面解析说明）。

---

四、脚本必须满足的格式

软件只识别带固定入口的脚本：

1. 必须有名为 __vsar_main 的函数（主逻辑写在这里）。

2. 建议有 __vsar_exit（退出清理；没有也能运行，静态检查时会警告）。

典型结构：

import app

import channel

import can

from VSARDllApi import VSAR_Can

def __vsar_main():

    app.init()                    # 建议第一步：初始化

    channel.start_measurement()   # 启动测量（与界面「启动测量」一致）

    # 在此编写你的业务……

    channel.stop_measurement()    # 结束测量

def __vsar_exit():

    pass                          # 可选：释放、收尾

可使用 import VSAR 一次性引入 app、channel、can 等模块。运行时会自动将 {VSAR 运行目录}/PythonApplet 加入 Python 路径，无需手动配置。

---

五、常用 API（用户视角）

5.1 模块与函数

模块	方法	用途
app	init()	运行前初始化；发送 CAN 前建议调用
app	log(级别, "文字")	输出到 VSAR 日志窗口
channel	start_measurement()	启动测量
channel	stop_measurement()	停止测量
channel	is_measurement()	查询是否已在测量
can	can_send(报文 [, 回调])	发送一帧 CAN
can	wait_can_recv(报文, 超时毫秒 [, 回调])	在限定时间内等待接收

5.2 日志级别

在脚本中 import VSAR 后可使用：

常量	值	含义
LOG_LVL_DEBUG	1	调试
LOG_LVL_INFO	2	信息
LOG_LVL_SUCCESS	3	成功
LOG_LVL_WARNING	4	警告
LOG_LVL_ERROR	5	错误

示例：app.log(VSAR.LOG_LVL_INFO, "开始发送")

5.3 CAN 报文结构 VSAR_Can

常用字段（与总线配置一致方可生效）：

字段	说明
canNo	CAN 通道号
Id	帧 ID
xtd	标准帧 / 扩展帧
dlc	DLC
byteDataLen	有效数据长度
FData	数据字节数组，最多 64 字节

发送示例：

from VSARDllApi import VSAR_Can

msg = VSAR_Can()

msg.canNo = 0

msg.Id = 0x100

msg.dlc = 8

msg.byteDataLen = 8

msg.FData[0] = 0x11

can.can_send(msg)

菜单中的「千帧递增」「千帧正弦」示例演示循环发报文，可直接运行后再修改 ID、周期与数据内容。

5.4 返回值

init、log、start_measurement、stop_measurement、can_send、wait_can_recv 等返回 ErrorCode：0 表示成功，非 0 表示失败或超时，可按需判断处理。

---

六、推荐使用流程

1. 配置工程：设备、CAN 通道、波特率等与平时抓包/发送一致。

2. 新建或打开小程序，从空模板或 CAN 示例开始编写。

3. 在 __vsar_main 中建议顺序：app.init() → channel.start_measurement() → 业务逻辑 → channel.stop_measurement()。

4. Ctrl+F9 静态检查，确认日志区无严重错误（E/F 类）。

5. F9 运行，观察状态栏与日志；可用 app.log 输出中间状态。

6. 结束后点击停止，再修改代码；切换工程前建议停止所有正在运行的小程序。

---

七、工程目录说明

路径	说明
{工程}/PythonApplet/PApp_{窗口ID}/PApp.py	当前小程序源码
{工程}/PythonApplet/PythonAppletList.json	工程内已创建小程序的窗口 ID 列表
{VSAR 运行目录}/PythonApplet/	Python SDK（PythonAPI）、VSAR_API.json、示例脚本等
{VSAR 运行目录}/Python313/	内置 Python 与 pylint
{VSAR 运行目录}/ScriptProcess.exe	运行用户脚本的子进程程序
{VSAR 运行目录}/PythonAppletManager.dll	Python 与主进程通信的动态库（由 PythonAPI 加载）

示例脚本路径（相对 VSAR 运行目录）：PythonApplet/example/（如 空模板.py、发送一帧can报文示例.py 等）。

---

八、常见问题

现象	处理建议
提示找不到 __vsar_main	检查函数名拼写，且源文件中包含该名称
pylint 报 E/F 错误	修正语法或未定义变量后再运行
import 失败 / 无法连接	从 VSAR 安装目录启动，确认存在 Python313、PythonApplet、ScriptProcess.exe、PythonAppletManager.dll
发不出 CAN	确认已 start_measurement()，通道号与界面配置一致，硬件已连接
收不到报文	增大 wait_can_recv 超时；核对通道、ID 与总线实际报文
运行中无法保存或检查	先点击停止，属正常运行保护
删除窗口失败	须先停止小程序运行

---

九、开发与架构（简要）

本目录 Business/PythonApplet 为 VSAR 业务插件（界面、工程保存、运行调度）；底层 SDK 位于 SDK/PythonAppletManager（管道协议、测量/CAN/日志与主进程对接）。

- 用户脚本由 ScriptProcess.exe 在子进程中执行。

- 主进程通过命名管道 \\.\pipe\runpy 与 PythonAppletManager.dll 交换 JSON 协议消息。

- Python 封装见 PythonAPI/（app.py、channel.py、can.py、VSARI.py、VSARDllApi.py）。

更完整的协议与模块说明可参考源码注释及 SDK/PythonAppletManager 各 API 实现。