POP BOLL

The Bollard SDK

Version 1 · Updated 2026-11-10 · Bollard SDK 0.2.0, shipped with Bollawax 0.2.4

The Bollard SDK is the open library that everything on the Pop Boll platform builds on, ours included: the Pop Boll's own image and this website run on the same code you can download here. It is plain Python that needs only the standard library, and plain JavaScript with no build step. Its import name is bollardeck in both.

You do not need our permission, an account or a fee to use it.

Note: No Pop Boll hardware has shipped. Today the SDK runs on your own computer: the simulated board, the routine simulator, the light matrix engine and the corpus gate all work with no device.

What is in 0.1.0#

  • Schemas and constants. A JSON Schema for every format the platform reads or writes (corpus manifests, licence blocks, routine manifests, cues, keymaps, device identity and more), a validator for them, and one set of constants that Python and JavaScript share. Each schema is also served at its own address, https://popboll.com/sdk/schema/<name>.schema.json; the list names them.
  • The corpus client and the licence gate. The one way to read a corpus, with a gate that refuses whatever the corpus's licence does not allow, and says why.
  • The device layer. The hardware abstraction with a simulated board, buttons and gestures, button cues, the keymap, device identity and maker codes.
  • Routines. Small Python programs that hook into the song factory, with a simulator and a command line.
  • The light matrix engine. Every frame the 13 × 8 matrix can show, as a pure function you can call.
  • The browser binding. The schemas, cues, gestures, keymap, matrix engine and corpus gate again in JavaScript, for a page, for Node and as an ES module.
  • Conformance vectors. Inputs with the answers they must give, which hold the Python and JavaScript halves to the same behaviour. They live in the source repository, not in the runtime archive below.

What is not in it yet#

These are planned. None of them has a date.

  • The deck service: the thing docks and apps will talk to. bollardeck.deck is a placeholder today.
  • Sign-in. Until it arrives, a client says who it acts for and the hub takes its word. It is planned; no version is promised yet.
  • A sandbox for third-party apps, on the device and in the browser.
  • A signed registry for publishing what you build, with sideloading for people who would rather not.
  • The Glass Snipler boundary. The Glass Snipler's own software is not open and is not part of the SDK. What is planned is the open edge of it: the events and frames an app can exchange with a Snipler. Two draft schemas and a placeholder, bollardeck.snipler, are all that exists now.

Licences#

  • The SDK's code is Apache-2.0, which includes a patent grant. Use it in open or closed work.
  • The specification pages are CC BY 4.0.
  • Bollawax images (the band itself) are not open. They run on devices under the Bollawax Device Licence, free and without asking. You do not need it to use the SDK.
  • The Glass Snipler's software is not open and is not part of the SDK. A device fetches and runs it under the Snipler Use Grant, free and without asking.
  • The names (Pop Boll, Bollawax, Bollard, bollardeck and the rest) are covered by the trademark policy, which says what you may call your own work.

There is no sign-up agreement.

Where to get it#

The runtime archive is at bollawax.org/sdk. It is one file, bollard-sdk-0.2.0.tar.gz, with its sha256 beside it, and it is exactly the copy our own images carry: the Python package, the browser binding, the licence and a list of every file with its checksum. It does not hold the conformance vectors, the tests or the examples, and pip install does not work from it. Unpack it and put its python folder on your PYTHONPATH.

From PyPI: pip install bollard-sdk installs the Python package; import it as bollardeck. It is the same code as the archive's python/ folder, without the browser binding.

The source repository is github.com/0gsd/bollard-sdk. It holds everything the archive leaves out: the conformance vectors, the tests, the examples and the changelog. pip install . works from a checkout.

Hello, in Python#

Save this as hello.py inside the unpacked archive and run PYTHONPATH=python python3 hello.py. It checks a cue list against its schema (the list is wrong on purpose, there is no button 4, so the first thing it prints is the problem it found), turns a button press into a gesture, asks the keymap what that gesture means, and draws a frame of the light matrix as text.

import bollardeck
from bollardeck import matrix, schema
from bollardeck.device import gestures, keymap

print("bollardeck", bollardeck.__version__, "speaks", bollardeck.SPEAKS["bollardeck"])
print(schema.validate("cue", [{"button": 4, "state": "on", "role": None}]))
engine = gestures.GestureEngine()
for gesture in engine.press(1, 0, 80) + engine.tick(2000):
    print(gesture.name, "means", keymap.resolve(gesture.name, None).value)
print(matrix.glyph_frame("heart", 0).ascii())

Hello, in the browser#

Save this as hello.html inside the unpacked archive and open it from disk. It does the same four things. No server is needed and nothing is fetched from a network.

<pre id="out"></pre>
<script src="js/bollardeck.js"></script>
<script>
  var out = ["bollardeck " + bollardeck.version + " speaks " + bollardeck.speaks.bollardeck];
  out.push(String(bollardeck.schema.validate("cue", [{button: 4, state: "on", role: null}])));
  var engine = bollardeck.gestures.engine();
  engine.press(1, 0, 80).concat(engine.tick(2000)).forEach(function (gesture) {
    out.push(gesture.name + " means " + bollardeck.keymap.resolve(gesture.name, null).value);
  });
  out.push(bollardeck.matrix.ascii(bollardeck.matrix.glyph("heart", 0)));
  document.getElementById("out").textContent = out.join("\n");
</script>

Reporting a problem#

Open an issue on the repository, or write to shake@bollawax.org if you would rather not use GitHub.

Say what you ran, what you expected and what happened. There is no support desk and we cannot promise a reply, but a clear report of something broken is the most useful thing you can send.

Pull requests are not accepted for now. The SDK is the upstream of code that runs on devices, and we are not yet set up to review outside changes with the care that needs. If you have a fix, describe it in a report and we will take it from there, with thanks. This may change.

CONTACT THE TEAM