Artisan事件动作命令速查表
本文是 Artisan（artisan scope）咖啡烘焙软件的事件动作命令速查表，覆盖
Config » Events与Config » Alarms中 Action 字段的可用命令、参数格式与语法约定。内容依据 Artisan 源码仓库
src/help/目录下四个内置帮助页原文整理：eventbuttons_help.py、eventsliders_help.py、alarms_help.py、symbolic_help.py。命令名与参数保持英文原文，说明为中文。整理日期：2026-09-15
目录
权威来源与查阅优先级
Artisan 的命令清单有三处来源，优先级从高到低：
| 优先级 | 来源 | 位置 | 适用场景 |
|---|---|---|---|
| 一 | 软件内置帮助页 | Config » Events 对话框内的 Help 按钮 |
与当前安装版本严格对应，配置前必查 |
| 二 | 官网文档 | artisan-scope.org/docs/events/、/docs/alarms/ |
理解事件、报警、动作的联动逻辑与实战配置 |
| 三 | 源码帮助页原文 | 仓库 src/help/ 目录下的 *_help.py |
离线查阅、批量检索、版本对比 |
表 1：命令清单的三处来源及优先级
官方文档对 Action 字段的定位是：「ADVANCED USERS - The Action column is where you can add automation commands. Check the Help page for the Events dialog to see all the possibilities.」即完整命令表以软件内置帮助页为准，官网文档只讲配置思路。
各对话框都有自己的帮助页，除事件按钮外还包括：alarms（报警动作）、event sliders（事件滑块）、event annotations（事件标注）、symbolic formulas（符号公式）、MODBUS、MQTT、S7、programs（外部程序）、transposer、autosave、energy、keyboard shortcuts。
版本差异提醒
帮助文本未逐条标注命令的引入版本。唯一明确标记废弃的是 MODBUS 的
write()，原文注明「DEPRECATED: use writeSingle for function 6 or writeWord for function 16」。若某条命令配置后不生效，先回软件内置帮助核对当前版本是否支持。另外，本文的命令清单读自仓库
master分支，比 v4.2.0 等发布版超前，可能含有当前版本尚未提供的命令。
语法约定
所有 Action 命令共享以下书写规则。
| 规则 | 写法 | 说明 |
|---|---|---|
| 多命令串联 | cmd1;cmd2;cmd3 |
用分号分隔，按顺序执行 |
| 当前值占位 | {} |
替换为当前按钮或滑块的值；事件类型带偏移时含偏移量 |
| 具名占位 | {ET}、{BT}、{time}、{ETB}、{BTB}、{WEIGHTin} |
依次为当前 ET、当前 BT、当前时间、背景 ET、背景 BT、批次重量（克）。可用于 Serial / Artisan / CallProgram / MODBUS / S7 / WebSocket 命令 |
| 上次读取值 | _ |
MODBUS、S7、WebSocket 的 read 结果绑定到此变量，可在后续命令中引用 |
| 上次按钮状态 | $ |
取值为 1（按下）或 0（正常） |
| 延迟 | sleep(<float>) |
单位为秒，可插入命令链中 |
| 注释 | # 之后的内容被忽略 |
仅报警的 Description 字段支持；其他 Action 不支持注释 |
| 大小写 | 命令名与符号变量按原文大小写 | 符号公式变量区分大小写 |
| 序列号参数 | <sn> |
Phidget 格式为 <hub_serial>[:<hub_port>]；Yoctopuce 为序列号或逻辑名 |
表 2：Action 命令通用语法约定
两条需要特别留意的行为差异：
- Serial Command 不拆分：整个 Documentation 字段作为一个字符串发送到串口设备。若设备不支持用分号拆包，需改用 Multiple Event 类型，引用多个隐藏按钮，每个按钮各自发送一条 Serial 命令。
- 滑块值的类型转换：除 IO、VOUT、S7、RC 四类外，所有 Slider 命令的值会从 float 转为 int。
设备专用命令（Hottop、Aillio R1、Fuji、DTA、Santoker、Kaleido、Orbiter、Shelly 等）仅在对应设备已连接时有效。
通用与流程控制命令
| 命令 | 用途 |
|---|---|
sleep(<float>) |
延迟指定秒数 |
button(i,b) |
将编号 i 的按钮设为按下（b 取 yes/true/t/1）或正常 |
button(<name>|<bool>) |
激活命名按钮，name 取 {START, CHARGE, DRY, FCs, FCe, SCs, SCe, DROP, COOL, OFF}；或把调用按钮本身设为按下 |
button() |
切换调用按钮的状态 |
visible(i,b) |
显示或隐藏编号 i 的按钮 |
slider(n,<bool>) |
显示或隐藏事件类型 n 的滑块，n 取 1～4；n=5 控制 PID SV 滑块 |
popup(<msg>[,<int>]) |
弹出消息框，可选在 <int> 秒后自动关闭 |
message(<msg>) |
在消息栏显示文本 |
notify(<title>,[<msg>]) |
发送系统通知 |
notifications(<bool>) |
启用或禁用通知 |
openProperties |
打开 Roast Properties 对话框 |
keyboard(<bool>) |
启用或禁用键盘模式 |
keepON(<bool>) |
启用或禁用 Keep ON |
表 3：通用与流程控制命令
报警与自动事件命令
| 命令 | 用途 |
|---|---|
alarm(n,<bool>) |
启用或禁用编号 n 的报警 |
alarms(<bool>) |
全局启用或禁用报警 |
alarmset(<as>) |
激活指定编号或标签的报警集 |
autoCHARGE(<bool>) |
启用或禁用自动 CHARGE |
autoDROP(<bool>) |
启用或禁用自动 DROP |
表 4：报警与自动事件命令
PID 控制命令
| 命令 | 用途 |
|---|---|
PIDon / PIDoff / PIDtoggle |
开启、关闭或切换 PID |
pidmode(<int>) |
设定模式：0=手动，1=RS（Ramp-Soak），2=背景跟随 |
p-i-d(<p>,<i>,<d>) |
设置 PID 三个参数 |
pidWeights(<beta>,<gamma>) |
设置 beta 与 gamma 权重 |
pidDerivativeFilter(<n>) |
微分滤波器大小，取值 0 ≤ n < 6 |
pidDerivativeLimit(<n>) |
微分限幅，取值 n ≥ 0 |
pidILF(<n>) |
积分限幅因子，取值 0 ≤ n ≤ 1 |
pidIWP(<bool>) |
切换积分抗饱和 |
pidIRoC(<bool>) |
切换目标处的积分重置 |
adjustSV(<float>) |
在当前 SV 基础上增减 |
pidSV(<float>) |
设定 SV，按当前温度单位 |
pidSVC(<float>) |
设定 SV，强制以摄氏度为单位 |
pidSVbuttons(<bool>) |
切换 SV 按钮的可见性 |
pidRS(<rs>) |
激活 Ramp-Soak 模式，取 1 起的编号或标签 |
pidSource(<int>) |
PID 输入源：0=BT，1=ET(SW)；Arduino 设备取 0～3 |
pidLookahead(<int>) |
PID 前瞻秒数 |
replayLookahead(<int>) |
Ramping Replay 的前瞻秒数 |
表 5：PID 控制命令
界面、画布与回放命令
| 命令 | 用途 |
|---|---|
setCanvasColor(<#RRGGBB>) |
设置画布颜色 |
resetCanvasColor |
重置画布颜色 |
palette(<p>) |
激活调色板，取 0～9 或标签 |
playbackmode(<int>) |
回放模式：0=关，1=按时间，2=按 BT，3=按 ET，4=BT/时间，5=ET/时间 |
playbackdropmode(<int>) |
DROP 回放模式，取 0～3 |
playback(n,<bool>) |
按事件类型 n（1～4）切换回放 |
ramp(n,<bool>) |
按事件类型 n（1～4）切换 ramping |
quantifier(n,<bool>) |
按事件类型切换量化器 |
showCurve(<name>,<bool>) |
name 取 {ET, BT, DeltaET, DeltaBT, BackgroundET, BackgroundBT} |
showExtraCurve(<dev>,<curve>,<bool>) |
curve 取 {T1, T2}，dev 从 0 起计数 |
showEvents(<type>,<bool>) |
type 取 1～5 |
showBackgroundEvents(<bool>) |
背景事件的显隐 |
zoom(<x>[,<y>]) |
缩放画布 |
pan(<x>[,<y>]) |
平移画布 |
center(<x>,<y>[,<clamp>]) |
居中并平移；clamp 默认取决于光标锁定状态 |
clamp(<n>) |
xy 光标锁定模式，取 0～4 |
followMode(<bool>) |
切换跟随模式 |
followModePanning(<x>[,<y>]) |
跟随模式下的额外平移 |
home / back / forward |
工具栏导航 |
setBatchSize(<float>) |
设置批次量；填负值则取背景曲线的值 |
loadBackground(<path>) |
加载背景曲线 |
clearBackground |
清除背景曲线 |
moveBackground(<dir>,<int>) |
dir 取 {up, down, left, right} |
upload2RoastHubs |
上传当前曲线到 RoastHubs |
tare(<int>) |
去皮：1=ET，2=BT，3=E1c1，4=E1c2，依此类推 |
表 6：界面、画布与回放命令
串口与烘焙机专用命令
| Action 类型 | 命令格式 | 说明 |
|---|---|---|
| Serial Command | ASCII 字符串或 a2b_uu(...) 二进制 |
整串发送到串口设备，不按分号拆包 |
| DTA Command | <addr>:<value>，如 4701:1000 |
值以 0.1 为单位时需乘 10；4719:0 表示停止加热 |
| Fuji Command | write(<unitId>,<register>,<value>) |
富士 PID 写入 |
| Hottop Heater / Fan | 直接填数值 | heater 取 0～100，fan 取 0～10 |
| Hottop Command | motor(n),solenoid(n),stirrer(n),heater(h),fan(f) |
n 取 0 或 1 |
| Aillio R1 Heater / Fan / Drum | 直接填数值 | 分别控制加热、风扇、滚筒 |
| Aillio R1 Command | PRS |
发送 PRS 指令 |
| p-i-d（独立 Action 类型） | <p>;<i>;<d> |
配置 PID 三参数 |
表 7：串口与各品牌烘焙机专用命令
MODBUS 命令
| 命令 | 功能码 | 说明 |
|---|---|---|
_ |
— | 上一次 MODBUS 读取的值 |
$ |
— | 上一次按钮状态（1 或 0） |
read(deviceID,reg) |
读 | 读 1 个 16 位寄存器，结果存入 _ |
readSigned(deviceID,reg) |
读 | 同上，按有符号数解释 |
readBCD(deviceID,reg) |
读 | 同上，按 BCD 解释 |
read32(deviceID,reg) |
读 | 读 2 个 16 位寄存器 |
read32Signed(deviceID,reg) |
读 | 同上，按有符号数解释 |
read32BCD(deviceID,reg) |
读 | 同上，按 BCD 解释 |
readFloat(deviceID,reg) |
读 | 读 2 个 16 位寄存器，按 32 位浮点解释 |
writeSingle([dev,reg,val],...) |
6 | 写单个 16 位整数 |
writem(...) |
16 | 写多个寄存器 |
writeWord(...) |
16 | 写多个寄存器 |
writeLong(...) |
16 | 写 32 位整数 |
writeBCD(...) |
16 | 写 BCD 值 |
wcoil(dev,reg,<bool>) |
5 | 写单个线圈 |
wcoils(dev,reg,[<bool>,...]) |
15 | 写多个线圈 |
mwrite(dev,reg,andMask,orMask[,value]) |
22 | 掩码写入 |
write(...) |
— | 已废弃，改用 writeSingle（功能码 6）或 writeWord（功能码 16） |
表 8：MODBUS 命令
S7 命令
| 命令 | 说明 |
|---|---|
_ / $ / sleep / button |
与通用语义一致 |
getDBbool(db,start,idx) |
读取 S7 数据块的布尔值 |
getDBint(db,start,idx) |
读取 S7 数据块的整数 |
getDBfloat(db,start,idx) |
读取 S7 数据块的浮点数 |
setDBbool(db,start,idx,val) |
写入布尔值 |
setDBint(db,start,idx,val) |
写入整数 |
setDBfloat(db,start,idx,val) |
写入浮点数 |
msetDBint(db,start,andMask,orMask,val) |
掩码写入整数 |
表 9：S7 命令
IO 与继电器命令
| 命令 | 平台 | 说明 |
|---|---|---|
set(c,b[,sn]) |
Phidget Binary Out | 设置通道 c 的开关状态 |
toggle(c[,sn]) |
Phidget Binary Out | 切换通道状态 |
pulse(c,t[,sn]) |
Phidget Binary Out | 脉冲输出，t 为毫秒 |
out(c,v[,sn]) |
Phidget Voltage Out | 电压输出，v 为浮点值 |
accel(c,v[,sn]) |
Phidget DCMotor | 设置加速度 |
vel(c,v[,sn]) |
Phidget DCMotor | 设置速度 |
limit(c,v[,sn]) |
Phidget DCMotor | 设置电流限制 |
on / off / flip |
Yoctopuce Relay | 继电器开、关、翻转 |
yset / pip / powerReset |
Yoctopuce Relay | 继电器其他控制 |
slider(c,v) |
通用 | 把滑块 c 移动到值 v |
santoker(<target>,<value>) |
Santoker | target 为十六进制字节形式的目标寄存器 |
kaleido(<target>,<value>) |
Kaleido | 支持 Serial 与 Network 两种连接 |
orbiter(<cmd>[,<val>[,<param>]]) |
Orbiter | cmd 为 1 字节十六进制 |
shellyrelay(n,b) |
Shelly | 智能插座开关 |
publish(<topic>,<value>) |
MQTT | 以 JSON 格式发布消息 |
表 10：IO 与继电器命令
PWM、电压输出与电机命令
| 命令 | 平台 | 说明 |
|---|---|---|
out(ch,val[,sn]) |
Phidget PWM | val 取 0～100 |
frequency / toggle / pulse |
Phidget PWM | 频率、切换、脉冲 |
outhub(port,val[,sn]) |
Phidget HUB PWM | HUB 端口输出 |
togglehub(port,val[,sn]) |
Phidget HUB PWM | HUB 端口切换 |
pulsehub(port,val[,sn]) |
Phidget HUB PWM | HUB 端口脉冲 |
enabled / freq / duty / move |
Yoctopuce PWM | duty 取 0.0～100.0 |
range / out / vout / cout |
Phidget / Yoctopuce VOUT | 电压输出与电流输出 |
pulse / pos / engaged / ramp |
Phidget RC | 舵机控制 |
volt / accel / veloc / set |
Phidget RC | 舵机控制 |
enabled / move / neutral / range |
Yoctopuce RC | 舵机控制 |
set / rescale / engaged(ch,...) |
Phidget Stepper | 步进电机控制 |
表 11：PWM、电压输出与电机命令
WebSocket、多重事件与外部程序
| 命令或类型 | 所属类型 | 说明 |
|---|---|---|
send(<json>) |
WebSocket | 发送 JSON；其中的字面 {} 需双写为 {{}} 转义 |
read(<json>) |
WebSocket | 发送并把响应绑定到 _ |
$ / sleep / button |
WebSocket | 与通用语义一致 |
| Multiple Event | 仅事件按钮可用 | 写法 <btnNum>[,<btnNum>],sleep(<float>),...，逗号分隔，触发其他按钮或插入延迟 |
| Call Program | 外部程序 | 填写程序或脚本路径，支持绝对路径与相对路径 |
表 12：WebSocket、多重事件与外部程序
报警专用动作
报警的动作在 Description 字段填写，可用类型与命令如下。
| Action 类型 | 命令写法 | 说明 |
|---|---|---|
| Pop Up | <text> |
弹窗显示的文本 |
| Event Button | <btn>[><val>],...，如 1>10,2,3>100 |
触发按钮，> 后可覆盖按钮的值 |
| Slider 1～4 | <value> |
设置对应滑块的数值 |
| START / DRY / FCs / FCe / SCs / SCe / DROP / COOL END / OFF / CHARGE | 无参数 | 触发对应的烘焙阶段事件 |
| RampSoak ON / RampSoak OFF | 无参数 | PID 的 Ramp-Soak 模式开关 |
| Set Canvas Color | <color> |
取十六进制色值或颜色名 |
| Reset Canvas Color | 无参数 | 重置画布颜色 |
表 13：报警专用动作类型
报警的 Description 中 # 之后的内容被忽略，可用于写配置备注而不显示在界面上。
符号公式的变量
符号公式是独立于 Action 命令的另一套体系，用于计算派生曲线与判断条件。变量区分大小写。
| 符号 | 含义 | 支持移位 |
|---|---|---|
t |
录制开始后的绝对时间（秒） | 是 |
b |
背景曲线的录制时间（秒） | 是 |
x |
当前通道读数（Plotter 中不可用） | 否 |
Y1, Y2, Y3... |
依次为 ET、BT、Extra#1-T1、Extra#1-T2、Extra#2-T1 等 | 是 |
B1, B2, B3... |
依次为 ET 背景、BT 背景、ExtraBg#1-A、#1-B 等 | 是 |
T1, T2, T3... |
ET、BT、Extra 的去皮值 | 否 |
E1–E4 |
各事件类型最近一次的事件值 | 否 |
R1, R2 |
ET、BT 的 RoR（已平滑） | 是 |
RB1, RB2 |
背景 ET、BT 的 RoR | 是 |
k, o |
RoR 到温度轴的缩放因子与偏移 | 否 |
CHARGE, DRY, FCs, FCe, SCs, SCe, DROP |
对应事件的索引；未设置时为 -1 |
否 |
bCHARGE, bDRY, ... |
背景曲线对应事件的索引 | 否 |
dCHARGE, dDRY, ... |
距离对应事件的秒数 | 否 |
AUCbase, AUCtarget, AUCvalue |
AUC 的基准值、目标值、当前值 | 否 |
pDRY, pFCs |
基于当前 RoR 预测到达 DRY 或 FCs 的秒数 | 否 |
aTMP, aHUM, aPRE |
环境温度、湿度、气压 | 否 |
WEIGHTin, MOISTUREin, TEMPunit |
批次量（克）、生豆含水率（%）、温标（0=摄氏度，1=华氏度） | 否 |
表 14：符号公式核心变量
符号公式的语法与函数
时间移位：Y2[-1] 取前一时刻的 BT，Y2[+1] 取后一时刻（后者仅在 Plotter 中可用）。
事件索引：Y2{0} 取第一条 BT，Y2{CHARGE} 取 CHARGE 时刻的 BT，b{CHARGE} 取背景曲线在 CHARGE 时刻的值。
条件表达式：(true_expr if cond else false_expr)，采用 Python 语义，非零视为 True，0 与 None 视为 False。
| 类别 | 可用项 |
|---|---|
| 数学函数 | abs、acos、asin、atan、cos、sin、tan、degrees、radians、exp、log(x[,base])、min(...)、max(...)、pow(x,y)、sqrt、bit(n,x) |
| 常量 | e（2.71828…）、pi（3.14159…） |
| Plotter 扩展 | P1–P9 引用前序绘图结果；F1–F9 引用本公式的历史结果，可构成反馈环路 |
表 15：符号公式的函数与常量
错误值传播
表达式中若任一变量的值为
-1（表示错误），整个表达式的结果即为-1。用括号包裹可以阻断传播，例如(Y1 + 1)在Y1为-1时结果为0。
配置要点
- 命令不生效先查版本：本表读自 master 分支，优先在软件内置帮助页核对该命令是否存在于当前版本。
- Serial 命令的特殊性：整个字段作为一个字符串发送，需要多条时用 Multiple Event 拆到多个隐藏按钮上。
- 注释只在报警里可用：
#注释仅报警的 Description 字段支持，写在其他 Action 中会被当作命令内容。 - 设备命令需先连接：烘焙机与 IO 设备的专用命令只在对应设备已连接时有效。
- 滑块值会取整：除 IO、VOUT、S7、RC 四类外，滑块命令的值由 float 转为 int，配置精度时需注意。
浙公网安备 33010602011771号