{"id":51421897,"url":"https://github.com/firechip/cobs-conformance","last_synced_at":"2026-07-05T00:17:23.788Z","repository":{"id":369356389,"uuid":"1289141995","full_name":"firechip/cobs-conformance","owner":"firechip","description":"Canonical conformance test vectors for COBS and COBS/R byte stuffing (single source of truth across language implementations).","archived":false,"fork":false,"pushed_at":"2026-07-04T22:11:20.000Z","size":737,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T22:14:22.072Z","etag":null,"topics":["byte-stuffing","cobs","cobs-r","conformance","framing","serialization","test-vectors"],"latest_commit_sha":null,"homepage":"https://firechip.github.io/cobs-conformance/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firechip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-04T11:32:45.000Z","updated_at":"2026-07-04T22:11:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/firechip/cobs-conformance","commit_stats":null,"previous_names":["firechip/cobs-conformance"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/firechip/cobs-conformance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firechip%2Fcobs-conformance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firechip%2Fcobs-conformance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firechip%2Fcobs-conformance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firechip%2Fcobs-conformance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firechip","download_url":"https://codeload.github.com/firechip/cobs-conformance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firechip%2Fcobs-conformance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35140187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["byte-stuffing","cobs","cobs-r","conformance","framing","serialization","test-vectors"],"created_at":"2026-07-05T00:17:23.247Z","updated_at":"2026-07-05T00:17:23.771Z","avatar_url":"https://github.com/firechip.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cobs-conformance\n\n[![CI](https://github.com/firechip/cobs-conformance/actions/workflows/ci.yml/badge.svg)](https://github.com/firechip/cobs-conformance/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nCanonical **conformance test vectors** for **Consistent Overhead Byte Stuffing\n(COBS)** and **COBS/R (Reduced)**. This is the single source of truth that keeps\nthe Firechip COBS implementations byte-identical across languages, and it lets\nany third-party implementation prove conformance too.\n\n## What is COBS?\n\nCOBS encodes an arbitrary byte string into one that contains no zero (`0x00`)\nbytes, at a small, predictable cost (at most one extra byte per 254 bytes, plus\none). A single `0x00` can then reliably delimit packets on a byte stream. See\nCheshire \u0026 Baker, *\"Consistent Overhead Byte Stuffing\"*, IEEE/ACM Transactions\non Networking, Vol. 7, No. 2, April 1999. COBS/R is a variant by Craig McQueen\nthat often removes the trailing overhead byte.\n\n## The vectors\n\n`vectors/vectors.jsonl` is [JSON Lines](https://jsonlines.org): one JSON object\nper line, all fields lowercase hex strings:\n\n```json\n{\"decoded\":\"\",\"cobs\":\"01\",\"cobsr\":\"01\"}\n{\"decoded\":\"02\",\"cobs\":\"0202\",\"cobsr\":\"02\"}\n{\"decoded\":\"110022\",\"cobs\":\"02110222\",\"cobsr\":\"021122\"}\n{\"decoded\":\"3132333435\",\"cobs\":\"063132333435\",\"cobsr\":\"3531323334\"}\n```\n\n| Field | Meaning |\n| ----- | ------- |\n| `decoded` | the original bytes (hex) |\n| `cobs` | the basic-COBS encoding of `decoded` (hex) |\n| `cobsr` | the COBS/R encoding of `decoded` (hex) |\n\nThe set covers every single-byte value, zero/non-zero runs around the 254-byte\nblock boundaries, the full `0x00..0xFF` ramp, and a large deterministic\npseudo-random sample biased toward edge cases.\n\n### Extended vectors\n\nTwo companion files cover the capabilities beyond the plain `0x00` codec (all\nfields are still lowercase hex).\n\n`vectors/sentinel.jsonl` — the **configurable-sentinel** codec, where an\narbitrary byte (not `0x00`) is the value the encoding avoids. Encoding is\nXOR-over-the-finished-stream, so a `sentinel` of `00` equals the plain codec:\n\n```json\n{\"decoded\":\"1100aa\",\"sentinel\":\"aa\",\"cobs\":\"a8bba800\",\"cobsr\":\"a8bb00\"}\n```\n\n| Field | Meaning |\n| ----- | ------- |\n| `decoded` | the original bytes (hex) |\n| `sentinel` | the delimiter byte the encoding avoids (one hex byte) |\n| `cobs` / `cobsr` | the sentinel encoding of `decoded` (hex) |\n\n`vectors/errors.jsonl` — decode **outcomes** for raw, often malformed frames, so\nerror behaviour is conformance-checked too:\n\n```json\n{\"encoded\":\"0511\",\"cobs\":null,\"cobsr\":\"1105\"}\n```\n\n| Field | Meaning |\n| ----- | ------- |\n| `encoded` | a raw frame to decode (hex) |\n| `cobs` | basic-COBS decode result (hex), or `null` if decoding must fail |\n| `cobsr` | COBS/R decode result (hex), or `null` if decoding must fail |\n\nThe same bytes can be valid COBS/R (a reduced final block) yet invalid basic\nCOBS (a truncated frame) — the example above is exactly that divergence.\n\n## Conform your implementation\n\nFor every line, decode the hex fields and assert:\n\n1. `your_cobs_encode(decoded) == cobs`\n2. `your_cobsr_encode(decoded) == cobsr`\n3. `your_cobs_decode(cobs) == decoded` and `your_cobsr_decode(cobsr) == decoded`\n4. neither `cobs` nor `cobsr` contains a `0x00` byte\n\nCI in each implementation repo downloads this file and runs exactly these\nchecks.\n\n## Regenerating / verifying\n\nPure Python 3, no dependencies:\n\n```console\npython generate.py                    # rewrites vectors/vectors.jsonl (deterministic)\npython verify.py vectors/vectors.jsonl # checks the file against reference.py\n```\n\n`reference.py` is the canonical reference implementation the vectors are\ngenerated from.\n\n## Implementations\n\nThe Firechip COBS family, all verified byte-identical against these vectors:\n\n| Language | Package |\n| -------- | ------- |\n| Rust | [`cobs_codec_rs`](https://crates.io/crates/cobs_codec_rs) ([repo](https://github.com/firechip/cobs_codec_rs)) |\n| Dart / Flutter | [`cobs_codec`](https://pub.dev/packages/cobs_codec) ([repo](https://github.com/firechip/cobs_codec)) |\n| Kotlin / Android | [`cobs_codec`](https://github.com/firechip/cobs_codec_kt) (Maven `dev.firechip:cobs_codec`) |\n| Swift (macOS/iOS/Linux) | [`CobsCodec`](https://github.com/firechip/cobs_codec_swift) (Swift Package Manager) |\n\n### Feature comparison\n\nHow the family compares with Craig McQueen's reference implementations and other\necosystem crates. Legend: ✓ supported · ◐ partial · ○ not supported · · not\napplicable.\n\n| Feature | `cobs_codec_rs` | `cobs_codec` · Dart | `cobs_codec` · Kotlin | `CobsCodec` · Swift | cobs-c | cobs · Python | libcobs | cobs · jamesmunns | cobs-codec · alvra | GlassGem · Swift | SerialFiller · C++ | KiTools · Python | espp · C++ |\n| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n| Basic COBS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |\n| COBS/R (reduced) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |\n| Configurable sentinel | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ○ | ✓ | ✓ | ○ | ○ | ○ | ○ |\n| In-place decode | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ○ | ✓ | ○ | ○ | ○ | ○ | ○ |\n| Incremental / streaming decode | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ○ | ✓ | ✓ (async) | ○ | ○ | ✓ | ✓ |\n| Frame delimiting | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ○ | ◐ | ✓ | ◐ | ○ | ◐ | ✓ |\n| Size helpers (max length) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ○ | ✓ | ○ | ○ | ○ | ○ | ✓ |\n| Typed error reporting | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ◐ | ✓ | ✓ | ○ | ✓ | ◐ | ○ |\n| `no_std` / freestanding | ✓ | · | · | · | ✓ | ○ | ✓ | ✓ | ○ | · | ○ | · | ○ |\n| Zero dependencies | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ○ | ○ | ✓ | ✓ | ○ | ○ |\n| Native framework hooks | ◐ (serde/defmt) | ✓ (`dart:convert`) | ✓ (java.io/Flow) | ○ | ○ | ○ | ○ | ◐ (serde/defmt) | ✓ (tokio-util) | ○ | ○ | ○ | ✓ (ESP-IDF) |\n| Verified against these vectors | ✓ | ✓ | ✓ | ✓ | source | source | ○ | ○ | ○ | ○ | ○ | ○ | ○ |\n\nThe first four columns are the Firechip family. **cobs-c** and **cobs** (Python)\nare McQueen's references and the *source* of these vectors. **libcobs** is a\nminimal basic-COBS implementation. **cobs** (jamesmunns) is the de-facto embedded\nRust crate, rich but with no COBS/R and not dependency-free. **cobs-codec**\n(alvra) is an async Tokio framing codec. **GlassGem** (armadsen) is a third-party\nSwift `Data` extension implementing basic COBS only — Foundation-based, with no\nCOBS/R and no configurable delimiter (both on its roadmap), which the family's\nstdlib-only `CobsCodec` provides. **SerialFiller** (gbmhunter) and **KiTools**\n(Kirale) embed basic COBS inside larger tools — a C++ serial-framing library and\na Python Thread / 802.15.4 CLI — rather than shipping it as a reusable package;\nKiTools is notable for a byte-for-byte streaming decoder. **espp** (esp-cpp) is\nEspressif's ESP-IDF C++ component: basic COBS with a thread-safe streaming\ndecoder and framing baked into `encode`, but no COBS/R, no configurable\nsentinel, and sentinel-value (not typed) errors. It always appends the trailing\n`0x00` delimiter and silently drops empty packets, so — unlike the rest of the\ntable — it is **not** byte-identical with the plain codec (an empty input encodes\nto nothing, where standard COBS emits `01`).\n\n## License\n\nMIT (c) 2026 Alexander Salas Bastidas ([Firechip](https://firechip.dev)). See\n[LICENSE](LICENSE). COBS/R and the reference implementation follow Craig\nMcQueen's MIT-licensed work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirechip%2Fcobs-conformance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirechip%2Fcobs-conformance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirechip%2Fcobs-conformance/lists"}