Note-emu - a drop-in virtual notecard library for note-c and note-cpp [community project]

Firmware
1

Hi all :waving_hand:

Following on from note-cpp, I’d like to share note-emu — a virtual Notecard you can use before your hardware arrives, or as part of your integration tests once it does.

It’s a drop-in transport for note-c/note-arduino and note-cpp that speaks to Blues’ cloud-hosted Notecard simulator (“softcard”) over HTTP. Your firmware calls the real Notecard API from day one; only the transport underneath is virtual.

The readme includes links to online Wokwi projects for note-c and note-cpp. Both Wokwi projects are ready to run once you add a Notehub personal access token - see secrets.h in each project.

What a run looks like — same request/response pattern you’d see on real hardware, only the bytes go to softcard.blues.com:

note-emu: resolved account UID: 00000000-0000-0000-0000-000000000000
=== iteration 1/5 ===
note-emu: POST /v1/write (46 bytes) -> rc=0 http=200 [685 ms]
note-emu: POST /v1/read  -> rc=0 http=200 bytes=384 [132 ms]
  version = notecard-11.1.1.1301

That notecard-11.1.1.1301 is a real Notecard firmware version. If your hub.set supplies a product, events reach your Notehub project through the same schema, routes, and event stream you would use with a physical Notecard. The only difference is that they are attributed to a softcard virtual device.

The whole idea is that switching to hardware is a transport swap without having to rewrite your notecard calls. Transport setup with note-emu:

// Virtual: WiFi → softcard
note::emu::Arduino softcard(NOTEHUB_PAT);
softcard.begin(wifiClient);
note::emu::SerialHal hal(*softcard.instance(), millis, delay);
note::link::SerialFramer<> framer(hal);
note::Protocol transport(framer);
note::Notecard nc(transport);

Against a real Notecard, the application is unchanged, just rewire the transport:

// Physical: I²C to Notecard
Notecard nc;
nc.begin(Wire);

Everything after nc — nc.hub.set()..., nc.card.version(), nc.note.add() — is unchanged.

A few things I think make it nice:

  • :globe_with_meridians: Zero-install prototyping — Wokwi browser sim + PAT → your first note.add in ~2 minutes
  • :puzzle_piece: Works with both note-c and note-cpp — pick your API. Umbrella headers make integration one line
  • :desktop_computer: Native builds too — a libcurl backend for desktop tests and CI; great for regression tests that hit softcard without any hardware in the loop
  • :electric_plug: Transport-level swap — plugs in at the serial-hook interface (NoteSetFnSerial for note-c, note::link::SerialHal for note-cpp). Same application code all the way to production
  • :package: Standalone — no external deps beyond your chosen HTTP backend
  • :test_tube: Examples for everything — Arduino sketches (note-c and note-cpp), PlatformIO projects, Wokwi projects, a native/libcurl demo

A note on scope: This is an independent community project — not affiliated with or supported by Blues, and “Notecard” is their trademark. It’s aimed at prototyping, testing, and integration. The README has a “Should I use this in Production?” section on why the physical Notecard beats software (cellular, power budget, security, edge reliability); but for the “waiting for hardware” and “keep our CI honest” cases, it’s a solid tool.

Repo, docs, and examples: GitHub - m-mcgowan/note-emu

Feedback, bug reports, and “I tried it on X” reports are all welcome. :folded_hands: