VSAR Python 小程序 — 用户使用说明
一、这是什么
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 实现。