202601 RCS-Lite 控制器客制车型顶升支撑配置
交大顶升车型需要在 RCS-Lite 控制器中完成顶升支撑机构的参数化控制。现场目标很明确：同一套任务模板既要支持顶升伸出，也要支持顶升收回，同时还要能在车体参数、任务模板和控制脚本之间保持一致。
本文基于现场配置界面与 sjt_ctrl.py 控制脚本，整理一套可复用的落地方案。脚本部分只保留核心逻辑，重点说明参数如何从任务模板传到控制器，再由机构脚本执行顶升动作。
场景目标
这套客制车型的核心需求有三点：
- 顶升动作不能写死在两个独立业务里，而是要通过任务参数区分“伸出”和“收回”。
- 任务模板 要能直接编排到调度流程中，调度侧只管传参，不关心底层 IO 细节。
- 车辆被取消任务或异常中断时，需要有明确的机构回收策略，避免顶升机构停在中间态。
对应现场界面，最终形成的是一套“任务模板透传参数 + 控制器脚本解析参数 + 执行器驱动机构”的方案。
总体方案
整套链路可以概括为下面 4 步：
- 在任务模板中增加“透传任务”步骤。
- 通过消息体下发
extend参数，1表示伸出，0表示收回。 - 控制器脚本
sjt_ctrl.py从attach_info中读取参数，并调用SjtActuator.extend()或SjtActuator.retract()。 - 动作执行完成后等待机构稳定，再返回任务完成状态。
这套设计的关键点是：顶升与下降不再依赖两份完全不同的脚本，而是统一由一个脚本根据参数切换执行路径。
RCS-Lite 侧配置要点
1. AMR 类型开启透传能力
在“AMR类型编辑”界面中，需要为该车型开启“是否透传”。
这个开关的作用，是允许任务模板中的参数透传到车端脚本。如果这里没有打开，即使任务模板配置了消息体，车端脚本也收不到期望的 attach_info 参数。
对于顶升车型，这一步是前置条件。
2. 服务能力集开启参数任务上报
在“Rcs能力集 -> 本地配置”中，需要开启“amr参数设置值任务上报”。
这个配置决定了任务参数能否按预期传递到控制器业务层。现场联调时，如果脚本里打印不到 extend 参数，优先检查这里是否已启用。
3. 客制车参数绑定机构脚本
在 MapStudioPro 的“客制车参数”页面中，需要重点确认两个脚本项：
| 配 置项 | 建议脚本 | 作用 |
|---|---|---|
| 第三方机构脚本 | sjt_ctrl | 正常任务流程中的顶升伸出/收回 |
| 取消任务脚本 | sjt_retract | 任务取消、异常退出时的安全收回 |
本文重点介绍的是 sjt_ctrl.py。实际项目里，取消任务脚本建议单独实现“强制收回”，这样任务在中断时不会把机构留在伸出状态。
任务模板配置
现场界面里分别配置了“交大顶升”和“交大下降”两套模板，本质上差异只有透传参数不同。
顶升模板
典型流程如下：
- 移动
- 透传任务
透传任务的消息体配置为：
[
{
"key": "extend",
"value": 1
}
]
这里的 value = 1 表示顶升伸出。
下降模板
典型流程如下：
- 移动
- 透传任务
- 移动
透传任务的消息体配置为：
[
{
"key": "extend",
"value": 0
}
]
这里的 value = 0 表示顶升收回。
从任务编排角度看，这种做法有两个直接好处：
- 模板维护简单，顶升/下降只靠参数区分，不需要重复维护两份机构逻辑。
- 上层流程更直观，任何人看到任务模板都能快速判断当前要执行的是伸出还是收回。
控制脚本设计
参数约定
脚本约定使用 extend 作为唯一动作参数：
{
"attach_info": [
{"key": "extend", "value": 1}
]
}
其中：
| 参数 | 含义 |
|---|---|
extend = 1 | 顶升伸出 |
extend = 0 | 顶升收回 |
这样定义后，任务模板、控制器日志和机构脚本之间的语义是一致的，联调时不容易出现“参数名字对了但动作含义反了”的问题。
核心代码
下面只保留脚本中的核心部分，用来说明参数解析和动作分发逻辑：
import enum
import time
import traceback
from sec_dev import TemplateBusiness, BusinessStatus
from dev_api import SecDevInterface
from sjt_actuator import SjtActuator, set_module_alarm
class ALARM_CODE(enum.IntEnum):
ARG_ERROR = 1
RUN_ERROR = 2
class Business(TemplateBusiness):
def __init__(self, robot: SecDevInterface, params):
super().__init__()
robot.log(f"sjt_ctrl script 参数: {params}")
extend_value = None
try:
for item in params["attach_info"]:
if item.get("key") == "extend":
extend_value = int(item["value"])
break
except Exception:
pass
if extend_value is None:
set_module_alarm(robot, ALARM_CODE.ARG_ERROR.value, 1, "脚本参数错误：缺少 extend 参数", "检查脚本参数")
self.do_extend = None
else:
self.do_extend = extend_value == 1
self.sjt = SjtActuator()
def execute(self, robot: SecDevInterface, args):
if self.do_extend is None:
return BusinessStatus.FAILED
try:
if self.do_extend:
self.sjt.extend(robot)
else:
self.sjt.retract(robot)
except Exception as exc:
robot.log(f"顶升动作失败: {exc}\n{traceback.format_exc()}")
set_module_alarm(robot, ALARM_CODE.RUN_ERROR.value, 1, f"顶升动作失败: {exc}", "检查顶升机构")
return BusinessStatus.FAILED
time.sleep(11)
return BusinessStatus.FINISHED
这段代码体现了 3 个核心设计点。
1. 只保留一个动作开关
脚本只关注一个参数 extend，初始化阶段就把它转换成布尔值 self.do_extend。这样后续执行阶段不需要再解析复杂参数，业务逻辑足够稳定。
2. 参数校验与动作执行分离
参数错误在 __init__ 阶段就完成判断，并上报参数异常告警。这样进入 execute() 时，只需要决定是否允许执行，不会把“参数缺失”和“机构动作失败”混为一类问题。
3. 动作完成后增加稳定等待
脚本在执行完伸出或收回后固定等待 11 秒，再返回 FINISHED。这不是为了拖慢任务，而是为了给线性执行器预留稳定时间，避免调度过早发起下一步动作，导致机构尚未到位。
小结
这套顶升支撑方案的关键，不在于脚本本身有多复杂，而在于配置、参数和执行逻辑是否保持同一语义。
落地时抓住 4 个点即可：
- AMR 类型开启透传。
- 服务能力集开启参数任务上报。
- 任务模板通过
extend参数区分伸出与收回。 - 控制器脚本统一解析参数，并调用同一套执行器接口。
这样做之后，RCS-Lite 侧的任务编排会更清晰，控制器脚本也更容易维护，后续如果再增加其他机构动作，也可以继续沿用这套参数化思路。