A free, open identification standard for mushroom cultivation bags.
Designed by Grove5 for the Cultivar smart grow chamber — given freely to the mycology community.
BagTag encodes everything a machine needs to know about a bag: substrate, species, and size. No app. No typing. Just scan and grow.
Why BagTag Exists
Hobbyist mycologists face a familiar frustration: every bag needs labeling, but labels get wet, smudge, or fall off. QR codes work but require phones and apps. Barcodes are fragile. Handwriting is error-prone.
BagTag solves this with industrial-grade machine vision made accessible:
- AprilTag 41h12 markers — readable in milliseconds, even at angles, through condensation, with mycelium creeping over the edges
- Packed enumeration — 1,970 valid bag configurations encoded into 2,115 available tag IDs
- Graceful fallbacks — damaged tag? Scan the QR. Custom substrate? Manual entry. Nothing is a dead end.
The Philosophy: Maximum Obvious, Graceful Fallback
BagTag attempts to load every obvious combination:
- 104 mushroom species across 32 substrate formulations
- All common commercial varieties (Oysters, Shiitake, Lion's Mane, Reishi...)
- All-in-One bags (grain + bulk), spawn-only, and bulk-only variants
- Commercial strains and experimental lines
But BagTag doesn't pretend to know everything:
- Custom substrates (slots 14, 23, 31) accept any species code
- Species 127 triggers manual entry — your unidentified wild isolate works fine
- Reserved tag IDs (1,970–2,114) leave room for future expansion
How It Works
Dual-Code Redundancy
| AprilTag (Front) | QR Code (Back) | |
|---|---|---|
| Readable by | Cultivar camera | Any phone |
| Speed | < 100ms | 1–3 seconds |
| Data | 12-bit grow profile | Full GMP traceability record |
| Robustness | Works damaged, occluded, at angle | Works when tag is destroyed |
| Human input | Zero | Optional manual override |
Neither code is a single point of failure. The QR is a strict superset — if the AprilTag fails, the human scans the QR and the Cultivar receives identical grow information.
The Encoding
Logical layout: 1 bit + 5 bits + 7 bits = 13 bits (theoretical)
Size Substrate Species
Physical reality: Packed enumeration → 0–1,969 (valid bags)
→ 1,970–2,114 (reserved)
From a tag ID, the Cultivar immediately knows:
- Temperature targets for colonization and fruiting
- Humidity profile and CO₂/FAE schedule
- Colonization timeline estimates
- Biological efficiency baselines
- Fruiting trigger conditions
Put the bag in. The machine does the rest.
Quick Start
Decode a Tag
cd tools
python decode.py 0
# Tag ID: 0
# Size: small
# Substrate: [00] Masters Mix + Millet
# Species: [00] Blue Oyster
# (Pleurotus ostreatus)
Explore All Tags
python decode.py --stats # Namespace summary
python decode.py --ranges # Tag ID ranges per substrate
python decode.py --tables # Full species tables
Generate Tables
python generate_tables.py
# Generates:
# - ../tables/substrates.md (all 32 substrates)
# - ../tables/species/*.md (32 per-substrate species tables)
# - ../BAGTAG_MASTER_TABLE.md (complete 0–1,969 reference)
Repository Structure
BagTag/
├── README.md ← This file
├── SPEC.md ← Full technical specification
├── BAGTAG_MASTER_TABLE.md ← Complete tag ID reference (auto-generated)
├── LICENSE ← MIT + AprilTag BSD attribution
│
├── tables/
│ ├── substrates.md ← 32 substrate slots (auto-generated)
│ └── species/ ← Per-substrate species tables
│ ├── aio-0-flagship-mm.md
│ ├── aio-1-speed-mm.md
│ └── ... (32 total)
│
└── tools/
├── bagtag_data.py ← 🎯 Single source of truth
├── decode.py ← Reference decoder + CLI
├── generate_tables.py ← Table generator
└── generate_tags.py ← Tag image generator (placeholder)
The entire encoding lives in tools/bagtag_data.py. Change that file, run generate_tables.py, and all documentation updates automatically.
Technical Highlights
AprilTag 41h12
- 2,115 valid IDs, Hamming distance 12
- Tolerates up to 5 misread bits
- Sub-centimeter 6DOF pose estimation
- Industrial machine vision standard
Packed Enumeration
Instead of wasting 75% of tag IDs on invalid (substrate, species) combinations, BagTag enumerates only valid bags:
| Approach | Valid IDs | Waste |
|---|---|---|
| Naive bit-fields (13 bits) | ~1,970 | ~75% |
| BagTag packed enum | 1,970 | 0% |
Each tag ID maps to exactly one valid (size, substrate, species) triple. No ambiguous decodes. No partial reads.
Species 127
Every substrate table reserves code 127 as "Other/prompt":
- New wild isolates
- Proprietary commercial strains
- User experiments
The Cultivar falls back to QR scan or manual entry. Nothing breaks.
Documentation
| Document | Purpose |
|---|---|
| SPEC.md | Complete encoding specification, bit layouts, decision trees |
| BAGTAG_MASTER_TABLE.md | Every valid tag ID 0–1,969 decoded |
| tables/substrates.md | All 32 substrate slots with descriptions |
| tables/species/ | 32 per-substrate species lookup tables |
For Makers & Builders
BagTag is hardware-agnostic. The reference decoder is pure Python. Port it to:
- Arduino + camera module
- Raspberry Pi + OpenCV
- Android/iOS apps
- Industrial PLCs
The encoding is documented, the tables are generated, the data is free.
License
MIT License — see LICENSE
Third-party: AprilTag (BSD 2-Clause), University of Michigan
You can:
- Use BagTag in commercial products
- Modify and redistribute
- Build proprietary Cultivar clones
- Print your own BagTags for home use
We ask:
- Keep the attribution
- Consider contributing improvements back
- Spread good mycology practices
Part of Grove5
BagTag was created for Cultivar — Grove5's smart dual-chamber mushroom cultivation appliance — and released freely because standards work best when they're actually standardized.
- Cultivar — Smart grow chamber with BagTag-native vision
- Cultivar Select — Subscription bag service (pre-printed with BagTag)
- BagTag — This open standard, free for everyone to use and build upon
Open source software, honest hardware.
Community
- Issues & PRs: Welcome on Grove5 Git
- Questions: Tag
@grove5on socials - Show & Tell: Tag your BagTag projects — we always want to amplify good work
Grow well.