Skip to content

Home

Jump to bottom
Craig McQueen edited this page May 11, 2017 · 1 revision

Consistent Overhead Byte Stuffing (COBS) implementation in C

This is code for Consistent Overhead Byte Stuffing (COBS) encoding and decoding, in C.

Functions are provided for encoding and decoding according to the basic COBS method. The COBS variants "Zero Pair Elimination" (ZPE) and "Zero Run Elimination" (ZRE) are not implemented.

C code is available elsewhere. But this implementation aims to:

  • be robust: full checking for:
    • Null pointers
    • Output buffer overflow
    • Invalid data when decoding:
      • 0x00 bytes
      • length code value that is bigger than the number of remaining input data bytes
  • use stdint.h
  • be suitable for use in embedded platforms:
    • no dynamic memory allocation
    • still have small code size
    • still be reasonably fast

This also provides a modified version of COBS, called COBS/R.

Modules Provided

|=C file|=.h file|=Short Name|=Long Name| |cobs.c|cobs.h|COBS|Consistent Overhead Byte Stuffing (basic method)| |cobsr.c|cobsr.h|COBS/R|[|Consistent Overhead Byte Stuffing—Reduced]]|

The following are not implemented:

|=Short Name|=Long Name| |COBS/ZPE|Consistent Overhead Byte Stuffing—Zero Pair Elimination| |COBS/ZRE|Consistent Overhead Byte Stuffing—Zero Run Elimination|

References

API Documentation

See the API documentation page for details.

Status

This software is under development, and is beta quality.

The code passes all the unit tests written in Python.

Unit Tests

Unit tests have been developed in Python 2.x, interfacing to the C code using the Python ctypes module. See the UnitTestPython directory.

Dependencies:

  • Python 2.x
  • C compiler that can compile the cobs source code into a shared library (so library for Linux, DLL for Windows). E.g. gcc compiler on Linux; MinGW gcc compiler on Windows.

It requires the code to be compiled into a DLL (Windows) or library file (Linux). A very simple batch file is provided for Windows to do so using the MinGW gcc compiler. For Linux a simple script is provided to create a Linux library file.

Python ctypes is used to create a wrapper that duplicates the interface used by the Python cobs module. Thus the unit tests for the Python module can be reused almost without change (just a changed import). See:

  • test_cobs.py
  • test_cobsr.py

The C library must deal with a pre-allocated output buffer, so must check for output buffer overflows. This behaviour must be unit-tested in addition to the Python unit tests. This code is found in:

  • test_cobs_c.py
  • test_cobsr_c.py

Python Implementation

This is developed in close conjunction with a Python implementation of COBS. The Python implementation includes a C extension, which uses a C implementation that is very similar to this pure C implementation.

License

This is released under the MIT license:

----------------------------------------------------------------------------
Copyright (c) 2010 Craig McQueen

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
----------------------------------------------------------------------------
Clone this wiki locally