Skip to content
PrinterialsPrinterials home

Connect a scale

A filament scale can keep your spool weights up to date without you typing anything. This page is how to point one at your inventory.

Not for sale yet

We are making one: Printerials Scale. Once it is finished, we will sell it ready-built.

Good ones already exist and are free: SpoolmanScale, FilaMan and SpoolEase are all an ESP board, a load cell and a printed stand, for somewhere around fifteen euros in parts. What they lack is a place to send the reading that is not a server you have to host yourself.

Why weigh at all

Because nothing else measures. Both Prusa and Bambu report the estimate your slicer made before the print, so a job that fails at 40% still counts as if it finished, and purge, wipe tower and hand-feeding never appear at all. A scale is the only thing in the chain that knows what is actually left.

Expect about ±5 g from a decent bench scale. Filament itself is sold with a ±20 to 30 g manufacturing tolerance, so the reading is more precise than the spool it is weighing.

Weigh when the printer is idle. While printing, the extruder pulls on the filament with anywhere from half a newton to seven and a half, which shows up as 50 to 765 g of phantom weight. That does not average out, because the pull is all in one direction.

Get a token

In your account, under Printers, choose Connect a device and give it a name. The token is shown once and cannot be recovered, because we store only a hash of it. A scale's token can do one thing: record measurements for your account. It cannot read your inventory, your catalogue or anything else, so a leaked one discloses nothing.

Send a reading

POST https://printerials.com/api/device/weight
Authorization: Bearer pra_...
Content-Type: application/json
X-Printerials-Firmware: 0.3.1

{ "spoolId": 42, "grossGrams": 845 }

grossGrams / netGrams: The weight is what the load cell reads with the spool on it, reel included. We take the reel off ourselves: the catalogue knows what an empty reel weighs for most spools, which is the number every other filament tracker asks you to look up and type in. A device that already knows its own tare sends the net weight instead. One or the other, not both.

The shape is close to Spoolman's measure endpoint, so a device that already speaks that needs a different URL and a token rather than new firmware.

X-Printerials-Firmware, X-Printerials-Hardware: Optional, and shown to you beside the device in your account: what firmware it runs and which board it is. Nothing depends on them.

Name the spool by its tag

If your scale reads NFC, send what it read instead of a spool id, and nobody has to pick anything from a list:

{
  "tag": {
    "uid": "E0:04:01:50:2A:1B:3C:4D",
    "tech": "iso15693",
    "memory": "4UAnAQP/AS+RARdVBDNkdGFnLm9yZy9z..."
  },
  "grossGrams": 845
}
uid
The chip's UID, in hex. Every NFC tag has one and it reads without knowing the format, so an OpenPrintTag spool, a Bambu spool whose contents are encrypted, and a blank sticker you wrote yourself are all recognised by it once you have linked them. Spelling does not matter: 04:A2:24:B1 and 04a224b1 are the same chip.
tech
Which radio answered: iso15693, ntag, mifare-classic or iso14443a. It tells us where the data starts in the memory.
memory
The chip's memory from its first block, base64, at most 4096 characters. On ISO 15693 that includes the capability container at byte 0; on NTAG it starts at page 0, UID and lock bytes included. We decode it ourselves, with the same decoder the Printerials app uses, so your firmware does not need to understand any tag format.

A read with only the UID works. A PN532, which cannot read ISO 15693, still finds a spool you linked before. It never creates a spool, because a UID says nothing about what is on the reel.

A tag you have not linked yet answers 404 with Tag not linked to a spool, which is a different thing from a broken reading: link it once on your spools page and it is known from then on.

What comes back

StatusMeaning
200Recorded. The body says whether the reel came off, the net weight and the reel weight we used when it did, and the tag's format when you sent a tag.
201A spool was created from the tag, then weighed. Only with createIfUnknown, and only for a tag whose barcode the catalogue knows.
400The body is not what this page describes. The message says which field.
401Token missing, unknown or revoked.
404No such spool on your shelf, or a tag nobody has linked. For a tag, the body still carries its format, so the device can say what it is holding.
409A spool would have been created, but the chip is already on one of your printers.
422The reading cannot be true: more than the spool could weigh full, or less than an empty reel. Check the calibration.
429Too many requests. Weigh on change, not on a tight loop.
200 { "data": { "spoolId": 42, "netGrams": 565, "tareGrams": 280, "tare": "known", "format": "openprinttag" }, "meta": { ... } }
200 { "data": { "spoolId": 42, "netGrams": null, "tareGrams": null, "tare": "unknown", "format": "openprinttag" }, "meta": { ... } }
404 { "data": { "format": "openprinttag" }, "meta": { "message": "Tag not linked to a spool", ... } }

tare: Whether the reel came off the weight you sent, in every 200 and 201. Worth telling your user apart from a plain success: a reading it could not come off is recorded, but the spool's weight did not change.

known
It came off. netGrams is what is on the spool now, and its weight is set to that. tareGrams is the reel we took off, or null when you sent the net yourself.
unknown
Nothing says what this reel weighs: not the tag, and not the catalogue for the spool's size. The reading is kept as you sent it, gross, and the spool's weight is left as it was. netGrams and tareGrams are null.
disagrees
The reading is more than 20 g under the reel weight we have on file, which is more likely that figure being wrong than your scale. Kept gross and the spool left alone, as for unknown.

Tags, and which reader you need

Four standards are in use and they disagree about almost everything except that a spool should say what it is. We accept all of them, because the chip's UID is the same question whichever answer the tag gives.

StandardRadioWhere you find it
OpenPrintTagISO 15693Every new Prusament. The most complete of the four.
TigerTagNTAGThe most spools in shops: eSUN, Sunlu, Rosa3D and others.
OpenTag3D, OpenSpoolNTAGMostly self-written.
Bambu LabMIFAREReadable, but only Bambu can make a valid one.

Those are two different radio protocols, and most readers do only one. A PN532 handles NTAG and MIFARE, so everything above except OpenPrintTag, which is ISO 15693 and needs a PN5180 or similar. If you want all four, choose the PN5180: with a PN532 you exclude Prusament, which is the one brand shipping tags today.

OpenPrintTag is also physically different: a 90 mm ring label on the reel flange, read by a coil of about 75 mm. That is why it reads through a full 2 kg spool at any rotation, which is exactly what a scale wants. An NTAG sticker has a range of a couple of centimetres and needs presenting to a marked spot.

The format in our answers is always one of openprinttag, opentag3d, openspool, tigertag, bambu, unknown.

A spool we have not seen

Add createIfUnknown and a tagged spool we have never seen can set itself up:

{
  "tag": { "uid": "E0:04:01:50:2A:1B:3C:4D", "tech": "iso15693", "memory": "4UAnAQP/..." },
  "grossGrams": 845,
  "createIfUnknown": true
}

Only a barcode on the chip creates a spool. A barcode is an identity somebody assigned on purpose; a brand and a material name are two strings that happen to agree, and binding your spool to the wrong colour on that basis is the one mistake here that is expensive to undo. Without one we answer 404, so you can link it yourself.

It is off unless you ask. A scale with no screen should not quietly fill somebody's shelf with everything that was ever set on it, so send it once the owner has said yes.

Where the tag states the empty reel weight, we use that rather than our own figure: the tag describes the spool in your hand, our catalogue describes the product in general.

Most spools still have no tag, which is why we keep a database of what empty reels weigh. Blank NTAG stickers cost a few cents and a PN532 writes them as easily as it reads them.

Moonraker, OctoPrint and Home Assistant

All three can talk to a Spoolman server, and printerials.com answers as one. Your printer then records the filament each print uses as it prints, and Home Assistant can show and change what is on your shelf. There is nothing new to install.

In your account, under Printers, choose Connect a device and pick Spoolman client. You get an address with the token in it, and that address is the whole configuration. Unlike a scale's, this token can read your shelf, because that is what these programs are for.

For Moonraker, in moonraker.conf:

[spoolman]
server: https://printerials.com/api/spoolman/pra_...
sync_rate: 5

Home Assistant's Spoolman integration and the OctoPrint Spoolman plugin ask for the server's URL. Give them the same address.

A printer reports extruded length, which we turn into grams with the filament's density and diameter. That is still an estimate, so it is shown beside the weighed figure and never subtracted from it.

Adding spools stays on this site, where a colour is chosen from the catalogue, so creating one through the Spoolman API is refused. Deleting one through it deletes it, as in Spoolman; archiving it keeps its history.

Bambu Lab printers

A Bambu printer does not talk to a Spoolman server itself. The community bridges below connect to it and report to one, and since printerials.com answers as one, they can report to your shelf. We did not write them. What follows is what each one does with our address: we replayed the requests its source code sends against our API, but have not run them on a real printer.

Each takes the same address as Moonraker above, with nothing after the token.

A bridge knows a Bambu spool by the tray UUID the AMS reads from its tag, and keeps it on the spool in a Spoolman extra field. Bridges cannot add spools here, so add the spool on printerials.com first and let the bridge link the tray to it. A spool without a Bambu tag is assigned to its slot by hand, in the bridge.

What they report is treated like any printer's report: an estimate, shown beside the weighed figure.

Bambuddy

A self-hosted print manager. With Spoolman as its inventory, it links an AMS slot to one of your spools and reports what each slot used when a print ends.

In its settings, under Filament Tracking, choose Spoolman and set the Spoolman URL to your address.

Works
Linking a slot to a spool with Link to Spoolman.
Filament used, per slot, when a print ends.
Does not work
Adding spools. Turn Auto-add unknown RFID spools off, or it tries on every AMS report and is refused.
Changing a spool's filament, price or empty reel weight from its inventory. Change those here.
Sync Spoolman Weights from AMS. It writes the AMS's remaining percentage as each spool's weight, which we cannot tell apart from a weighing and would record as one. Do not use it.

bambulab-ams-spoolman-filamentstatus

A service that follows the AMS over the printer's local connection. From version 1.3 it reads what each print used from the sliced file, which it downloads from the printer, and reports it when the print ends.

In its settings, under Spoolman connection, set Endpoint to your address, or set it in the compose file:

SPOOLMAN_ENDPOINT=https://printerials.com/api/spoolman/pra_...
Works
Linking a Bambu spool to one of yours by its tag, or assigning a slot by hand in its web UI.
Filament used, when a print ends, in G-code tracking.
The slot as the spool's location, with that setting on.
Archive empty spools. An archived spool is finished here: off your shelf, with its weighings and prints kept.
Does not work
Version 1.2 and earlier, and legacy mode in later versions. They write the AMS's remaining percentage as the spool's weight after every change, which is an estimate presented as a weighing, and we refuse it.
Creating a spool or a filament from its dialogs.

OpenSpoolMan

A web app for NFC tags and the AMS. It assigns spools to trays and spends what the slicer said a print would use, or, with layer tracking, what each layer used.

In its environment, set the Spoolman address to yours, with no slash at the end:

SPOOLMAN_BASE_URL=https://printerials.com/api/spoolman/pra_...

Its instructions have you add two extra fields in Spoolman's web interface, which we do not have. Add them once with these two requests instead:

curl -X POST https://printerials.com/api/spoolman/pra_.../api/v1/field/spool/tag \
  -H "Content-Type: application/json" -d '{"name": "tag", "field_type": "text"}'
curl -X POST https://printerials.com/api/spoolman/pra_.../api/v1/field/spool/active_tray \
  -H "Content-Type: application/json" -d '{"name": "active_tray", "field_type": "text"}'
Works
Assigning a Bambu tag to a spool, and a spool to a tray.
Spending filament, by weight and by length.
Does not work
Extra fields on filaments. Filaments here are the catalogue's, so anything it reads from them is empty.

SpoolmanSync

Connects Home Assistant's Bambu Lab integration to Spoolman. You assign spools to trays in its web app, and a Home Assistant automation reports what each print used.

In its settings, set the Spoolman URL to your address.

Works
Assigning a spool to a tray, which also sets its location, and storing the tray UUID.
Filament used, as Home Assistant reports it.

What it changes

A reading the reel came off sets the spool's weight and the date it was weighed. That is the only thing allowed to change that number: anything read from a printer or a sliced file is an estimate and is shown beside it instead. So a reading also clears whatever the estimate had drifted, and the shelf stops asking you to weigh.

Trouble

Write to [email protected]. If you are building a scale and want something from this endpoint that is not here, say so. It is easier to add than to guess.