//
//  Klipper G-Code Macro: M109
//  功能: 等待挤出机加热到指定温度
//  原始命令: M109 - 设置挤出机温度并等待达到目标值
//

[gcode_macro M109]
# 定义G-Code宏M109
# 此宏重写标准的M109命令，用于更精确的温度控制

# 重命名已存在的M109命令为M99109
# 这样可以保留原始M109功能，同时使用自定义实现
rename_existing: M99109

# 宏的G-Code部分开始
gcode:
    # 注释: 从传入参数中提取温度值S
    # params是包含所有传入参数的字典
    # params.S 获取名为S的参数（目标温度值）
    # |float 将参数转换为浮点数类型
    {% set s = params.S|float %}
    
    # 注释: 立即设置挤出机温度到目标值
    # 使用M104命令设置温度，不等待
    # 循环遍历所有传入参数，保持原样传递给M104
    # 这样可以保留所有可能的参数（如R、T等）
    M104 {% for p in params %}{'%s%s' % (p, params[p])}{% endfor %}
    
    # 注释: 条件判断 - 只有当目标温度不为0时才等待
    # 如果S=0，表示关闭加热器，无需等待
    {% if s != 0 %}
        
        # 注释: 等待挤出机温度达到指定范围
        # TEMPERATURE_WAIT是Klipper内置命令
        # SENSOR=extruder 指定监测挤出机温度传感器
        # MINIMUM={s} 设置最低温度阈值
        # MAXIMUM={s+1} 设置最高温度阈值（比目标温度高1度）
        # 注意: 使用s+1而不是s是为了防止温度过冲导致的无限等待
        TEMPERATURE_WAIT SENSOR=extruder MINIMUM={s} MAXIMUM={s+1}
        
    {% endif %}
    
    # 注释: 可选 - 添加温度达到后的确认信息
    # 可以取消下面行的注释，在达到温度时发送确认消息
    # RESPOND MSG="Extruder temperature reached: {s}°C"
    
    # 注释: 可选 - 添加超时保护
    # 可以取消下面行的注释，设置最大等待时间（例如300秒）
    # TIMEOUT=300

# 宏的G-Code部分结束

# 使用说明:
# 1. 将此宏添加到Klipper的打印机配置文件中
# 2. 调用方式与标准M109相同，例如: M109 S200
# 3. S参数为必需，表示目标温度（摄氏度）
# 4. 支持其他标准参数，如T（工具选择）、R（材料推荐温度）等

# 注意事项:
# 1. 此宏重写了标准M109命令，确保与现有G-code脚本兼容
# 2. 温度范围设置防止了温度轻微过冲导致的无限等待
# 3. 如果不需要等待加热（如S=0），则直接设置温度并返回
# 4. 原始M109命令仍可通过M99109访问（调试用途）