Commit 525e44a

[](https://github.com/devkyato/OpenNet/releases)

OpenNet is a dependency-free typed messaging protocol for direct communication

between ESP32 devices, Raspberry Pi computers, and backend services. It sends

JSON, text, signed integers, finite doubles, booleans, null, and arbitrary binary

data over TCP/TLS or another reliable ordered stream.

Version 0.1.1 is an alpha release for real projects and learning. It has a

documented wire format, bounded resource use, retries and duplicate suppression,

native Arduino protocol tests, Python tests across 3.9–3.14, reproducible release

packages, measured local performance, and security guidance. It does not claim

that a radio or internet route exists when the underlying hardware/network is

unavailable.

- One small API and one frame format across ESP32 and Python.

- Typed values without a JSON dependency for every scalar or binary payload.

- Optional application ACKs, retry with stable message IDs, and bounded

duplicate suppression.

- TCP/TLS over Wi-Fi, Ethernet, or routed networks.

- Generic Arduino `Stream` support for UART, USB serial, and Bluetooth Classic

SPP on compatible ESP32 hardware.

- Strict control frames, CRC-32 corruption detection, payload limits, bounded

queues, connection limits, and partial transport-write handling.

- CLI tools to serve, send, ping, and benchmark.

- Arduino IDE, PlatformIO/VS Code, Python, Linux/systemd, and security tutorials.

Python wheel from the release page:

python -m pip install \

https://github.com/devkyato/OpenNet/releases/download/v0.1.1/opennet_protocol-0.1.1-py3-none-any.whl

opennet --version

For an isolated command:

For Raspberry Pi/Linux, extract `OpenNet-linux-0.1.1.tar.gz` and run

`sudo ./install.sh`. It creates a hardened, unprivileged systemd service with a

loopback-only default. For Arduino IDE, install `OpenNet-0.1.1.zip` through

**Sketch > Include Library > Add .ZIP Library**.

The Python distribution is installable with pip, but v0.1.1 is distributed from

GitHub Releases rather than the public PyPI index.

Terminal one:

opennet serve --echo

Terminal two:

opennet ping --count 5

opennet send sensor/temperature 24.7 --type float

opennet send device/state '{"online":true}' --type json

opennet benchmark --count 1000 --payload-size 64

Python code is equally small:

async with OpenNetClient("127.0.0.1") as client:

message_id = await client.send(

"lab/temperature", 24.7, retries=2

)

print("acknowledged", message_id)

The CLI defaults to loopback and refuses remote plaintext unless it is explicitly

allowed for a trusted development network. Use verified TLS—and mutual TLS when

device identity matters—outside isolated local testing.

- [Measured TCP/TLS and 20-client load results](docs/benchmarks.md)

- [Comparison with raw TCP, MQTT, WebSocket, and HTTP](docs/comparison.md)

- [Architecture, ACK retry, and defensive boundaries](docs/architecture.md)

- [Actual GitHub adoption counters and analytics limits](docs/adoption-analytics.md)

- [Transport support, including Bluetooth boundaries](docs/transports.md)

Measured loopback results are software baselines, not invented Wi-Fi or hardware

claims. Hardware field reports are welcome through the

[compatibility process](docs/compatibility.md).

- [Tutorials](docs/tutorials.md)

- [CLI reference](docs/cli.md)

- [Linux/Raspberry Pi service guide](docs/linux-service.md)

- [Getting started](docs/getting-started.md)

- [Development tips](docs/tips.md)

- [Security guide](docs/security.md)

- [ONP/1 protocol specification](docs/protocol.md)

- [Contributing](CONTRIBUTING.md)

Student contributions are welcome. Good changes include a reproducible test,

clear documentation, or a complete compatibility report. OpenNet follows

[Semantic Versioning](https://semver.org/) and is licensed under the

[MIT License](LICENSE).

The CLI defaults to loopback and requires an explicit flag for remote plaintext.

Mutual TLS is available when deployments must authenticate client devices. See the

[security guide](docs/security.md) for commands, limits, and deployment checklists.

OpenNet does not collect telemetry from library users. The only current adoption

signals are aggregate GitHub repository and release counters.

Snapshot queried from the GitHub API on 2026-07-29:

| Signal | Actual value |

|---|---:|

| GitHub views in returned 14-day window | 0 |

| Unique viewers in returned window | 0 |

| Git clones in returned window | 1 |

| Unique cloners in returned window | 1 |

| Stars | 0 |

| Forks | 0 |

| Watchers/subscribers | 1 |

| Open issues | 3 |

| v0.1.0 release asset downloads | 0 |

These values are a transparent early-project baseline, not evidence of a user

population. GitHub traffic is a rolling window and may lag. Demographic data

(age, location, school, occupation, or device ownership) is unavailable and

should not be guessed. Future releases can report platform compatibility and

opt-in survey results without adding tracking to the library.

OpenNet separates ONP/1 framing from the byte stream carrying it. Both endpoints

must provide a reliable, ordered stream; Wi-Fi itself is not required.

The Python package provides the reference codec and asyncio TCP/TLS client and

server. The Arduino implementation accepts either a `Client` (`WiFiClient`,

`WiFiClientSecure`) or an already-open Arduino `Stream` (`Serial`,

`BluetoothSerial`). The frame bytes are identical across transports.

BLE GATT is packet-oriented, not a continuous byte stream. It needs an adapter

that fragments and reassembles ONP frames; v0.1.1 does not claim direct BLE

support. ESP32-C3/S3 boards also do not provide Bluetooth Classic SPP.

Python retries reuse the message ID, and the server suppresses duplicate handler

execution within a configurable bounded window. An ACK proves that the peer

parsed and accepted the frame; it does not make delivery durable across power

loss. Durable applications must persist outbound messages and application state.

- Payload, topic, receive-queue, connection, and duplicate-window bounds prevent

unbounded routine growth.

- The CRC-32 catches accidental corruption before the application sees a value.

- Strict type and control-frame validation rejects malformed inputs.

- Remote CLI connections require TLS unless plaintext is explicitly enabled.

- TLS provides confidentiality and server identity; mutual TLS can also identify

clients.

See [Security](security.md) for the trust model and [Transports](transports.md)

for supported connection types.

These are actual controlled measurements from the v0.1.1 worktree on

2026-07-29. They are reproducible with `benchmarks/loopback.py`; they are not

estimates and are not presented as Wi-Fi, Bluetooth, Raspberry Pi, or ESP32

field results.

Environment: Windows 11 build 26200, AMD64 Family 25 Model 68, CPython 3.14.4,

IPv4 loopback. Each row uses one warm-up message per client and then times a

complete DATA-to-ACK round trip. TLS used a locally generated RSA-2048

certificate with certificate validation enabled.

| Transport | Clients | Payload | Messages | p50 | p95 | Mean | Throughput |

|---|---:|---:|---:|---:|---:|---:|---:|

| TCP | 1 | 0 B | 1,000 | 0.164 ms | 0.279 ms | 0.195 ms | 5,069.6 msg/s |

| TCP | 1 | 64 B | 1,000 | 0.156 ms | 0.264 ms | 0.178 ms | 5,566.1 msg/s |

| TCP | 1 | 1 KiB | 1,000 | 0.159 ms | 0.265 ms | 0.186 ms | 5,346.0 msg/s |

| TCP | 1 | 64 KiB | 1,000 | 0.224 ms | 0.329 ms | 0.245 ms | 4,045.8 msg/s |

| TLS | 1 | 0 B | 1,000 | 0.231 ms | 0.351 ms | 0.262 ms | 3,578.0 msg/s |

| TLS | 1 | 64 B | 1,000 | 0.226 ms | 0.340 ms | 0.254 ms | 3,843.5 msg/s |

| TLS | 1 | 1 KiB | 1,000 | 0.236 ms | 0.357 ms | 0.265 ms | 3,712.9 msg/s |

| TLS | 1 | 64 KiB | 1,000 | 0.361 ms | 0.572 ms | 0.434 ms | 2,270.7 msg/s |

| TCP load | 20 | 64 B | 2,000 | 2.879 ms | 5.296 ms | 3.177 ms | 5,861.5 msg/s |

The run proves that the codec, client, server, ACK path, concurrency handling,

and verified TLS path work together on this local device under the stated load.

Loopback removes radio interference and network hops, so these numbers are a

software baseline—not a prediction for a real deployment. Wi-Fi latency depends

on signal, access-point congestion, power saving, and hardware. Bluetooth SPP

depends on radio and serial baud/stack behavior.

For a field report, record the exact board, firmware, access point, distance/RSSI,

payload mix, TLS mode, run duration, reconnects, failures, and p50/p95/p99. The

[compatibility guide](compatibility.md) contains a report checklist.