DRAFT · SPECULATIVE

Pop Boll Developer Specifications

Version 1.1-draft · Status: speculative draft · Updated 2026-11-10 · As of Bollawax 0.2.4 and Bollard SDK 0.1.0

Speculative draft. No Pop Boll hardware has shipped, and nothing on these pages has been built or validated on hardware. Dimensions, pinouts and protocols will change without notice, and nothing here is an offer, a commitment or a promise of compatibility. We would love to hear about partnership, OEM and dev-kit ideas: use the contact form below.

Note: The band's brain is a removable cart, the Bolltridge. It lives in the ball, and the same cart can also go into other docks, such as the Glass Snipler. The software pages here are current with Bollawax 0.2.4. The hardware page is not: Bollard still documents the first interface, under the Boll's foot, and the specification that replaces it for the cart is not written.

These pages are for people who want to build things for the Pop Boll: software that changes how the Boll writes songs, clients of its corpora, and docks and accessories. They are open specifications. You do not need our permission, a licence fee or a certification to build to them.

What the Pop Boll is#

The Pop Boll is a glowing ball with a tiny band inside. Sixteen virtual musicians jam, seven judges score every take, and together they write and play pop songs, learning from licensed song collections called corpora.

• Its brain is a cart. The band runs on the Bolltridge, a cart that stands in the ball. Take the cart out and the ball is a speaker and a light; put the cart in another dock and the same band plays there.
• It works offline. Everything the band needs is on the cart. A Boll that has never been online makes songs exactly like one that has. When it is online, it fetches new corpora and uploads the songs it made.
• It lights up. Its lights show each musician in their own colour, in time with the music.
• It has a front panel, the medallion, with three buttons, a USB-C port and a 3.5 mm audio output.

The Bollard SDK#

The Bollard SDK is the open library (Apache-2.0) that every client of the platform builds on, ours included: the Pop Boll's image and popboll.com run on it. Its import name is bollardeck, in Python and in the browser. Version 0.1.0 ships with Bollawax 0.2.4 and holds:

• routines: the hooks into the song factory, with a simulator and a command line;
• the device layer: buttons and gestures, button cues, the keymap, device identity and maker codes, and the 13 × 8 light matrix engine, the same code on the device and on the web;
• the corpus client: the one way to read a corpus, with a gate that refuses whatever a corpus's licence does not allow;
• schemas for every format, with a validator.

Not available yet, and planned: the deck service that docks and apps will talk to, sign-in, a sandbox for third-party apps, a signed registry, and the Glass Snipler's capability boundary. bollardeck Part C has the detail, and the SDK's own page says where to get it and how to start.

Bollard and bollardeck#

Bollard is the open ecosystem of docks and accessories, and the interface they share. The published Bollard Physical Specification is version 1: a dock mates with the Boll's foot through a 3.5 mm plug, a USB-C plug and a row of 10 spring pins. With the cart, the interface that matters becomes the Bollport, the single USB-C connection between a cart and the dock it stands in, and Bollard v2 will be the open specification for building such a dock. It is not written; Bollard §25 lists what is decided.

bollardeck is the API and the SDK. Routines are small Python programs that hook into the Boll's song factory on your own Boll; they are built and you can write one today. The dock messages (reading what is playing, the song's MIDI stems, the beat, the lights and the buttons, and sending volume, transport, remix and light-sync requests) are a draft with no service behind them yet. The bollardeck API covers both, and the SDK.

Device classes#

PWHAMSS and the Glass Snipler#

The Boll plays by itself. PWHAMSS (Personal Workshop for Human-Device Animation and MIDI Sync Systems) is the family of Pop Boll devices where a person works alongside the band instead: the same Bollawax engine, the same sixteen musicians and seven judges, the same licensed corpora, with a person at the keys pulling material out of songs, cutting it and handing it back. Every PWHAMSS device keeps an always-visible Workshop, keys that redraw their legends with the mode, a frame that every screen and light draws from, and a personal library that follows the person through HAMS sync. The PWHAMSS page states those principles, the event and frame contract, and the roadmap.

The Glass Snipler is the first PWHAMSS device: a slab whose whole face is one display under glass, with a touch Workshop across the top and, on a removable clear plate, four clear knobs (Small, Medium, Large, Huge), four mode diamonds (K, P, S, A), 48 clear keys and six side keys, each showing through to what the display draws for it. Everything you make on it is a sniplet (a stem, a riff, a loop, a beat or a macro); SNIP POP lifts material off the Workshop and SNIP PUT drops it back; the band listens to what you cue and may steal finished public sniplets into its own riff books. Its computer is a Bolltridge cart docked in its back, the same cart that lives in a Pop Boll. The Glass Snipler is a proprietary product; the Glass Snipler page has the layout, the key maps, the sniplet format and what is not decided.

Neither device exists in hardware. The design is built first as a web simulator at popboll.com/pwhamss, open to superusers during development, that runs the same state machine the slab will.

Bollard v1 at a glance#

This table is the v1 foot interface. For the cart and the Bollport, see Bollard §25.

The specifications#

• Bollard Physical Specification, version 1.0-draft, for hardware developers: datums and dimensions, the floating plate and piston, the BCR-10 pins and pinout, power, USB-C roles, analog audio, enumeration, sync, profiles, stacking, the Boll Cap, the Reference Bollard speaker design, hobbyist builds, the conformance checklist, and what is decided for Bollard v2.
• bollardeck API, version 0.2-draft, for software developers: routines (hooks, context, limits, packaging and two complete examples); the Bollard SDK (buttons, gestures, cues, the keymap, the corpus client and its gate, the schemas); and the draft dock messages (transports, the envelope, the handshake and capabilities, stems and rights).
• Popsniplish, edition 0.1.0, for software developers: the MiniCOSM the band inside the Boll speaks, told as a MiniCOSM is told on cosmoes.org: its volumes, modules and kinds, the entries as constructed fabulas and their shorts, the vote, morphs and readings, the knob lexicon, the eight moves it declares for Thym, its checks, FEED on a Boll and conformance, with the reference generated from its manifest and programs.

Good places to start:

• Writing a routine: hooks and the example routines.
• Reading a corpus: the corpus client and the gate.
• Handling the three buttons or lighting them: buttons, gestures, cues and the keymap.
• Writing dock software (a draft): the handshake and the example dock.
• Building a dock for the cart: what is decided for Bollard v2.
• Writing a renderer or a tool for a PWHAMSS device: the frame and event contract and the Glass Snipler's modes and sniplets.

Status and versioning#

The hardware pages are speculative drafts. No Pop Boll or dock has been built to these documents, and there is no shipping date. The software is further on: routines and the Bollard SDK are built and run in Bollawax 0.2.4. Each specification ends with an "Open items" section that lists what has not yet been validated on hardware.

• Bollard minor versions only add registers, classes, profiles or JSON fields. Any mechanical change, or any change to an assigned pin, is a new major version with a new header magic.
• bollardeck additions within a major version are optional fields, new message types, new error codes and new capabilities. Removing a field or changing its meaning is a new major version, negotiated in the hello handshake.
• The two move independently. A Bollard v1.0 dock speaks bollardeck/1.
• The Bollard SDK has its own version numbers, starting at 0.1.0, and says which wire and format versions it speaks (bollardeck.SPEAKS).
• Expect breaking changes before the 1.0 final releases. Each page carries its own change log.

Licensing#

The platform is licensed in layers: the text of these pages and the hardware specifications are CC BY 4.0, the hardware reference designs (the Reference Bollard, the Lux Puck and the Boll Cap) are CERN-OHL-P v2, so anyone can build and sell closed commercial docks, and the open code, the Bollard SDK with its examples, is Apache-2.0, which includes an explicit patent grant. Everything else is all rights reserved: Bollawax itself (the band, the judges and every image) runs on your device under the standing Bollawax Device Licence, free and without asking; the Glass Snipler's software and design are all rights reserved for now; and each corpus stays under its own licence and artist agreement and is never redistributable.

• Bollawax Device Licence: build, sell or own a device that runs a genuine Bollawax image, with no registration and no fee.
• Snipler Use Grant: fetch and run the Glass Snipler's software on a device that runs a genuine Bollawax image, with no registration and no fee.
• Trademark policy: the names, and how to say "Runs Bollawax", "Bollard compatible" or "works with the Pop Boll". The licences above cover documents, designs and code, not the names and logos. You may describe a product as "built to the Bollard Physical Specification v1.0, Full profile" (or whichever profile applies).
• Maker codes: the free registry of the 3 to 6 letter codes in device serials.
• The Pop Boll Shake (PDF): the plain-English agreement artists sign to lend their music to Pop Boll.
• What "study" means: exactly what the musicians keep when they study a corpus, and that no AI model is trained on it.
• Hosting your own corpus: for artists who keep their recordings on their own server and let Pop Boll pull from it (a draft; the Pop Boll side is not built yet).

None of these pages is legal advice, and the device licence and the trademark policy are drafts awaiting counsel review.

Get in touch#

Use the contact form below. We would especially like to hear from:

• dock, speaker and accessory makers interested in partnership or OEM work;
• developers who want a dev kit when one exists;
• anyone who finds a mistake, an ambiguity or a missing number in these drafts.

Tell us what you want to build and which profile you have in mind. Nothing you send commits either of us to anything.

FAQ#

Can I build and sell a dock?#

Yes. That is the point of an open specification. Build any shape, on any profile, and sell it under your own name at any price. The Reference Bollard speaker is an open reference design that anyone may build and sell as well. Because these are drafts, and because the dock interface is changing for the cart, please do not cut production tooling until Bollard v2 is published.

Do I need permission?#

No. There is no certification, no licence fee and no approval step for hardware. Conformance is self-declared: if you say your product is "Bollard v1.0, Full profile", you are stating that it passes the checklist for that profile. You are responsible for your product's safety and regulatory compliance. A future storefront may list docks, and listing would ask for a short self-declaration, but it will not be required to build or sell anything.

When will Bolls ship?#

There is no date. No Pop Boll hardware has shipped, and this specification is published ahead of the hardware so that people can comment on it and start designing.

Can I get a dev kit?#

Not for hardware. If you would like a dev kit when one exists, say so through the contact form. For software you need nothing from us: the Bollard SDK's simulated board, its routine simulator and its schemas run on any computer.

Can routines run on the website?#

No. Routines run only on your own Pop Boll. The website never runs user routines, and its song factory loads none. Routines work only with the corpora already on your Boll, and no API creates corpora.

Does my accessory have to touch the Boll?#

It will not have to. The draft lets any accessory speak bollardeck over Bluetooth Low Energy with no physical connection at all. That service is not built yet.