s1d3sw1ped
b67b37dc59
Drop zip/JSON from the root API. dump remains an adapter for the Android app format; inventory and an AMS wand both call Parse(uid, image).
294 lines
8.7 KiB
Markdown
294 lines
8.7 KiB
Markdown
# bambu-nfc library
|
||
|
||
Date: 2026-08-23
|
||
|
||
Go module that parses Bambu Lab filament NFC dumps (from the phone dump app) and derives MIFARE Key-A from a chip UID. The inventory website will import this module. Other filament brands are out of scope for v1, but dump I/O and MIFARE 1K layout live in their own packages so they can move to a common module later.
|
||
|
||
Repo: `ssh://gitea@git.s1d3sw1ped.com:2222/s1d3sw1ped/bambu-nfc.git`
|
||
Module: `git.s1d3sw1ped.com/s1d3sw1ped/bambu-nfc`
|
||
Go: 1.25
|
||
|
||
## Goal
|
||
|
||
Given a `filanfc-dump/v1` zip, JSON, or 1024-byte image, return typed Bambu tags and merge two stickers on the same spool. Given a chip UID, return the 16 Key-A values used to dump a Bambu MIFARE Classic 1K tag.
|
||
|
||
Success: `go test -race ./...` passes against the six real dumps in `testdata/`; `Merge` yields three spools (two PETG Translucent, one PETG Basic Black).
|
||
|
||
## Non-goals
|
||
|
||
- HTTP, inventory, remaining-weight tracking
|
||
- AMS SPI / PN532 / wand hardware
|
||
- Creality, OpenTag, Elegoo, NDEF
|
||
- A `filamentnfc` common module (only package seams)
|
||
- CLI
|
||
- Writing or cloning tags
|
||
- Brand auto-detect across vendors
|
||
|
||
## Packages
|
||
|
||
```
|
||
bambunfc/ // package bambunfc — Bambu parse, KeysA, Merge
|
||
dump/ // filanfc-dump/v1 JSON + zip; no filament fields
|
||
mifare/ // 1K constants and sector/block helpers; no brand map
|
||
```
|
||
|
||
Callers of the website import `git.s1d3sw1ped.com/s1d3sw1ped/bambu-nfc` only. `dump` and `mifare` are public so they can be copied into a common module without rewriting their APIs.
|
||
|
||
Bambu-only: HKDF salt/info, block map, `tray_uid`, `Brand: "Bambu Lab"`.
|
||
|
||
## dump
|
||
|
||
Brand-blind. A dump is one sticker: chip UID + 1K image.
|
||
|
||
JSON matches the Android app (`filanfc-dump/v1`):
|
||
|
||
```json
|
||
{
|
||
"format": "filanfc-dump/v1",
|
||
"scanned_at": "2026-08-23T19:52:02.388908Z",
|
||
"chip_uid": "e27be276",
|
||
"sak": "08",
|
||
"atqa": "0004",
|
||
"tech": ["android.nfc.tech.MifareClassic"],
|
||
"sectors_ok": [0, 1, …, 15],
|
||
"sectors_fail": [],
|
||
"dump_hex": "<2048 hex chars>",
|
||
"dump_b64": "<base64>"
|
||
}
|
||
```
|
||
|
||
```go
|
||
package dump
|
||
|
||
const FormatV1 = "filanfc-dump/v1"
|
||
|
||
type Dump struct {
|
||
Format string
|
||
ScannedAt time.Time
|
||
ChipUID string // lowercase hex, no separators
|
||
SAK string
|
||
ATQA string
|
||
Tech []string
|
||
SectorsOK []int
|
||
SectorsFail []int
|
||
Image []byte // always 1024 when valid
|
||
}
|
||
|
||
func ParseJSON(r io.Reader) (Dump, error)
|
||
func ParseZip(r io.Reader) ([]Dump, error)
|
||
```
|
||
|
||
- `dump_hex` and `dump_b64` must decode to the same 1024 bytes; if both present and they disagree → `ErrInvalidDump`.
|
||
- Zip entries `{chip_uid}.json` are parsed; `.bin` files are ignored if JSON is present (JSON already carries the image). A `.bin` without JSON is not required in v1.
|
||
- Chip UID in JSON is normalized to lowercase hex.
|
||
|
||
## mifare
|
||
|
||
```go
|
||
package mifare
|
||
|
||
const (
|
||
Sectors = 16
|
||
Blocks = 64
|
||
BlockSize = 16
|
||
SectorSize = 64
|
||
Size1K = 1024
|
||
)
|
||
|
||
func SectorOf(block int) int
|
||
func BlockRange(sector int) (first, last int) // last exclusive
|
||
func SectorBytes(image []byte, sector int) ([]byte, error)
|
||
```
|
||
|
||
No keys, no brand parse.
|
||
|
||
## bambunfc
|
||
|
||
```go
|
||
package bambunfc
|
||
|
||
const BrandBambuLab = "Bambu Lab"
|
||
|
||
type Color struct {
|
||
R, G, B, A uint8
|
||
}
|
||
|
||
func (c Color) Hex() string // "#RRGGBBAA" uppercase hex
|
||
|
||
type Tag struct {
|
||
Brand string
|
||
ChipUID string
|
||
TrayUID string // 32 lowercase hex chars
|
||
Type string // detailed type, e.g. "PETG Translucent"
|
||
Material string // block 2, e.g. "PETG"
|
||
MaterialID string // e.g. "GFG01"
|
||
VariantID string // e.g. "G01-B0"
|
||
Color Color
|
||
WeightG int
|
||
DiameterMM float32
|
||
LengthM int
|
||
MinHotendC int
|
||
MaxHotendC int
|
||
BedC int
|
||
DryC int
|
||
DryHours int
|
||
Produced string // block 12 ASCII, may be empty
|
||
SpoolWidthRaw uint16 // block 10 offset 4; encoding not trusted
|
||
}
|
||
|
||
type Spool struct {
|
||
Brand string
|
||
TrayUID string
|
||
ChipUIDs []string // unique, sorted
|
||
Type string
|
||
Material string
|
||
MaterialID string
|
||
VariantID string
|
||
Color Color
|
||
WeightG int
|
||
DiameterMM float32
|
||
LengthM int
|
||
MinHotendC int
|
||
MaxHotendC int
|
||
BedC int
|
||
DryC int
|
||
DryHours int
|
||
Produced string
|
||
SpoolWidthRaw uint16
|
||
}
|
||
|
||
func KeysA(uid []byte) ([16][6]byte, error)
|
||
func Parse(uid, image []byte) (Tag, error) // raw ISO UID + 1024-byte 1K image
|
||
func Merge(tags []Tag) ([]Spool, error)
|
||
|
||
The website and any AMS wand feed `Parse` with raw NFC. The `dump` package is only an adapter for the Android zip/JSON format; it is not the library’s input surface.
|
||
```
|
||
|
||
### KeysA
|
||
|
||
RFC 5869 HKDF-SHA256:
|
||
|
||
- IKM = raw UID bytes (4 or 7; length from the caller)
|
||
- salt = `9a759cf2c4f7caff222cb9769b41bc96`
|
||
- info = `RFID-A\0`
|
||
- output 96 bytes → 16 keys of 6 bytes, sector 0 first
|
||
|
||
Empty UID → `ErrUID`. Matches `python3 deriveKeys.py 11223344` / the Android app. Golden Key-A hex (uppercase) for UID `11223344`:
|
||
|
||
```
|
||
0729F3B2D37A
|
||
2027210D85E7
|
||
D77B2E7C92BC
|
||
29126A53A2EE
|
||
E49850F62778
|
||
9A9128B882BD
|
||
45F69B980786
|
||
90DD67095D6B
|
||
EB994746CD69
|
||
B4AEB23473E3
|
||
445E850D699C
|
||
5C9BD5BD9FD7
|
||
1062AFE9F5F5
|
||
81EE5259CF6B
|
||
0920CEEEE2BC
|
||
BAF630CCBFD3
|
||
```
|
||
|
||
### Parse
|
||
|
||
MIFARE Classic 1K Bambu map (little-endian). Input is raw NFC only: `uid` is the ISO 14443 chip ID; `image` is 1024 bytes. Empty UID → `ErrUID`. Wrong image length → `ErrImageSize`. All-zero tray UID (block 9) → `ErrIncomplete`. No dump `sectors_fail` list — missing data is whatever is in the image (typically zeros).
|
||
|
||
| Block | Field |
|
||
|---|---|
|
||
| 2 | Material, NUL-trimmed ASCII |
|
||
| 4 | Type (detailed), NUL-trimmed ASCII |
|
||
| 1 | VariantID 8 + MaterialID 8, NUL-trimmed |
|
||
| 5 | RGBA 4; weight `uint16` @4; diameter `float32` @8 |
|
||
| 6 | dry °C, dry hours, bed type (ignored), bed °C, max hotend, min hotend — all `uint16` LE |
|
||
| 9 | TrayUID 16 raw bytes → hex |
|
||
| 10 | `uint16` @4 → `SpoolWidthRaw` (optional; zero if sector 2 failed) |
|
||
| 12 | Produced ASCII (optional) |
|
||
| 14 | length meters `uint16` @4 (optional) |
|
||
|
||
`uid` is encoded to lowercase hex on `Tag.ChipUID`. Block 0 UID is not compared (cloned magic tags can rewrite it).
|
||
|
||
Not Bambu: if Type and Material are both empty after NUL-trim → `ErrNotBambu`.
|
||
|
||
Brand is always `BrandBambuLab` on success.
|
||
|
||
### Merge
|
||
|
||
Group by `Brand + TrayUID`. Empty `TrayUID` → `ErrIncomplete` (do not invent ids). Different brands never share a group.
|
||
|
||
Within a group, `ChipUIDs` is the sorted unique set. Filament fields come from the first tag; if two tags in the group disagree on Type, Material, Color, or WeightG → `ErrConflict`.
|
||
|
||
Output spool order: sorted by TrayUID.
|
||
|
||
## Errors
|
||
|
||
```go
|
||
var (
|
||
ErrImageSize = errors.New("image size")
|
||
ErrIncomplete = errors.New("incomplete tag")
|
||
ErrNotBambu = errors.New("not bambu")
|
||
ErrUID = errors.New("uid")
|
||
ErrConflict = errors.New("tag conflict")
|
||
)
|
||
|
||
Dump JSON/zip errors live in package `dump` (`dump.ErrInvalidDump`, `dump.ErrImageSize`).
|
||
```
|
||
|
||
Wrap with `%w`. Error strings lowercase, no punctuation.
|
||
|
||
`mifare.SectorBytes` on short image → `ErrImageSize` from bambunfc via wrap, or dump parse fails first.
|
||
|
||
## Tests
|
||
|
||
Fixtures: copy from dump-app `docs/dumps/2026-08-23-filanfc-last-scans/` (and the zip `docs/dumps/2026-08-23-filanfc-last-scans.zip`) into this repo as `testdata/dumps/` (json+bin) and `testdata/dumps.zip`. Source machine path: `/fast/projects/scratch/New Folder (2)/docs/dumps/`.
|
||
|
||
| Test | Expect |
|
||
|---|---|
|
||
| KeysA(`11223344`) | 16 keys matching Android/Python golden list |
|
||
| Parse each testdata `.bin` with UID from the filename | 6 tags, all `BrandBambuLab` |
|
||
| Merge those tags | 3 spools; Translucent tray `2fb8e0e972084e74bf737393b28e7b12` has chips `52d60177`, `e27be276`; second Translucent `aa42f322172c48e99c0ece895346ea9f`; Basic `3cb568b7af4f41819412fe60afc5c446` |
|
||
| Colors | `#61B0FF80` and `#000000FF` |
|
||
| Diameter | `1.75` |
|
||
| Types | `PETG Translucent` ×4 tags, `PETG Basic` ×2 |
|
||
| 1023-byte image | `ErrImageSize` |
|
||
| image with block 9 all zeros | `ErrIncomplete` |
|
||
| empty UID KeysA | `ErrUID` |
|
||
| Merge two tags same tray different Type | `ErrConflict` |
|
||
|
||
Table-driven tests, `t.Parallel()` on subtests, `go test -race ./...`.
|
||
|
||
## Layout on disk
|
||
|
||
```
|
||
go.mod
|
||
dump/dump.go
|
||
dump/dump_test.go
|
||
mifare/mifare.go
|
||
mifare/mifare_test.go
|
||
kdf.go
|
||
parse.go
|
||
merge.go
|
||
color.go
|
||
errors.go
|
||
kdf_test.go
|
||
parse_test.go
|
||
merge_test.go
|
||
testdata/dumps/
|
||
README.md
|
||
```
|
||
|
||
No `pkg/`, `src/`, or `internal/` for these three packages (dump/mifare must stay importable).
|
||
|
||
## Resolved decisions
|
||
|
||
- Brand field always `"Bambu Lab"` on successful parse; no multi-brand detect in v1
|
||
- Common module deferred; dump + mifare are the extraction boundary
|
||
- Diameter is float32 at block 5 offset 8 (confirmed by real dumps)
|
||
- Tray UID is 16 binary bytes, hex-encoded
|
||
- Spool width left as raw uint16
|
||
- No CLI in v1
|