Skip to content
BranchesTags

Repository files navigation

FlashForge 3D Printer Integration for Home Assistant

A Home Assistant custom integration for modern FlashForge printers using the local HTTP API in LAN mode for reliable, real-time monitoring and control.

Features

Category Feature Details
Monitoring 28 Sensors Real-time temperatures (per-toolhead on the Creator 5 series, plus a heated chamber), print progress, filament tracking, fan speeds, air quality (5M Pro / Creator 5 Pro TVOC), active Material Station slot, print completion time, lifetime statistics, and diagnostics
4 Binary Sensors Printing status, connectivity, error detection, pause state
Live Camera Feed MJPEG stream auto-detected from the printer-reported camera stream URL or the standard OEM fallback endpoint when firmware omits it
5 Image Entities Active g-code thumbnail, plus 4 Material Station slot color swatches (AD5X / Creator 5 series — filament color + material label)
Control Switches LED control, plus Pro-only camera power toggle
Select Entity Filtration mode control (Off/Internal/External)
4 Buttons Pause, resume, cancel print jobs, and clear printer status directly from Home Assistant
Print Job Card Browse the files on the printer, match each tool to a Material Station slot (AD5X), and start the print — a dashboard card installed with the integration
Architecture HTTP-First Design Superior reliability compared to TCP-only implementations
Async/Await Fully asynchronous for optimal Home Assistant integration
Auto-Discovery UDP-based network discovery with manual fallback
Configurable Polling Adjust update frequency from 5-300 seconds

Supported Hardware

Printer Model Support Status
FlashForge Adventurer 5M Supported
FlashForge Adventurer 5M Pro Supported
FlashForge AD5X Supported
FlashForge Creator 5 Supported
FlashForge Creator 5 Pro Supported
Legacy TCP-only models (including Adventurer 4) Not Supported

Feature availability is detected at runtime. The camera entity is always created, and it becomes available when the printer reports an active OEM stream URL or the standard OEM fallback stream endpoint responds. The camera power switch remains Pro-only.

This integration does not support legacy TCP-only printers.

Requirements

Requirement Details
Home Assistant 2025.1.0 or newer
Python Library flashforge-python-api 1.2.0+
Network Local LAN connectivity to printer
Printer Setup LAN mode enabled with serial number and check code

Installation

Method Steps
Via HACS (Recommended) 1. Open HACS in Home Assistant
2. Click on Integrations
3. Click the ⋮ menu (top right) → Custom repositories
4. Add repository:
   • URL: https://github.com/GhostTypes/ff-5mp-hass
   • Category: Integration
5. Click Add
6. Search for "FlashForge" in HACS
7. Click Download
8. Restart Home Assistant
Manual Installation 1. Download the latest release
2. Extract the custom_components/flashforge folder
3. Copy to your Home Assistant config/custom_components/ directory
4. Restart Home Assistant

Configuration

Step Instructions
Prerequisites: Enable LAN Mode Before adding the integration, you must enable LAN mode on your FlashForge printer:

1. On the printer touchscreen, go to Settings → Network → LAN Mode
2. Enable LAN mode
3. Note the Check Code (8-digit code) - you'll need this for setup

Video Tutorial
Option 1: Automatic Discovery (Recommended) 1. Go to Settings → Devices & Services → Integrations
2. Click + Add Integration
3. Search for "FlashForge"
4. Select your AD5X, Adventurer 5M, Adventurer 5M Pro, Creator 5, or Creator 5 Pro from the discovered list
5. Enter your printer's Check Code
6. Click Submit
Option 2: Manual Configuration 1. Go to Settings → Devices & Services → Integrations
2. Click + Add Integration
3. Search for "FlashForge"
4. Select "Configure Manually"
5. Enter:
   • IP Address: Your printer's IP (e.g., 192.168.1.100)
   • Printer Name: Friendly name (optional)
   • Serial Number: From the printer settings screen. Must include the SN prefix (e.g. SN123456789) — the SN printed on the back sticker is part of the value you enter, not just a label
   • Check Code: From LAN mode settings
6. Click Submit
Configuration Options After setup, you can adjust settings:

1. Go to Settings → Devices & Services → FlashForge
2. Click ⋮ on your printer → Configure
3. Scan Interval: Update frequency in seconds (5-300, default: 10)
LED Switch Override If your printer's LED switch is not detected but you know it is supported, enable Always show LED switch in the options. This will force the LED switch to appear regardless of printer capability checks.

Available Entities

Sensors

Entity Description Unit
sensor.flashforge_machine_status Current printer state (idle, printing, paused, error) -
sensor.flashforge_nozzle_temperature Current extruder temperature °C
sensor.flashforge_nozzle_target_temperature Target extruder temperature °C
sensor.flashforge_bed_temperature Current bed temperature °C
sensor.flashforge_bed_target_temperature Target bed temperature °C
sensor.flashforge_print_progress Print completion percentage %
sensor.flashforge_current_file Currently printing file name -
sensor.flashforge_current_layer Current layer number -
sensor.flashforge_total_layers Total layer count -
sensor.flashforge_elapsed_time Time spent printing seconds
sensor.flashforge_remaining_time Estimated time remaining seconds
sensor.flashforge_filament_length Estimated filament length needed meters
sensor.flashforge_filament_weight Estimated filament weight grams
sensor.flashforge_print_speed Speed adjustment percentage %
sensor.flashforge_z_offset Z-axis compensation mm
sensor.flashforge_nozzle_size Installed nozzle size -
sensor.flashforge_filament_type Current filament type -
sensor.flashforge_lifetime_filament Total filament used over printer lifetime meters
sensor.flashforge_lifetime_runtime Total runtime over printer lifetime -
sensor.flashforge_tool_[1-4]_temperature Per-toolhead current nozzle temperature (Creator 5 series) °C
sensor.flashforge_tool_[1-4]_target_temperature Per-toolhead target nozzle temperature (Creator 5 series) °C
sensor.flashforge_chamber_temperature Heated chamber current temperature (Creator 5 series) °C
sensor.flashforge_chamber_target_temperature Heated chamber target temperature (Creator 5 series) °C

Binary Sensors

Entity Description Device Class
binary_sensor.flashforge_printing On when actively printing running
binary_sensor.flashforge_online On when printer is connected connectivity
binary_sensor.flashforge_error On when error detected problem
binary_sensor.flashforge_paused On when print is paused -
binary_sensor.flashforge_door_open On when the lid or front door is ajar door (Creator 5 Pro)

Switches

Entity Description Availability
switch.flashforge_led Control printer LED lights All Models
switch.flashforge_camera Toggle the OEM camera power state Pro models

Select Entities

Entity Description Options Availability
select.flashforge_filtration_mode Control filtration system Off, Internal, External 5M Pro / Creator 5 Pro

Buttons

Entity Description
button.flashforge_pause_print Pause active print job
button.flashforge_resume_print Resume paused print job
button.flashforge_cancel_print Cancel and abort print job
button.flashforge_clear_status Clear printer status/errors

Camera

Entity Description
camera.flashforge_camera Live MJPEG stream from the printer-reported OEM camera URL

Starting Prints — the Job Card

The integration ships a dashboard card for starting prints of files already on the printer, including the material matching step the AD5X needs for multi-material files.

Adding it: the card is installed and registered with the integration — there is no separate HACS entry and no Lovelace resource to add. Edit a dashboard → Add card → search for FlashForge Print Job → pick your printer.

Note

After installing or updating, reload the page once. A browser tab loads the list of frontend modules when the page opens, so a tab that was already open before the install does not know the card exists yet — the picker will not offer it. The integration tells you when this applies: you will get a notification in the sidebar saying the card is ready. Press Ctrl+R (Cmd+R on a Mac) and it will be there. You will not be asked again until the next update.

Using it:

  1. Pick a file. Each row shows its thumbnail, print time, filament weight and per-tool material swatches, where the printer reports them.
  2. Optionally tick Level the bed before printing.
  3. Press Start print.
    • Single-material file, or a printer with no Material Station — a confirmation dialog, then the print starts.
    • Material Station file (AD5X) — the matching dialog opens. Every tool in the file must be mapped to a loaded slot before the print can start. A sensible mapping is pre-filled for you; review it and press Start print, or click a tool and then the slot you want it to come from to change it.

The matching rules, identical to the FlashForge desktop app:

Situation Result
Slot material differs from the tool's material Blocked — PLA cannot be printed from a PETG slot
Slot color differs from the tool's color Allowed, with a warning — the print will come out a different color
Slot is empty, or already assigned to another tool Cannot be selected
A tool is left unmapped Start print stays disabled

Note

Only the ten most recent files are listed, on every model. That is what the printer's HTTP API offers; the full local file listing exists only over the legacy TCP channel this integration deliberately does not speak. Send a file from your slicer and it will appear at the top of the list.

Note

Per-file metadata (print time, filament weight, per-tool materials) is reported by the AD5X only. The 5M / 5M Pro and the Creator 5 / Creator 5 Pro report file names only, so those rows show a name and start without a matching step.

On the Creator 5 series this is a firmware limitation, not an omission here: its /gcodeList response carries no per-file detail at all, so there is nothing to build a matching dialog from. The Material Station slot entities still work — those come from a different endpoint — and matching still applies when you send a multi-material file from your slicer, because the printer does the matching itself at upload time.

Languages

The integration and the job card both follow the language set in your Home Assistant profile — there is nothing to configure.

Language Integration Job card
English ✅ ✅
German (Deutsch) ✅ ✅

German was contributed by @RedAces. Anything not yet translated falls back to English rather than showing a blank.

Adding a language

Two files, both plain JSON, both copied from the English version beside them:

  1. The integration — copy custom_components/flashforge/translations/en.json to <code>.json (e.g. fr.json) and translate the values. Keys must match English exactly; Home Assistant has no per-key fallback here.
  2. The job card — copy custom_components/flashforge/frontend/translations/en.json the same way. Leave {placeholders} such as {slot} and {tool} intact and in a natural position for your language. Keys you omit fall back to English, so a partial translation is fine.

Keep _one / _other pairs together (tools_one, tools_other) — they are chosen by count, and a missing half renders empty.

Then run pytest tests/unit/test_translations.py, which checks both files against English for missing or unknown keys, mismatched placeholders, and incomplete plurals. No build step and no JavaScript changes are involved. PRs welcome.

Usage Examples

Automation: Notify When Print Completes

automation:
  - alias: "3D Print Complete Notification"
    trigger:
      - platform: state
        entity_id: binary_sensor.flashforge_printing
        from: "on"
        to: "off"
    action:
      - service: notify.mobile_app
        data:
          title: "Print Complete"
          message: "{{ states('sensor.flashforge_current_file') }} finished printing!"

Automation: Alert on Print Error

automation:
  - alias: "3D Printer Error Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.flashforge_error
        to: "on"
    action:
      - service: notify.mobile_app
        data:
          title: "Printer Error"
          message: "FlashForge printer has encountered an error!"
          data:
            priority: high

Automation: Turn Off LED When Print Finishes

automation:
  - alias: "Turn Off Printer LED After Print"
    trigger:
      - platform: state
        entity_id: binary_sensor.flashforge_printing
        from: "on"
        to: "off"
    action:
      - service: switch.turn_off
        target:
          entity_id: switch.flashforge_led

Lovelace Card Example

type: entities
title: FlashForge Printer
entities:
  - entity: sensor.flashforge_machine_status
  - entity: binary_sensor.flashforge_printing
  - entity: sensor.flashforge_print_progress
  - entity: sensor.flashforge_nozzle_temperature
  - entity: sensor.flashforge_bed_temperature
  - entity: sensor.flashforge_remaining_time
  - type: divider
  - entity: button.flashforge_pause_print
  - entity: button.flashforge_resume_print
  - entity: button.flashforge_cancel_print
  - entity: button.flashforge_clear_status
  - type: divider
  - entity: switch.flashforge_led
  - entity: switch.flashforge_camera
  - entity: select.flashforge_filtration_mode

Camera Card

type: picture-glance
camera_image: camera.flashforge_camera
entities:
  - binary_sensor.flashforge_printing
  - sensor.flashforge_print_progress

Troubleshooting

Issue Problem Solutions
Discovery Not Finding Printer Automatic discovery doesn't detect your printer • Ensure printer is on the same network/subnet as Home Assistant
• Check firewall settings (UDP port 18007 must be open)
• Verify LAN mode is enabled on the printer
• Try manual configuration with IP address
Connection Failed During Setup Setup fails with connection error • Verify printer has LAN mode enabled
• Check the check code is correct (codes can expire)
• Ensure printer is powered on and connected to network
• Test API access manually: http://<PRINTER_IP>:8898/info
• Verify the serial number includes the SN prefix and matches the value shown on the printer settings screen
Entities Show "Unavailable" Integration installed but entities are unavailable • Check printer is online and reachable
• Verify credentials are still valid
• Reload the integration: Settings → Integrations → FlashForge → ⋮ → Reload
• Check Home Assistant logs for connection errors
Camera Entity Unavailable The camera entity shows unavailable • The camera entity is always created, but it only becomes available when the printer reports an active OEM camera stream URL or the standard OEM fallback stream endpoint responds
• Verify the OEM camera is installed and enabled on the printer
• The switch.flashforge_camera power control remains Pro-only
Remaining / Completion Time Missing or Wrong sensor.flashforge_remaining_time stays at 0 and sensor.flashforge_print_completion_time stays unknown during an active print • FlashForge firmware only calculates an ETA when the sliced file carries its own print-time metadata, which is written by FlashForge's OrcaSlicer fork and FlashPrint but not by regular OrcaSlicer or similar slicers
• Without it the printer reports estimatedTime: 0 over the API, so there is no accurate value for the integration to display
• The printer's own screen still shows a time because it reads the file directly — that isn't exposed over the HTTP API
• Fix: run orca2flashforge as a post-processing script in your slicer to add the metadata FlashForge firmware expects
Python API Not Installing Integration fails due to missing flashforge-python-api • Verify Home Assistant has internet access
• Check PyPI is reachable: https://pypi.org/project/flashforge-python-api/
• Try manual install: pip install flashforge-python-api in HA environment
• Restart Home Assistant after installation
Static IP Recommended - For best reliability, assign a static IP address to your printer in your router's DHCP settings. This prevents connection issues if the printer's IP changes.

Related Projects

Project Description Link
Python API Library Core HTTP API client for FlashForge printers ff-5mp-api-py
TypeScript API Library TypeScript/JavaScript API client ff-5mp-api-ts
FlashForgeUI Cross-platform monitoring & control application FlashForgeUI-Electron

License

This project is licensed under the MIT License - see the LICENSE file for details.

If you find this integration useful, please star the repository!

About

Powerful Home Assistant plugin for FlashForge 3D printers

Topics

3d-printerflashforgehacshome-assistanthome-assistant-integration

Resources

Readme
MIT license
Activity

Stars

20 stars

Watchers

1 watching

Forks

5 forks
Report repository

Releases

Packages

Contributors

Languages