Skip to content

About

Field notes and reference code for driving a Bambu Lab X2D from an LLM agent: official Traditional Chinese HMS error text, toolpath parsing as a queryable structure, and a survey of what eight existing projects already cover.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

bambu-x2d-agent-notes

Field notes and reference code for driving a Bambu Lab X2D from an LLM agent over the LAN protocol (MQTT + FTPS + RTSPS).

This is not another MCP server, and not another protocol dump. The LAN protocol is already well covered by other projects — see Prior art for a capability matrix of eight of them. Everything in this repo is what was still missing after checking those eight, verified against a real X2D (serial prefix 20P, firmware as of 2026-08).

What this adds

1. Traditional Chinese HMS error text — docs/hms-zh-tw.md

Bambu's HMS error codes have official Traditional Chinese descriptions, but no open-source project ships them. ha-bambulab — the only project with a multi-language HMS text library — has 24 locale files, of which the only Chinese ones are hms_zh-Hans and hms_zh_cn, both Simplified. bambuddy's zh-TW.ts has zero HMS codes in it.

The tables exist on every machine that has Bambu Studio installed. This document explains where they live, how the per-model filename maps to your printer's serial number, and the JSON structure. Reference reader in src/hms_text.py.

We do not redistribute the tables. They are Bambu's copyrighted resource files. This repo tells you how to read the copy you already have, which also means your text stays in sync when Studio updates.

2. Toolpath parsing as a structured query surface — docs/toolpath-llm.md

Of the eight projects surveyed, exactly one (bambuddy) parses G-code toolpaths at all, and it renders them in a web UI. No project exposes toolpath geometry as something an agent can ask questions about — "which layer is the colour change on", "how much filament does this region use", "where is the print head right now relative to the model".

3. Agent-facing control design — docs/x2d-protocol.md

All five existing Bambu MCP servers have zero occurrences of X2D. The protocol notes here cover the X2D-specific fields, cross-referenced against where each one is already implemented elsewhere, plus the parts that matter specifically when a language model — rather than a human clicking a button — is the one issuing commands.

What this does not add

Stated plainly, because it took a survey to find out:

Thing Already done by
device.ctc.info.temp chamber temperature, packed low/high word ha-bambulab pybambu/models.py
vir_slot external spool slots OrcaSlicer, BambuStudio, ha-bambulab, bambuddy, SpoolEase
Dual-nozzle extruder.info[], packed temperatures ha-bambulab
HMS severity extraction from the code ha-bambulab get_HMS_severity()
X2D model identification, certificates, RTSPS camera bambuddy, ha-bambulab
LAN MQTT control, FTPS, print submission, AMS all eight projects

If you need those, use those projects. They are better maintained than this will be.

Requirements

The printer must be in LAN Only Mode with Developer Mode enabled. Without it, current firmware requires RSA-SHA256 command signing and rejects everything except the chamber light. This is Bambu's authorization control system, not a transport-layer issue — see docs/x2d-protocol.md.

Turning it on disconnects Bambu Cloud, the Handy app, and MakerWorld sync. It is reversible.

License

MIT — see LICENSE.

The HMS resource files this code reads are not covered by that license; they belong to Bambu Lab and are not included here.


繁體中文

這是把 Bambu Lab X2D 接給 LLM agent 用的實測筆記與參考程式碼。

不是又一個 MCP server,也不是又一份協定文件。 LAN 協定已經被其他專案寫得 很完整了(能力矩陣比對了八個)。這裡放的是把那八個查完 之後還空著的部分,全部對著一台真的 X2D 驗過。

三塊:

  1. HMS 錯誤碼繁體中文 — 官方有繁中說明,但沒有任何 開源專案帶。ha-bambulab 的 24 個語系檔裡中文只有簡體兩份。這份文件說明 官方表在哪、檔名的機型碼怎麼從序號推、JSON 長什麼樣。不轉載表本身, 那是 Bambu 的資源檔;讀你自己機器上那份,Studio 更新時還會跟著更新。
  2. 刀路解析成可查詢的結構 — 八個專案裡只有一個 會解 G-code 刀路,而且是畫成網頁。沒有人把刀路做成 agent 問得動的東西。
  3. 給 agent 用的控制設計 — 五個 Bambu MCP server 的 X2D 命中數全部是 0。

這裡沒有的東西(ctc 腔溫、vir_slot、雙噴頭、HMS 嚴重度、X2D 機型識別 與憑證)上面表格標了各自已經做好的專案,需要就去用那些,它們維護得比這裡好。

印表機要開 LAN Only + Developer Mode,否則現在的韌體會要求 RSA-SHA256 指令簽章,除了腔燈以外全部拒絕。開了會斷雲端、Handy 與 MakerWorld,可以復原。

About

Field notes and reference code for driving a Bambu Lab X2D from an LLM agent: official Traditional Chinese HMS error text, toolpath parsing as a queryable structure, and a survey of what eight existing projects already cover.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages