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.

We do not sell one

We do publish one you can build: see Printerials Scale. It is open source and made of commodity parts, and you owe us nothing for it.

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. Building a fourth one would help nobody. 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. That sounds rough until you notice that 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 is not noise that averages 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. It can do exactly 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

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

If your scale reads NFC, name the spool by the tag on it instead and nobody has to pick anything from a list:

{ "tagUid": "04:A2:24:B1", "grossGrams": 845 }

That is the chip’s UID, not anything from the tag’s contents. 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 all work the same. Spelling does not matter — 04:A2:24:B1 and 04a224b1 are the same chip.

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.

grossGrams 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. If your device already knows its own tare, send netGrams instead. Send one or the other, not both.

The shape is deliberately close to Spoolman’s PUT /spool/{id}/measure, so a device that already speaks that needs a different URL and a token rather than new firmware.

What comes back

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.

Those are two different radio protocols, and most readers do only one. A PN532 handles NTAG, MIFARE and so everything above except OpenPrintTag, which is ISO 15693 and needs a PN5180 or similar. If you are choosing a reader and want all four, choose the PN5180 — with a PN532 you permanently 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.

Tell us what the tag said

Send the decoded fields alongside the UID and a spool we have never seen can set itself up:

{
  "tagUid": "04:A2:24:B1",
  "grossGrams": 845,
  "createIfUnknown": true,
  "tag": {
    "format": "openprinttag",
    "gtin": "8595184010102",
    "nominalNettoFullWeight": 1000,
    "emptyContainerWeight": 201
  }
}

Field names follow OpenPrintTag, whose vocabulary the others map onto. format may be openprinttag, tigertag, opentag3d, openspool, bambu or raw.

Only the GTIN 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 a GTIN we match on nothing and answer 404, so you can link it yourself.

createIfUnknown 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 — 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; blank OpenPrintTag rings are about 37 cents at a thousand.

What it changes

A reading 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.