note-posix

POSIX platform hooks and transport layer for the Blues Notecard — communicate with your Notecard from any Linux or POSIX-compatible system.

---

Overview

note-posix is a thin platform adaptation layer that wires the note-c library into any POSIX-compatible environment. It provides:

• Memory hooks — malloc/free wrappers
• Time hooks — clock_gettime + nanosleep via CLOCK_MONOTONIC
• Debug output hook — fputs to stderr
• Thread safety — pthread_mutex_t mutex hooks registered with note-c
• Serial transport — termios UART driver (NoteSetFnSerial)
• I2C transport — Linux i2c-dev kernel interface (NoteSetFnI2C)

It is modeled after blues/note-zephyr but targets standard POSIX APIs instead of Zephyr RTOS primitives, making it suitable for:

• Linux laptops and desktops
• Raspberry Pi (all models)
• BeagleBone and similar SBCs
• Any embedded Linux system with a POSIX-compatible libc

---

Requirements

Hardware

• Any Blues Notecard (cellular, Wi-Fi, or LoRa)
• For serial: USB cable (Notecard USB port or Notecarrier AUX UART header)
• For I2C: Notecarrier with I2C pins exposed (Raspberry Pi header or bare pins)

Software

Requirement	Version
CMake	≥ 3.20
C compiler	C11 (gcc, clang)
C++ compiler	C++14 (for unit tests)
pthreads	Any POSIX-compliant
linux/i2c-dev.h	Linux kernel headers (I2C transport only)

Install on Debian/Ubuntu:

sudo apt-get install cmake build-essential

Cloudware

• Notehub.io account (free) — required to sync Notes to the cloud

---

Quick Start

1. Clone with submodules

git clone --recurse-submodules https://github.com/zakoverflow/note-posix.git
cd note-posix

2. Build

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel $(nproc)

3. Run hub-status

Connect a Notecard via USB or I2C, then:

# Serial (USB)
./build/examples/hub-status/hub-status --serial /dev/ttyUSB0

# I2C (Raspberry Pi)
./build/examples/hub-status/hub-status --i2c /dev/i2c-1

Sample output:

Connected via serial: /dev/ttyUSB0 @ 9600 baud

--- card.status ---
  status    : {connected}
  usb       : true
  connected : true
  cell      : false
  sync      : false
  storage   : 0%
  time      : 1741200000
  inbound   : 0
  outbound  : 0

--- hub.status ---
  status    : connected
  connected : true

---

Adding to Your Project

Use CMake FetchContent to pull note-posix (and its note-c submodule) into your project:

include(FetchContent)

FetchContent_Declare(
    note_posix
    GIT_REPOSITORY https://github.com/zakoverflow/note-posix.git
    GIT_TAG        main
    GIT_SUBMODULES note-c
)

FetchContent_MakeAvailable(note_posix)

target_link_libraries(my_app PRIVATE note_posix)

Then in your code:

#include <notecard.h>
#include <note.h>

int main(void)
{
    notecard_posix_init();
    notecard_open_serial("/dev/ttyUSB0", 9600);

    J *req = NoteNewRequest("card.version");
    J *rsp = NoteRequestResponse(req);
    if (rsp) {
        NoteDeleteResponse(rsp);
    }

    notecard_close();
    return 0;
}

---

API Reference

All public functions are declared in notecard/notecard.h.

notecard_posix_init

void notecard_posix_init(void);

Initialize the POSIX platform hooks for the Notecard. Must be called once before any other Notecard operations. Registers memory allocation, time, debug output, and mutex hooks with note-c.

---

notecard_open_serial

bool notecard_open_serial(const char *port, int baud);

Open a serial (UART) connection to the Notecard.

Parameter	Description
port	Path to the serial device, e.g. "/dev/ttyUSB0", "/dev/ttyAMA0"
baud	Baud rate. Use 9600 for the LP UART or 115200 for the AUX UART

Returns true on success, false on error (device not found, permission denied, etc.).

---

notecard_open_i2c

bool notecard_open_i2c(const char *device, uint16_t addr);

Open an I2C connection to the Notecard. Linux only — uses the kernel's i2c-dev interface.

Parameter	Description
device	Path to the I2C bus device, e.g. "/dev/i2c-1"
addr	I2C address. Use NOTE_I2C_ADDR_DEFAULT (0x17) unless the address has been changed

Returns true on success, false on error.

Note: On Raspberry Pi, enable I2C with sudo raspi-config → Interface Options → I2C, then reboot.

---

notecard_close

void notecard_close(void);

Close the active transport connection and release all associated resources. Safe to call even if no transport is currently open.

---

Examples

Example	Description
hub-status	Connect to the Notecard and print card.status + hub.status
note-add	Add a Note (with optional JSON body) to a notefile
note-repl	Interactive JSON REPL — send raw JSON requests and see responses

See examples/README.md for details on each.

---

Building

Default (tests + examples)

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel $(nproc)

Tests only

cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DNOTE_POSIX_BUILD_TESTS=ON \
  -DNOTE_POSIX_BUILD_EXAMPLES=OFF
cmake --build build
ctest --test-dir build --output-on-failure

Examples only

cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DNOTE_POSIX_BUILD_TESTS=OFF \
  -DNOTE_POSIX_BUILD_EXAMPLES=ON
cmake --build build

With coverage (requires lcov)

sudo apt-get install lcov
cmake -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DNOTE_POSIX_COVERAGE=ON \
  -DNOTE_POSIX_BUILD_EXAMPLES=OFF
cmake --build build
cmake --build build --target coverage

---

Thread Safety

note-posix registers a pthread_mutex_t-based mutex with note-c via NoteSetFnNoteMutex. This means all note-c API calls are automatically serialized, and it is safe to call Notecard APIs from multiple threads concurrently.

The mutex is initialized statically with PTHREAD_MUTEX_INITIALIZER and is not recursive — do not call note-c API functions from within a note-c callback on the same thread.

---

Supported Platforms

Platform	Serial	I2C	Notes
Linux x86-64 (laptop/desktop)	✅	✅	/dev/ttyUSB0, /dev/i2c-N
Raspberry Pi (all models)	✅	✅	/dev/ttyAMA0 or /dev/ttyUSB0, /dev/i2c-1
BeagleBone Black	✅	✅	/dev/ttyO*, /dev/i2c-*
Other embedded Linux (POSIX libc)	✅	✅ (Linux only)	I2C requires linux/i2c-dev.h
macOS	✅	❌	I2C stub returns false; serial works via /dev/cu.*
Other POSIX (FreeBSD, etc.)	✅	❌	I2C stub; serial works if termios is available

---

License

MIT License. Copyright (c) 2025 Blues Inc. See LICENSE for details.

Contributing

Issues and pull requests are welcome. Please follow the existing code style (Linux kernel-adjacent C, clang-format with the project's style).