Filament Manager is an offline-first Android application for keeping track of the filament that is currently loaded in a fleet of 3D printers. It provides a fast shop-floor overview without requiring printer integrations, an account, a server, or an internet connection, while optionally synchronizing with a self-hosted FilamentManager Server.
The project is maintained by Martin Pihrt and is published at github.com/pihrt-com/filamentmanager-mobile-app.
- Printer slots can load a specific available spool from the synchronized server inventory, including search by material, color, manufacturer, location, batch, or short spool ID.
- Adding filament now explicitly offers an existing spool, a new spool read from OpenPrintTag, or manual creation.
- Manual spool creation can reuse an existing synchronized material or create a new material from entered details.
- The synchronized material and spool catalog is cached locally, and load/unload actions update availability immediately while the network synchronization finishes.
This repository contains the offline-first Android application, NFC/OpenPrintTag workflow, local SQLite data, import and export, and Android builds. The companion FilamentManager Server repository contains the optional self-hosted PHP server, responsive web administration, users and roles, shared inventory, backups, updates, and REST API. The mobile app works without the server; connecting both repositories' products adds secure bidirectional synchronization without removing offline operation.
Use this README for Android installation, phone workflows, NFC, local data, and synchronization behavior. Use the server README for hosting, installation, administrator setup, backups, updates, device access, and API documentation.
The screenshots below were captured from the application running on a real Android phone.
The home screen displays every configured printer and the filament currently loaded in it. Each printer card shows:
- the printer name, for example
MK3-1,MK4-1,XL-1, orRaise-1; - the material type, such as PLA, PETG, ASA, or a custom value;
- the user-defined color name and a visual color marker;
- the remaining filament weight in grams.
The overview is scrollable and adapts automatically to portrait, landscape, phone, and wider-screen layouts.
On first launch, the application opens the Add your first printer screen. After the printer name is entered, one or more loaded filament positions can be added. A conventional printer can have one position, while a multi-material printer such as an XL can have any number of independent positions. The data model does not impose a manufacturer-specific slot limit.
Tapping a printer on the home screen opens its loaded-filament editor. The material, color, selected color marker, and remaining weight can be changed without accidentally renaming the printer. Printer names and printer removal are managed separately in Settings.
- Offline inventory of printers and their currently loaded filament.
- Unlimited filament positions per printer.
- Material, color, visual color marker, and remaining weight for every position.
- Responsive portrait and landscape user interface.
- Natural A–Z, Z–A, or saved custom drag-and-drop printer ordering.
- Every loaded filament position is shown on the home card without collapsing extra positions.
- Light, dark, and system-default themes.
- English and Czech user interfaces.
- Android-style XML string catalogs used for all user-visible application text.
- Local SQLite storage with foreign-key integrity.
- No account, cloud service, analytics, or network connection required.
- Original Filament Manager launcher icon.
- Database backup, transfer, and restore.
- Separate printer management and loaded-filament editing flows.
- Experimental OpenPrintTag NFC-V reading and remaining-weight writing for every filament position; physical Prusa spool validation is pending.
- Optional bidirectional synchronization with a self-hosted FilamentManager Server.
- Secure Android storage for rotating server tokens; passwords are never persisted.
- Persistent offline change queue with manual synchronization and conflict resolution.
- Pull-to-refresh synchronization, a live cloud connection indicator, printer operational-state badges, and spool unloading from printer slots.
- Detailed spool metadata including manufacturer, commercial name, diameter, original and tare weights, purchase date, storage location, batch, OpenPrintTag ID, and notes.
- Searchable loading of exact available server-inventory spools and reuse of existing material definitions when creating a new spool.
- Preset colors plus a custom RGB picker with live HEX preview.
Settings contains a Connect to FilamentManager Server switch. When it is disabled, the application behaves exactly as a local-only application. When enabled, the user enters the self-hosted server address, username, and password. The password is used only for sign-in; access and rotating refresh tokens are stored through Android secure storage.
The first connection always asks how existing data should be handled:
- Upload phone data is available when the server has no printers.
- Download server data creates a local safety backup before replacing the phone inventory.
- Merge both sides previews duplicate printer names and renames conflicting phone records before upload.
Subsequent edits are saved to SQLite immediately and the application makes a non-blocking synchronization attempt after a printer is saved or deleted and after a spool is unloaded. If the server or network is unavailable, mutations remain in a persistent queue and are uploaded during the next automatic or manual synchronization. Server-side web changes are then downloaded to the phone. Version conflicts are never silently overwritten; the user chooses whether the server or phone versions should win.
Pull down on the printer overview to synchronize manually. The cloud icon shows whether server synchronization is disabled, online, offline, or still being checked. Printer data and operational states synchronize in both directions, while printer ordering remains an independent display preference: the server keeps its A–Z, Z–A, or custom web order and the phone keeps its own A–Z, Z–A, or drag-and-drop order. Administrators can inspect, revoke, and remove mobile device authorizations in the server Settings page. See the server's REST API documentation for the protocol details.
Settings contains a Backup and transfer section.
Export database creates a versioned JSON backup containing every printer and all of its filament positions. Android's standard share sheet can send the file through email, messaging, cloud storage, or another installed application.
Import database accepts a Filament Manager JSON backup and asks how it should be applied:
- Add to existing keeps the current database and adds the imported printers. If an imported printer name already exists, a numeric suffix is added so that no existing record is overwritten.
- Replace everything atomically removes the current inventory and replaces it with the contents of the backup.
The backup contains a format identifier and schema version. Invalid or unsupported files are rejected instead of being partially imported.
User-visible text is stored outside Dart source code in Android-style XML catalogs:
assets/i18n/values/strings.xml English
assets/i18n/values-cs/strings.xml Czech
The application follows the phone language by default. English or Czech can be selected explicitly in Settings. A test verifies that both catalogs contain the same set of string keys, making it safe to add further languages later.
- Minimum: Android 12 (API level 31)
- Target: Android 16 (API level 36, latest stable API at the time of release)
- Package ID:
com.pihrt.filamentmanager.mobile
The project can be opened directly in Android Studio with the Flutter and Dart plugins installed. Open the repository root using File > Open.
Printer and filament data is stored in the application's private SQLite database on the Android device. In local-only mode, Filament Manager does not upload inventory or personal data. When the user explicitly connects a FilamentManager Server, inventory changes are synchronized with that chosen server over its REST API. The password is not stored; authentication tokens use Android secure storage. Data can also leave the device when the user explicitly exports and shares a backup.
The app supports the OpenPrintTag NFC-V (ISO 15693) format. Each filament position has its own NFC controls. Reading a compatible spool imports all available supported data: material, commercial name, manufacturer, RGB color, remaining and original net weights, empty-spool weight, filament diameter, purchase date from the user auxiliary region, brand-specific instance ID, and OpenPrintTag UUID. The tag UID is linked to that position, after which the remaining weight can be written back to the same tag.
For safety, a write requires the same tag UID (and instance identifier when available), updates only the OpenPrintTag auxiliary region, and reads the tag again to verify the stored weight. Manual entry remains available for ordinary spools and phones without NFC.
The codec and write-region logic pass automated tests using the official OpenPrintTag test vector and an extended metadata vector. A physical tag has been confirmed to read the basic material, color, and weight fields. Treat NFC writing as experimental until the updated build is retested against the physical spool.
assets/i18n/ XML localization catalogs
assets/images/ Original application artwork
lib/data/ SQLite repository and versioned backup format
lib/localization/ XML localization loader
lib/models/ Printer and filament domain models
lib/sync/ Server API, secure authentication, offline queue, and synchronization
lib/theme/ Light and dark Material themes
lib/ui/ Responsive application screens
test/ Widget, localization, import, and backup tests
android/ Android package and release-signing configuration
Requirements:
- Flutter 3.47.1 or newer compatible stable release;
- Android Studio with Flutter and Dart plugins;
- Android SDK platform 36;
- Java 17 or the runtime bundled with Android Studio.
Install dependencies and run the checks:
flutter pub get
flutter analyze
flutter testRun on a connected Android device:
flutter runRelease signing is intentionally kept outside the Git repository. The Android build reads the following local file:
%USERPROFILE%/android-keys/filamentmanager-mobile-signing.properties
Expected keys:
storeFile=C:/path/to/filamentmanager-mobile-upload
storePassword=secret
keyAlias=filamentmanager-mobile-upload
keyPassword=secretNever commit the keystore or signing properties. The repository .gitignore contains defensive rules for keystores and signing configuration.
If storeFile still contains an obsolete absolute path after the signing folder is moved, the Android build safely falls back to a keystore with the same filename beside the properties file.
Build release artifacts with:
flutter build apk --release
flutter build appbundle --releaseThe APK is intended for direct testing. The AAB is intended for Google Play, where Play App Signing should manage the application's distribution key and the local keystore should be registered as its upload key.
Current application version: 1.4.2 (build 16)
Release date: 2026-09-15
The version and release date are also visible in the application's Settings screen together with the author and source-code links.
Filament Manager is distributed under the GNU General Public License v3.0. See the repository LICENSE file for the complete license text.