bambu-labs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bambu Labs

Use this skill for local-network Bambu Lab print handoffs after a plain

.gcode

file already exists and has been validated. This skill does not slice models.

当纯

.gcode

文件已存在并通过验证后，可使用此技能进行本地网络中的Bambu Lab打印任务交接。此技能不负责模型切片。

Safety Rules

安全规则

Default to dry-run plans. Real printer traffic requires
```
--execute
```
.
Never start a print without
```
--execute --confirm-start-print
```
.
Pause and cancel controls are live printer requests; default to dry-run plans. Canceling a print requires
```
--execute --confirm-cancel-print
```
.
Treat an explicit user request to print or start a specific job as live-start authorization; do not pause for a second confirmation solely for physical checks. Still validate the G-code, inspect the dry-run payload, read printer status, prefer upload-only before upload-start, state the physical checks, and stop if validation/status/intent is unsafe or ambiguous.
Do not ask for the printer serial by default; fetch it from the printer TLS certificate with
```
serial
```
or let
```
send
```
cache it.
Prefer workspace-root
```
bambu-printers.json
```
over repeating access codes in commands. The file is local config and should be ignored by Git.
Before a live start, state the physical checks: clear build plate, correct plate/filament/nozzle, safe surroundings, and operator nearby.
Publishing MQTT is only a start request. Confirm acceptance with printer status/UI and physical observation.

默认采用试运行方案。实际打印机操作需要使用
```
--execute
```
参数。
未使用
```
--execute --confirm-start-print
```
参数时，绝不能启动打印。
暂停和取消控制是实时打印机请求；默认采用试运行方案。取消打印需要使用
```
--execute --confirm-cancel-print
```
参数。
将用户明确要求打印或启动特定任务视为实时启动授权；无需仅为物理检查而暂停等待二次确认。仍需验证G-code、检查试运行负载、读取打印机状态、优先选择仅上传再进行上传启动、说明物理检查内容，若验证/状态/意图存在不安全或模糊情况则停止操作。
默认不要询问打印机序列号；使用
```
serial
```
命令从打印机TLS证书中获取，或让
```
send
```
命令缓存该序列号。
优先使用工作区根目录下的
```
bambu-printers.json
```
文件，而非在命令中重复输入访问码。该文件为本地配置，应被Git忽略。
实时启动前，说明物理检查内容：清理打印平台、确认平台/耗材/喷嘴正确、环境安全、操作员在旁。
发布MQTT仅为启动请求。需通过打印机状态/UI和物理观察确认请求已被接受。

CAD Viewer Handoff

CAD 查看器交接

After completing Bambu work that creates or modifies a local supported print artifact such as

.gcode

.3mf

, you must ALWAYS hand the explicit file path to

$cad-viewer

when that skill is installed.

$cad-viewer

must start CAD Viewer if it is not already running and return link(s) to the relevant created or updated file(s); if

$cad-viewer

is unavailable or startup fails, report that instead of silently omitting the handoff.

完成创建或修改本地支持的打印工件（如

.gcode

或

.3mf

）的Bambu相关工作后，若

$cad-viewer

技能已安装，必须始终将明确的文件路径传递给它。

$cad-viewer

必须启动CAD查看器（若尚未运行）并返回相关已创建或更新文件的链接；若

$cad-viewer

不可用或启动失败，需报告该情况，而非静默跳过交接步骤。

Workflow

工作流程

Generate and validate plain G-code with
```
$gcode
```
. If no slicer is installed, install OrcaSlicer and retry; do not treat the missing slicer as a blocker. On macOS, prefer
```
brew install --cask orcaslicer
```
.
Configure the printer. The user can either give the IP/access code in the thread and let the agent write JSON, or edit
```
bambu-printers.json
```
directly. For a new printer setup or onboarding request, read
```
references/new-printer-onboarding.md
```
first. Walk the user through the model-specific touchscreen steps to find the IP and LAN access code, and make Enable LAN Only plus Enable Developer Mode explicit before running local start workflows.

bash

python scripts/bambu_lan_print.py config set \
  --printer a1-mini \
  --host 192.168.1.34 \
  --access-code 12345678 \
  --model a1-mini \
  --fetch-serial

Manual JSON shape:

json

{
  "printers": {
    "a1-mini": {
      "host": "192.168.1.34",
      "access_code": "12345678",
      "model": "a1-mini"
    }
  }
}

On A1/A1 Mini, find the IP and LAN access code on the printer touchscreen under network/LAN settings. Enable LAN Only and Developer Mode when offered, then power-cycle before retrying local start commands.

Read status before live work:

bash

python scripts/bambu_lan_print.py status \
  --printer a1-mini \
  --push-all \
  --wait-seconds 10

Dry-run the exact handoff, inspect the JSON payload, then run upload-only. Only after upload succeeds should you run upload-start. If the user explicitly asked to print or start the job, proceed to
```
upload-start --execute --confirm-start-print
```
after the validation, status, and upload checks pass. If the user only asked to prepare, slice, upload, or review, stop before the start request.

使用
```
$gcode
```
生成并验证纯G-code。若未安装切片器，安装OrcaSlicer并重试；不要将缺少切片器视为阻碍。在macOS系统上，优先使用
```
brew install --cask orcaslicer
```
命令安装。
配置打印机。用户可在对话中提供IP/访问码，让Agent写入JSON文件，或直接编辑
```
bambu-printers.json
```
文件。对于新打印机设置或入门请求，先阅读
```
references/new-printer-onboarding.md
```
文件。引导用户完成特定型号触摸屏步骤以查找IP和LAN访问码，并在运行本地启动工作流前明确要求启用仅LAN模式和启用开发者模式。

bash

python scripts/bambu_lan_print.py config set \
  --printer a1-mini \
  --host 192.168.1.34 \
  --access-code 12345678 \
  --model a1-mini \
  --fetch-serial

手动JSON格式：

json

{
  "printers": {
    "a1-mini": {
      "host": "192.168.1.34",
      "access_code": "12345678",
      "model": "a1-mini"
    }
  }
}

在A1/A1 Mini上，可在打印机触摸屏的网络/LAN设置中找到IP和LAN访问码。出现选项时启用仅LAN模式和开发者模式，然后重启打印机后再重试本地启动命令。

进行实时操作前读取状态：

bash

python scripts/bambu_lan_print.py status \
  --printer a1-mini \
  --push-all \
  --wait-seconds 10

试运行精确的交接流程，检查JSON负载，然后执行仅上传操作。仅在上传成功后才可执行上传启动操作。若用户明确要求打印或启动任务，在验证、状态和上传检查通过后，直接执行
```
upload-start --execute --confirm-start-print
```
。若用户仅要求准备、切片、上传或审核，则在启动请求前停止操作。

Handoff Modes

交接模式

--handoff template-project

is the validated A1 Mini path from this repo's LAN debugging. It starts from validated plain

.gcode

, copies a known-good same-printer

.gcode.3mf

template, replaces

Metadata/plate_N.gcode

, writes the plate MD5, uploads the project to the FTPS root, and publishes

print.project_file

with

url: ftp:///<name>.gcode.3mf

bash

python scripts/bambu_lan_print.py send \
  --printer a1-mini \
  --gcode /tmp/job.gcode \
  --handoff template-project \
  --template-project /path/to/same-printer-template.gcode.3mf \
  --action upload-start

Execute after review when the user explicitly asked to print or start, or after physical confirmation when intent is unclear:

bash

python scripts/bambu_lan_print.py send \
  --printer a1-mini \
  --gcode /tmp/job.gcode \
  --handoff template-project \
  --template-project /path/to/same-printer-template.gcode.3mf \
  --action upload-start \
  --execute \
  --confirm-start-print

--handoff plain

uploads

cache/<name>.gcode

and publishes

print.gcode_file

. Keep it for diagnostics or printers/firmware where this is known to work. On the tested A1 Mini, direct plain G-code was uploaded successfully but

gcode_file

failed or was ignored, so do not use it as the A1 Mini live-start path.

--handoff bambox-project

packages plain

.gcode

with

bambox

, uploads the

.gcode.3mf

project to FTPS root, and publishes

print.project_file

. Currently enabled only for

p1s-0.4

with

PLA

ASA

, or

PETG-CF

. Known but disabled until validated profiles exist:

a1-mini-0.4

a1-0.4

x1c-0.4

, and

p1p-0.4

--handoff template-project

是此仓库LAN调试中已验证的A1 Mini路径。它从已验证的纯

.gcode

开始，复制一个已知可用的同型号打印机

.gcode.3mf

模板，替换

Metadata/plate_N.gcode

，写入平台MD5值，将项目上传至FTPS根目录，并发布带有

url: ftp:///<name>.gcode.3mf

的

print.project_file

。

bash

python scripts/bambu_lan_print.py send \
  --printer a1-mini \
  --gcode /tmp/job.gcode \
  --handoff template-project \
  --template-project /path/to/same-printer-template.gcode.3mf \
  --action upload-start

当用户明确要求打印或启动时，或意图不明确时经物理确认后，在审核完成后执行：

bash

python scripts/bambu_lan_print.py send \
  --printer a1-mini \
  --gcode /tmp/job.gcode \
  --handoff template-project \
  --template-project /path/to/same-printer-template.gcode.3mf \
  --action upload-start \
  --execute \
  --confirm-start-print

--handoff plain

会上传

cache/<name>.gcode

并发布

print.gcode_file

。此模式用于诊断或已知可正常工作的打印机/固件。在测试的A1 Mini上，纯G-code上传成功，但

gcode_file

请求失败或被忽略，因此不要将此作为A1 Mini的实时启动路径。

--handoff bambox-project

会使用

bambox

打包纯

.gcode

，将

.gcode.3mf

项目上传至FTPS根目录，并发布

print.project_file

。目前仅对使用PLA、ASA或PETG-CF耗材的

p1s-0.4

启用。已知但因缺少已验证配置文件而禁用的型号：

a1-mini-0.4

、

a1-0.4

、

x1c-0.4

和

p1p-0.4

。

Common Debugging Commands

常见调试命令

Fetch/cache serial:

bash

python scripts/bambu_lan_print.py serial \
  --printer a1-mini \
  --json

Clear a stale printer error after fixing the underlying cause:

bash

python scripts/bambu_lan_print.py clear-error \
  --printer a1-mini \
  --execute

Use

--mqtt-qos 1 --wait-after-publish 10

send

when debugging whether the printer acknowledged the MQTT publish and what status it reported immediately afterward.

获取/缓存序列号：

bash

python scripts/bambu_lan_print.py serial \
  --printer a1-mini \
  --json

修复根本原因后清除打印机的过期错误：

bash

python scripts/bambu_lan_print.py clear-error \
  --printer a1-mini \
  --execute

调试打印机是否确认MQTT发布以及发布后立即报告的状态时，在

send

命令中使用

--mqtt-qos 1 --wait-after-publish 10

参数。

Print Controls

打印控制

For a running print, use dedicated print-control commands rather than ad hoc MQTT snippets. These commands publish only a control request; they do not upload files or start a new job. Read status after execution to confirm the printer state changed.

Dry-run pause payload:

bash

python scripts/bambu_lan_print.py pause \
  --printer a1-mini

Execute pause and collect printer reports:

bash

python scripts/bambu_lan_print.py pause \
  --printer a1-mini \
  --execute \
  --mqtt-qos 1 \
  --wait-after-publish 10

Dry-run cancel payload. The Bambu LAN command sent to the printer is

stop

bash

python scripts/bambu_lan_print.py cancel \
  --printer a1-mini

Execute cancel only when the user explicitly asks to cancel/stop the print or after confirmation when intent is ambiguous:

bash

python scripts/bambu_lan_print.py cancel \
  --printer a1-mini \
  --execute \
  --confirm-cancel-print \
  --mqtt-qos 1 \
  --wait-after-publish 10

对于正在运行的打印任务，使用专用的打印控制命令而非临时MQTT代码片段。这些命令仅发布控制请求；不负责上传文件或启动新任务。执行后读取状态以确认打印机状态已更改。

试运行暂停负载：

bash

python scripts/bambu_lan_print.py pause \
  --printer a1-mini

执行暂停并收集打印机报告：

bash

python scripts/bambu_lan_print.py pause \
  --printer a1-mini \
  --execute \
  --mqtt-qos 1 \
  --wait-after-publish 10

试运行取消负载。发送给Bambu打印机的LAN命令为

stop

：

bash

python scripts/bambu_lan_print.py cancel \
  --printer a1-mini

仅当用户明确要求取消/停止打印，或意图模糊时经确认后，执行取消操作：

bash

python scripts/bambu_lan_print.py cancel \
  --printer a1-mini \
  --execute \
  --confirm-cancel-print \
  --mqtt-qos 1 \
  --wait-after-publish 10

Failure Modes

故障模式

```
gcode_file
```
returns
```
result: fail
```
or leaves the printer
```
IDLE
```
: plain G-code upload worked, but the firmware rejected or ignored direct local start. For A1 Mini, switch to
```
template-project
```
.
Project uploaded under
```
cache/
```
starts then fails with
```
print_error: 83935248
```
or
```
0500-C010
```
: clear the error, upload project handoffs to FTPS root, and use
```
ftp:///<name>.gcode.3mf
```
.
```
file:///sdcard/cache/...
```
or local HTTP URLs appear accepted but nothing starts: stop using those URL forms for this workflow.
Bambu Studio or OrcaSlicer project export crashes on macOS: do not keep retrying GUI-backed project export. Use OrcaSlicer for plain
```
.gcode
```
, then this skill for handoff.
Stale
```
gcode_state: FAILED
```
or HMS after enabling Developer Mode: clear the printer error and power-cycle before retrying.
FTPS login works but upload fails with
```
553
```
or missing
```
cache/
```
: check printer storage/SD card status before MQTT start.
MQTT status works but start does not: confirm serial, access code, Developer Mode/LAN Only status, and the exact handoff payload before retrying.

Read

references/new-printer-onboarding.md

for new printer setup,

references/local-lan-protocol.md

for protocol details, and

references/real-printer-checklist.md

before first live use on a new printer.

```
gcode_file
```
返回
```
result: fail
```
或打印机处于
```
IDLE
```
状态：纯G-code上传成功，但固件拒绝或忽略了直接本地启动。对于A1 Mini，切换至
```
template-project
```
模式。
上传至
```
cache/
```
目录的项目启动后失败，出现
```
print_error: 83935248
```
或
```
0500-C010
```
：清除错误，将项目交接文件上传至FTPS根目录，并使用
```
ftp:///<name>.gcode.3mf
```
。
```
file:///sdcard/cache/...
```
或本地HTTP URL看似被接受但未启动：在此工作流中停止使用这些URL格式。
Bambu Studio或OrcaSlicer项目导出在macOS上崩溃：不要反复尝试基于GUI的项目导出。使用OrcaSlicer生成纯
```
.gcode
```
，然后使用此技能进行交接。
启用开发者模式后出现过期的
```
gcode_state: FAILED
```
或HMS：清除打印机错误并重启后再重试。
FTPS登录成功但上传失败，出现
```
553
```
或缺少
```
cache/
```
目录：发送MQTT启动请求前检查打印机存储/SD卡状态。
MQTT状态可用但启动失败：重试前确认序列号、访问码、开发者模式/仅LAN模式状态以及精确的交接负载。

新打印机设置请阅读

references/new-printer-onboarding.md

，协议细节请阅读

references/local-lan-protocol.md

，首次在新打印机上进行实时操作前请阅读

references/real-printer-checklist.md

。