Package: cobs
Author:Craig McQueenContact:http://craig.mcqueen.id.au/Copyright:2010 Craig McQueenPython functions for encoding and decoding COBS.IntroThecobspackage is provided, which contains modules containing functions
for encoding and decoding according to COBS methods.What Is COBS?COBS is a method of encoding a packet of bytes into a form that contains no
bytes with value zero (0x00). The input packet of bytes can contain bytes
in the full range of 0x00 to 0xFF. The COBS encoded packet is guaranteed to
generate packets with bytes only in the range 0x01 to 0xFF. Thus, in a
communication protocol, packet boundaries can be reliably delimited with 0x00
bytes.The COBS encoding does have to increase the packet size to achieve this
encoding. However, compared to other byte-stuffing methods, the packet size
increase is reasonable and predictable. COBS always adds 1 byte to the
message length. Additionally, for longer packets of lengthn, itmayadd
n/254 (rounded down) additional bytes to the encoded packet size.For example, compare to the PPP protocol, which uses 0x7E bytes to delimit
PPP packets. The PPP protocol uses an “escape” style of byte stuffing,
replacing all occurences of 0x7E bytes in the packet with 0x7D 0x5E. But that
byte-stuffing method can potentially double the size of the packet in the
worst case. COBS uses a different method for byte-stuffing, which has a much
more reasonable worst-case overhead.For more details about COBS, see the references[1][2].I have included a variant on COBS,COBS/R, which slightly modifies COBS to
often avoid the +1 byte overhead of COBS. So in many cases, especially for
smaller packets, the size of a COBS/R encoded packet is the same size as the
original packet. See below for more details aboutCOBS/R.References[1](1,2,3,4)Consistent Overhead Byte StuffingStuart Cheshire and Mary BakerIEEE/ACM Transations on Networking, Vol. 7, No. 2, April 1999[2](1,2)PPP Consistent Overhead Byte Stuffing (COBS)PPP Working Group Internet DraftJames Carlson, IronBridge NetworksStuart Cheshire and Mary Baker, Stanford UniversityNovember 1997Modules ProvidedModuleShort NameLong Namecobs.cobsCOBSConsistent Overhead Byte Stuffing (basic method)[1]cobs.cobsrCOBS/RConsistent Overhead Byte Stuffing–Reduced“Consistent Overhead Byte Stuffing–Reduced” (COBS/R) is my own invention,
a modification of basic COBS encoding, and is described in more detail below.The following are not implemented:Short NameLong NameCOBS/ZPEConsistent Overhead Byte Stuffing–Zero Pair Elimination[1]COBS/ZREConsistent Overhead Byte Stuffing–Zero Run Elimination[2]A pure Python implementation and a C extension implementation are provided. If
the C extension is not available for some reason, the pure Python version will
be used.UsageThe modules provide anencodeand adecodefunction.The input should be a byte string, not a Unicode string. Basic usage:>>> from cobs import cobs
>>> encoded = cobs.encode(b'Hello world\x00This is a test')
>>> encoded
b'\x0cHello world\x0fThis is a test'
>>> cobs.decode(encoded)
b'Hello world\x00This is a test'COBS/Rusage is almost identical:>>> from cobs import cobsr
>>> encoded = cobsr.encode(b'Hello world\x00This is a test')
>>> encoded
b'\x0cHello worldtThis is a tes'
>>> cobsr.decode(encoded)
b'Hello world\x00This is a test'Any type that implements the buffer protocol, providing a single block of
bytes, is also acceptable as input:>>> from cobs import cobs
>>> encoded = cobs.encode(bytearray(b'Hello world\x00This is a test'))
>>> encoded
b'\x0cHello world\x0fThis is a test'
>>> cobs.decode(encoded)
b'Hello world\x00This is a test'Note that theencodefunction does not add any framing0x00byte at
the end (or beginning) of the encoded data. Similarly, thedecodefunction
does not strip or split on any framing0x00bytes, but treats any0x00bytes as a data input error. The details of data framing is
application-specific, so it is the user’s application’s responsibility to
implement the framing and deframing that is suitable for the needs of the
application.Supported Python VersionsPython >= 3.6 are supported, and have both a C extension and a pure Python
implementation.Python versions < 3.6 might work, but have not been tested.InstallationThe cobs package is installed usingdistutils.  If you have the tools
installed to build a Python extension module, run the following command:python setup.py installIf you cannot build the C extension, you may install just the pure Python
implementation, using the following command:python setup.py build_py install --skip-buildUnit TestingBasic unit testing is in thetestsub-module, e.g.cobs.cobs.test. To run it:python -m cobs.cobs.test
python -m cobs.cobsr.testDocumentationDocumentation is written with Sphinx. Source files are provided in thedocdirectory. It can be built using Sphinx 0.6.5. It uses thepngmathSphinx
extension, which requires Latex anddvipngto be installed.The documentation is available online at:http://packages.python.org/cobs/LicenseThe code is released under the MIT license. See LICENSE.txt for details.Consistent Overhead Byte Stuffing–Reduced (COBS/R)A modification of COBS, which I’m calling “Consistent Overhead Byte
Stuffing–Reduced” (COBS/R), is provided in thecobs.cobsrmodule. Its
purpose is to save one byte from the encoded form in some cases. Plain COBS
encoding always has a +1 byte encoding overhead. See the references for
details[1]. COBS/R can often avoid the +1 byte, which can be a useful
savings if it is mostly small messages that are being encoded.In plain COBS, the last length code byte in the message has some inherent
redundancy: if it is greater than the number of remaining bytes, this is
detected as an error.In COBS/R, instead we opportunistically replace the final length code byte with
the final data byte, whenever the value of the final data byte is greater than
or equal to what the final length value would normally be. This variation can be
unambiguously decoded: the decoder notices that the length code is greater than
the number of remaining bytes.ExamplesThe byte values in the examples are in hex.First example:Input:2FA200927302This example is encoded the same in COBS and COBS/R. Encoded (length code bytes
are bold):032FA204927302Second example:The second example is almost the same, except the final data byte value is
greater than what the length byte would be.Input:2FA200927326Encoded in plain COBS (length code bytes are bold):032FA204927326Encoded in COBS/R:032FA2269273Because the last data byte (26) is greater than the usual length code
(04), the last data byte can be inserted in place of the length code, and
removed from the end of the sequence. This avoids the usual +1 byte overhead of
the COBS encoding.The decoder detects this variation on the encoding simply by detecting that the
length code is greater than the number of remaining bytes. That situation would
be a decoding error in regular COBS, but in COBS/R it is used to save one byte
in the encoded message.