> For the complete documentation index, see [llms.txt](https://klipper.3dwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://klipper.3dwork.io/klipper/mejoras/sensores-de-filamento.md).

# Sensores de filamento

Una impresión de 12 horas que se queda sin filamento a mitad de camino es frustrante y costosa. Un sensor de filamento **pausa automáticamente la impresión** cuando detecta falta de filamento o problemas de flujo, permitiéndote cambiar material sin perder la pieza.

El sensor vigila el filamento continuamente: detecta si no hay material, pausa de forma limpia, te avisa para cambiar, y reanuda exactamente donde se quedó.

{% hint style="info" %}
**¿No sabes cuál sensor elegir?** Mira la tabla de abajo y busca tu rango de presupuesto, o ve directamente a la sección [¿Cuál elijo?](#cual-elijo).
{% endhint %}

***

## 📊 Comparativa Rápida de Sensores

| Sensor              | Tipo       | Detección             | Costo  | Precisión  | Mantenimiento | Comprar                                                                                                                                    |
| ------------------- | ---------- | --------------------- | ------ | ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pulsador/Óptico** | Switch     | Ausencia              | 5-15€  | Baja       | Ninguno       | [AliExpress](https://s.click.aliexpress.com/e/182731559?productUrl=https://www.aliexpress.com/w/wholesale-3d-printer-filament-sensor.html) |
| **Dyze Orthus**     | Movimiento | Ausencia + Atascos    | 80€+   | Muy Alta   | Bajo          | [Dyze.ca](https://www.dyze.ca/pages/products/orthus-filament-sensor)                                                                       |
| **BTT SFS v2.0**    | Hybrid     | Ausencia + Movimiento | 25-35€ | Alta       | Bajo          | [AliExpress](https://s.click.aliexpress.com/e/182731559?productUrl=https://www.aliexpress.com/w/wholesale-BTT-smart-filament-sensor.html)  |
| **BTT SFS v1.0**    | Movimiento | Ausencia + Movimiento | 15-25€ | Media      | Rodamientos   | [AliExpress](https://s.click.aliexpress.com/e/182731559?productUrl=https://www.aliexpress.com/w/wholesale-BTT-SFS-v1.html)                 |
| **Orbiter Sensor**  | Integrado  | Ausencia + Botones    | 30€\*  | Alta       | Bajo          | [AliExpress](https://s.click.aliexpress.com/e/182731559?productUrl=https://www.aliexpress.com/w/wholesale-orbiter-filament-sensor.html)    |
| **Genérico Motion** | Movimiento | Ausencia              | 10-20€ | Baja-Media | Bajo          | [AliExpress](https://s.click.aliexpress.com/e/182731559?productUrl=https://www.aliexpress.com/w/wholesale-filament-motion-sensor.html)     |

{% hint style="info" %}
**Nota sobre Orbiter:** El precio de 30€ es SOLO el sensor. El extrusor Orbiter completo cuesta 80-100€, pero ya incluye el sensor integrado.

**Links de AliExpress:** Son búsquedas con nuestro ID de afiliado. Cambia modelo/marca dentro de AliExpress si prefieres otro proveedor.
{% endhint %}

***

## ¿Cuál elijo?

{% tabs %}
{% tab title="< 20€" %}
**Sensor óptico/pulsador genérico.**

Funciona. No detecta atascos, solo si hay o no hay filamento — pero para la mayoría de usuarios domésticos es suficiente. Si lo rompes, compras otro por 5€.

→ Lee la sección **Pulsador/Óptico** más abajo.
{% endtab %}

{% tab title="20-40€" %}
**BTT SFS v2.0, sin dudar.**

Detecta ausencia Y atascos, sin rodamientos, sin mantenimiento. La mejor relación calidad-precio del mercado ahora mismo.

→ Lee la sección **BTT SFS v2.0** más abajo.
{% endtab %}

{% tab title="> 60€" %}
**Dyze Orthus, si imprimes 24/7 o en granja.**

Encoder óptico de precisión, sin partes móviles, calibración muy fina. Para uso profesional donde no te puedes permitir un fallo.

→ Lee la sección **Dyze Orthus** más abajo.
{% endtab %}

{% tab title="Tienes Orbiter" %}
**Usa el sensor integrado, no compres nada más.**

Si ya tienes un extrusor Orbiter, el sensor viene incluido y está optimizado para esa plataforma.

→ Lee la sección **Orbiter** más abajo.
{% endtab %}
{% endtabs %}

***

## Configuración por Sensor

{% tabs %}
{% tab title="Pulsador/Óptico" %}
Sensores básicos que **detectan si hay filamento o no**. No miden movimiento ni detectan atascos — solo presencia/ausencia. Para la mayoría de usuarios de impresión doméstica es más que suficiente.

Hay dos variantes:

* **Mecánico (pulsador):** una palanca que el filamento presiona al pasar
* **Óptico:** un LED + fotoreceptor que detecta si el filamento corta el haz

Son funcionalmente idénticos. El óptico aguanta mejor en máquinas con mucha vibración.

<figure><img src="/files/3xDci8CwDvCAkyQkBggi" alt=""><figcaption><p>Sensor de pulsador típico - 3 cables (V, S, GND)</p></figcaption></figure>

### Instalación Física

{% stepper %}
{% step %}

#### Elige la ubicación

* **Bowden:** coloca el sensor antes del tubo (entre extrusor y entrada del tubo Bowden)
* **Direct Drive:** monta entre el bloque del extrusor y la entrada de filamento — necesitas unos \~40×30mm de espacio libre
  {% endstep %}

{% step %}

#### Conecta los 3 cables

| Cable         | Destino                                               |
| ------------- | ----------------------------------------------------- |
| **GND**       | GND mainboard                                         |
| **V**         | 5V (o 3.3V — consulta la especificación de tu sensor) |
| **SEÑAL**     | Pin endstop libre (PA4, etc.)                         |
| {% endstep %} |                                                       |

{% step %}

#### Verifica mecánicamente

Pasa filamento manualmente y comprueba que presiona la palanca o corta el haz. Si no hay reacción física, la configuración no servirá de nada.
{% endstep %}
{% endstepper %}

### Configuración en Klipper

```ini
[filament_switch_sensor filament_runout]
switch_pin: PA4                    # Ajusta según tu mainboard
pause_on_runout: True
runout_gcode:
    M118 Sin filamento!
    M600                           # Macro de cambio de filamento
insert_gcode:
    M118 Filamento insertado
    LOAD_FILAMENT
event_delay: 3.0
pause_delay: 0.1

[respond]
# Necesario para M118
```

**Parámetros clave:**

| Parámetro         | Qué hace                                                                        |
| ----------------- | ------------------------------------------------------------------------------- |
| `switch_pin`      | Pin donde va la señal del sensor                                                |
| `pause_on_runout` | `True` = pausa automática al detectar problema                                  |
| `event_delay`     | Espera (segundos) antes de reaccionar — sube este valor si hay falsos positivos |
| `pause_delay`     | Espera antes de ejecutar el `runout_gcode`                                      |

### Pros y Contras

**✅ Lo bueno**

* Muy barato (5-15€) — compra varios de reserva
* Sin mantenimiento
* Compatible con cualquier mainboard
* Fácil de diagnosticar: funciona o no funciona

**❌ Lo malo**

* No detecta atascos
* No detecta flujo lento
* Falsos positivos si el Bowden es muy largo
* Requiere que el filamento presione físicamente bien

### Troubleshooting

<details>

<summary>Sensor no detecta cambios</summary>

1. Invierte la lógica del pin: cambia `switch_pin: PA4` por `switch_pin: !PA4`
2. Comprueba la conexión física (¿el cable SEÑAL está en el pin correcto?)
3. Verifica que el filamento presiona completamente la palanca

</details>

<details>

<summary>Falsos positivos frecuentes</summary>

1. Sube `event_delay` a 5-10 segundos
2. Asegúrate de que el bracket no vibra durante la impresión
3. Monta el sensor en un soporte más rígido

</details>

<details>

<summary>Se activa pero no pausa la impresión</summary>

1. Verifica que `[pause_resume]` está definido en tu `printer.cfg`
2. Comprueba que la macro `M600` existe

</details>

### Test Final

{% stepper %}
{% step %}

#### Test estático

Fluidd/Mainsail → **Miscellaneous** → **Filament Sensors**. Presiona y retira filamento manualmente. ¿El estado cambia? → Sensor OK ✅
{% endstep %}

{% step %}

#### Test en impresión real

Inicia una impresión. A los 20-30 minutos, extrae el filamento manualmente. ¿La máquina pausa en menos de 3 segundos? → Configuración correcta ✅
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Dyze Orthus" %}
Sensor profesional de movimiento. Encoder óptico que detecta cada **0.5mm de desplazamiento**, sin partes móviles, sin mantenimiento. La opción para granjas de impresión o producción 24/7.

**Lo que lo diferencia de los demás:**

* Detecta atascos antes de que arruinen la pieza
* Sensibilidad ajustable por tipo de filamento
* "Instala y olvídate durante años"

{% hint style="warning" %}
**¿Vale la pena para uso doméstico?** Solo si imprimes muy frecuentemente y no te puedes permitir fallos. Para impresión casual, el BTT SFS v2.0 hace el mismo trabajo por mucho menos.
{% endhint %}

<figure><img src="/files/00HIAonJC7TzJX66nCau" alt=""><figcaption><p>Dyze Orthus - Sensor profesional de movimiento</p></figcaption></figure>

### Tabla de Calibración

El parámetro `detection_length` depende del diámetro del filamento, la posición del selector y la sensibilidad que quieras.

<figure><img src="/files/yzYKiphMDIDbjpEweVjc" alt=""><figcaption><p>Tabla oficial Dyze - valores de detection_length según configuración</p></figcaption></figure>

{% hint style="info" %}
**Regla práctica:** Usa el valor de la tabla + 2-3mm para reducir falsos positivos durante los primeros días. Afinas después.
{% endhint %}

### Instalación Física

{% stepper %}
{% step %}

#### Ubica el sensor

Después del drive del extrusor, con el filamento perpendicular al sensor. Espacio necesario: 40×20×30mm. No aprietes demasiado — es un sensor óptico delicado.
{% endstep %}

{% step %}

#### Conecta los 3 cables

| Cable         | Color        | Destino           |
| ------------- | ------------ | ----------------- |
| GND           | Negro        | GND mainboard     |
| 5V            | Rojo         | 5V mainboard      |
| Señal         | Blanco/Verde | Pin endstop libre |
| {% endstep %} |              |                   |

{% step %}

#### Verifica el LED

Debe estar en **verde fijo** tras conectar. Si está rojo o apagado, hay un problema de alimentación — no sigas hasta resolverlo.
{% endstep %}
{% endstepper %}

### Configuración en Klipper

```ini
[filament_motion_sensor orthus]
detection_length: 10               # Ajusta según tabla + margen
extruder: extruder
switch_pin: PA4
pause_on_runout: True
runout_gcode:
    M118 Filamento agotado (Orthus)
    M600
insert_gcode:
    M118 Filamento cargado
    LOAD_FILAMENT
event_delay: 3.0
pause_delay: 0.01                  # Muy bajo: el sensor es preciso

[respond]
```

### Indicadores LED

| LED                  | Significado                                |
| -------------------- | ------------------------------------------ |
| 🟢 Verde fijo        | Alimentado y listo                         |
| 🟢 Verde parpadeante | Filamento en movimiento (detección activa) |
| 🔴 Rojo              | Sin alimentación o error                   |

### Calibración Paso a Paso

{% stepper %}
{% step %}

#### Confirma el LED verde

Sin LED verde no tiene sentido continuar. Si está rojo, revisa la alimentación y el cableado antes de tocar nada en Klipper.
{% endstep %}

{% step %}

#### Test manual de movimiento

Mueve filamento 10mm hacia adelante. El LED debe parpadear. Si no parpadea, el problema está en el pin de señal en la configuración.
{% endstep %}

{% step %}

#### Ajusta detection\_length

* Muchos falsos positivos → **sube** el valor (+2mm cada vez)
* No detecta nunca → **baja** el valor (-2mm) o revisa el cableado
* Objetivo: que detecte al mover entre 5 y 10mm
  {% endstep %}

{% step %}

#### Test en impresión real

Inicia impresión. A los 5 minutos, extrae el filamento manualmente. ¿Pausa en menos de 2 segundos? ✅. ¿Tarda más o no pausa? → Sube `detection_length` 2mm y repite.
{% endstep %}
{% endstepper %}

### Pros y Contras

**✅ Lo bueno**

* Ultra-preciso (cada 0.5mm)
* Sin partes móviles
* Sin mantenimiento
* Compatible con cualquier filamento

**❌ Lo malo**

* Precio elevado (80€+)
* Requiere calibración inicial
* Sobredimensionado para uso doméstico
  {% endtab %}

{% tab title="BTT SFS v2.0" %}
El sensor más recomendado para uso general. Combina dos sensores en uno: un switch que detecta si hay filamento, y un encoder que detecta si está fluyendo. Si uno falla, el otro te cubre.

Sin rodamientos, sin mantenimiento, precio razonable. **Si no sabes qué sensor comprar, compra este.**

<figure><img src="/files/6940TkjVYpWG6JaSWfqX" alt=""><figcaption><p>BTT SFS v2.0 - Compacto y versátil</p></figcaption></figure>

### Instalación Física

{% stepper %}
{% step %}

#### Ubica el sensor

Después del drive del extrusor, con el filamento fluyendo perpendicularmente. Dimensiones: 45×25×25mm. No aprietes demasiado los tornillos.
{% endstep %}

{% step %}

#### Conecta los cables (4-6 según modelo)

| Cable            | Destino                                 |
| ---------------- | --------------------------------------- |
| GND              | GND mainboard                           |
| 5V               | 5V mainboard                            |
| SWITCH\_PIN      | Pin endstop (PA4, etc.)                 |
| ENCODER\_PIN     | Otro pin endstop disponible (PA5, etc.) |
| {% endstep %}    |                                         |
| {% endstepper %} |                                         |

{% hint style="info" %}
**Truco:** Si puedes, usa un bracket de hot-swap. Facilita el reemplazo sin desmontar todo el extrusor.
{% endhint %}

### Configuración (Dual Sensor)

```ini
# SENSOR SWITCH (detección de ausencia de filamento)
[filament_switch_sensor SFS_switch]
switch_pin: gpio18               # Ajusta según tu mainboard
pause_on_runout: False           # Lo controlamos con macros
runout_gcode:
    M118 Switch: Sin filamento
insert_gcode:
    M118 Switch: Filamento insertado

# SENSOR ENCODER (detección de movimiento y atascos)
[filament_motion_sensor SFS_encoder]
switch_pin: gpio17
detection_length: 2.88           # Mínimo recomendado por BTT
extruder: extruder
pause_on_runout: False
runout_gcode:
    M118 Encoder: Atasco detectado
insert_gcode:
    M118 Encoder: Flujo normal

[respond]
```

{% hint style="warning" %}
**`pause_on_runout: False`** es intencional en ambos sensores. Las macros de abajo controlan cuándo pausar realmente. Con `True` en los dos puede haber conflictos y pausas duplicadas.
{% endhint %}

**Parámetros críticos:**

* **`detection_length: 2.88mm`** = mínimo del sensor. Si hay falsos positivos, sube +1mm (hasta \~5mm como máximo).
* **`pause_on_runout: False`** = la pausa la gestiona la macro `FILAMENT_CHECK`.

### Macros de Control

```ini
# Deshabilitar en boot (evita falsos positivos durante precalentamiento)
[delayed_gcode SFS_BOOTDISABLE]
initial_duration: 1
gcode:
    SET_FILAMENT_SENSOR SENSOR=SFS_switch ENABLE=0
    SET_FILAMENT_SENSOR SENSOR=SFS_encoder ENABLE=0

# Activar antes de imprimir (llamar desde START_PRINT)
[gcode_macro SFS_ENABLE]
description: Activar sensores antes de impresión
gcode:
    M117 Activando sensores de filamento
    G92 E0
    SET_FILAMENT_SENSOR SENSOR=SFS_switch ENABLE=1
    SET_FILAMENT_SENSOR SENSOR=SFS_encoder ENABLE=1

# Desactivar al terminar (llamar desde END_PRINT)
[gcode_macro SFS_DISABLE]
description: Desactivar sensores al terminar
gcode:
    M117 Desactivando sensores
    G92 E0
    SET_FILAMENT_SENSOR SENSOR=SFS_switch ENABLE=0
    SET_FILAMENT_SENSOR SENSOR=SFS_encoder ENABLE=0

# Pausa solo si ambos sensores confirman problema (más fiable)
[gcode_macro FILAMENT_CHECK]
gcode:
    {% set sensor_switch = printer["filament_switch_sensor SFS_switch"] %}
    {% set sensor_encoder = printer["filament_motion_sensor SFS_encoder"] %}
    
    {% if sensor_switch.filament_detected == False %}
        PAUSE
        M118 ¡Filamento agotado!
        M600
    {% elif sensor_encoder.filament_detected == False %}
        PAUSE
        M118 ¡Atasco o problema de flujo!
    {% endif %}
```

### Integración en el Laminador

Añade esto al **G-code de inicio** en Cura, PrusaSlicer o el que uses:

```gcode
; Calentamiento
M104 S{material_print_temperature}
M140 S{material_bed_temperature}

; Espera a temperatura
M109 S{material_print_temperature}
M190 S{material_bed_temperature}

; Activar sensores AQUÍ (nozzle ya caliente)
SFS_ENABLE

; Macro de inicio
START_PRINT
```

### v2.0 vs v1.0

**v2.0 — esta versión**

* Sin rodamientos
* Sin mantenimiento
* Más compacto
* 25-35€
* ✅ **Cómprala**

**v1.0 — versión anterior**

* Con rodamientos (lubricar cada 6 meses)
* Más grande
* 15-25€
* Solo si el presupuesto es muy ajustado

### Troubleshooting

<details>

<summary>Ambos sensores reportan false sin razón</summary>

1. Verifica que llegan 5V al sensor (mide con multímetro si es necesario)
2. Comprueba el cableado GPIO pin a pin
3. Ejecuta `FIRMWARE_RESTART`

</details>

<details>

<summary>Solo el switch funciona, el encoder no</summary>

1. Verifica que el filamento pasa correctamente por el canal del encoder
2. Sube `detection_length` a 5mm
3. Comprueba que no hay suciedad o pelos dentro del encoder

</details>

<details>

<summary>Falsos positivos continuos</summary>

1. Sube `event_delay` a 5 segundos
2. Revisa que el filamento está bien alineado en el sensor
3. Comprueba que el soporte está rígido y no vibra

</details>

### Test Final

{% stepper %}
{% step %}

#### Test de switches

Fluidd/Mainsail → **Miscellaneous** → **Filament Sensors**. Presiona y retira filamento. ¿Cambian `SFS_switch` y `SFS_encoder`? ✅
{% endstep %}

{% step %}

#### Test del encoder

Mueve filamento lentamente (micro-movimientos de 2-3mm). El estado del encoder debe fluctuar. Si no cambia, revisa el cableado del encoder específicamente.
{% endstep %}

{% step %}

#### Test en impresión

Inicia impresión. A los 20 minutos, extrae filamento manualmente. ¿Pausa en menos de 3 segundos? ✅. Si no pausa, verifica que `SFS_ENABLE` está en tu `START_PRINT`.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="BTT SFS v1.0" %}
La versión anterior del SFS. Mismo principio que el v2.0 pero con rodamientos que necesitan lubricación periódica. Si puedes, coge el v2.0 — por 10€ más te ahorras el mantenimiento.

<figure><img src="/files/A2DDmNBlKB7R1qV0Eozo" alt=""><figcaption><p>BTT SFS v1.0 - Con rodamientos (requiere lubricado)</p></figcaption></figure>

{% hint style="warning" %}
**La diferencia clave con el v2.0:** el v1.0 necesita `switch_pin: ^PA9` (nota el `^`). Sin el `^` de pull-up, el sensor no funciona. Es el error más común en esta versión.
{% endhint %}

### Instalación Física

{% stepper %}
{% step %}

#### Ubica el sensor

Después del drive del extrusor. Dimensiones: \~50×30×30mm (más grande que el v2.0). No aprietes demasiado los tornillos sobre los rodamientos.
{% endstep %}

{% step %}

#### Conecta los 3 cables

| Cable         | Destino                              |
| ------------- | ------------------------------------ |
| GND           | GND mainboard                        |
| 5V            | 5V mainboard                         |
| SEÑAL         | Pin endstop **con pull-up** (`^PA9`) |
| {% endstep %} |                                      |

{% step %}

#### Ten aceite a mano

El v1.0 necesita lubricación cada 3-6 meses. Anota la fecha de instalación para no olvidarlo.
{% endstep %}
{% endstepper %}

### Configuración

```ini
[filament_motion_sensor BTT_Smart]
detection_length: 7              # Empieza con 7mm (más alto que el v2.0)
extruder: extruder
switch_pin: ^PA9                 # ^ = pull-up (CRÍTICO en v1.0)
pause_on_runout: True
runout_gcode:
    M118 Filamento agotado
    M600
insert_gcode:
    M118 Filamento cargado
    LOAD_FILAMENT
event_delay: 3.0
pause_delay: 0.01

[respond]
```

**Diferencias clave respecto al v2.0:**

* `detection_length: 7mm` (vs 2.88mm en v2.0 — los rodamientos necesitan más margen)
* `switch_pin: ^PA9` — el `^` activa pull-up, es imprescindible
  * Sin `^`: el sensor nunca detecta nada
  * Si aun así no funciona: prueba sin `^` (algunos modelos lo tienen incorporado)

### Mantenimiento de Rodamientos

{% stepper %}
{% step %}

#### Cada 3-6 meses

Extrae el cartucho del sensor, aplica 1-2 gotas de aceite ligero (aceite de máquina de coser o 3-en-1), gira manualmente 10-20 veces, y vuelve a instalar.
{% endstep %}

{% step %}

#### Señales de que toca mantenimiento antes de plazo

* El sensor "pega" o se mueve con resistencia
* Detección inconsistente (a veces detecta, a veces no)
* Ruido anormal al pasar filamento

Si ves alguna de estas señales, lubrica aunque no hayan pasado 6 meses.
{% endstep %}
{% endstepper %}

### Macros

```ini
[delayed_gcode SFS_BOOTDISABLE]
initial_duration: 1
gcode:
    SET_FILAMENT_SENSOR SENSOR=BTT_Smart ENABLE=0

[gcode_macro SFS_ENABLE]
description: Activar sensor antes de impresión
gcode:
    M117 SFS ENABLED
    G92 E0
    SET_FILAMENT_SENSOR SENSOR=BTT_Smart ENABLE=1

[gcode_macro SFS_DISABLE]
description: Desactivar sensor después de impresión
gcode:
    M117 SFS DISABLED
    G92 E0
    SET_FILAMENT_SENSOR SENSOR=BTT_Smart ENABLE=0
```

### Pros y Contras

**✅ Lo bueno**

* Más barato que el v2.0 (15-25€)
* Misma capacidad de detección de atascos
* Fácil de encontrar

**❌ Lo malo**

* Rodamientos requieren lubricación periódica
* Más grande y aparatoso
* El pull-up `^` es un punto de fallo frecuente si lo olvidas

### Test Final

{% stepper %}
{% step %}

#### Verifica el pull-up

En Fluidd/Mainsail el estado debe cambiar al mover filamento. Si siempre está "disconnected" o "false", prueba añadir o quitar el `^` del pin.
{% endstep %}

{% step %}

#### Test manual

Mueve filamento lentamente \~10mm. Observa si `filament_detected` cambia en la interfaz web.
{% endstep %}

{% step %}

#### Test en impresión

Inicia impresión. Extrae filamento manualmente. ¿Pausa en menos de 3 segundos? ✅. Si no: sube `detection_length` a 8-10mm y repite.
{% endstep %}

{% step %}

#### Planifica el mantenimiento

Anota la fecha de hoy en el calendario. En 6 meses, lubrica los rodamientos. Es el único mantenimiento que necesita este sensor.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Orbiter" %}
Sensor integrado en los extrusores **Orbiter v1, v1.5 y v2**. Si ya tienes uno, el sensor viene incluido — solo hace falta cablearlo y configurarlo.

Tiene dos ventajas únicas respecto a otros sensores: **botones físicos** para carga/descarga de emergencia y un **LED de estado** visible en todo momento.

<figure><img src="/files/TxZBw0YfKvhSrCP7JIuR" alt=""><figcaption><p>Orbiter con sensor integrado - LED indicador de estado</p></figcaption></figure>

### LED Indicador

| Color      | Significado                            |
| ---------- | -------------------------------------- |
| 🟢 Verde   | Filamento cargado, listo para imprimir |
| 🟠 Naranja | Botón de descarga presionado           |
| 🔴 Rojo    | Sin filamento detectado                |

### Cableado (4 cables)

| Cable           | Color       | Destino                    |
| --------------- | ----------- | -------------------------- |
| GND             | 🔵 Azul     | GND mainboard              |
| Alimentación    | 🔴 Rojo     | 3.3V (o 5V con adaptación) |
| Señal filamento | 🟢 Verde    | Puerto servo o endstop     |
| Botón descarga  | 🟡 Amarillo | Otro pin endstop           |

**Pines de ejemplo para Octopus:**

| Función          | Puerto        | Pin |
| ---------------- | ------------- | --- |
| GND (Azul)       | Servo GND     | —   |
| 3.3V/5V (Rojo)   | Servo 5V      | —   |
| Sensor (Verde)   | Servo señal   | PA2 |
| Botón (Amarillo) | Endstop señal | PA0 |

### Instalación

{% stepper %}
{% step %}

#### Descarga la configuración oficial

```
https://orbiterprojects.com/download/filamentsensor/OrbiterSensor.cfg
```

{% endstep %}

{% step %}

#### Edita OrbiterSensor.cfg con tus pines

```ini
[gcode_button sensor_fs]
pin: PA2          # VERDE → pin de señal del filamento

[gcode_button sensor_fu]
pin: PA0          # AMARILLO → pin del botón de descarga
```

{% endstep %}

{% step %}

#### Añade a printer.cfg

```ini
[include OrbiterSensor.cfg]

[extruder]
min_extrude_temp: 180   # Necesario para que el sensor funcione correctamente
...
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Orbiter v2.2:** Las señales están invertidas. Añade `!` delante de cada pin:

```ini
pin: !PA2      # Verde
pin: !PA0      # Amarillo
```

{% endhint %}

### Macros Incluidas en OrbiterSensor.cfg

El archivo ya incluye todo lo necesario:

* **`LOAD_FILAMENT`** — carga automática al insertar filamento
* **`UNLOAD_FILAMENT`** — descarga automática al pulsar el botón
* Los **botones físicos** ejecutan estas macros directamente, sin pasar por la interfaz web

### Macros Adicionales (Opcionales)

```ini
# Pausa personalizada al detectar falta de filamento
[gcode_macro PAUSE_FILAMENT_MISSING]
gcode:
    PAUSE
    M118 Filamento agotado - Presiona botón descarga para cambiar

# Reanudar después de cambio con tiempo de estabilización
[gcode_macro RESUME_AFTER_FILAMENT]
gcode:
    G4 P10000          # Espera 10 segundos antes de reanudar
    RESUME
```

### Pros y Contras

**✅ Lo bueno**

* Integrado = menos cables que gestionar
* Botones físicos = no necesitas la pantalla para emergencias
* LED visible = sabes el estado de un vistazo
* Compatible con Orbiter v1, v1.5 y v2

**❌ Lo malo**

* Solo funciona con extrusores Orbiter
* El extrusor completo cuesta 80-100€
* Configuración algo más compleja que un sensor genérico

### Test Final

{% stepper %}
{% step %}

#### Test del LED

Conecta con filamento cargado. ¿LED verde? ✅. Retira el filamento. ¿LED rojo? ✅. Si los colores no corresponden, revisa el cableado del cable verde.
{% endstep %}

{% step %}

#### Test de botones

Presiona el botón de descarga (cable amarillo). ¿Ejecuta `UNLOAD_FILAMENT`? ✅. Presiona el botón de carga. ¿Ejecuta `LOAD_FILAMENT`? ✅.
{% endstep %}

{% step %}

#### Test en impresión

Con LED verde, inicia impresión. A mitad, presiona el botón de descarga. ¿Pausa automáticamente? ✅. ¿Se descarga el filamento? ✅.
{% endstep %}

{% step %}

#### Test de recuperación completa

Inserta filamento nuevo. ¿El LED cambia a verde? ✅. Ejecuta `RESUME` desde la interfaz. ¿Continúa la impresión desde donde se quedó? ✅.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

## 🔍 Troubleshooting Avanzado

### Diagnóstico Rápido

Antes de tocar nada en la configuración, comprueba el estado visual en la interfaz:

{% stepper %}
{% step %}

#### Abre Fluidd o Mainsail

Ve a **Miscellaneous** → **Filament Sensors**.
{% endstep %}

{% step %}

#### Observa el estado en tiempo real

Inserta y retira filamento manualmente. El estado debe cambiar entre `true` y `false`. Si no cambia, hay un problema físico o de configuración.
{% endstep %}

{% step %}

#### Consulta por consola si necesitas más detalle

```gcode
QUERY_FILAMENT_SENSOR

# Resultado esperado:
# SFS_switch: filament_detected=true
# SFS_encoder: filament_detected=true
```

{% endstep %}
{% endstepper %}

### Problemas Frecuentes

<details>

<summary>❌ "Filament sensor not found"</summary>

El nombre del sensor en el comando no coincide con el de `printer.cfg`.

```ini
# Si el sensor se llama "mi_sensor" en la configuración:
QUERY_FILAMENT_SENSOR SENSOR=mi_sensor    # ✅ Correcto
QUERY_FILAMENT_SENSOR SENSOR=SFS_switch   # ❌ Error (nombre incorrecto)
```

</details>

<details>

<summary>❌ Estado siempre "filament_detected = false" sin razón</summary>

En orden de probabilidad:

1. Invierte la lógica del pin: `switch_pin: !PA4`
2. Verifica la alimentación (¿llega tensión al sensor?)
3. Comprueba que el GND está bien conectado
4. Ejecuta `FIRMWARE_RESTART`

</details>

<details>

<summary>❌ El estado no cambia al insertar o retirar filamento</summary>

1. Verifica que el pin en `printer.cfg` es el correcto
2. Prueba combinaciones: `PA4` → `!PA4` → `^PA4` → `^!PA4`
3. Comprueba el montaje mecánico: ¿el sensor presiona bien el filamento?
4. Si el filamento es muy fino o grueso, puede no activar el sensor

</details>

<details>

<summary>❌ Falsos positivos cada 2-3 minutos</summary>

1. Sube `event_delay` a 10 segundos
2. El sensor probablemente vibra con la máquina — monta un bracket más rígido
3. Comprueba que el filamento no roza el sensor lateralmente
4. Añade amortiguación (goma fina) entre el sensor y el chasis

</details>

<details>

<summary>❌ Detecta al inicio pero después deja de responder</summary>

El pin necesita pull-up. Añade `^` antes del valor:

```ini
switch_pin: ^PA4    # El ^ activa el pull-up interno
```

</details>

***

## 📈 Mejores Prácticas

### Timing: Cuándo Activar y Desactivar

**El error más común** es tener los sensores activos durante el precalentamiento. El filamento frío, los micro-movimientos del extrusor y los cambios de temperatura generan falsos positivos que paran la impresión antes de que empiece.

La solución es simple: deshabilita en boot, habilita solo cuando el nozzle ya está caliente.

{% stepper %}
{% step %}

#### Deshabilita en boot

```ini
[delayed_gcode SFS_BOOTDISABLE]
initial_duration: 1
gcode:
    SET_FILAMENT_SENSOR SENSOR=SFS_switch ENABLE=0
    SET_FILAMENT_SENSOR SENSOR=SFS_encoder ENABLE=0
```

{% endstep %}

{% step %}

#### Activa en START\_PRINT, después del calentamiento

```ini
[gcode_macro START_PRINT]
gcode:
    # ... precalentamiento ...
    M109 S{material_print_temperature}   # Espera temperatura nozzle
    M190 S{material_bed_temperature}     # Espera temperatura cama
    
    SFS_ENABLE    # ← Aquí: nozzle ya caliente, listo para imprimir
    
    # ... resto de tu START_PRINT ...
```

{% endstep %}

{% step %}

#### Desactiva en END\_PRINT

```ini
[gcode_macro END_PRINT]
gcode:
    # ... limpieza final ...
    SFS_DISABLE
```

{% endstep %}
{% endstepper %}

### Integración con M600 (Cambio de Filamento)

M600 coordina la pausa limpia: retrae filamento, espera a que insertes el nuevo, y reanuda desde exactamente el mismo punto. Sin ella, una pausa simple deja el nozzle en medio de la pieza.

```ini
[gcode_macro M600]
description: Cambio de filamento
gcode:
    PAUSE                           # Pausa la impresión
    M117 Cambio de filamento...
    UNLOAD_FILAMENT                 # Descarga el filamento actual
    M118 Inserta nuevo filamento y ejecuta RESUME

[gcode_macro RESUME]
rename_existing: RESUME_ORIGINAL
gcode:
    {% if printer.pause_resume.is_paused %}
        LOAD_FILAMENT              # Carga el nuevo filamento
        G92 E0
        RESUME_ORIGINAL            # Reanuda la impresión
    {% endif %}
```

### Referencia de Parámetros

#### [`filament_switch_sensor`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor) — Pulsador/Óptico

Detecta **presencia/ausencia** de filamento. Sin capacidad de detectar atascos.

| Parámetro                                                                                   | Default | Rango típico    | Para qué sirve                                                                   |
| ------------------------------------------------------------------------------------------- | ------- | --------------- | -------------------------------------------------------------------------------- |
| [`switch_pin`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor)      | —       | Pin (ej. `PA4`) | Pin de señal. Obligatorio. Usa `!PA4` para invertir lógica, `^PA4` para pull-up  |
| [`pause_on_runout`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor) | `True`  | True / False    | Pausa automáticamente al detectar falta de filamento                             |
| [`runout_gcode`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor)    | —       | gcode           | Comandos ejecutados al detectar falta de filamento (ej. `M600`)                  |
| [`insert_gcode`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor)    | —       | gcode           | Comandos ejecutados al reinsertar filamento                                      |
| [`event_delay`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor)     | —       | 0.5 – 10s       | Espera antes de procesar el evento. Súbelo si hay falsos positivos por vibración |
| [`pause_delay`](https://www.klipper3d.org/Config_Reference.html#filament_switch_sensor)     | —       | 0.01 – 1s       | Tiempo entre detectar el problema y ejecutar la pausa                            |

***

#### [`filament_motion_sensor`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor) — BTT SFS, Dyze Orthus, Genérico Motion

Detecta **movimiento real del filamento**. Cubre ausencia + atascos + flujo lento.

| Parámetro                                                                                    | Default | Rango típico    | Para qué sirve                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`switch_pin`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)       | —       | Pin (ej. `PA4`) | Pin de señal. Obligatorio. Usa `!` para invertir lógica, `^` para pull-up                                                                                                                     |
| [`detection_length`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor) | `7.0mm` | 2.88 – 15mm     | Distancia mínima de filamento que debe moverse para registrar cambio. **El parámetro más importante de este tipo de sensor** — demasiado bajo = falsos positivos, demasiado alto = no detecta |
| [`extruder`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)         | —       | nombre          | Nombre del extrusor asociado (normalmente `extruder`). Obligatorio                                                                                                                            |
| [`pause_on_runout`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)  | `True`  | True / False    | Pausa automáticamente al detectar problema de flujo                                                                                                                                           |
| [`runout_gcode`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)     | —       | gcode           | Comandos ejecutados al detectar atasco o falta de filamento                                                                                                                                   |
| [`insert_gcode`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)     | —       | gcode           | Comandos ejecutados cuando el flujo se reanuda                                                                                                                                                |
| [`event_delay`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)      | —       | 0.5 – 10s       | Espera antes de procesar el evento. Crítico en sensores de movimiento — demasiado bajo dispara falsas alarmas                                                                                 |
| [`pause_delay`](https://www.klipper3d.org/Config_Reference.html#filament_motion_sensor)      | —       | 0.01 – 1s       | Tiempo entre detectar el problema y ejecutar la pausa                                                                                                                                         |

{% hint style="info" %}
**Diferencia clave entre los dos tipos:** `filament_switch_sensor` no tiene `detection_length` ni `extruder` porque no mide movimiento — solo sabe si el filamento está o no está. `filament_motion_sensor` necesita saber de qué extrusor viene el movimiento para calcular correctamente la distancia.
{% endhint %}

**Latencia total estimada:** 1 – 3 segundos desde el problema hasta la máquina pausada (suma de `event_delay` + `pause_delay` + tiempo de reacción del firmware).

***

## 🎯 Consejos y Advertencias

{% tabs %}
{% tab title="¿Qué sensor compro?" %}

* **< 20€:** Sensor pulsador/óptico genérico — funciona, sin florituras
* **20-40€:** BTT SFS v2.0 — la mejor opción para la mayoría
* **> 60€:** Dyze Orthus — solo para granjas o producción intensiva
* **Tienes Orbiter:** Usa el integrado, no compres nada más
  {% endtab %}

{% tab title="Error del precalentamiento" %}
**Síntomas:**

* La impresora pausa justo antes de empezar a imprimir
* Ves `filament_detected: false` sin razón durante el calentamiento

**Causa:** el sensor estaba activo mientras el nozzle calentaba.

**Solución:**

1. Añade `[delayed_gcode SFS_BOOTDISABLE]` para desactivar en boot
2. Llama a `SFS_ENABLE` solo **después** de `M109`
3. Llama a `SFS_DISABLE` en `END_PRINT`
   {% endtab %}

{% tab title="Vibración y montaje" %}
**Síntomas:** falsos positivos cada 2-3 minutos, especialmente en impresoras rápidas o con camas volantes (bedslinger).

**Soluciones en orden:**

1. `event_delay: 10` — espera más antes de reaccionar
2. Bracket muy rígido — evita el plástico flexible para montar el sensor
3. Amortigua el punto de montaje con goma o espuma fina
4. Alinea bien el filamento — no debe rozar lateralmente el sensor
   {% endtab %}

{% tab title="Óptico vs Mecánico" %}
**Mecánico (pulsador)**

* Más barato
* Aguanta mejor las vibraciones
* La palanca se puede desgastar con el tiempo

**Óptico**

* Sin desgaste mecánico
* Mejor para filamentos abrasivos (fibra de carbono, etc.)
* Puede acumular polvo — limpia el receptor cada meses
  {% endtab %}

{% tab title="Mantenimiento" %}

| Sensor          | Qué necesita            | Cada cuánto    |
| --------------- | ----------------------- | -------------- |
| BTT SFS v2.0    | Nada                    | —              |
| BTT SFS v1.0    | Lubrica rodamientos     | Cada 3-6 meses |
| Pulsador/óptico | Revisa presión mecánica | Cada 3-6 meses |
| Dyze Orthus     | Revisa cableado         | Cada año       |

**Señales de que algo va mal:** detección inconsistente de repente, más falsos positivos que antes, ruido anormal al pasar filamento.
{% endtab %}

{% tab title="El test definitivo" %}
**Antes de dormir mientras imprime:**

{% stepper %}
{% step %}

#### Imprime una pieza de prueba (\~1 hora)

{% endstep %}

{% step %}

#### A mitad de impresión, extrae el filamento manualmente

{% endstep %}

{% step %}

#### Evalúa el resultado

* ¿La máquina pausó en menos de 3 segundos? ✅ Confiable
* ¿Siguió imprimiendo sin pausar? ❌ Revisa configuración
  {% endstep %}

{% step %}

#### Repite 3 veces

Si falla una vez de tres, no lo des por bueno. Revisa timing y parámetros antes de fiarte para impresiones largas sin supervisión.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

***

## 🆘 Referencias

* **Documentación Klipper oficial:** <https://www.klipper3d.org/G-Codes#query\\_filament\\_sensor>
* **BTT SFS v2.0 GitHub:** <https://github.com/bigtreetech/smart-filament-sensor>
* **Dyze Orthus:** <https://www.dyze.ca/pages/products/orthus-filament-sensor>
* **Orbiter sensor:** <https://orbiterprojects.com/orbiter-filament-sensor/>

***

**Última actualización:** 2026-05-22 **Autor:** HAL (Technical Writer - 3Dwork.io)

{% hint style="success" %}
Con un sensor bien configurado y el test definitivo superado 3 veces, tus impresiones largas están aseguradas. Nunca más perderás una pieza por falta de filamento.
{% endhint %}