跨维智能制造产品文档中心

外观

外挂脚本使用指南

约 2418 字大约 8 分钟

2026-01-26

外挂脚本作为软件的拓展点，被 Pickwiz 调用，不需要修改核心代码即可添加业务逻辑，灵活适配现场的定制化需求，如补偿机械臂安装误差、单位转换、避障策略调整、协议适配等，不涉及网络通信功能。当系统运行到相应环节时（如计算抓取姿态后、准备发送数据给机械臂前），会自动调用外挂脚本中的这些函数。

目前外挂脚本可以添加的位置有三处：

  • PickWiz接收到机器人报文时

  • PickWiz处理占位符信息时

  • PickWiz发送给机器人报文时

如使用的是除Tcp协议外的其他协议，则只会在处理占位符信息的时候生效

1. 创建Python文件

在目录C:\Users\dex\.dexforce\kuawei_data\robot_hooks下创建一个 python 文件，方法如下图所示。

在C:sersex.dexforceuaweidataobothooks目录下鼠标右键新建一个文本文档

将新建的文本文档的扩展名修改为.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 (勾选了碰撞检测插件时)

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 data

3. 修改占位符信息

占位符可以在系统的各种配置和消息中使用，用于动态替换为实际值，各占位符的含义、默认值、数据类型如下表所示。

占位符含义默认值数据类型
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抓取工件ID1短整型
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(碰撞检测)料框尺寸ID1短整型
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 data

4. 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