TCOBS

Table of Contents

1. About The project
1. TCOBS Specification
1. TCOBS Framing Encoder and Decoder
- 3.1. TCOBS Encoding
- 3.2. TCOBS Decoding
- 3.3. TCOBS Testing
1. Getting Started
- 4.1. Prerequisites
- 4.2. Installation
- 4.3. Usage in Go
  - 4.3.1. Decoding
  - 4.3.2. Encoding
1. Roadmap
1. Contributing
1. License
1. Contact
- 8.1. Acknowledgments

1. About The project

TCOBS is a variant of COBS combined with real-time RLE data compression especially for short messages containing integers.
The consistent overhead with TCOBS is 1 byte for each starting 31 bytes in the worst case, when no compression is possible. (Example: A 1000 bytes buffer can be encoded with max 33 additional bytes.) This is more compared to the original COBS with +1 byte for each starting 254 bytes but if the data contain integer numbers, as communication packets often do, the encoded data will be statistically shorter with TCOBS compared to the legacy COBS.

(back to top)

2. TCOBS Specification

See ./docs/TCOBSSpecification.md.

(back to top)

3. TCOBS Framing Encoder and Decoder

3.1. TCOBS Encoding

tcobs.h and tcobs.c contain the encoder as C-code.
The encoding in Go is possible with tcobs.go using tcobs.c with CGO.
The Go idiomatic usage is to use a NewEncoder(w io.Writer, size int) (p *encoder) and its Reader interface (see read.go)

3.2. TCOBS Decoding

tcobs.go contains the decoder as Go-code.
The decoding in C is not implemented (yet).
The Go idiomatic usage is to use a NewDecoder(r io.Reader, size int, multi bool) (p *decoder) and its Writer interface (see write.go)

3.3. TCOBS Testing

tcobs_test.go contains test code. CGO is not supported inside test files but usable through Go functions.
- Testing: go test ./...:
The test execution can take several seconds. If your computer is slow you can reduce the loop count in the test functions TestEncodeDecode*.

(back to top)

4. Getting Started

Add ./tcobs.c to your embedded project and use function TCOBSEncode to convert a buffer into TCOBS format.
After transmitting one (or more) TCOBS package(s) transmit a 0-delimiter byte.
Decoding is currently implemented in Go.
- Encoder and Decoder in other languages are easy to implement using the TCOBS specification and the given C- and Go-code.
Contributions are appreciated.

4.1. Prerequisites

Just a C compiler and, for testing, a Go installation.

4.2. Installation

To use TCOBS with Go execute go get github.com/rokath/tcobs

4.3. Usage in Go

For example usage check the tests.

4.3.1. Decoding

The function tcobs.Decode is usable standalone.
Also it is possible to create a Decoder instance and use the Read method.

4.3.2. Encoding

The function tcobs.CEncode is usable standalone.
Also it is possible to create an Encoder instance and use the Write method.

(back to top)

5. Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

6. Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!