@snap-calliope/extension

Snap! extension connecting Snap! to the Calliope mini v3 over BLE (Web Bluetooth) or USB serial (via the Snap!Out desktop app).

What it does

The extension adds a Calliope palette to Snap! with blocks for:

| Category | Blocks | |---|---| | Display | Show text, clear display, set pixel, show LED pattern | | Audio | Play tone, stop tone | | Sensors | Motion (pitch, roll, acceleration, compass), environment (temperature, light, sound) | | Buttons | Current state reporter; hat block for events (press, release, click, long click, hold) | | Gestures | Hat block for tilt, shake, free fall, G-force events | | GPIO | Digital / PWM output; digital / analog input; pull mode; hat block for pin events | | RGB LEDs | Set all three RGB LEDs by colour with optional brightness (0–100 %) | | Motors | Set motor A, B, or A+B to a speed between −100% and 100% |

Architecture

Snap! script
    │
    ▼
extension.js  ← registers SnapExtensions primitives, hosts sensor cache and event queue
    │
    ├── sensor cache   (latest STATE + MOTION values; polled by reporter blocks)
    ├── event queue    (button / gesture / pin events; consumed by hat blocks)
    │
    ├── transport/ble.js  — Web Bluetooth: polls STATE/MOTION/ANALOG every 50 ms,
    │                       subscribes to ACTION_EVENT and PIN_EVENT notifications
    └── transport/usb.js  — IPC client: receives push frames from @snap-calliope/bridge
                            running in the Snap!Out main process

Both transports implement the same interface; whichever connects first becomes active. If both transports connect simultaneously the BLE transport takes priority.

File structure

src/
  extension.js         — SnapExtensions registration, sensor cache, event queue, palette button
  protocol.js          — Microbit More v2 frame encoder/decoder (mirrors firmware/CalliopeCommon.h)
  snap-helpers.js      — runAsync (Snap! proc yield bridge) and snapListToRows helper
  blocks.xml           — Snap! block library XML (bundled into the IIFE by esbuild)
  transport/
    ble.js             — Web Bluetooth transport
    usb.js             — USB serial IPC client (Snap!Out only)
  __tests__/
    protocol.test.js   — Jest unit tests for the protocol codec
dist/
  snap-calliope-extension.js  — bundled IIFE (output of npm run build)

Build

npm install
npm run build     # produces dist/snap-calliope-extension.js
npm run watch     # same, with file-watch rebuild
npm test          # Jest unit tests

The build output is a single self-contained IIFE that can be loaded via a <script> tag in any Snap! host page, or bundled directly into a Snap!Out renderer.

Loading in Snap!

The extension registers itself when the script is loaded. In a plain browser page:

<script src="dist/snap-calliope-extension.js"></script>

In Snap!Out the extension is injected automatically by the renderer's inject.js together with the IPC bridge (@snap-calliope/bridge).

Connecting

Click Connect Calliope… in the Calliope palette and choose:

• BLE — wireless via Web Bluetooth (requires a browser that supports the API and a Calliope with the matching firmware in Bluetooth mode).
• USB — wired via Snap!Out; requires @snap-calliope/bridge to be registered in the main process.

After a successful connection the button label changes to Disconnect Calliope.

Protocol

Frames follow the Microbit More v2 wire protocol. The constants in protocol.js are the host-side mirror of firmware/src/CalliopeCommon.h. That file is the authoritative source — keep the two in sync whenever the firmware is updated.

i18n

German translations are injected into SnapTranslator.dict.de by injectCalliopeTranslations(). The function is also exposed as window.__SNAP_CALLIOPE_INJECT_TRANSLATIONS__ so that Snap!Out can re-invoke it after language switches (SnapTranslator.unload() wipes custom entries on every change).

License

AGPL-3.0-or-later