CRUMBS

CRUMBS (Communications Router and Unified Message Broker System) is a small, portable C-based protocol for controller/peripheral I²C messaging. The project ships a C core (encoding/decoding, CRC) and thin platform HALs for Arduino and Linux so the same protocol works on microcontrollers and native hosts.

Features

• Variable-Length Message Format: 4–31 byte frames with opaque byte payloads (0–27 bytes)
• Controller/Peripheral Architecture: One controller, multiple addressable devices
• Per-Command Handler Dispatch: Register handlers for specific command types
• Message Builder/Reader Helpers: Type-safe payload construction via crumbs_msg.h
• Event-Driven Communication: Callback-based message handling
• CRC-8 Protection: Integrity check on every message
• CRUMBS-aware Discovery: Core scanner helper to find devices that speak CRUMBS

Quick Start (Arduino — C API)

#include <crumbs_arduino.h>
#include <crumbs_msg.h>

crumbs_context_t controller_ctx;
crumbs_arduino_init_controller(&controller_ctx);

crumbs_message_t m;
crumbs_msg_init(&m);
m.type_id = 1;
m.command_type = 1;

// Type-safe payload building
crumbs_msg_add_float(&m, 25.5f);  // e.g. change a temperature value
crumbs_msg_add_u8(&m, 0x01);      // e.g. configure the channel index

crumbs_controller_send(&controller_ctx, 0x08, &m, crumbs_arduino_wire_write, NULL);

Installation

1. Download or clone this repository
2. Place the CRUMBS folder in your Arduino libraries directory
3. Include in your sketch: #include <crumbs_arduino.h> (Arduino) or #include "crumbs.h" (C projects)

No external dependencies required — CRC implementations are included under src/crc.

Hardware Requirements

• Arduino or compatible microcontroller
• I2C bus with 4.7kΩ pull-up resistors on SDA/SCL lines
• Unique addresses (0x08-0x77) for each peripheral device

Documentation

Documentation is available in the docs directory:

• Getting Started - Installation and basic usage
• API Reference - Core C API and platform HALs
• Handler Guide - Per-command handler dispatch tutorial
• Message Helpers - Payload building and reading helpers
• Protocol Specification - Message format details
• Examples - Code examples and patterns

Examples

Working examples for Arduino, Linux, and PlatformIO are provided under examples/:

• examples/arduino/ — Arduino sketches (simple, display, and handler-based examples)
• examples/linux/ — Native Linux controller examples using the Linux HAL
• examples/platformio/ — PlatformIO projects (ready to build with pio run)
• examples/common/ — Shared command header definitions (LED, servo)

License

GPL-3.0 - see LICENSE file for details.