Spoolman Entity Integration#

Each Spoolman spool is exposed in Home Assistant as a device that owns a collection of sensor and select entities. Two platform files drive this: sensor.py creates read-only measurement and metadata sensors, and select.py creates a writable location select. All entity state comes from a shared SpoolManCoordinator 1 that polls the Spoolman API for spools, filaments, extra fields, and locations each refresh cycle.

The dynamic listener pattern means new spools appear automatically in Home Assistant without a reload — as does any new location added in Spoolman. See Dynamic Entity Registration below for details.

Sensor Entities Per Spool#

The _build_entities_for_spool() helper assembles the full sensor stack for a single spool. All sensor classes live in the sensors/ directory and are exported via sensors/__init__.py.

Always created (regardless of data):

Conditionally created (only when the corresponding field is present on the spool or filament object): SpoolRegistered, SpoolFirstUsed, SpoolLastUsed, SpoolPrice, SpoolWeight, SpoolLotNumber, SpoolComment, FilamentDensity, FilamentDiameter, FilamentExtruderTemp, FilamentBedTemp, FilamentArticleNumber, FilamentName, FilamentMaterial, FilamentColorHex, VendorName, FilamentWeight 2.

Extra fields: One SpoolExtraField sensor is created per key in spool["extra"], tracked by (spool_id, field_key) tuple to avoid duplicates 3.

Entity pictures (100×100 px PNG) are generated for Spool and FilamentColorHex entities via _generate_entity_picture(), which supports single-color, coaxial, and longitudinal multi-color filaments.

SpoolLocation: Sensor vs. Select#

Location is represented by two distinct entities on the same spool device:

• SpoolLocation (sensor) — A read-only SensorEntity defined in sensors/spool_location.py. Its state property returns spool.get("location", "Unknown") 4. This is useful for automations that react to where a spool is stored.

• SpoolLocationSelect (select) — A writable SelectEntity defined in select.py. Selecting a new option calls api.patch_spool(spool_id, {"location": option}) and immediately triggers a coordinator refresh. The icon for both is mdi:map-marker.

Both share the same unique_id pattern — spoolman_{entry_id}_spool_{id}_location — using sensor. and select. prefixes respectively 5 6.

Location Options: Canonical List vs. Derived Fallback#

The dropdown options for SpoolLocationSelect are resolved by _resolve_locations(coordinator_data, spools):

1. Primary: uses coordinator.data["locations"], populated each poll by GET /api/v1/location 1. This includes locations that are configured in Spoolman but have no spool assigned (e.g., empty AMS trays) — fixing the issue tracked in PR #839 7.
2. Fallback: if the /location endpoint is absent (older Spoolman servers), derives the list from the location field of all known spools 8.

SpoolLocationSelect._handle_coordinator_update() re-invokes _resolve_locations() on every coordinator update, so newly added locations appear in the dropdown without requiring a reload 9.

Dynamic Entity Registration#

Before PR #839, entities were only created for spools present at async_setup_entry time — new spools required a full integration reload. Both platforms now register a coordinator listener to detect and register entities on the fly.

In sensor.py 10:

• The add_dynamic_entities() callback fires on each coordinator update.
• It computes the diff between coordinator.data["spools"] and the existing_spool_ids set.
• New spools are passed to _async_add_new_spools(), launched via hass.async_create_task() so the synchronous callback can trigger the async image-generation path.
• New extra-field sensors on already-known spools are also detected and registered in the same callback.

In select.py 11:

• add_dynamic_selects() mirrors the same pattern, creating a SpoolLocationSelect for each new spool ID.

Both listeners are registered once via coordinator.async_add_listener(...) at the end of async_setup_entry 12 13.

Key Files#