DDR-0032: E27 Frame Length Field Includes CRC Bytes

Status: Accepted
Date: 2025-01-xx

Context
-------
The E27 API Communications documentation specifies that each framed message contains
a 2-byte little-endian length field that is transmitted in the clear.

Ambiguity existed during early implementation about whether the CRC bytes were
included in this length calculation or appended afterward.

Empirical testing against live E27 hardware, Node-RED reference flows, and protocol
documentation confirm that the CRC bytes ARE included in the length value.

Decision
--------
The implementation SHALL interpret and generate the E27 frame length field as follows:

- Length field:
  - 2 bytes, little-endian
  - Always transmitted in the clear
  - Represents the total byte count starting at:
      protocol byte
    and ending at:
      CRC bytes (inclusive)
  - Does NOT include the STARTCHAR (0x7E)

Formally:

  length =
      1 byte  protocol
    + 2 bytes payload length field
    + N bytes payload (ciphertext or clear data)
    + 2 bytes CRC16

The CRC16 calculation is performed over the same byte range
(protocol through payload), and the resulting CRC bytes are appended and counted
within the length.

Consequences
------------
- frame_build MUST include CRC bytes when computing the length field
- deframe logic MUST wait for length bytes that include CRC before validation
- Incorrect length interpretation will cause framing desynchronization
- CRC validation must occur only after full length bytes are accumulated
- STARTCHAR is never counted toward length

Related
-------
- ADR-010x (E27 framing and transport semantics)
- DDR-0031 (Framing resynchronization rule)
- DDR-0028 (CRC calculation details)
- Tests: test_e27_framing.py, test_e27_roundtrip.py
