Start Here
Getting started
TutorialEverything a new contributor needs to orient themselves — what the project is, what you need, and where to jump in.
What Sorter V2 is
Sorter V2 is an open-source LEGO sorting machine. Feed bulk LEGO into a hopper, and the machine singulates each piece, classifies it by part number (and optionally color), and drops it into the correct bin. The project is source-available; see CONTRIBUTING.md for licensing details. V1 exists as a reference but is no longer maintained; V2 is the active development target.
Current status
| Subsystem | Status | Notes |
|---|---|---|
| C-channel singulation | Working | 3-stage design, ~330 pieces/hour, targeting 1,000 |
| Classification (Brickognize API) | Working | 98.5% accuracy on supported parts, 0.56s avg response |
| Object detection (chamber zone) | Working | NanoDet + YOLO11s trained, benchmarked on Pi 5 + Orange Pi 5 |
| Host software (Python backend) | WIP | Coordinator, state machines, vision manager functional |
| SvelteKit UI | WIP | Setup wizard, camera calibration, runtime dashboard in progress |
| Hive community platform | WIP | Upload pipeline, shared profiles, crowd verification |
| Electronics / PCB | WIP | Feeder + distribution board schematics in review (Rev 0.3) |
| Hardware CAD | WIP | V2 CAD mostly complete in Onshape, validation in progress |
| Build guide / assembly docs | Stub | No step-by-step guide yet |
What you need
Hardware
A full bill of materials is still being finalized alongside the build guide (currently a stub — see Current status). At a high level the machine is built from an Orange Pi host, several stepper motors driving the C-channel feeder and rotating bin tower, basically controller boards, USB cameras, and 3D-printed structural parts on 2020 aluminum extrusion — all off-the-shelf, 3D-printable, or laser-cuttable. Detailed part choices and costs will be published with the build guide.
Tools
Soldering iron (PINECIL V2 recommended), pliers, wire strippers, screwdrivers, hacksaw.
Software
Python 3.12+, Node.js 20+, pnpm. The install script handles dependencies on Debian 12 / Ubuntu 24.04 / Pi OS Bookworm.
Pick a contribution track
- Mechanical / CAD — The project uses Onshape (free, web-based, collaborative). DM Spencer your email for document access. Start by browsing the V2 CAD and checking open bounties for mechanical tasks.
- Electronics — PCB schematics are in KiCad. Active work on feeder and distribution board reviews. Background in EE or PCB layout is valuable.
- Software — Python backend + SvelteKit frontend. See the Sorter install guide.
- ML / Vision — Classification research, training data collection, model optimization. See Classification research and Object detection research.
Key resources
| Resource | Link |
|---|---|
| GitHub organization | github.com/basicallysource |
| V2 CAD (active) | Onshape document |
| V1 CAD (reference only) | Onshape document |
| Brickognize API docs | api.brickognize.com/docs |
| Shared Google Drive | Design docs and presentations |
| Documentation site | docs.basically.website |
How the project works
- Contributions go through pull requests on GitHub. Branch protection is enabled on main.
- Bounties are posted on the Discord bounty board for discrete, high-priority tasks. Claim one if you can deliver within the posted timeline.
- Communication happens on Discord. Engineering sync calls happen periodically and are recorded for async viewing.
- CAD collaboration uses Onshape shared documents. Request access by DMing Spencer your Onshape email.
- Design reviews are scheduled for electronics and mechanical changes before merging.