Skip to content

Add IoTivity BLE OCF framing codec - #72

Merged
QuiteYellow merged 1 commit into
QuiteYellow:mainfrom
Moballo-LLC:codex/ble-ocf-codec
Aug 31, 2026
Merged

Add IoTivity BLE OCF framing codec#72
QuiteYellow merged 1 commit into
QuiteYellow:mainfrom
Moballo-LLC:codex/ble-ocf-codec

Conversation

@Jason-Morcos

Copy link
Copy Markdown
Contributor

What this adds

IoTivity's BLE adapter carries reliable-transport CoAP PDUs in complete GATT characteristic values. This adds the pure BLE framing layer sequenced after the TCP codec in #28 and #70:

  • two-byte start/source-port/secure/destination-port header encoding and decoding;
  • four-byte big-endian first-frame PDU length;
  • MTU-sized fragmentation with source-compatible full non-final frames;
  • fixed-frame-size and adaptive reassembly;
  • conservative PDU bounds, strict metadata/length checks, and fail-closed reset after malformed or interleaved input; and
  • metadata-only result representations so logging a result does not include the PDU.

mtu is documented as IoTivity's complete characteristic-value frame size, not the raw ATT MTU. A default ATT MTU of 23 normally means a 20-byte value.

The adaptive reassembler derives the peer frame size from each start frame. That matches IoTivity's sender, which fills an incomplete first frame to the usable frame size, while avoiding dependence on a platform-specific negotiated-MTU API.

The header has no fragment sequence number, so a full-size continuation duplicated or reordered with identical metadata cannot be distinguished at this layer. The documentation calls that out directly; the codec does reject duplicate starts, orphan continuations, detectable missing or shortened fragments, and port/security changes.

Source and device contract

The wire format is tied to Samsung's public IoTivity sources (cafragmentation.h, cafragmentation.c, and the BLE adapter send loop), linked from the README.

This is also the framing contract used by our working integration. It has successfully carried /oic/res and a protected-resource GET through a Home Assistant Bluetooth proxy to a Samsung refrigerator; the protected read returned the expected 4.03 without a credential. The same API is used by our bounded BLE/DTLS and ownership-transaction callers, while all connection, GATT, authentication, and transaction policy stays outside this package.

Validation

  • 58 focused BLE codec tests plus the package import-isolation test
  • 670 tests on Python 3.14 with current dependencies
  • 670 tests on Python 3.11 with cbor2==5.6.0, pyOpenSSL==23.1.0, and pytest==8.0.0
  • 1,730 LocalThings tests against this checkout
  • 62 current integration BLE OCF/DTLS/OTM tests with the public BLE and TCP modules substituted
  • 5,000 deterministic randomized fragmentation/reassembly round trips
  • wheel and sdist content checks plus isolated installed-wheel import/codec smoke test
  • share-safety and Ruff checks

@QuiteYellow
QuiteYellow merged commit c4005f1 into QuiteYellow:main Aug 31, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants