状态看板与指令 ======================================================================= .. toctree:: :maxdepth: 5 状态看板 -------------------------------------- 状态看板实际上是一个默认随着插件开机自启动的controller，名称为fairino_hardware_state_broadcaster，它以500HZ的频率监控插件中所有状态反馈接口，并以topic的形式发布出来，消息类型名称是fairino_hardware_state_broadcaster/msg/HardwareState。 .. centered:: 表2-1 具体的msg定义 .. list-table:: :widths: 20 20 60 :header-rows: 0 :align: center * - **字段名称** - **数据类型** - **物理含义与业务释义** * - header - std_msgs/Header - 包含时间戳（Timestamp）与坐标系信息，用于数据帧的高精度时间同步。 * - joint_names - string[] - 关节名称。对应 URDF 中定义的关节名，用于保证数据映射不乱序。 * - errorcode - int32[] - 单轴伺服错误码。记录各关节驱动器自身的独立报警状态（如单轴过载/编码器异常）。 * - position - float64[] - 实际位置反馈。电机的真实位置读数（单位：rad 或 m）。 * - velocity - float64[] - 实际速度反馈。电机的真实速度读数（单位：rad/s 或 m/s）。 * - effort - float64[] - 实际电流/力矩反馈。电机当前的实际出力估算值。 * - sensortorque - float64[] - 传感器力矩反馈。若配备双编码器或外部关节扭矩传感器，此处为真实物理扭矩。 * - stateword - uint16[] - 伺服状态字 (Statusword)。严格对应 EtherCAT CiA 402 标准状态机字典（如 0x0237 代表运行使能）。 * - opmode - int32[] - 伺服运行模式 (Mode of Operation)。如 8 代表 CSP（周期同步位置），10 代表 CST（周期同步力矩）。 * - command_position - float64[] - 指令位置。ROS 2 控制器刚向该关节下发的目标点位。与 position 相减可得“跟随误差”。 * - command_velocity - float64[] - 指令速度。ROS 2 控制器下发的目标前馈速度。 * - command_torque - float64[] - 指令力矩。ROS 2 控制器下发的目标前馈力矩。 * - version_major - float64 - 主版本号。底层硬件或固件的核心大版本。 * - version_minor - float64 - 次版本号。功能更新版本迭代号。 * - version_minor2 - float64 - 修订版本号。小补丁或 Bug 修复号。 * - hexerrorcode_curerrcode - int32 - 当前系统致命/运行故障码。对应 32 位 Hex 码。非零时立即触发全臂抱闸及 Dump 故障快照。 * - hexerrorcode_curwarncode - float64 - 当前系统一般警告码。对应 32 位 Hex 码（如触发轨迹削峰）。仅作记录上报，不阻断运动。 * - generalio_di - uint32 - 通用数字输入 (DI)。通过 32 位二进制掩码表示多路数字输入电平（如安全门、外部按钮状态）。 * - generalio_ai - float64 - 通用模拟输入 (AI)。0-10V 或 4-20mA 模拟量信号的数字化读数。 * - interface485_feedback485 - float64 - RS-485 接口反馈。用于末端智能夹爪或外部串口传感器的通信数据回读。 * - interfacecan_feedbackcan - float64 - CAN 总线接口反馈。扩展 CAN 节点的外围通信数据或状态反馈。 * - interfacesdo_sdoreaddata - float64 - SDO 读取数据。EtherCAT 非周期性数据对象 (SDO) 字典查询后返回的参数值。 * - interfacesdo_sdostatus - float64 - SDO 通信状态。反映 SDO 异步读写请求是否成功握手或报错。 * - interfaceGripper1_act - float64 - 左臂夹爪的act状态(需要具有末端板的手臂型号) * - interfaceGripper1_id - float64 - 左臂夹爪的id(需要具有末端板的手臂型号) * - interfaceGripper1_cmdnum - float64 - 左臂夹爪指令号(需要具有末端板的手臂型号) * - interfaceGripper1_curpos - float64 - 左臂夹爪的当前位置(需要具有末端板的手臂型号) * - interfaceGripper1_curtor - float64 - 左臂夹爪的当前电机扭矩(需要具有末端板的手臂型号) * - interfaceGripper1_done - float64 - 左臂夹爪的当前指令执行是否执行完成(需要具有末端板的手臂型号) * - interfaceGripper1_error - float64 - 左臂夹爪的当前错误码(需要具有末端板的手臂型号) * - interfaceGripper2_act - float64 - 右臂夹爪的act状态(需要具有末端板的手臂型号) * - interfaceGripper2_id - float64 - 右臂夹爪的id(需要具有末端板的手臂型号) * - interfaceGripper2_cmdnum - float64 - 右臂夹爪指令号(需要具有末端板的手臂型号) * - interfaceGripper2_curpos - float64 - 右臂夹爪的当前位置(需要具有末端板的手臂型号) * - interfaceGripper2_curtor - float64 - 右臂夹爪的当前电机扭矩(需要具有末端板的手臂型号) * - interfaceGripper2_done - float64 - 右臂夹爪的当前指令执行是否执行完成(需要具有末端板的手臂型号) * - interfaceGripper2_error - float64 - 右臂夹爪的当前错误码(需要具有末端板的手臂型号) * - freedrive1_flag - float64 - 左臂拖动按钮触发标志位，1代表触发(需要具有末端板的手臂型号) * - freedrive2_flag - float64 - 右臂拖动按钮触发标志位，1代表触发(需要具有末端板的手臂型号) * - force_sensor1_linx - float64 - 左臂力矩传感器x方向力(需要具有末端板的手臂型号) * - force_sensor1_liny - float64 - 左臂力矩传感器y方向力(需要具有末端板的手臂型号) * - force_sensor1_linz - float64 - 左臂力矩传感器z方向力(需要具有末端板的手臂型号) * - force_sensor1_rotx - float64 - 左臂力矩传感器x方向扭矩(需要具有末端板的手臂型号) * - force_sensor1_roty - float64 - 左臂力矩传感器y方向扭矩(需要具有末端板的手臂型号) * - force_sensor1_rotz - float64 - 左臂力矩传感器z方向扭矩(需要具有末端板的手臂型号) * - force_sensor2_linx - float64 - 左臂力矩传感器x方向力(需要具有末端板的手臂型号) * - force_sensor2_liny - float64 - 右臂力矩传感器y方向力(需要具有末端板的手臂型号) * - force_sensor2_linz - float64 - 右臂力矩传感器z方向力(需要具有末端板的手臂型号) * - force_sensor2_rotx - float64 - 右臂力矩传感器x方向扭矩(需要具有末端板的手臂型号) * - force_sensor2_roty - float64 - 右臂力矩传感器y方向扭矩(需要具有末端板的手臂型号) * - force_sensor2_rotz - float64 - 右臂力矩传感器z方向扭矩(需要具有末端板的手臂型号) 其中，hexerrorcode_curerrcode是当前系统的错误码，一旦该数值为非0，说明系统存在错误，由于错误码显示使用了十进制，而编写错误码采用了十六进制，因此需要讲十进制数据转换成十六进制数，才能解析出错误码对应的故障信息，以下是32位错误码组成说明。 .. centered:: 表2-2 插件32位错误码组成说明表 .. list-table:: :widths: 20 20 60 :header-rows: 0 :align: center * - **字节位置** - **名称** - **取值及含义** * - [31:24] 字节4 - Severity (故障等级) - | 0x00 = OK (正常) | 0x01 = INFO (提示信息) | 0x02 = WARN (一般警告，不阻断运行) | 0x0E = ERROR (运行故障，打断运动) | 0x0F = FATAL (致命故障，触发急停与安全锁) * - [23:16] 字节3 - Subsystem (子系统模块) - | 0x00 = INIT (初始化过程) | 0x10 = RUN (运行过程) | 0x20 = SENSOR (传感器) | 0x30 = HAL (硬件抽象层反馈) * - [15:08] 字节2 - MainCode (主错误码) - 例如：0x00, 0x01, 0xFF (全局广播) * - [07:00] 字节1 - SubCode (从错误码) - 流水号，用于精确区分具体的报错原因 .. note:: 请注意，目前规定致命级别的错误不支持错误恢复，错误级别的均可以通过指令服务器的reseterror指令恢复，警告级别的信息会通过curwarncode提示但是不会中断系统运行。 .. centered:: 表2-3 致命(FATAL)级别故障码 .. list-table:: :widths: 20 20 60 :header-rows: 0 :align: center * - **完整Hex数值** - **故障释义** - **排查与处理方向** * - 0x0F000001 - 参数读取异常，非法参数 - 启动之前是否自行修改过配置文件，或者配置文件是否损坏，建议重新运行frconfig指令，使用法奥给的配置文件进行从站配置 * - 0x0F000002 - 伺服从站格式非法，正则解析减速比失败 - 启动之前是否自行修改过配置文件，或者配置文件是否损坏，建议重新运行frconfig指令，使用法奥给的配置文件进行从站配置 * - 0x0F000004 - 初始化共享内存或者信号量打开失败 - HAL库没有正确启动，请联系法奥技术人员排查 * - 0x0F000008 - 读取初始状态和校验错误 - 调用的HAL库版本不对，请使用法奥提供的升级包进行升级后重启 * - 0x0F000010 - 读取初始状态从站信息校验错误,检查ethercat拓扑结构 - 从站数量和类型校验错误，请检查当前加载的配置是否和真实硬件对应并且确认开机的时候EtherCAT线是接在控制器上的 * - 0x0F000020 - 读取初始状态共享内存对象为空错误 - HAL库退出，请联系法奥技术人员排查 * - 0x0F000040 - 读取初始状态超时 - HAL库退出，请联系法奥技术人员排查 * - 0x0F100001 - 共享内存看门狗超时 - HAL 库掉线或底层驱动进程死掉。排查底层 igh 进程是否正常存活，检查 IPC 共享内存机制是否被阻塞。 * - 0x0F100101 - 从站信息和校验错误 - 底层获取的伺服数据包 CRC 校验失败。重点检查总线网线是否松动、水晶头是否良好，或线缆是否受到强电磁干扰。 * - 0x0F100102 - 从站数量或类型异常 - 实际扫描到的物理关节数量/型号，与 YAML 配置文件定义的拓扑结构不一致。检查配置文件加载是否正确。 * - 0x0F100103 - 状态共享内存指针为空 - 内存映射失败。ROS 2 hardware_interface 无法正确挂载读取机械臂状态的共享内存地址。 * - 0x0F100201 - 指令共享内存指针为空 - 内存映射失败。ROS 2 hardware_interface 无法正确挂载下发运动指令的共享内存地址。 .. note:: 请注意，在系统刚启动的时候，解析出来的错误码可能在以上表格中找不到，比如会出现0x0F00005，这个错误码是0x0F00001和0x0F00004的组合，因为在系统初始化的时候，进行一系列的操作均可能出现错误，但是系统没启动之前，这些错误无法立即给出，只能采用叠加累计的方式，因此会在初始化后出现这种组合错误码。 .. centered:: 表2-4 错误(ERROR)级别错误码 .. list-table:: :widths: 20 20 60 :header-rows: 0 :align: center * - **完整Hex数值** - **故障释义** - **排查与处理方向** * - 0x0E10FF01 - 驱动器故障 (全局广播) - 0xFF 代表任意轴的广播报警。电机可能发生了过流、过载、碰撞导致过力矩，或编码器掉线。需结合单轴 errorcode 进一步定位具体关节。 * - 0x0E100001 - 软急停触发 - 逻辑急停被拍下。上位机或示教器下发了紧急停止指令，底层立刻中断当前运动队列以保障安全。 * - 0x0E100002 - 指令队列长度过长 - 插补缓冲区溢出。上位机下发轨迹点位过密或控制频率过高，导致底层消费者处理超时。需检查控制器执行频率设置。 .. centered:: 表2-5 警告(WARN)级别错误码 .. list-table:: :widths: 20 20 60 :header-rows: 0 :align: center * - **完整Hex数值** - **警告释义** - **排查与处理方向** * - 0x02100001 - 指令步进较大 (触发削峰) - 规划器下发的相邻两点位置差值超过了底层的最大速度/加速度限制，底层强制进行了削峰平滑。可能会导致实际轨迹与预期有极小偏差。 * - 0x02100002 - 指令队列写入失败 - 瞬时并发过高，导致系统在极短瞬间无法将插补点推入无锁队列，可能引起短暂的运动卡顿。 指令服务器 ---------------------------------------- 指令服务器是随着插件系统默认开机自启动的一个controller，名称是fairino_hardware_command_controller，它对外提供了一个名称为command的action服务器，其自定义交互消息格式为： .. centered:: 表2-6 自定义交互消息格式 .. list-table:: :widths: 40 60 :header-rows: 0 :align: center * - string command - Request (Goal) - 字符串指令，例如 "Enable(1)" * - string error_code - Result - 控制器专属 16位 Hex 错误码，例如 "0xC000" * - float32 progress - Feedback - 执行进度 (0.0 ~ 100.0) .. centered:: 表2-7 目前支持的指令表 .. list-table:: :widths: 20 40 40 :header-rows: 0 :align: center * - **指令名称** - **功能深度描述** - **输入参数说明** * - activatecontroller - 激活指定的 ROS 2 控制器。通过调用 controller_manager 的服务，将目标控制器状态从 inactive 切换为 active。 - args[0]: 控制器名称 (String)示例: fairino_trajectory_controller * - deactivatecontroller - 停用指定的 ROS 2 控制器。将正在运行的控制器状态切换为 inactive，常用于控制权交接（如切出轨迹控制，切入阻抗控制）。 - args[0]: 控制器名称 (String)示例: fairino_trajectory_controller * - enable - 机器人使能 (Servo ON)。向下位机发送指令，闭合继电器，给各关节伺服电机上电并开启力矩输出。 - 无参数的情况下是全部关节使能，有参数的情况按照Bit位使能(比如1是第一关节，2是第二关节，4是第三关节，8是第四关节，7是一二三关节) * - disable - 机器人下使能 (Servo OFF)。切断伺服电机力矩输出，机械臂进入抱闸（Brake）状态。 - 同enable函数用法 * - setdo - 设置数字输出 (Digital Output)。控制机器人控制柜或末端工具的 IO 针脚电平，用于触发外围设备（如夹爪、焊枪、继电器）。 - args[0]: IO 端口索引/名称args[1]: 状态 ("1"/"true" 开, "0"/"false" 关) * - zeroing - 执行机械臂零点标定。触发底层寻零逻辑，使关节自动寻找机械原点并重置绝对编码器偏置。 - 同enable用法 * - reseterror - 错误复位。当底层触发 ERROR 报警导致抱闸后，如果物理故障已解除，调用此指令清除底层错误标志，使系统恢复待机状态。 - 无参数 * - frconfig - 动态生成机器人的核心配置文件。拉起后台 Python 脚本，解析 YAML 配置，动态生成 URDF 模型和 controller_manager 配置文件。 - args[0] (可选): /opt/fairino_art_plugin/config文件夹下配置文件名。若为空，默认使用 "fairino_config.yaml"，等同于frconfig(fairino_config.yaml) * - upgradeplugin - 自动升级底层驱动与插件包。解压传入的 zip 包，清理旧环境，将新代码覆盖至 /opt 系统目录，并自动修复 .sh 及可执行文件的权限。 - args[0]: 升级包 .zip 的绝对路径。示例: ["/tmp/update_v2.zip"] * - packlog - 一键打包系统日志与 Dump 故障快照。将 /home/fairino/plugin_log/ 下的故障快照及系统运行日志压缩成一个归档文件，方便现场人员拷贝导出。 - 无参数 (或可选传入目标导出路径) * - recorddata - 控制用户高频数据录制器。在内存中开启/关闭 20MB 的循环数据录制队列，用于抓取高精度的关节位置、力矩及状态波形。 - args[0]: 动作指令。仅接受 "start" 或 "stop" (忽略大小写)。 * - switchmode - 切换伺服控制模式，注意，关节伺服有位置模式和扭矩模式，模块化伺服有位置模式和速度模式，指定序号的伺服如果参数和允许的模式不适配会返回错误 - args[0]:模式名称,position为位置模式，velocity为速度模式，torque为扭矩模式，args[1]:从站mask掩码，按照bit位为1的从站序号去切换模式 * - reboot - 重启指令 - 无参数 * - shutdownsys - 关机指令 - 无参数 * - getecatcommstatus - 获取ethercat通讯信息，用于辅助诊断ethercat通讯状态 - 无参数 * - enablevelff - 开启指定速度前馈（默认关闭）,插件根据位置指令差分计算速度前馈并下发给电机，用于减小位置跟踪延迟。仅在位置控制模式下生效。 - 同enable函数用法 * - disablevelff - 关闭机器人速度前馈功能 - 同enable函数用法 同样的，根据上面阐述的指令服务器交互信息格式，每个一string指令都会有一个string反馈值，这个返回值是16位的错误码系统，其具体函数见如下表格： .. centered:: 表2-8 具体函数表 .. list-table:: :widths: 20 40 40 :header-rows: 0 :align: center * - **返回值** - **触发场景释义** - **常见排查与处理建议** * - "0xC000" - 执行成功。指令完整拉起并顺利结束。 - 无需处理，上位机可继续下发后续流程。 * - "0xC010" - 参数非法或防注入拦截。传入参数为空，或包含危险 Shell 字符。 - 检查上位机下发的参数，确保仅包含合法文件路径或纯文本。 * - "0xC011" - 依赖服务不可用。试图调用的 ROS 2 内部服务（如 controller_manager）掉线或未就绪。 - 检查目标节点是否存活，或等待系统完全启动后再下发指令。 * - "0xC012" - 硬件状态异常。在下发需要硬件配合的指令时，检测到底层处于报错或未使能状态。 - 请先查阅 fairino_hardware 的硬件报警码，复位硬件后再试。 * - "0xC013" - 指令超时。指令在规定时间内未完成（如下载、系统响应等）。 - 检查网络连接或系统负载是否过高。 * - "0xC020" - 控制器切换失败。软切换（如从关节空间切换到笛卡尔空间 Controller）被系统拒绝。 - 检查控制器名称是否拼写正确，或控制器端口占用冲突 * - "0xC021" - 校零超时。 - 检查插件是否正常运行中 * - "0xC030" - 配置生成失败。Python 脚本解析 YAML 或生成 URDF/控制器配置失败。 - 检查 YAML 格式是否正确，文件是否人为篡改或者出现乱码 * - "0xC040" - 解压升级包失败。unzip 指令返回非零退出码。 - 检查 .zip 文件路径是否正确、压缩包是否损坏或 /tmp 空间是否满。 * - "0xC041" - 目录覆盖失败。插件升级覆盖到 /opt/... 目录时出错。 - 检查目录的权限归属（属主是否为 fairino）或是否被占用。 * - "0xC050" - 打包日志失败。收集、压缩 Dump 文件及系统运行日志时报错。 - 检查目标存储路径权限及磁盘剩余容量。 * - "0xC060" - 数据记录操作失败。recorddata(start/stop) 指令处理失败或写入异常。 - 检查 /tmp/record_data 目录是否可写，或内存中是否存在死锁。 * - "0xC0FE" - 未知指令。上位机发送了一个 Action Server 无法解析的命令字。 - 对齐上位机与下位机的通信协议接口文档。 * - "0xC0FF" - 底层抛出异常。C++ 或脚本内部发生未捕获的严重崩溃/被系统强杀。 - 需查看宿主机 dmesg 或节点标准输出，排查段错误（Segfault）或依赖丢失。