{"id":46540406,"url":"https://github.com/jdempsey77/filament-iq","last_synced_at":"2026-04-01T22:28:24.430Z","repository":{"id":342703860,"uuid":"1174812658","full_name":"jdempsey77/filament-iq","owner":"jdempsey77","description":"Filament lifecycle tracking for Bambu Lab printers via Home Assistant, AppDaemon and Spoolman","archived":false,"fork":false,"pushed_at":"2026-03-26T21:29:35.000Z","size":1236,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T02:34:21.180Z","etag":null,"topics":["appdaemon","bambu-lab","hacs","home-assistant","spoolman"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdempsey77.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-06T21:44:42.000Z","updated_at":"2026-03-26T21:29:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jdempsey77/filament-iq","commit_stats":null,"previous_names":["jdempsey77/filament-iq"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/jdempsey77/filament-iq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdempsey77%2Ffilament-iq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdempsey77%2Ffilament-iq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdempsey77%2Ffilament-iq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdempsey77%2Ffilament-iq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdempsey77","download_url":"https://codeload.github.com/jdempsey77/filament-iq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdempsey77%2Ffilament-iq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appdaemon","bambu-lab","hacs","home-assistant","spoolman"],"created_at":"2026-03-07T01:03:46.930Z","updated_at":"2026-04-01T22:28:24.422Z","avatar_url":"https://github.com/jdempsey77.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/filament-iq-banner.svg\" alt=\"Filament IQ\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n**Deterministic filament identity and lifecycle management for Bambu Lab printers with Home Assistant, AppDaemon, and Spoolman.**\n\n![Spool inventory with color dots, progress bars, and location badges](docs/screenshots/spools-list.png)\n\n## What it does\n\nFilament IQ connects your Bambu Lab AMS to [Spoolman](https://github.com/Donkie/Spoolman) so every spool is tracked automatically. RFID spools are identified by tag. Non-RFID spools are matched by material and color. Filament consumption is recorded after every print. A custom Lovelace card gives you full spool, filament, and vendor management without leaving Home Assistant.\n\n## Screenshots\n\n| | |\n|---|---|\n| ![Spool inventory](docs/screenshots/spools-list.png) **Spool inventory** — color dots, progress bars, material badges, location tags, search and filter toolbar | ![Add spool](docs/screenshots/spools-add.png) **Add a spool** — inline form with location dropdown |\n| ![SpoolmanDB import](docs/screenshots/spoolmandb-import.png) **SpoolmanDB import** — fuzzy search across 6,957+ filaments, auto-fills all fields | ![Edit filament](docs/screenshots/filaments-edit.png) **Edit filament** — inline editing with color preview |\n| ![3D Printer dashboard](docs/screenshots/printer-dashboard.png) **Printer dashboard** — live print status, camera feed, AMS slot monitoring with offline detection | |\n\n## Features\n\n- **Automatic filament consumption tracking** after every print via 3MF slicer data or RFID weight deltas\n- **RFID spool auto-identification** — Bambu RFID tags matched to Spoolman records\n- **Non-RFID matching** by material + color signature\n- **Filament IQ Manager card** — full Create/Read/Update/Delete for spools, filaments, and vendors\n- **SpoolmanDB import** — fuzzy search 6,957+ filaments from the community database, one-click import\n- **Location tracking** — AMS slots, Shelf, New, or custom locations with colored badges\n- **Smart filtering** — filter by vendor, material, location, or free-text search\n- **Archive empty spools** in one tap\n- **AMS offline detection** — slots show \"AMS Offline\" when a unit is disconnected\n- **Works via Nabu Casa** — all data flows through HA's authenticated WebSocket, no ports to expose\n- **AMS 2 Pro + AMS HT support** — any combination of 4-slot and 1-slot units\n\n## Requirements\n\n- Home Assistant 2024.1+\n- [ha-bambulab](https://github.com/greghesp/ha-bambulab) integration (Bambu Lab printer integration)\n- [Spoolman](https://github.com/Donkie/Spoolman) v0.19+ (filament database)\n- [AppDaemon](https://github.com/AppDaemon/appdaemon) addon\n- [HACS](https://hacs.xyz/) (Home Assistant Community Store)\n\n**Required HACS frontend cards** (for the 3D Printer dashboard view):\n\n- [mushroom](https://github.com/piitaya/lovelace-mushroom)\n- [button-card](https://github.com/custom-cards/button-card)\n- [card-mod](https://github.com/thomasloven/lovelace-card-mod)\n- [layout-card](https://github.com/thomasloven/lovelace-layout-card)\n- [browser-mod](https://github.com/thomasloven/hass-browser_mod)\n\n\u003e The Filament IQ Manager card itself has **no HACS dependencies**. It is a standalone Preact custom element.\n\n## Installation\n\n### 1. Clone the repo\n\n```bash\ngit clone https://github.com/jdempsey77/filament-iq.git\ncd filament-iq\n```\n\n### 2. Install AppDaemon apps\n\nCopy the `appdaemon/apps/filament_iq/` directory to your AppDaemon apps directory:\n\n```bash\nscp -r appdaemon/apps/filament_iq/ \\\n  root@homeassistant.local:/addon_configs/a0d7b954_appdaemon/apps/\n```\n\nAdd entries from `appdaemon/apps/apps.yaml` to your own `apps.yaml`, updating:\n- `spoolman_url` to your Spoolman instance URL\n- `printer_serial` to your Bambu printer serial (uppercase)\n- `printer_model` to your printer model (e.g. `p1s`)\n\n### 3. Install the proxy component\n\nCopy `custom_components/filament_iq_proxy/` to your HA custom components:\n\n```bash\nscp -r custom_components/filament_iq_proxy/ \\\n  root@homeassistant.local:/config/custom_components/\n```\n\nAdd to your `configuration.yaml`:\n\n```yaml\nfilament_iq_proxy:\n  spoolman_url: \"http://localhost:7912\"\n```\n\nRestart Home Assistant to load the component.\n\n### 4. Register the Lovelace card\n\nCopy the built card JS to your HA `www` directory:\n\n```bash\nscp packages/lovelace-card/dist/filament-iq-manager.js \\\n  root@homeassistant.local:/config/www/\n```\n\nIn Home Assistant, go to **Settings \u003e Dashboards \u003e Resources \u003e Add Resource**:\n- URL: `/local/filament-iq-manager.js`\n- Type: JavaScript Module\n\n### 5. Set up the dashboard\n\nRun the interactive setup script:\n\n```bash\n./scripts/setup-dashboard.sh\n```\n\nIt will ask for your printer serial and AMS configuration (type, index, name per unit). It generates a `filament-iq-dashboard.yaml` file ready to use.\n\nCopy the generated file to your HA config directory and add to `configuration.yaml`:\n\n```yaml\nlovelace:\n  dashboards:\n    filament-iq:\n      mode: yaml\n      title: Filament IQ\n      icon: mdi:brain\n      filename: filament-iq-dashboard.yaml\n```\n\nRestart Home Assistant.\n\n## AMS Configuration\n\nThe setup script supports any combination of AMS units. Common configurations:\n\n| Unit | Slots | HA sensor prefix | ams_index |\n|------|-------|------------------|-----------|\n| AMS Pro/Lite (first) | 1-4 | `ams_0_` | 0 |\n| AMS Pro/Lite (second) | 5-8 | `ams_1_` | 1 |\n| AMS HT (first) | varies | `ams_128_` | 128 |\n| AMS HT (second) | varies | `ams_129_` | 129 |\n\nFind your AMS indices in HA: **Developer Tools \u003e States** and search for `ams_`. The number in `sensor.p1s_XXXXX_ams_NUMBER_humidity` is your AMS index.\n\n## Using the card\n\n### Spools tab\nFull spool inventory with color dots, progress bars, material badges, and location tags. Click any row to expand the inline edit panel. Use the toolbar to search or filter by vendor, material, or location.\n\n### Filaments tab\nView and edit all filament definitions. Click **Import** to open SpoolmanDB fuzzy search — type a query like `bambu red pla` or `overture petg gray` and pick a result. All fields (density, diameter, weight, temperatures) are pre-filled. The vendor is auto-matched or created on import.\n\n### Vendors tab\nAdd and edit filament vendors. Vendor count shows how many filaments reference each vendor.\n\n## Troubleshooting\n\n**Card shows \"Loading...\" permanently**\nThe `filament_iq_proxy` component is not loaded. Verify it appears in HA: Developer Tools \u003e Services \u003e search for `filament_iq_proxy.api_call`. If missing, check that the component files are in `/config/custom_components/filament_iq_proxy/` and that `filament_iq_proxy:` is in your `configuration.yaml`. Restart HA after installing.\n\n**\"Too Generic to auto-match\" on a slot**\nA non-RFID spool matches multiple entries in Spoolman with the same material and color. Tap the slot card to manually select the correct spool. This is expected behavior.\n\n**SpoolmanDB import shows no results**\nThe database loads on first open (6,957 entries). Wait for \"Loading database...\" to finish, then search. Use specific multi-word queries: `bambu red pla` works better than just `red`.\n\n**\"Configuration error\" on custom cards**\nHACS cards are missing or resource URLs are incorrect. Verify all required HACS cards are installed. Check **Settings \u003e Dashboards \u003e Resources** for correct paths.\n\n**AMS slots show \"AMS Offline\"**\nThe AMS unit's humidity sensor is unavailable. Check the physical connection between the AMS and printer. The slot cards will recover automatically when the AMS reconnects.\n\n## Architecture\n\n```\nBambu Lab Printer (MQTT)\n       |\n       v\nha-bambulab integration (HA entities)\n       |\n       v\nAppDaemon / filament_iq apps\n       |  urllib (HTTP)\n       v\nSpoolman (filament database)\n       |  REST API\n       v\nfilament_iq_proxy (HA custom component)\n       |  HA WebSocket + events\n       v\nfilament-iq-manager (Preact Lovelace card)\n```\n\n**Data flow:**\n1. Bambu printer publishes state via MQTT\n2. ha-bambulab creates HA entities (tray status, print progress, etc.)\n3. AppDaemon apps monitor print lifecycle, match spools, record consumption\n4. Spoolman stores all filament/spool data via REST API\n5. The custom component proxies browser requests to Spoolman through HA's WebSocket\n6. The Preact card renders the UI and calls the proxy for all CRUD operations\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdempsey77%2Ffilament-iq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdempsey77%2Ffilament-iq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdempsey77%2Ffilament-iq/lists"}