blerpc-protocol 0.8.0__tar.gz

blerpc_protocol-0.8.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 tdaira
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

blerpc_protocol-0.8.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: blerpc-protocol
+Version: 0.8.0
+Summary: Container and command protocol layers for BLE RPC
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/tdaira/blerpc-protocol
+Project-URL: Repository, https://github.com/tdaira/blerpc-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Dynamic: license-file
+
+# blerpc-protocol
+
+BLE RPC protocol library for Python and C.
+
+Part of the [bleRPC](https://blerpc.net) project.
+
+## Overview
+
+Python and C implementation of the bleRPC binary protocol:
+
+- Container fragmentation and reassembly with MTU-aware splitting
+- Command packet encoding/decoding with protobuf payload support
+- Control messages (timeout, stream end, capabilities, error)
+- **Encryption layer** — E2E encryption with X25519 key exchange, Ed25519 signatures, and AES-128-GCM
+
+The Python and C implementations are fully compatible and share the same wire format.
+
+## Installation
+
+```
+pip install blerpc-protocol
+```
+
+## Usage
+
+```python
+from blerpc_protocol import ContainerSplitter, ContainerAssembler, CommandPacket, CommandType
+
+# Encode a command
+packet = CommandPacket(CommandType.REQUEST, "Echo", protobuf_bytes)
+payload = packet.serialize()
+
+# Split into BLE-sized containers
+splitter = ContainerSplitter(mtu=247)
+containers = splitter.split(payload)
+
+# Send containers over BLE, then reassemble on the other side
+assembler = ContainerAssembler()
+for container in received_containers:
+    result = assembler.feed(container)
+    if result is not None:
+        response = CommandPacket.deserialize(result)
+```
+
+## Encryption
+
+The library provides E2E encryption using a 4-step key exchange protocol (X25519 ECDH + Ed25519 signatures) and AES-128-GCM session encryption.
+
+```python
+from blerpc_protocol.crypto import central_perform_key_exchange, BlerpcCryptoSession
+
+# Perform key exchange (central side)
+session = await central_perform_key_exchange(send=ble_send, receive=ble_receive)
+
+# Encrypt outgoing commands
+ciphertext = session.encrypt(plaintext)
+
+# Decrypt incoming commands
+plaintext = session.decrypt(ciphertext)
+```
+
+## C Library
+
+The C implementation is a Zephyr module with zero external dependencies. Add it to your `west.yml` manifest:
+
+```yaml
+- name: blerpc-protocol
+  url: https://github.com/tdaira/blerpc-protocol
+  revision: main
+  path: modules/lib/blerpc-protocol
+```
+
+Headers are in `c/include/blerpc_protocol/`. See [container.h](c/include/blerpc_protocol/container.h), [command.h](c/include/blerpc_protocol/command.h), and [crypto.h](c/include/blerpc_protocol/crypto.h) for the API.
+
+## Requirements
+
+- Python 3.11+
+
+## License
+
+[Apache-2.0](LICENSE)

blerpc_protocol-0.8.0/README.md

@@ -0,0 +1,81 @@
+# blerpc-protocol
+
+BLE RPC protocol library for Python and C.
+
+Part of the [bleRPC](https://blerpc.net) project.
+
+## Overview
+
+Python and C implementation of the bleRPC binary protocol:
+
+- Container fragmentation and reassembly with MTU-aware splitting
+- Command packet encoding/decoding with protobuf payload support
+- Control messages (timeout, stream end, capabilities, error)
+- **Encryption layer** — E2E encryption with X25519 key exchange, Ed25519 signatures, and AES-128-GCM
+
+The Python and C implementations are fully compatible and share the same wire format.
+
+## Installation
+
+```
+pip install blerpc-protocol
+```
+
+## Usage
+
+```python
+from blerpc_protocol import ContainerSplitter, ContainerAssembler, CommandPacket, CommandType
+
+# Encode a command
+packet = CommandPacket(CommandType.REQUEST, "Echo", protobuf_bytes)
+payload = packet.serialize()
+
+# Split into BLE-sized containers
+splitter = ContainerSplitter(mtu=247)
+containers = splitter.split(payload)
+
+# Send containers over BLE, then reassemble on the other side
+assembler = ContainerAssembler()
+for container in received_containers:
+    result = assembler.feed(container)
+    if result is not None:
+        response = CommandPacket.deserialize(result)
+```
+
+## Encryption
+
+The library provides E2E encryption using a 4-step key exchange protocol (X25519 ECDH + Ed25519 signatures) and AES-128-GCM session encryption.
+
+```python
+from blerpc_protocol.crypto import central_perform_key_exchange, BlerpcCryptoSession
+
+# Perform key exchange (central side)
+session = await central_perform_key_exchange(send=ble_send, receive=ble_receive)
+
+# Encrypt outgoing commands
+ciphertext = session.encrypt(plaintext)
+
+# Decrypt incoming commands
+plaintext = session.decrypt(ciphertext)
+```
+
+## C Library
+
+The C implementation is a Zephyr module with zero external dependencies. Add it to your `west.yml` manifest:
+
+```yaml
+- name: blerpc-protocol
+  url: https://github.com/tdaira/blerpc-protocol
+  revision: main
+  path: modules/lib/blerpc-protocol
+```
+
+Headers are in `c/include/blerpc_protocol/`. See [container.h](c/include/blerpc_protocol/container.h), [command.h](c/include/blerpc_protocol/command.h), and [crypto.h](c/include/blerpc_protocol/crypto.h) for the API.
+
+## Requirements
+
+- Python 3.11+
+
+## License
+
+[Apache-2.0](LICENSE)

blerpc_protocol-0.8.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blerpc-protocol"
+version = "0.8.0"
+description = "Container and command protocol layers for BLE RPC"
+license = "Apache-2.0"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "cryptography>=41.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage = "https://github.com/tdaira/blerpc-protocol"
+Repository = "https://github.com/tdaira/blerpc-protocol"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]

blerpc_protocol-0.8.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blerpc_protocol-0.8.0/src/blerpc_protocol/__init__.py

@@ -0,0 +1,62 @@
+"""blerpc-protocol: Container and command protocol layers for BLE RPC."""
+
+from blerpc_protocol.command import CommandPacket, CommandType
+from blerpc_protocol.container import (
+    ATT_OVERHEAD,
+    CAPABILITY_FLAG_ENCRYPTION_SUPPORTED,
+    CONTROL_HEADER_SIZE,
+    FIRST_HEADER_SIZE,
+    SUBSEQUENT_HEADER_SIZE,
+    Container,
+    ContainerAssembler,
+    ContainerSplitter,
+    ContainerType,
+    ControlCmd,
+    make_capabilities_request,
+    make_capabilities_response,
+    make_error_response,
+    make_key_exchange,
+    make_stream_end_c2p,
+    make_stream_end_p2c,
+    make_timeout_request,
+    make_timeout_response,
+)
+from blerpc_protocol.crypto import (
+    BlerpcCrypto,
+    BlerpcCryptoSession,
+    CentralKeyExchange,
+    KnownKeyStore,
+    PeripheralKeyExchange,
+    central_perform_key_exchange,
+    tofu_verify,
+)
+
+__all__ = [
+    "ATT_OVERHEAD",
+    "BlerpcCrypto",
+    "BlerpcCryptoSession",
+    "CAPABILITY_FLAG_ENCRYPTION_SUPPORTED",
+    "CentralKeyExchange",
+    "CONTROL_HEADER_SIZE",
+    "FIRST_HEADER_SIZE",
+    "SUBSEQUENT_HEADER_SIZE",
+    "CommandPacket",
+    "CommandType",
+    "Container",
+    "ContainerAssembler",
+    "ContainerSplitter",
+    "ContainerType",
+    "ControlCmd",
+    "make_capabilities_request",
+    "make_capabilities_response",
+    "make_error_response",
+    "make_key_exchange",
+    "make_stream_end_c2p",
+    "make_stream_end_p2c",
+    "make_timeout_request",
+    "make_timeout_response",
+    "PeripheralKeyExchange",
+    "KnownKeyStore",
+    "central_perform_key_exchange",
+    "tofu_verify",
+]

blerpc_protocol-0.8.0/src/blerpc_protocol/command.py

@@ -0,0 +1,76 @@
+"""Command encode/decode layer for blerpc.
+
+Command format (bits):
+| type(1) | reserved(7) | cmd_name_len(8) | cmd_name(N*8) |
+| data_len(16) | data(data_len*8) |
+
+- type: 0=request, 1=response
+- cmd_name: ASCII command name
+- data_len: little-endian uint16
+- data: protobuf-encoded bytes
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class CommandType(IntEnum):
+    REQUEST = 0
+    RESPONSE = 1
+
+
+@dataclass
+class CommandPacket:
+    """A single command packet."""
+
+    cmd_type: CommandType
+    cmd_name: str
+    data: bytes = b""
+
+    def serialize(self) -> bytes:
+        """Serialize command to bytes."""
+        name_bytes = self.cmd_name.encode("ascii")
+        if len(name_bytes) > 255:
+            raise ValueError(f"cmd_name too long: {len(name_bytes)} > 255")
+        if len(self.data) > 65535:
+            raise ValueError(f"data too long: {len(self.data)} > 65535")
+
+        # Byte 0: type in MSB (bit 7), reserved bits 6-0 = 0
+        byte0 = (self.cmd_type & 0x01) << 7
+        return (
+            bytes([byte0])
+            + struct.pack("<B", len(name_bytes))
+            + name_bytes
+            + struct.pack("<H", len(self.data))
+            + self.data
+        )
+
+    @staticmethod
+    def deserialize(data: bytes) -> CommandPacket:
+        """Deserialize bytes into a CommandPacket."""
+        if len(data) < 2:
+            raise ValueError(f"Command packet too short: {len(data)} bytes")
+
+        # Byte 0: type in MSB
+        cmd_type = CommandType((data[0] >> 7) & 0x01)
+        cmd_name_len = data[1]
+
+        offset = 2
+        if len(data) < offset + cmd_name_len + 2:
+            raise ValueError("Command packet truncated")
+
+        cmd_name = data[offset : offset + cmd_name_len].decode("ascii")
+        offset += cmd_name_len
+
+        data_len = struct.unpack_from("<H", data, offset)[0]
+        offset += 2
+
+        payload = data[offset : offset + data_len]
+        return CommandPacket(
+            cmd_type=cmd_type,
+            cmd_name=cmd_name,
+            data=payload,
+        )