Docs update

Author: latonita

ARCHITECTURE.md

@@ -67,6 +67,31 @@ UART → check_frame() → COMPLETE / NEED_MORE / ERROR
 | **Logger** | Static logging interface, silent by default |
 | **utils** | Value conversion, OBIS/datetime formatting, type helpers |
 
+## Zero-Heap Architecture
+
+All parsing transforms happen in a single caller-owned work buffer. **No heap
+allocation occurs during `parse()`.** The caller provides the buffer at setup:
+
+```cpp
+uint8_t work_buf[1024];
+parser.set_work_buffer(work_buf, sizeof(work_buf));
+```
+
+The pipeline copies input into the work buffer, then transforms in-place:
+
+```
+work_buf: [7E HDLC frames 7E]  ← memcpy from input
+    ↓ HDLC decode (strip framing, concatenate payloads)
+work_buf: [E0 GBT blocks]
+    ↓ GBT reassembly (strip block headers)
+work_buf: [DB ciphertext]
+    ↓ AES-GCM decrypt in-place
+work_buf: [0F DATA-NOTIFICATION AXDR...]
+    ↓ strip APDU header → AxdrParser reads directly
+```
+
+Each stage produces output ≤ input, so the buffer never grows.
+
 ## Caller vs Library Responsibilities
 
 The library is **stateless** between calls — it does not buffer or accumulate data.
@@ -76,9 +101,10 @@ The library is **stateless** between calls — it does not buffer or accumulate
 | Reading bytes from UART | Caller |
 | Detecting frame boundaries (0x7E / 0x16) | Caller |
 | Accumulating multi-frame messages | Caller (using `check_frame()` to know when done) |
-| Decoding transport framing (HDLC / M-Bus) | Library |
-| Reassembling GBT blocks | Library |
-| Decrypting AES-GCM | Library |
+| Providing a work buffer (`set_work_buffer()`) | Caller |
+| Decoding transport framing (HDLC / M-Bus) | Library (in-place) |
+| Reassembling GBT blocks | Library (in-place) |
+| Decrypting AES-GCM | Library (in-place) |
 | Walking AXDR structure and matching patterns | Library |
 | Delivering parsed values via callbacks | Library |
 

HOWTO.md

@@ -87,6 +87,33 @@ parser.set_skip_crc_check(true);
 
 This affects HDLC and M-Bus only. It has no effect in `RAW` mode.
 
+## Providing A Work Buffer
+
+The parser performs all transforms (frame decoding, GBT reassembly, decryption,
+APDU unwrapping) in a single caller-owned work buffer. **No heap allocation occurs
+during `parse()`.**
+
+```cpp
+uint8_t work_buf[1024];  // stack, static, or PSRAM — caller controls placement
+parser.set_work_buffer(work_buf, sizeof(work_buf));
+```
+
+The work buffer must be at least as large as the biggest raw frame the meter sends.
+If no work buffer is set, or the frame exceeds its capacity, `parse()` returns
+`{0, 0}` and logs an error.
+
+Typical sizes:
+
+| Scenario | Recommended size |
+|---|---|
+| Unencrypted single-frame HDLC | 256–512 bytes |
+| Encrypted single-frame M-Bus | 512 bytes |
+| Multi-frame HDLC or GBT (e.g. Landis+Gyr E450) | 1024 bytes |
+
+The input buffer passed to `parse()` is **not modified** — data is copied into the
+work buffer first, then transformed in-place through each pipeline stage. Each stage
+produces output that is equal or smaller in size, so the buffer never grows.
+
 ## Accumulating Frames
 
 Some meters split a single DLMS message across multiple transport frames (HDLC
@@ -311,9 +338,11 @@ ESPHome-style integration:
 
 class MyMeterComponent {
     dlms_parser::DlmsParser parser_;
+    uint8_t work_buf_[1024]{};
 
 public:
     void setup() {
+        parser_.set_work_buffer(work_buf_, sizeof(work_buf_));
         parser_.load_default_patterns();
         parser_.set_frame_format(dlms_parser::FrameFormat::HDLC);
 
@@ -353,6 +382,8 @@ Examples of meter-specific customization from the test suite:
 
 | Symptom | Likely cause |
 |---|---|
+| `No work buffer set` error | call `set_work_buffer()` before `parse()` |
+| `Frame too large for work buffer` | increase work buffer size |
 | `parse()` returns 0 | no patterns loaded |
 | `parse()` returns 0 with patterns loaded | no pattern matched the AXDR layout |
 | `HCS error` or `FCS error` | wrong frame format, damaged frame, or non-standard CRC |

README.md

@@ -19,7 +19,10 @@ It is designed for embedded and integration-heavy environments such as ESPHome,
 ```cpp
 #include "dlms_parser/dlms_parser.h"
 
+uint8_t work_buf[1024];  // caller-owned, no heap allocation during parse()
+
 dlms_parser::DlmsParser parser;
+parser.set_work_buffer(work_buf, sizeof(work_buf));
 parser.set_frame_format(dlms_parser::FrameFormat::RAW);
 parser.load_default_patterns();
 
@@ -31,7 +34,7 @@ auto on_value = [](const char* obis, float num, const char* str, bool is_numeric
     }
 };
 
-size_t count = parser.parse(frame_bytes, frame_len, on_value);
+auto [count, consumed] = parser.parse(frame_bytes, frame_len, on_value);
 printf("%zu objects found\n", count);
 ```
 
@@ -54,11 +57,12 @@ parser.set_decryption_key(key);
 ## Typical Usage Flow
 
 1. Create `dlms_parser::DlmsParser`
-2. Select the frame format
-3. Set the decryption key if the meter is encrypted
-4. Load built-in patterns and optionally register custom ones
-5. Pass one complete frame to `parse()`
-6. Consume extracted values in the callback
+2. Provide a work buffer (`set_work_buffer`)
+3. Select the frame format
+4. Set the decryption key if the meter is encrypted
+5. Load built-in patterns and optionally register custom ones
+6. Pass one complete frame to `parse()`
+7. Consume extracted values in the callback
 
 ## Documentation
 

REFERENCE.md

@@ -11,6 +11,7 @@ Main facade that composes frame decoding, APDU handling, decryption, and AXDR pa
 | Method | Description |
 |---|---|
 | `set_frame_format(FrameFormat)` | Select transport wrapper: `RAW`, `HDLC`, or `MBUS` |
+| `set_work_buffer(buf, capacity)` | Provide a caller-owned buffer for in-place transforms — **required before `parse()`** |
 | `set_skip_crc_check(bool)` | Skip CRC/checksum validation for HDLC and M-Bus |
 | `set_decryption_key(std::array<uint8_t, 16>)` | Set AES-128-GCM key from a fixed array |
 | `set_decryption_key(std::vector<uint8_t>)` | Set AES-128-GCM key from a vector of exactly 16 bytes |