TL-消息与服务定义功能包

1. tl_ros2_interface 功能包说明

tl_ros2_interface 功能包为 TL 系列机械臂在 ROS2 框架下提供消息（msg）和服务（srv）接口定义，供上层驱动或应用调用。该包本身没有可执行程序，主要作用为定义协议数据结构和服务接口。

2. tl_ros2_interface 使用说明

该功能包并没有可执行的使用命令，其主要作用为为其他功能包提供必须的消息文件。

3. tl_ros2_interface 文件总览

tl_ros2_interface/
├── CMakeLists.txt        # 编译规则
├── package.xml           # 依赖声明
├── msg/                  # 消息定义
│   ├── ArmStatus.msg
│   ├── CartesianPose.msg
│   ├── JobFileName.msg
│   ├── ModbusMasterParam.msg
│   ├── ModbusRTUParam.msg
│   ├── ModbusTCPParam.msg
│   ├── MoveCommand.msg
│   ├── ObjectInfo.msg
│   ├── RobotDHParam.msg
│   ├── RobotJointParam.msg
│   ├── ServolMove.msg
│   └── ToolParam.msg
├── srv/                  # 服务定义
│   ├── CoordTransform.srv
│   ├── GetAllJobFileName.srv
│   ├── GetCoordNum.srv
│   ├── GetCurrentCoord.srv
│   ├── GetCurrentLineJointSpeed.srv
│   ├── GetCurrentMode.srv
│   ├── GetCurrentMotorTorque.srv
│   ├── GetDHParam.srv
│   ├── GetDigitalInputOutput.srv
│   ├── GetGlobalPos.srv
│   ├── GetJointSoftwareVersion.srv
│   ├── GetJointTemperature.srv
│   ├── GetJointVoltage.srv
│   ├── GetMotorCurrent.srv
│   ├── GetPosReachable.srv
│   ├── GetPosTransform.srv
│   ├── GetRobotJointParam.srv
│   ├── GetRobotState.srv
│   ├── GetSpeed.srv
│   ├── JobRun.srv
│   ├── JobInsertMove.srv
│   ├── Jogging.srv
│   ├── LogDownload.srv
│   ├── ModbusRead.srv
│   ├── ModbusWrite.srv
│   ├── OpenServoJ.srv
│   ├── QueueMotionMoveJ.srv
│   ├── QueueMotionSetStatus.srv
│   ├── RestoreDefaultDHParam.srv
│   ├── SetAxisZeroPos.srv
│   ├── SetControllerIP.srv
│   ├── SetCoordNum.srv
│   ├── SetCurrentCoord.srv
│   ├── SetCurrentMode.srv
│   ├── SetDHParam.srv
│   ├── SetDigitalOutput.srv
│   ├── SetDragMode.srv
│   ├── SetGlobalPos.srv
│   ├── SetRobotJointParam.srv
│   ├── SetSpeed.srv
│   ├── SetToolParam.srv
│   ├── SetUserCoord.srv
│   ├── ToolHandCalib.srv
│   ├── TrackPlayback.srv
│   └── TrackSave.srv

4. tl_ros2_interface 消息（msg）说明

以下列出 msg 文件定义及字段说明。

4.1 机械臂运行状态 ArmStatus

builtin_interfaces/Time stamp
string run_state

msg 成员

• stamp: 时间戳
• run_state: 运行状态描述字符串

4.2 直角坐标系位姿 CartesianPose

std_msgs/Header header
geometry_msgs/Point position
geometry_msgs/Vector3 rpy
float64 arm_angle

msg 成员

• header: 标准消息头
• position: x,y,z 位置（米）
• rpy: 姿态欧拉角（弧度）
• arm_angle: 机械臂额外角度（弧度）

4.3 作业文件名 JobFileName

string[] file_name

msg 成员

• file_name: 作业文件名数组

4.4 ModbusMaster 参数 ModbusMasterParam

string type
bool start_addr
tl_ros2_interface/ModbusTCPParam tcp
tl_ros2_interface/ModbusRTUParam rtu

msg 成员

• type: "TCP" 或 "RTU"
• start_addr: 是否从起始地址开始
• tcp: Modbus TCP 参数
• rtu: Modbus RTU 参数

4.5 ModbusRTU 参数 ModbusRTUParam

int32 slave_id
int32 port
int32 baudrate
int32 data_bit
int32 stop_bit
string check_bit

msg 成员

• slave_id: 从站 ID
• port: 串口号
• baudrate: 波特率
• data_bit: 数据位
• stop_bit: 停止位
• check_bit: 校验方式

4.6 ModbusTCP 参数 ModbusTCPParam

string ip
int32 port

msg 成员

• ip: 目标 IP
• port: 目标端口

4.7 运动指令 MoveCommand

float64[] target_pos_value
string target_pos_name
int32 target_pos_type
int32 coord
float64 velocity
float64 velocity_sync
float64 acc
float64 dec
int32 pl
int32 time
int32 tool_num
int32 user_num
int32 posidtype
int32 configuration
int32 spin
bool para_sync

msg 成员

• target_pos_value: 目标位置数值数组（关节或笛卡尔）
• target_pos_name: 目标位置名称
• target_pos_type: 位置类型标识
• coord: 坐标系编号
• velocity/velocity_sync/acc/dec: 速度与加减速参数
• pl/time: 轨迹/时间相关参数
• tool_num/user_num: 工具/用户坐标编号
• posidtype/configuration/spin/para_sync: 其他标志位或配置

4.8 目标检测结果 ObjectInfo

string type
geometry_msgs/PointStamped pos

msg 成员

• type: 目标类型
• pos: 检测到的目标位置（带时间戳）

4.9 机器人 DH 参数 RobotDHParam

# 对应 SDK tl::RobotDHParam：alpha[6]/a[6]/theta[6]/d[6]/eulerAngle/mountingAngle
float64[] alpha           # 1-6轴DH参数alpha，单位：deg
float64[] a               # 1-6轴DH参数a，单位：mm
float64[] theta           # 1-6轴DH参数theta，单位：deg
float64[] d               # 1-6轴DH参数d，单位：mm
int32 euler_angle         # 欧拉角模式
float64 mounting_angle    # 机器人安装角度，单位：deg

msg 成员

• alpha: 1-6轴DH参数alpha（deg）
• a: 1-6轴DH参数a（mm）
• theta: 1-6轴DH参数theta（deg）
• d: 1-6轴DH参数d（mm）
• euler_angle: 欧拉角模式
• mounting_angle: 机器人安装角度（deg）

4.10 机械臂关节参数 RobotJointParam

float64 reduction_ratio
int32 encoder_resolution
float64 pos_sw_limit
float64 neg_sw_limit
float64 rated_rot_speed
float64 rated_derot_speed
float64 max_rot_speed
float64 max_derot_speed
float64 rated_vel
float64 rated_devel
float64 max_acc
float64 max_dec
int32 direction

msg 成员

• reduction_ratio: 减速比
• encoder_resolution: 编码器位数
• pos_sw_limit: 轴正限位
• neg_sw_limit: 轴反限位
• rated_rot_speed: 电机额定正转速
• rated_derot_speed: 电机额定反转速
• max_rot_speed: 电机最大正转速
• max_derot_speed: 电机最大反转速
• rated_vel: 额定正速度
• rated_devel: 额定反速度
• max_acc: 最大加速度
• max_dec: 最大减速度
• direction: 模型方向，1：正向，-1：反向

4.11 工具参数 ToolParam

float64 x
float64 y
float64 z
float64 a
float64 b
float64 c
float64 payload_mass
float64 payload_inertia
float64 payload_mass_center_x
float64 payload_mass_center_y
float64 payload_mass_center_z

msg 成员

• x: X轴偏移方向
• y: Y轴偏移方向
• z: Z轴偏移方向
• a: 绕A轴旋转
• b: 绕B轴旋转
• c: 绕C轴旋转
• payload_mass: 负载质量
• payload_inertia: 负载惯性
• payload_mass_center_x: 负载质心X
• payload_mass_center_y: 负载质心Y
• payload_mass_center_z: 负载质心Z

4.12 ServoL 直线伺服 ServolMove

float64[] target_pose     # [x, y, z, rx, ry, rz] 目标笛卡尔位姿
float64 step_size         # 插值步长 (mm)，相邻插值点之间的最大笛卡尔距离，默认 2.0
int32 coord               # 坐标系：1=基座标系(Base) 2=工具坐标系(Tool) 3=用户坐标系(User)

msg 成员

• target_pose: 目标笛卡尔位姿 [x, y, z, rx, ry, rz]
• step_size: 插值步长（mm），默认 2.0
• coord: 坐标系编号（1=基座标系，2=工具坐标系，3=用户坐标系）

前置条件：需先调用 open_servoj 打开关节跟踪模式；每次收到该话题消息，节点自动获取当前位姿，插值并 IK 转为关节角后通过 servoj 发送。

5. tl_ros2_interface 服务（srv）说明

下面列出 srv 文件的请求/响应字段及简要说明。

5.1 坐标转换 CoordTransform

int32 origin_coord
int32 target_coord
int32 form
float64[] origin_pos
float64[] reference_pos
---
bool success
string message
float64[] target_pos

• origin_coord/target_coord: 源/目标坐标系编号
• form: 转换模式
• origin_pos/reference_pos: 输入位置与参考位置
• 返回: success/message/target_pos

5.2 所有作业文件名 GetAllJobFileName

---
bool success
string message
tl_ros2_interface/JobFileName[] robots_file

• 返回所有作业文件名列表
• 返回: success/message/robots_file（作业文件名列表）

5.3 坐标系编号 GetCoordNum

---
bool success
string message
int32 tool_num
int32 user_num

• 返回工具与用户坐标系编号
• 返回: success/message/tool_num（工具坐标系编号）/user_num（用户坐标系编号）

5.4 当前坐标系 GetCurrentCoord

---
bool success
string message
int32 coord

• 返回当前坐标系编号
• 返回: success/message/coord（当前坐标系编号）

5.5 机器人 DH 参数 GetDHParam

---
bool success
string message
tl_ros2_interface/RobotDHParam param

• 返回机器人 DH 参数
• 返回: success/message/param（DH 参数）

5.6 数字输入输出状态 GetDigitalInputOutput

---
bool success
string message
int32[] input
int32[] output

• 返回数字输入输出状态
• 返回: success/message/input（数字输入状态数组）/output（数字输出状态数组）

5.7 全局路点 GetGlobalPos

string pos_name
---
bool success
string message
float64[] pos

• 输入 pos_name，返回对应全局路点
• pos_name: 全局位置点名称
• 返回: success/message/pos（位置坐标数组）

5.8 关节软件版本号 GetJointSoftwareVersion

int32 axis_num
---
bool success
string message

• 查询指定轴的软件版本（返回 message）
• axis_num: 轴编号
• 返回: success/message（软件版本信息）

5.9 关节温度 GetJointTemperature

---
bool success
string message
float64[] temperatures

• 返回各关节温度数组
• 返回: success/message/temperatures（各关节温度数组）

5.10 关节电压 GetJointVoltage

---
bool success
string message
float64[] joint_voltage
float64[] positioner_voltage

• 返回关节电压数组
• 返回: success/message/joint_voltage（关节电压数组）/positioner_voltage（定位器电压数组）

5.11 电机温度 GetMotorCurrent

---
bool success
string message
float64[] motor_current

• 返回电机电流数组
• 返回: success/message/motor_current（电机电流数组）

5.12 目标位姿可达状态 GetPosReachable

float64[] pos
string move_type
---
bool success
string message

• 输入目标位姿，返回是否可达
• pos: 目标位姿数组
• move_type: 运动类型（如关节运动、直线运动等）
• 返回: success/message

5.13 位姿转换 GetPosTransform

float64[] input
---
bool success
string message
float64[] output

• 输入位姿，返回转换后的位姿
• input: 输入位姿数组
• 返回: success/message/output（转换后的位姿数组）

5.14 关节参数 GetRobotJointParam

int32 id
---
bool success
string message
tl_ros2_interface/RobotJointParam param

• 查询并返回指定关节参数
• id: 关节编号
• 返回: success/message/param（关节参数）

5.15 机械臂运行状态 GetRobotState

int32 channel
bool stop
int32 mode
int32 interval
bool io_state
int32 position
bool detail_motion_pos
int32 pos_sum
string[] io_port
string[] optional
---
bool success
string message

• 获取机械臂运行相关状态，包含 IO 与运动详情
• channel: 通道号
• stop: 是否停止
• mode: 模式
• interval: 查询间隔
• io_state: 是否返回 IO 状态
• position: 位置类型
• detail_motion_pos: 是否返回详细运动位置
• pos_sum: 位置数量
• io_port: 指定 IO 端口列表
• optional: 其他可选参数
• 返回: success/message

5.16 获取机械臂运行速度 GetSpeed

---
bool success
string message
float64 speed

• 返回当前全局速度设置

5.17 插入运动指令 JobInsertMove

int32 line
tl_ros2_interface/MoveCommand cmd
---
bool success
string message

• 向作业文件插入一条运动指令
• line: 插入的行序号
• cmd: 运动指令（MoveCommand 类型）
• 返回: success/message

5.18 运行指定作业文件 JobRun

string job_name
---
bool success
string message

• 请求运行指定作业文件
• job_name: 作业文件名
• 返回: success/message

5.19 机械臂点动 Jogging

int32 axis
bool direction
---
bool success
string message

• 点动控制指定轴及方向
• axis: 轴编号
• direction: 运动方向（true 为正方向，false 为负方向）
• 返回: success/message

5.20 下载日志 LogDownload

int32 count
string directory_path
---
bool success
string message

• 请求下载日志到目录
• count: 日志条数
• directory_path: 下载保存路径
• 返回: success/message

5.21 写 Modbus ModbusWrite

int32 master_id
int32 addr
int32[] data
tl_ros2_interface/ModbusMasterParam master_param
---
bool success
string message

• 向Modbus从站写入数据
• master_id: 主站 ID
• addr: 寄存器地址
• data: 要写入的数据数组
• master_param: Modbus 主站通信参数（TCP 或 RTU）
• 返回: success/message

5.22 读 Modbus ModbusRead

int32 master_id
int32 addr
int32 quantity
tl_ros2_interface/ModbusMasterParam master_param
---
bool success
string message
int32[] data

• 从Modbus读取数据
• master_id: 主站 ID
• addr: 寄存器起始地址
• quantity: 读取的寄存器数量
• master_param: Modbus 主站通信参数（TCP 或 RTU）
• 返回: success/message/data

5.23 关节跟踪 OpenServoJ

float64[] vmax
float64[] amax
float64[] jmax
---
bool success
string message

• 设置并打开关节伺服的最大速度/加速度
• vmax: 最大速度数组
• amax: 最大加速度数组
• jmax: 最大加加速度数组
• 返回: success/message

5.24 MoveJ 队列运动 QueueMotionMoveJ

bool is_continue
tl_ros2_interface/MoveCommand cmd
---
bool success
string message

• 将 MoveJ 命令加入队列或继续队列执行
• is_continue: 是否继续队列执行（false 为新队列，true 为继续）
• cmd: 运动指令
• 返回: success/message

5.25 MoveJ 队列运动模式 QueueMotionSetStatus

bool status
---
bool success
string message

• 设置队列运动模式开关
• status: true 开启队列运动，false 关闭队列运动
• 返回: success/message

5.26 机械臂默认 DH 参数 RestoreDefaultDHParam

int32 robot_num
---
bool success
string message

• 恢复默认 DH 参数
• robot_num: 机器人编号
• 返回: success/message

5.27 设置关节零点 SetAxisZeroPos

int32 axis
---
bool success
string message

• 设置轴零位
• axis: 轴编号
• 返回: success/message

5.28 控制器有线网口IP设置 SetControllerIP

string name
string addr
string gateway
string dns
---
bool success
string message

• 配置控制器网络参数
• name: 网络接口名称
• addr: IP 地址
• gateway: 网关地址
• dns: DNS 服务器地址
• 返回: success/message

5.29 设置坐标系编号 SetCoordNum

int32 tool_num
int32 user_num
---
bool success
string message

• 设置工具坐标系和用户坐标系编号
• tool_num: 工具坐标系编号
• user_num: 用户坐标系编号
• 返回: success/message

5.30 设置当前坐标系 SetCurrentCoord

int32 coord
---
bool success
string message

• 设置当前坐标系
• coord: 坐标系编号
• 返回: success/message

5.31 设置当前运行模式 SetCurrentMode

int32 mode
---
bool success
string message

• 设置当前工作模式
• mode: 工作模式
• 返回: success/message

5.32 设置机械臂 DH 参数 SetDHParam

tl_ros2_interface/RobotDHParam param
---
bool success
string message

• 设置机器人 DH 参数
• param: DH 参数
• 返回: success/message

5.33 设置数字输出 SetDigitalOutput

int32 port
int32 value
---
bool success
string message

• 设置数字输出口值
• port: 输出端口号
• value: 输出值（0 或 1）
• 返回: success/message

5.34 设置拖拽模式 SetDragMode

int32 mode
---
bool success
string message

• 设置拖拽（示教）模式
• mode: 拖拽模式（0 关闭，1 开启）
• 返回: success/message

5.35 设置全局位点 SetGlobalPos

string pos_name
float64[] pos_info
---
bool success
string message

• 设置/保存全局位置点
• pos_name: 位置点名称
• pos_info: 位置坐标数组
• 返回: success/message

5.36 设置关节参数 SetRobotJointParam

int32 id
tl_ros2_interface/RobotJointParam param
---
bool success
string message

• 设置指定关节参数
• id: 关节编号
• param: 关节参数
• 返回: success/message

5.37 设置运行速度 SetSpeed

float64 speed
---
bool success
string message

• 设置全局速度
• speed: 速度值（百分比或比例）
• 返回: success/message

5.38 设置工具手参数 SetToolParam

int32 tool_num
tl_ros2_interface/ToolParam param
---
bool success
string message

• 设置工具参数（TCP、负载）
• tool_num: 工具编号
• param: 工具参数（位姿、负载等）
• 返回: success/message

5.39 设置用户坐标系 SetUserCoord

int32 user_num
tl_ros2_interface/CartesianPose pos
---
bool success
string message

• 设置用户坐标系的笛卡尔位姿
• user_num: 用户坐标系编号
• pos: 笛卡尔位姿
• 返回: success/message

5.40 工具手参数标定 ToolHandCalib

int32 tool_num
int32 point_num
---
bool success
string message

• 工具手标定
• tool_num: 工具编号
• point_num: 标定点数
• 返回: success/message

5.41 拖拽轨迹回放 TrackPlayback

int32 vel
---
bool success
string message

• 回放轨迹
• vel: 回放速度
• 返回: success/message

5.42 保存轨迹 TrackSave

string traj_name
---
bool success
string message

• 保存轨迹
• traj_name: 轨迹名称
• 返回: success/message

5.43 当前电机力矩 GetCurrentMotorTorque

---
bool success
string message
int32[] motor_torque
int32[] motor_torque_sync

• 查询当前电机力矩
• 返回: success/message/motor_torque（当前电机力矩）/motor_torque_sync（同步轴电机力矩）

5.44 当前线速度和关节速度 GetCurrentLineJointSpeed

---
bool success
string message
float64 line_speed
float64[] joint_speed
float64[] joint_speed_sync

• 查询当前线速度和关节速度
• 返回: success/message/line_speed（当前线速度）/joint_speed（关节速度）/joint_speed_sync（同步轴关节速度）

5.45 查询当前运行模式 GetCurrentMode

---
bool success
string message
int32 mode

• 查询当前运行模式
• 返回: success/message/mode（当前模式：0-示教 1-远程 2-运行）