Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 37 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,19 @@ artifact on the gateway's disk. Filing a record in the ELN is optional and goes
only through the central dashboard's ingest ([Print records and ELN
ingest](#print-records-and-eln-ingest)); the gateway never writes to the ELN.

## Documentation for agents

Read the [operating guide](src/bambu_server/docs/AGENT_GUIDE.md) for identity,
A1 agent mode, slicing/submission, claimed-camera decisions, external-spool
mapping, completion and recovery. The [API overview](docs/API_REFERENCE.md)
summarizes the endpoint families.

The service serves `/agent-docs`, `/agent-docs/api-reference` (generated from
its actual OpenAPI), `/llms.txt`, and the JSON `/docs/agent` guide. All are
credential-free documentation reads without printer I/O. Swagger at `/docs`
is read-only. Dashboard registration belongs on the shared `bambu_gateway`
entry; deploy these routes before enabling the new registry links.

## Architecture

```text
Expand Down Expand Up @@ -424,14 +437,36 @@ a *record*, not an action: it marks the job `approved` and sets
### STL slicing

With `slicer.enabled`, `POST /submissions` also takes an `.stl` for any printer
listed under `slicer.machine_profiles`, plus a `material` listed under
`slicer.filament_profiles`. The gateway runs the installed Bambu Studio CLI
listed under `slicer.machine_profiles`, plus a configured `material`. Each
printer may name its own machine, process and filament presets; a bare machine
name retains the shared process/filament defaults. An explicit per-printer
filament map replaces those defaults. Presets with a `compatible_printers`
list must include the selected machine, including inherited restrictions.
The gateway runs the installed Bambu Studio CLI
headlessly in a scratch directory, forcing two machine facts the stock presets
get wrong: the nozzle type the printer reports and the build plate declared in
its profile. The resulting `.3mf` is then validated and queued like any other
upload, and the job carries `provenance` (source mesh hash, presets, slicer
version). Slicing runs inline in the request.

For A1 server-side PLA slicing, add the following alongside existing printer
entries under `slicer.machine_profiles` in the local configuration:

```yaml
bambu_a1_01:
machine: Bambu Lab A1 0.4 nozzle
process: 0.20mm Standard @BBL A1
filaments:
PLA: Generic PLA @BBL A1
```

Agents upload multipart fields `file=design.stl`,
`target_machine=bambu_a1_01`, and `material=PLA` to `POST /submissions`
through the authenticated edge with their own API key and `X-Agent-Id`.
A1 agent mode must be on. There is no separate `/slice` endpoint. HTTP 201
returns a stored submission; inspect its validation and state before approval.
Slicing and submission do not claim, upload to, or start the physical printer.

### Control plane

Off unless `dispatch.enabled` is set. When on, each printer gets STATUS_SPEC
Expand Down
44 changes: 39 additions & 5 deletions docs/API_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,39 @@ The dashboard also publishes the live schema through
`/api/equipment/bambu_gateway/documentation/openapi.json` and a read-only Swagger
viewer at `/api/equipment/bambu_gateway/documentation/docs`.

The served [agent guide](../src/bambu_server/docs/AGENT_GUIDE.md) is available
at `/agent-docs`; `/agent-docs/api-reference` generates the full method/path,
parameter, request, response and shared-schema reference from the running
app's OpenAPI. `/llms.txt` indexes the documentation, and `/docs/agent` exposes
the service-level JSON guide for SDK discovery as `bambu_gateway`. The
dashboard registers these under the same documentation proxy prefix above.
Swagger is read-only; the documentation proxy cannot execute commands.

## Endpoint summary

All paths are relative to the gateway. `{id}` denotes a printer or submission
ID as indicated by the prefix. The generated reference is authoritative for
the routes enabled in a deployment.

| Purpose | Methods and paths |
|---|---|
| Discovery and health | `GET /`, `/health`, `/status`, `/whoami`, `/printers` |
| Per-printer reads | `GET /printers/{id}/`, `/health`, `/status`, `/profile`, `/queue` |
| Submit and review | `POST /submissions`; `GET /submissions`, `/submissions/{id}`; `POST /submissions/{id}/approve`, `/cancel` |
| Claims (dispatch enabled) | `POST /printers/{id}/control/claim`, `/heartbeat`, `/release` |
| Printer I/O (dispatch enabled) | `POST /printers/{id}/control/snapshot`, `/light`, `/start_print`, `/stop_print` |
| View-only camera (dispatch enabled) | `GET /printers/{id}/camera.jpg` |
| Agent switch | `GET /printers/{id}/agent-mode`; `POST` on that path is admin-only, never agent-operated |
| Completion and pickup | `GET /events`, `/submissions/{id}/objects`, `/submissions/{id}/pickup-targets` |
| Durable records | `GET /submissions/{id}/artifact`, `/result`, `/plate.jpg`; `DELETE /submissions/{id}` for terminal-job housekeeping |
| Optional ELN delivery | `GET` / `POST /submissions/{id}/eln-ingest`; `GET /results/outbox` |
| Optional vision advisory | `POST /printers/{id}/bed-check` (dispatch and vision enabled) |
| Documentation | `GET /docs`, `/openapi.json`, `/agent-docs`, `/agent-docs/api-reference`, `/docs/agent`, `/llms.txt` |

Agents use the SDK for printer I/O. An occupied or unclear claimed snapshot
means release the claim and stop; never send a start request to test the gate.
Failed or uncertain dispatches require human reconciliation, without retries.

## Printer inventory

`GET /printers` discovers configured printers. For each ID:
Expand All @@ -26,9 +59,10 @@ chamber camera frame (`image/jpeg`, `Cache-Control: no-store`, capture time in
`X-Captured-At`) without a claim. It is the one read that touches the printer:
the camera is read at most once per printer every 2 s and the frame is shared by
all callers; 503 when the camera does not deliver one. A frame from here is
never plate-check evidence: a camera `start_print` records its own frame under
the claim (a fresh capture when no `snapshot_token` is sent, or a
`/control/snapshot` taken under the claim within 5 minutes).
never plate-check evidence. A person's camera `start_print` records a fresh
frame when no `snapshot_token` is sent, or uses a claimed `/control/snapshot`
no older than 5 minutes. An agent must supply its own claimed snapshot and
visual decision; the agent age limit is normally 120 seconds.

| Tray field | Meaning |
|---|---|
Expand Down Expand Up @@ -70,8 +104,8 @@ printer in agent mode — `agent_camera`), and an `ams_mapping` of
`{filament_id, ams_id, tray_id}`. Refusals are 412 with a body naming the
failed gate; `allowed_actions` on `/status` mirrors them, and
`details.claimed_by` names the holder. `GET /submissions/{id}/plate.jpg` returns
the camera frame a start was confirmed against. Without dispatch enabled none
of these paths exist.
the camera frame a start was confirmed against. Without dispatch enabled the
control routes are absent; the stored plate-evidence route remains registered.

**Camera snapshot for a plate check.** `POST /printers/{id}/control/snapshot`
with the claim token returns `{token, printer_id, captured_at, sha256,
Expand Down
14 changes: 13 additions & 1 deletion printers.example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -65,11 +65,23 @@ slicer:
profiles_dir: /home/you/.local/opt/bambu-studio/squashfs-root/resources/profiles/BBL
work_dir: var/slicer
timeout_s: 600
# Defaults for a printer that does not name its own process or filaments.
process_profile: "0.20mm Standard @BBL X1C"
filament_profiles: # material a submitter names -> filament preset
PLA: "Bambu PLA Basic @BBL X1C"
machine_profiles: # printer id -> machine preset; others refuse .stl
# Printer id -> its presets; a printer not listed refuses .stl. A bare string
# is the machine preset alone, with the defaults above. A printer whose
# motion differs from the defaults' (an A1 bed-slinger against X1C presets)
# names its own `process` and `filaments`; its `filaments` replace the
# defaults rather than adding to them. A bundled preset that lists
# `compatible_printers` must list this machine, or slicing is refused.
machine_profiles:
bambu_x1c_01: "Bambu Lab X1 Carbon 0.4 nozzle"
# bambu_a1_01:
# machine: "Bambu Lab A1 0.4 nozzle"
# process: "0.20mm Standard @BBL A1"
# filaments:
# PLA: "Bambu PLA Basic @BBL A1"

printers:
- id: bambu_x1c_01
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ where = ["src"]
# The submission page ships with the package so a non-editable install serves
# /ui too, not just a checkout-based deploy.
[tool.setuptools.package-data]
bambu_server = ["static/*.html"]
bambu_server = ["static/*.html", "docs/*.md"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
Expand Down
67 changes: 60 additions & 7 deletions src/bambu_server/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,33 @@ class ResultsSettings(BaseModel):
worker_tick_s: float = Field(default=2.0, ge=0.05, le=60)


def _upper_material_keys(value: Any) -> Any:
if isinstance(value, dict):
return {str(key).strip().upper(): preset for key, preset in value.items()}
return value


class SlicerPrinterPresets(BaseModel):
"""The presets one printer slices with.

Only ``machine`` is required. ``process`` and ``filaments`` fall back to the
gateway-wide ``process_profile`` and ``filament_profiles`` when omitted;
a printer whose kinematics differ from those defaults (an A1 against X1C
presets) must name its own. A ``filaments`` map *replaces* the defaults
rather than extending them, so a material the printer does not list is
refused instead of being sliced with another machine's preset.
"""

machine: str = Field(min_length=1)
process: str | None = Field(default=None, min_length=1)
filaments: dict[str, str] | None = None

@field_validator("filaments", mode="before")
@classmethod
def upper_keys(cls, value: Any) -> Any:
return _upper_material_keys(value)


class SlicerSettings(BaseModel):
"""Bambu Studio CLI slicing of an uploaded ``.stl``.

Expand All @@ -255,25 +282,51 @@ class SlicerSettings(BaseModel):
profiles_dir: Path | None = None
work_dir: Path = Path("var/slicer")
timeout_s: float = Field(default=600.0, ge=30, le=3600)
#: The process preset applied to every slice. One, deliberately: the
#: submitter picks a material, not a print profile.
#: The default process preset, for a printer that does not name its own.
#: One per printer, deliberately: the submitter picks a material, not a
#: print profile.
process_profile: str = "0.20mm Standard @BBL X1C"
#: Material name (as the submitter types it, upper-cased) to the filament
#: preset to slice with. A material with no entry cannot be sliced here.
#: Default material name (as the submitter types it, upper-cased) to the
#: filament preset to slice with, for a printer that does not name its own.
#: A material with no entry cannot be sliced here.
filament_profiles: dict[str, str] = Field(default_factory=dict)
#: Printer id to the machine preset for it (e.g. "Bambu Lab P1S 0.4 nozzle").
#: Printer id to its presets. A bare string is the machine preset alone
#: (e.g. "Bambu Lab P1S 0.4 nozzle"), with the defaults above.
#: A printer with no entry does not accept ``.stl`` uploads.
machine_profiles: dict[str, str] = Field(default_factory=dict)
machine_profiles: dict[str, SlicerPrinterPresets] = Field(default_factory=dict)
#: Ceiling on an uploaded mesh.
max_stl_bytes: int = Field(default=100 * 1024 * 1024, ge=1024)

@field_validator("filament_profiles", mode="before")
@classmethod
def upper_keys(cls, value: Any) -> Any:
return _upper_material_keys(value)

@field_validator("machine_profiles", mode="before")
@classmethod
def accept_bare_machine(cls, value: Any) -> Any:
if isinstance(value, dict):
return {str(key).strip().upper(): preset for key, preset in value.items()}
return {
printer_id: {"machine": presets} if isinstance(presets, str) else presets
for printer_id, presets in value.items()
}
return value

def presets_for(self, printer_id: str) -> SlicerPrinterPresets | None:
return self.machine_profiles.get(printer_id)

def process_for(self, printer_id: str) -> str:
presets = self.presets_for(printer_id)
if presets is not None and presets.process is not None:
return presets.process
return self.process_profile

def filaments_for(self, printer_id: str) -> dict[str, str]:
presets = self.presets_for(printer_id)
if presets is not None and presets.filaments is not None:
return presets.filaments
return self.filament_profiles


class Settings(BaseModel):
printers: list[PrinterDefinition] = Field(min_length=1)
Expand Down
Loading
Loading