外挂脚本使用指南
外挂脚本作为软件的拓展点，被 Pickwiz 调用，不需要修改核心代码即可添加业务逻辑，灵活适配现场的定制化需求，如补偿机械臂安装误差、单位转换、避障策略调整、协议适配等，不涉及网络通信功能。当系统运行到相应环节时（如计算抓取姿态后、准备发送数据给机械臂前），会自动调用外挂脚本中的这些函数。
目前外挂脚本可以添加的位置有四处：
PickWiz接收到机器人报文时
PickWiz处理接收占位符信息时
PickWiz处理发送占位符信息时
PickWiz发送给机器人报文时
MC/Snap7/Modbus不存在报文的概念，故不存在第一和第四处外挂脚本处理指令的机制
1. 创建Python文件
在目录C:\Users\dex\.dexforce\kuawei_data\robot_hooks下创建一个 python 文件，方法如下图所示。
在C:\Users\dex\.dexforce\kuawei_data\robot_hooks目录下鼠标右键新建一个文本文档 
将新建的文本文档的扩展名修改为.py，点击“是”改变扩展名 
将如下代码复制到新建的Python文件中。
from typing import List
from PickLight.log.logger import logger_pipe
class AttrHooks(object): #创建1个AttrHooks类，里面包含多个钩子函数，系统会自动识别并调用这些函数
#所有钩子函数都遵循相同的参数格式：
#@staticmethod
#def received_messages_hook(data: str, context) -> str
# PickWiz接收到机器人指令，received_messages_hook
# PickWiz向机器人发送指令前，messages_hook
# PickWiz处理占位符信息，占位符_hook
# data：需要处理的原始数据，类型根据场景而定；context：上下文信息，包含机器人配置，作业配置id等附加信息
# context：机器人上下文信息, 上下文信息，包含机器人配置，作业配置id等附加信息，可以在钩子函数内使用context.get_available_context()获取当前函数可用的上下文信息context：上下文信息，包含机器人配置，作业配置id等附加信息，可通过 context.get_available_context() 获取当前可用的上下文配置。目前可用的上下文信息具体如下。
机器人配置：robot_config
保留小数点位数：decimals
机器人自由度：dof_type
旋转表达式：rotation_type
长度单位：translation_unit
角度单位：euler_angle_unit
作业配置id：config_ids
作业id：task
标定id：calibration
机器人id：robot
视觉参数id：vision_param
ROI id：roi
产品id：product
夹具id：end_effector
场景物体id：scene_object (勾选了碰撞检测插件时)
roi
2d ROI信息: roi2d
3d ROI信息: roi3d
2. PickWiz 接收到机器人指令
PickWiz 接收到机器人发送的指令时，可在新建的Python文件中的AttrHooks类增加pre_receive_messages_hook 函数，处理接收到的机器人消息。
❗当前外挂脚本函数仅在“刷新配置”和“发送检测结果”两个特定时刻才会被系统注册生效，故如果修改了
pre_receive_messages_hook函数，需要手动切换配置或触发一次检测才能让修改的函数生效，否则系统仍然会使用旧函数。
示例：当 PickWiz 收到机器人发来的简短指令码（比如示例里的 “210”“211” 这类短报文）时，通过外挂脚本里的pre_receive_messages_hook函数做解析处理，把短指令码直接替换成机器人能识别执行的、带完整参数的指令（比如把 “210” 换成 “d,0,0,0,0,0,0,1”），避免因短指令信息不全导致机器人无法响应或执行出错，快速适配现场机器人的指令交互需求。
@staticmethod
def pre_receive_messages_hook(data: str, context) -> str: #当PickWiz接收到机器人发送的指令，且根据机器人发送的字段不同，调整软件接收的机器人字段
logger_pipe.info("available context: %s", context.get_available_context())
logger_pipe.info("received messages: %s", data)
if data == "210":
data = "d,0,0,0,0,0,0,1"#收到"210"时，替换为完整指令"d,0,0,0,0,0,0,1"
elif data == "211":
data = "d,0,0,0,0,0,0,2"#收到"211"时，替换为"d,0,0,0,0,0,0,2"
return data示例：固定作业配置（比如固定作业配置中 ROI 的 ID），当 PickWiz 接收到机器人指令时，会先检查当前上下文context 里的 ROI ID 是否为 1，如果不是 1，就自动把指令内容改成 “d,0,0,0,0,0,0,1”，以此将 ROI ID 固定为 1，避免现场因 ROI 配置错乱导致抓取、检测等作业出错。
@staticmethod
def pre_receive_messages_hook(data: str, context) -> str: #当PickWiz接收到机器人发送的指令，判断roi 的id是否为1，若不为1，通过占位符${roi_id}切换roi为1
logger_pipe.info("available context: %s", context.get_available_context())
logger_pipe.info("raw messages: %s", data)
if context["config_ids"]["roi"] != 1:
data = "d,0,0,0,0,0,0,1"
logger_pipe.info("modified messages: %s", data)
return data3. 修改接收占位符信息
占位符可以在系统的各种配置和消息中使用，用于动态替换为实际值，PickWiz接收到的指令中，各占位符的含义、默认值、数据类型如下表所示。
| 占位符 | 含义 | 数据类型 |
|---|---|---|
| p | 机器人6d位姿 | 6位浮点型 |
| j | 机器人关节姿态 | 6位浮点型 |
| ps | 工件尺寸 | 1-3位浮点型 |
| p_tol | 工件尺寸容差 | 1-3位浮点型 |
| pid | 工件ID | 短整型 |
| wid | 作业ID | 短整型 |
| calib_id | 标定配置ID | 短整型 |
| ee_id | 末端工具ID | 短整型 |
| roi_id | ROI ID | 短整型 |
| vp_id | 视觉参数ID | 短整型 |
| so_id | 场景物体ID | 短整型 |
| co | 拍照计算类型 | 短整型 |
| max_merge_num | 单行最大组合数 | 短整型 |
| max_merge_lines | 最大组合行数 | 短整型 |
如需修改占位符信息，可在新建的Python文件中的AttrHooks类增加占位符_hook 函数。
示例：固定作业配置（比如固定作业配置中 ROI 的 ID），当PickWiz接收到机器人发送的指令，强制将 ROI ID 固定为 1，避免现场因 ROI 配置错乱导致抓取、检测等作业出错。
@staticmethod
def roi_id_hook(data: str, context) -> str: #当PickWiz接收到机器人发送的指令，强制切换roi id 为1
logger_pipe.info("raw pid: %s", data)
data = 1
logger_pipe.info("modified pid: %s", data)
return data4. 修改发送占位符信息
占位符可以在系统的各种配置和消息中使用，用于动态替换为实际值，PickWiz发送给机器人的指令中，各占位符的含义、默认值、数据类型如下表所示。
| 占位符 | 含义 | 默认值 | 数据类型 |
|---|---|---|---|
| s | 检测结果信号 | 1 | 短整型 |
| vn | 有效实例数量 | 1 | 短整型 |
| ln | 剩余实例数量 | 1 | 短整型 |
| rn | 返回实例数量 | 1 | 短整型 |
| tn | 实例检测总量 | 1 | 短整型 |
| pre_pick | 前进点 | 2,j1,j2,j3,j4,j5,j6,j1,j2,j3,j4,j5,j6 | 浮点型 |
| post_pick | 后撤点 | 2,j1,j2,j3,j4,j5,j6,j1,j2,j3,j4,j5,j6 | 浮点型 |
| pose_index | 抓取点索引 | 1 | 短整型 |
| grasp_pose | 抓取点位姿 | 0,0,0,0,0,0 | 浮点型 |
| grasp_pid | 抓取工件ID | 1 | 短整型 |
| length | 工件长度(沿图像x方向) | 0.2 | 浮点型 |
| width | 工件宽度(沿图像y方向) | 0.2 | 浮点型 |
| height | 工件高度 | 0.1 | 浮点型 |
| rect_length | 工件长度(沿图像x方向) | 0.1 | 浮点型 |
| rect_width | 工件宽度(沿图像y方向) | 0.1 | 浮点型 |
| direction | 工件朝向(0:沿x为横,1:沿y为竖) | 1 | 短整型 |
| left_top | 左上顶点 | x,y,z | 浮点型 |
| right_top | 右上顶点 | x,y,z | 浮点型 |
| left_bottom | 左下顶点 | x,y,z | 浮点型 |
| right_bottom | 右下顶点 | x,y,z | 浮点型 |
| entity | 返回实例类型(0:工件,1:托盘) | 0 | 短整型 |
| category_id | 工件类别 | 0 | 短整型 |
| aux_info | 额外信息 | ... | 浮点型 |
| radius | 圆面半径 | 0.2 | 浮点型 |
| pmf_height | 圆柱高度 | 0.2 | 浮点型 |
| sr | 自动标定采样结果 | 1 | 短整型 |
| cp | 自动标定下次采样位姿 | 0,0,0,0,0,0 | 浮点型 |
| so_size_id | (碰撞检测)料框尺寸ID | 1 | 短整型 |
| so_size | (碰撞检测)料框尺寸(长,宽,高,长边厚度,宽边厚度，底厚度) | 0.1,0.1,0.1,0.1,0.1,0.1 | 浮点型 |
| so_pose | (碰撞检测)料框位姿 | 0,0,0,0,0,0 | 浮点型 |
如需修改占位符信息，可在新建的Python文件中的AttrHooks类增加占位符_hook 函数。
示例：调整检测结果信号
@staticmethod
def s_hook(data: List[int], context) -> List[int]: # 调整检测结果信号，当返回信号不为成功(100)时，其他都置为异常(-1)
logger_pipe.info("raw signal: %s", data)
if data and data[0] != 100:
data[0] = -1
logger_pipe.info("modified signal: %s", data)
return data示例：调整抓取高度
@staticmethod
def grasp_pose_hook(data: List[float], context) -> List[float]: #调整抓取高度，把所有抓取点的Z坐标增加0.01。适用于补偿机械臂安装误差，或根据工件高度微调抓取点。
logger_pipe.info("raw poses: %s", data)
# 增加Z坐标值
if data and len(data) >= 6:
modified_data = data.copy()
pose_size = 6 # 每个姿态由6个数值组成
poses_count = len(data) // pose_size
for i in range(poses_count):
z_index = i * pose_size + 2 # Z坐标在第3个位置(索引2)
if z_index < len(modified_data):
modified_data[z_index] += 0.01 # Z坐标增加0.01
logger_pipe.info("modified poses: %s", modified_data)
return modified_data
return data5. PickWiz 向机器人发送指令前
PickWiz 向机器人发送指令前，如需处理消息，可在新建的Python文件中的AttrHooks类增加pre_send_messages_hook函数。
在机器人未配置 “拆分报文” 功能时，
data列表通常只有 1 个元素，即待发送的完整指令报文，函数只需处理这一个元素即可。当机器人配置了 “拆分报文” 功能（即将一条完整指令拆分为多条子报文发送）时，
data列表会包含所有拆分后的子报文，每个子报文作为列表的一个元素，函数需对列表中的所有子报文元素分别处理，确保每条子报文都符合发送要求。
示例：在PickWiz 向机器人发送指令前，调整指令字符串里第一位占位符的内容，该函数会先读取待发送的原始指令列表data（默认列表长度为 1，仅含一条完整指令），然后按现场需求判断并修改指令字符串第一位占位符的内容（比如当第一位占位符对应的信号不是成功值 100 时，就将其强制改为 - 1），确保机器人收到的指令中第一位占位符内容符合作业要求，避免因原始占位符数据异常导致机器人执行错误。
@staticmethod
def pre_send_messages_hook(data: List[str], context) -> List[str]:# 当第一位占位符为${s}时，调整返回信号，当返回信号不为成功(100)时，其他都置为异常(-1)
logger_pipe.info("raw messages: %s", data[0])
result = data[0]
if result and result.split(",")[0] != "100":
data[0] = "-1" + result[result.find(","):]
logger_pipe.info("modified messages: %s", data[0])
return data