Print Buddy documentation

This page is published on the Print Buddy documentation site. Its content is copied from docs/README.md in the Print Buddy repo, which is the source of truth.

Project overview · Contributing

1. Install one mode

• Light install: one command for a Raspberry Pi or Debian/Ubuntu machine; asks about your printer and sets up the standalone bot or a Hermes profile. Needs a Discord bot.
• Standalone bot: Discord without Hermes or a required LLM; token permissions, configuration, setup checks and systemd services.
• Telegram bot setup: run the standalone bot on Telegram instead of Discord (#164); a pure bot with no LLM, long polling, inline-keyboard prompts. Also covers pairing with ZMod's moonraker-telegram-bot as a companion for live control, notifications and timelapse (#300).
• Matrix bot setup: run the standalone bot in a Matrix room instead (#164); a pure bot with no LLM, /sync polling, numbered-list prompts, unencrypted room required.
• Hermes installation: profile installation, private overlays and listener setup.
• Docker: container configuration, persistent storage and service lifecycle. Follow the guide for the checked-out revision; do not assume a draft packaging PR is available.
• More than one printer: one instance per printer for a multi-printer household, with one shared Spoolman (#257 Stage 0).
• From the image to a first A1 print: the Docker image on a Bambu Lab A1, step by step (#274): Compose overrides, A1 templates from the bundled OrcaSlicer, the hand-written hardware record, MakerWorld token, Discord, the LAN print opt-in and the fixes still pending. Verified on an A1 on 26 Oct 2026.

Do not run both Discord modes with the same token. Installing, enabling services and contacting a printer are separate actions from offline model analysis.

2. Configure and use

• YAML configuration and TOML migration: schema, precedence and safety limits.
• Guided setup and debugging in Discord: the /print-buddy setup checklist (resumable, consent-gated, never collects the token) and the read-only, redacted /print-buddy debugging checks.
• Settings reference: every setting with its YAML key, environment variable and Docker value, plus Docker build arguments and secrets.
• Detailed project reference: workflow examples, commands, printer models, spool identity rules, monitoring and updates.
• Printer macros: /print-macros live macro discovery on Moonraker printers, and the per-vendor macro matrix.
• Printer profiles and offline delivery: vendor/model inheritance, supported delivery methods and verification limitations.
• Optional Flash Studio slicer: opt-in, user-installed Flash Studio executable for Flashforge printers; an empty path keeps the normal OrcaSlicer choice.
• Home Assistant panic and printer controls: direct, no-LLM AD5X/ZMod printer controls from a Home Assistant dashboard, including the emergency-stop panic restart; no extra daemon.
• AD5X integration contract: printer-specific behavior and limitations.
• ZMod printers: all five ZMod models (AD5X, AD5M, AD5M Pro supported; Creator 5 / 5 Pro staged), and how their filament systems differ.
• OctoPrint/Marlin notes: read the integration-specific limits before assuming Moonraker feature parity.
• Bambu Lab printers: profiles for every single-nozzle Bambu Lab printer (A1, A1 mini, P1P, P1S, P2S, X1, X1 Carbon, X1E, H2S), generating slicer profiles from your own OrcaSlicer, the G-code guard, opt-in read-only LAN status, unverified values, and the licensing basis awaiting approval.
• Bambu Lab live connectivity research: LAN MQTT/FTPS evidence from maintained integrations, the 2025 authorization change, the staged live-support plan for the A1/P1S, and the unknowns that need a live test.
• Prusa printers: the MK4S/CORE One/XL/MINI+ profiles, generating slicer profiles from your own OrcaSlicer, the PrusaLink LAN client (status, verified upload, gated start), and what is not supported.
• Elegoo printers: the Neptune 4 family on Moonraker and the Centauri Carbon on SDCP, generating slicer profiles from your own OrcaSlicer, the SDCP LAN client (status, verified upload, gated start), and what is not supported.
• Read-only mesh topology audit: topology metrics, CLI usage, and manifold/watertight checks.
• 100%-scale geometry layout and export: multi-object single-plate packing, status ladder, and geometry-only export boundaries.
• Opt-in reviewed CAD split plans and dowel connectors: reviewed split presets, chamfered dowel generation, OpenSCAD CSG script synthesis, and post-boolean volume conservation checks.

3. Troubleshoot by symptom

Symptom	First check
Model intake is refused for size or complexity	Simplify or split the model offline; see intake resource limits.
Bot replies twice	Confirm only one mode uses the token; see standalone setup.
Startup rejects a setting	Read the named key and configuration precedence; YAML takes precedence over corresponding TOML files.
Slicing fails or model does not fit	Check slicer command, selected printer/profile and model bounds in the reference. Do not bypass G-code or clearance guards.
Spool or color disagrees with the printer	Read the reference's spool/IFS source-of-truth rules before rebinding slots.
Installation or update fails	Use the guide for your selected mode; collect the actual error without tokens, private model files or personal service addresses.
Physical print problem (first layer, clog, heat creep, mesh, ringing)	/print-troubleshoot in Discord, or the troubleshooting guide; /print-lookup <query> searches the knowledge, firmware and printer registries. Both are read-only and send nothing to the printer.

python3 -m print_buddy.doctor checks setup and can contact configured Moonraker and Spoolman services. Run it only where those contacts are authorized. A clean check does not prove physical readiness.

4. Develop and review

• Contribution workflow and pull request template.
• Release-note guidance and internal release history.
• Rename migration for older installations.
• CAD evaluation and reuse map for technical background, not promises of shipped capability.

These versioned repository pages are the documentation home. Update them with behavior changes so readers can use the documentation for their checked-out revision.

5. Internal and historical records

These pages are kept as records of past work, not instructions to follow. Do not use them as setup or configuration guidance; the guides above are authoritative.

• Docker #117 acceptance record: historical acceptance record for the #117 Docker packaging work.
• Docker #117 progress record: historical progress log for the #117 Docker packaging work.
• Issue #126 timelapse record: historical record of the #126 timelapse delivery contract.
• Hardcoded values inventory: internal inventory of hardcoded values, kept for maintainers.

Documentation ownership and wiki policy

This docs/ directory is the dedicated, versioned documentation location for issue #120, not a placeholder for a future website. Installation, configuration, workflow reference and troubleshooting live here so changes can be reviewed with code. GitHub renders these pages directly; use the docs for your selected revision rather than assuming main describes an installed release.

Every feature PR must identify its documentation and wiki impact using the contribution checklist. Update the relevant guide and this index when adding a new page. A separate GitHub Wiki, if maintained, should provide links or summaries pointing here; it is not a second source of configuration or safety instructions. No wiki publication or synchronization is automated by the PR checks.