docs: mostly cosmetic revisions to all markdown

Author: CameronBrooks11

CONTRIBUTING.md

@@ -174,7 +174,7 @@ We follow a concise in-source documentation style. See [docs/doxygen-style-guide
  * @param msg Message to encode
  * @param buffer Output buffer (min 31 bytes)
  * @param buffer_len Size of output buffer
- * @return Encoded frame length (4-31 bytes), or 0 on error
+ * @return Encoded frame length (4–31 bytes), or 0 on error
  */
 size_t crumbs_encode_message(const crumbs_message_t *msg,
                              uint8_t *buffer,

README.md

@@ -18,46 +18,56 @@ CRUMBS (Communications Router and Unified Message Broker System) is a small, por
 
 ## Features
 
-- **Variable-Length Message Format**: 4-31 byte frames with opaque byte payloads (0-27 bytes)
+- **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_message_helpers.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)
+## Quick Start
 
 ```c
 #include <crumbs_arduino.h>
 #include <crumbs_message_helpers.h>
 
-crumbs_context_t controller_ctx;
-crumbs_arduino_init_controller(&controller_ctx);
+crumbs_context_t ctx;
+crumbs_arduino_init_controller(&ctx);
 
 crumbs_message_t m;
-crumbs_msg_init(&m, 0x01, 0x01);  // type_id=1, opcode=1
+crumbs_msg_init(&m, 0x01, 0x01);     // type_id=1, opcode=1
+crumbs_msg_add_float(&m, 25.5f);     // Payload: float
+crumbs_msg_add_u8(&m, 0x01);         // Payload: byte
 
-// 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);
+crumbs_controller_send(&ctx, 0x08, &m, crumbs_arduino_wire_write, NULL);
 ```
 
+Upload [hello examples](examples/core_usage/arduino/hello_peripheral/) to two Arduinos, wire I²C + GND, Serial Monitor (115200): `s`/`r`. See [examples/](examples/).
+
 ## 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)
+**PlatformIO (Recommended):**
+
+```ini
+[env]
+lib_deps = cameronbrooks11/CRUMBS@^0.10.3
+```
 
-No external dependencies required - CRC implementations are included under `src/crc`.
+**Arduino IDE:** Tools → Manage Libraries → "CRUMBS" → Install, or copy to `~/Arduino/libraries/`
+
+**Linux/Native:** CMake build (see [CONTRIBUTING.md](CONTRIBUTING.md))
+
+No external dependencies.
 
 ## Hardware Requirements
 
 - Arduino or compatible microcontroller
-- I²C bus with 4.7k-Ohm pull-up resistors on SDA/SCL lines
-- Unique addresses (0x08-0x77) for each peripheral device
+- I²C bus with 4.7kΩ pull-up resistors on SDA/SCL
+- Unique addresses (0x08–0x77) for each peripheral
+- **Level shifter if mixing 5V/3.3V devices**
+
+**Wiring:** SDA↔SDA, SCL↔SCL, GND↔GND (+ 4.7kΩ pull-ups to VCC)
 
 ## Documentation
 
@@ -89,6 +99,18 @@ Examples are organized into three progressive tiers:
 
 See [examples/README.md](examples/README.md) for complete platform coverage and [docs/examples.md](docs/examples.md) for detailed documentation.
 
+## Troubleshooting
+
+**No communication:** Check 4.7kΩ pull-ups, common ground, addresses. Level shifter for 5V↔3.3V.
+
+**CRC errors:** Shorten wires (<30cm), `Wire.setClock(50000)`, add 0.1µF caps.
+
+**Handlers:** `build_flags = -DCRUMBS_MAX_HANDLERS=16` in platformio.ini.
+
+Details: [platform-setup.md](docs/platform-setup.md)
+
+---
+
 ## License
 
 GPL-3.0 - see [LICENSE](LICENSE) file for details.

TODO.md

@@ -21,16 +21,16 @@ typedef struct {
     uint8_t address;      // Device address (not serialized, for context only)
     uint8_t type_id;      // Device/module type identifier
     uint8_t opcode;       // Command/query opcode
-    uint8_t data_len;     // Payload length (0-27)
+    uint8_t data_len;     // Payload length (0–27)
     uint8_t data[27];     // Payload buffer
     uint8_t crc8;         // CRC-8 checksum over serialized frame
 } crumbs_message_t;
 ```
 
-**Serialized frame format** (4-31 bytes):
+**Serialized frame format** (4–31 bytes):
 
-```
-[type_id:1][opcode:1][data_len:1][data:0-27][crc8:1]
+```text
+[type_id:1][opcode:1][data_len:1][data:0–27][crc8:1]
 ```
 
 CRC is computed over: `type_id + opcode + data_len + data[0..data_len-1]`
@@ -61,7 +61,7 @@ typedef struct crumbs_context_t {
 ```c
 #define CRUMBS_MAX_PAYLOAD      27    // Maximum payload bytes
 #define CRUMBS_MESSAGE_MAX_SIZE 31    // Maximum serialized frame size
-#define CRUMBS_VERSION          0x0A03 // Library version (0x0A03 = v0.10.3)
+#define CRUMBS_VERSION          1003  // Library version (1003 = v0.10.3, formula: major*10000 + minor*100 + patch)
 ```
 
 ### Callback Signatures
@@ -182,8 +182,14 @@ Send a message from controller to a peripheral device.
 - `0` — Success
 - `-1` — Invalid arguments (NULL ctx/msg/write_fn)
 - `-2` — Context not in controller role
-- `-3` — Encode failed
-- `>0` — I2C write error (from write_fn)
+- `-3` — Encode failed (data_len > 27 or buffer issue)
+- `>0` — I2C write error (platform-specific, from write_fn)
+
+**Common issues:**
+
+- Return `-3`: Check `msg->data_len` ≤ 27
+- Return `>0`: I²C bus error - check wiring, pull-ups, address
+- No response from peripheral: Add 10ms delay before reading
 
 **Example:**
 
@@ -192,6 +198,10 @@ crumbs_message_t msg;
 crumbs_msg_init(&msg, 0x01, 0x10);  // type=LED, opcode=query
 int rc = crumbs_controller_send(&ctx, 0x08, &msg,
                                 crumbs_arduino_wire_write, NULL);
+if (rc != 0) {
+    Serial.print("Send failed: ");
+    Serial.println(rc);  // Debug error code
+}
 ```
 
 ### Peripheral Operations
@@ -204,13 +214,9 @@ int crumbs_peripheral_handle_receive(crumbs_context_t *ctx,
 
 Process incoming data on a peripheral device. Decodes the message, validates CRC, and invokes callbacks/handlers.
 
-**Returns:**
-
-- `0` — Success (callbacks invoked)
-- `-1` — Invalid arguments, not peripheral role, or decode failed
-- `-2` — CRC mismatch
+**Returns:** `0`=success, `-1`=invalid/decode fail, `-2`=CRC error (check wiring, use `crumbs_get_crc_error_count()`)
 
-Typically called from Wire `onReceive()` callback on Arduino.
+Called from Wire `onReceive()` on Arduino.
 
 ---
 
@@ -320,7 +326,7 @@ void my_handler(crumbs_context_t *ctx,
 - `ctx` — The CRUMBS context
 - `opcode` — The command that triggered this handler
 - `data` — Payload bytes (may be NULL if data_len == 0)
-- `data_len` — Payload length (0-27)
+- `data_len` — Payload length (0–27)
 - `user_data` — Opaque pointer registered with this handler
 
 ### Handler Dispatch Flow
@@ -547,7 +553,7 @@ Wire-based read function for scanner and diagnostics.
 
 **Returns:**
 
-- Number of bytes read (0-31)
+- Number of bytes read (0–31)
 - Negative values on error
 
 ### Bus Scanner
@@ -677,7 +683,7 @@ Platform-independent bus scanner for CRUMBS-compatible devices.
 
 **Parameters:**
 
-- `start_addr`/`end_addr` — Inclusive probe range (0x08-0x77 typical)
+- `start_addr`/`end_addr` — Inclusive probe range (0x08–0x77 typical)
 - `strict` — Non-zero: request data-phase read (strong detection). Zero: ACK probe only.
 - `write_fn`/`read_fn` — Platform primitives
 - `found` — Output array for discovered addresses

docs/api-reference.md

@@ -14,7 +14,7 @@ CRUMBS is a lightweight I²C messaging protocol enabling controllers (e.g., sing
 
 CRUMBS was created to solve practical problems in distributed embedded systems:
 
-- **Compact wire format**: 4-31 bytes per message (variable length)
+- **Compact wire format**: 4–31 bytes per message (variable length)
 - **Robust communication**: CRC-8 integrity checking for noisy I²C buses
 - **Portable C core**: Easy to integrate on resource-constrained microcontrollers
 - **Platform abstraction**: Thin HALs for Arduino (Wire) and Linux (linux-wire)
@@ -108,7 +108,7 @@ The same headers are used by peripheral firmware to implement handlers.
 **Bus topology:**
 
 - Modules connect to shared I²C bus (SDA/SCL)
-- Each peripheral at unique 7-bit address (0x08-0x77)
+- Each peripheral at unique 7-bit address (0x08–0x77)
 - Controller initiates all communication (I²C master)
 - Pull-up resistors required (typically 4.7kΩ)
 
@@ -124,7 +124,7 @@ Controllers use CRUMBS-aware scanning to discover devices on the bus:
 
 **How Discovery Works:**
 
-1. **Bus scan**: Controller probes each address (0x08-0x77)
+1. **Bus scan**: Controller probes each address (0x08–0x77)
 2. **Read attempt**: Tries to read a CRUMBS frame from each address
 3. **Validation**: Decodes message and validates CRC
 4. **Type extraction**: Valid response contains type_id in frame
@@ -258,7 +258,7 @@ Controller can:
 
 - Wire format encoding/decoding
 - CRC-8 computation and validation
-- Frame boundaries (4-31 bytes)
+- Frame boundaries (4–31 bytes)
 - Role management (controller/peripheral)
 
 **Platform Layer (HALs):**
@@ -276,10 +276,10 @@ Controller can:
 
 ### Wire Format
 
-**Serialized frame** (4-31 bytes):
+**Serialized frame** (4–31 bytes):
 
 ```
-[type_id:1][opcode:1][data_len:1][data:0-27][crc8:1]
+[type_id:1][opcode:1][data_len:1][data:0–27][crc8:1]
 ```
 
 **Key properties:**
@@ -460,8 +460,8 @@ The LHWIT family is intentionally simple (4 module types, basic commands) to rem
 **Buffer sizing:**
 
 - `crumbs_message_t`: 31 bytes (fixed maximum)
-- `crumbs_context_t`: ~100-200 bytes depending on handler configuration
-- Handler table: configurable (0-255 entries)
+- `crumbs_context_t`: ~100–200 bytes depending on handler configuration
+- Handler table: configurable (0–255 entries)
 
 ### CRC Implementation
 

docs/architecture.md

@@ -56,7 +56,7 @@ float range = 0.0 to 1.0;  // or: 0.0-1.0
 - Decorative Unicode symbols
 - Non-standard punctuation
 
-### Examples
+### Examples (Documentation)
 
 ```markdown
 <!-- ✅ GOOD -->

docs/character-usage-guide.md

@@ -1,6 +1,17 @@
 # CRUMBS Documentation
 
-Arduino I²C communication library for controller/peripheral messaging with variable-length payloads and CRC validation.
+I²C messaging library for controller/peripheral communication with CRC validation.
+
+## 🚀 Start Here
+
+1. [Platform Setup](platform-setup.md) → PlatformIO
+2. Test I²C: [scanner](https://playground.arduino.cc/Main/I2cScanner/)
+3. Upload [hello examples](../examples/core_usage/arduino/)
+4. Read [Protocol](protocol.md) and [examples](examples.md)
+
+Issues? [Troubleshooting](../README.md#troubleshooting)
+
+---
 
 ## Quick Start
 
@@ -48,14 +59,15 @@ void setup() {
 
 ## Features
 
-- **Variable-length payload** (0–27 bytes per message)
-- **Controller/peripheral architecture** (one controller, multiple devices)
-- **Per-command handler dispatch** (register handlers for specific opcodes)
-- **Message builder/reader helpers** (type-safe payload construction)
-- **Event-driven callbacks** (message and request handling)
-- **CRC-8 data integrity** (automatic validation)
-- **CRUMBS-aware discovery** (find devices that speak the protocol)
-- **Platform support** (Arduino, PlatformIO, Linux)
+- **Variable-length payload** (0–27 bytes, 4–31 total frame)
+- **Controller/peripheral** (one controller, up to 112 devices)
+- **Handler dispatch** (per-opcode callbacks, O(n) lookup)
+- **Message helpers** (type-safe: u8, u16, u32, i32, float)
+- **Event callbacks** (on_message, on_request)
+- **CRC-8 integrity** (auto validation, error stats)
+- **Discovery** (scan for compatible devices)
+- **Platforms** (Arduino, PlatformIO, Linux)
+- **Zero allocation** (deterministic, RTOS-safe)
 
 ---
 
@@ -120,13 +132,13 @@ typedef struct {
     uint8_t address;      // Device I²C address (not serialized)
     uint8_t type_id;      // Device/module type identifier
     uint8_t opcode;       // Command/query opcode
-    uint8_t data_len;     // Payload length (0-27)
+    uint8_t data_len;     // Payload length (0–27)
     uint8_t data[27];     // Payload buffer
     uint8_t crc8;         // CRC-8 checksum
 } crumbs_message_t;
 ```
 
-**Wire format:** `[type_id:1][opcode:1][data_len:1][data:0-27][crc8:1]` (4-31 bytes)
+**Wire format:** `[type_id:1][opcode:1][data_len:1][data:0–27][crc8:1]` (4–31 bytes)
 
 ### Core Functions