# Ha Bambulab

> Complete reference for all actions available in ha-bambulab automations.

---

# Ha-bambulab Actions Reference

Complete reference for all actions available in ha-bambulab automations.

## Action Syntax

All actions require either a `device_id` or `entity_id` in the data field:

```yaml
# For most actions (device_id)
action: bambu_lab.<action_name>
data:
  device_id: <printer_device_id>
  <other_parameters>

# For AMS/spool tray actions (entity_id)
action: bambu_lab.<action_name>
data:
  entity_id: <tray_entity_id>
  <other_parameters>
```

## Send Command

Send arbitrary GCODE commands to printer.

**Action ID:** `bambu_lab.send_command`

```yaml
action: bambu_lab.send_command
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  command: M104 S200
```

**Parameters:**

- `command` (string, required): GCODE command (e.g., `M104 S200`)

**Warning:** Does not verify printer state; ensure printer is idle before sending.

---

## Print Project File

Print a 3MF file from printer SD card.

**Action ID:** `bambu_lab.print_project_file`

```yaml
action: bambu_lab.print_project_file
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  filepath: cache/filename.3mf
  plate: 1
  timelapse: true
  bed_leveling: false
  flow_cali: false
  vibration_cali: false
  layer_inspect: false
  use_ams: true
  ams_mapping: -1,-1,2,-1
```

**Parameters:**

- `filepath` (string, required): Path to 3MF file on SD card (relative to root, e.g., `cache/filename.3mf`)
- `plate` (number, optional): Plate number to print
- `timelapse` (boolean, optional): Record timelapse of print
- `bed_leveling` (boolean, optional): Perform bed leveling before print
- `flow_cali` (boolean, optional): Perform flow calibration before print
- `vibration_cali` (boolean, optional): Perform vibration calibration (XY Mech Sweep) before print
- `layer_inspect` (boolean, optional): Enable first layer inspection during print
- `use_ams` (boolean, optional): Use AMS (external spool used if false)
- `ams_mapping` (string, optional): AMS tray mapping (e.g., `2,-1,0`)

**Notes:**

- 3MF file must be on SD card root or cache folder
- File must contain sliced GCODE (export as "Export sliced file" from slicer)
- AMS mapping is comma-separated values; -1 means tray not used

---

## Extrude or Retract Filament

Extrude or retract filament through the extruder.

**Action ID:** `bambu_lab.extrude_retract`

```yaml
action: bambu_lab.extrude_retract
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  type: Extrude
  force: false
```

**Parameters:**

- `type` (string, required): `Extrude` or `Retract`
- `force` (boolean, optional): Force operation even if nozzle temperature < 170°C

---

## Load Filament

Load filament from AMS tray or external spool into extruder.

**Action ID:** `bambu_lab.load_filament`

```yaml
action: bambu_lab.load_filament
data:
  entity_id: sensor.ams_tray_1
  temperature: 220
```

**Parameters:**

- `temperature` (number, optional): Target nozzle temperature after load; uses filament midpoint if not specified

**Notes:**

- `entity_id` must be an AMS or external spool tray entity
- Works with filament settings from RFID tags

---

## Unload Filament

Unload filament from nozzle.

**Action ID:** `bambu_lab.unload_filament`

```yaml
action: bambu_lab.unload_filament
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
```

**Parameters:** None

---

## Set Filament

Set filament type and properties for AMS tray or external spool.

**Action ID:** `bambu_lab.set_filament`

```yaml
action: bambu_lab.set_filament
data:
  entity_id: sensor.ams_tray_1
  tray_info_idx: GFL96
  tray_color: FF00FF00
  tray_type: PLA
  nozzle_temp_min: 190
  nozzle_temp_max: 240
```

**Parameters:**

- `tray_info_idx` (string, required): Bambu filament ID (e.g., `GFL96` for Generic PLA Silk)
- `tray_color` (string, required): RGBA color value (e.g., `FF0000FF` for opaque red)
- `tray_type` (string, required): Filament type (e.g., `PLA`, `PETG`, `TPU`)
- `nozzle_temp_min` (number, required): Minimum recommended nozzle temperature
- `nozzle_temp_max` (number, required): Maximum recommended nozzle temperature

**Notes:**

- `entity_id` must be an AMS or external spool tray entity
- Filament IDs are from Bambu's filament database

---

## Get Filament Data

Get JSON string with all known filaments.

**Action ID:** `bambu_lab.get_filament_data`

```yaml
action: bambu_lab.get_filament_data
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
```

**Parameters:** None

**Returns:** JSON string with complete filament database

---

## Move Axis

Move printer axis (printhead, bed, gantry).

**Action ID:** `bambu_lab.move_axis`

```yaml
action: bambu_lab.move_axis
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  axis: X
  distance: 10
```

**Parameters:**

- `axis` (string, required): Axis to move (`X`, `Y`, or `Z`)
- `distance` (number, required): Distance in mm (negative reverses direction)

**Axis Meanings by Printer:**

- **X1/P1:** X/Y move printhead, Z moves bed
- **A1:** Z moves gantry, Y moves bed, X moves printhead

**Notes:**

- Negative distance values move axis in reverse direction
- Z negative moves upward (away from bed)

---

## Skip Objects

Skip specific objects during active print.

**Action ID:** `bambu_lab.skip_objects`

```yaml
action: bambu_lab.skip_objects
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  objects: 409,1463
```

**Parameters:**

- `objects` (string, required): Comma-separated object IDs to skip

**Notes:**

- Available object IDs are in the printable objects entity attributes
- Only works during active print

---

## Read RFID Tag

Trigger AMS to re-read RFID tag on current spool.

**Action ID:** `bambu_lab.read_rfid`

```yaml
action: bambu_lab.read_rfid
data:
  entity_id: sensor.ams_tray_1
```

**Parameters:** None

**Notes:**

- `entity_id` must be an AMS tray entity
- Useful for updating spool information

---

## Start Filament Drying

Start filament drying in AMS 2 Pro or AMS HT.

**Action ID:** `bambu_lab.start_filament_drying`

```yaml
action: bambu_lab.start_filament_drying
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  temp: 65
  rotate_tray: false
  duration: 12
```

**Parameters:**

- `temp` (number, required): Drying temperature in Celsius
  - AMS 2 Pro max: 65°C
  - AMS HT max: 85°C
- `rotate_tray` (boolean, required): Rotate tray during drying
- `duration` (number, required): Drying duration in hours

---

## Stop Filament Drying

Stop active filament drying.

**Action ID:** `bambu_lab.stop_filament_drying`

```yaml
action: bambu_lab.stop_filament_drying
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
```

**Parameters:** None

---

## Common Automation Examples

### Pause Print When Bed Reaches Temperature

```yaml
alias: Pause if bed overheats
trigger:
  - platform: numeric_state
    entity_id: sensor.bed_temperature
    above: 65
action:
  - action: bambu_lab.extrude_retract
    data:
      device_id: a1b2c3d4e5f6g7h8i9j0
      type: Extrude
```

### Send Custom GCODE

```yaml
alias: Home all axes
action: bambu_lab.send_command
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  command: G28
```

### Start Print from SD Card

```yaml
alias: Start test print
action: bambu_lab.print_project_file
data:
  device_id: a1b2c3d4e5f6g7h8i9j0
  filepath: cache/test_print.3mf
  use_ams: true
  timelapse: true
```

### Notify on Print Error

```yaml
alias: Notify on printer error
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_error
action:
  - action: notify.notify
    data:
      title: "Printer Error: {{ trigger.event.data.name }}"
      message: "{{ trigger.event.data.code }}: {{ trigger.event.data.error }}"
```

### Load Specific Filament

```yaml
alias: Load filament for PLA print
action: bambu_lab.load_filament
data:
  entity_id: sensor.ams_tray_1
  temperature: 210
```

### Move Printer to Safe Position

```yaml
alias: Home printer
sequence:
  - action: bambu_lab.move_axis
    data:
      device_id: a1b2c3d4e5f6g7h8i9j0
      axis: X
      distance: 0
  - action: bambu_lab.move_axis
    data:
      device_id: a1b2c3d4e5f6g7h8i9j0
      axis: Y
      distance: 0
  - action: bambu_lab.move_axis
    data:
      device_id: a1b2c3d4e5f6g7h8i9j0
      axis: Z
      distance: 0
```

---

# Ha-bambulab Device Triggers Reference

Device triggers allow you to create automations based on printer events without needing to understand the underlying sensors.

## Overview

Device triggers provide convenient event-based automation triggers. Unlike sensors which show persistent state, some triggers (like "Print canceled") are transient events that occur momentarily.

All trigger events include the printer name in the data payload, allowing you to reference it in automation actions.

## Available Triggers

### Print Started

Triggered when a print job begins.

**Type:** `bambu_lab.print_started`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_started
action:
  - action: notify.notify
    data:
      title: "Print Started"
      message: "{{ trigger.event.data.name }} has started printing"
```

---

### Print Finished

Triggered when a print job completes successfully.

**Type:** `bambu_lab.print_finished`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_finished
action:
  - action: notify.notify
    data:
      title: "Print Complete"
      message: "{{ trigger.event.data.name }} has finished printing"
  - action: light.turn_off
    target:
      entity_id: light.bedroom
```

---

### Print Canceled

Triggered when a print is canceled.

**Type:** `bambu_lab.print_canceled`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name

**Notes:** This is a transient event; there is no persistent "canceled" state on the printer.

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_canceled
action:
  - action: notify.notify
    data:
      title: "Print Canceled"
      message: "{{ trigger.event.data.name }} print was canceled"
```

---

### Print Failed (X1 Only)

Triggered when a print fails on X1 printer.

**Type:** `bambu_lab.print_failed`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name

**Notes:** Only available on X1 printers.

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_failed
action:
  - action: notify.notify
    data:
      title: "Print Failed"
      message: "{{ trigger.event.data.name }} print has failed"
```

---

### HMS Error Detected

Triggered when a hardware maintenance system (HMS) error is detected.

**Type:** `bambu_lab.hms_error`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name
- `code`: Error code (e.g., `0101`)
- `error`: Human-readable error description
- `url`: Wiki link to error documentation

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.hms_error
action:
  - action: notify.notify
    data:
      title: "Printer Error on {{ trigger.event.data.name }}"
      message: |
        Error {{ trigger.event.data.code }}: {{ trigger.event.data.error }}
        More info: {{ trigger.event.data.url }}
```

---

### Print Error Detected

Triggered when a print error occurs (distinct from HMS errors).

**Type:** `bambu_lab.print_error`

**Trigger Data:**

- `device_id`: Printer device ID
- `name`: Printer name
- `code`: Error code
- `error`: Human-readable error description

**Notes:** These are print-specific errors that aren't surfaced as HMS errors.

**Example:**

```yaml
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_error
action:
  - action: notify.notify
    data:
      title: "Print Error on {{ trigger.event.data.name }}"
      message: "{{ trigger.event.data.code }}: {{ trigger.event.data.error }}"
```

---

## Creating Automations with Device Triggers

### Method 1: From Device Page

1. Open Home Assistant Settings
2. Go to Devices & Services > Devices
3. Find your Bambu Lab printer device
4. Scroll to "Automations" section
5. Click "Create Automation"
6. Select the trigger you want
7. Configure actions

### Method 2: From Automations Page

1. Open Automations section
2. Click "Create Automation"
3. Select "Device" as trigger platform
4. Choose your Bambu Lab printer device
5. Select the trigger type
6. Configure actions

## Using Trigger Data in Templates

All trigger event data is accessible in Jinja2 templates via `trigger.event.data`:

```yaml
# Access trigger data in notifications
data:
  title: "{{ trigger.event.data.name }}"
  message: "{{ trigger.event.data.error }}"

# Access in conditionals
condition:
  - condition: template
    value_template: "{{ trigger.event.data.code == '0101' }}"

# Store in variable for later use
variables:
  printer_name: "{{ trigger.event.data.name }}"
  error_code: "{{ trigger.event.data.code }}"
```

## Common Automation Patterns

### Send Notification on Print Completion

```yaml
alias: Notify on print complete
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_finished
action:
  - action: notify.notify
    data:
      title: "Print Complete"
      message: "Your {{ trigger.event.data.name }} print is done!"
```

### Alert on Any Error

```yaml
alias: Alert on printer errors
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.hms_error
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_error
action:
  - action: notify.notify
    data:
      title: "Printer Alert: {{ trigger.event.data.name }}"
      message: "{{ trigger.event.data.code }}: {{ trigger.event.data.error }}"
```

### Turn On Light During Print

```yaml
alias: Light on during print
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_started
action:
  - action: light.turn_on
    target:
      entity_id: light.printer_area
    data:
      brightness: 255

condition: []

id: '1234567890'
```

### Clean Up After Print

```yaml
alias: Clean up after printing
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.print_finished
action:
  - action: light.turn_off
    target:
      entity_id: light.printer_area
  - action: switch.turn_off
    target:
      entity_id: switch.printer_exhaust_fan
  - delay:
      minutes: 5
  - action: notify.notify
    data:
      title: "Printer Cooled Down"
      message: "Safe to remove print from {{ trigger.event.data.name }}"
```

### Conditional Actions Based on Error Code

```yaml
alias: Handle specific errors
trigger:
  - platform: device
    device_id: a1b2c3d4e5f6g7h8i9j0
    type: bambu_lab.hms_error
action:
  - choose:
      - conditions:
          - condition: template
            value_template: "{{ trigger.event.data.code == '0101' }}"
        sequence:
          - action: notify.notify
            data:
              title: "Nozzle Error"
              message: "The nozzle needs attention"
      - conditions:
          - condition: template
            value_template: "{{ trigger.event.data.code == '0102' }}"
        sequence:
          - action: notify.notify
            data:
              title: "Bed Error"
              message: "The bed needs attention"
    default:
      - action: notify.notify
        data:
          title: "Unknown Error"
          message: "{{ trigger.event.data.error }}"
```

## Advantages Over Sensor-Based Triggers

Using device triggers instead of sensor-based automation has several benefits:

1. **Simpler automation creation** - Visual editor support without needing to understand sensors
2. **Transient events** - Can trigger on events that don't have persistent state (e.g., print canceled)
3. **Better readability** - Automations are easier to understand at a glance
4. **Structured data** - Trigger payload provides all relevant error information in one place
5. **Validation** - Device trigger editor prevents invalid configurations

## Limitations

- Device triggers can only be created through the Home Assistant UI or YAML
- Some advanced scenarios may still require sensor-based triggers for more complex logic
- Transient events are only available as triggers (not as persistent sensors)