cobs-crc16-cbor-core

A TypeScript library for exchanging structured data with small embedded devices using COBS, CRC-16 and a CBOR subset.

• Documentation
• Code

Features

• Implements encoders and decoders for the "Consistent Overhead Byte Stuffing (COBS)"
  • See Wikipedia article for details
• Implements a CRC-16-CCITT calculation, encoders and decoders
  • See Wikipedia article for details
• Implements encoders and decoders for a subset of the "Concise Binary Object Representation (CBOR)" specification
  • See Specification for details
• Implements a minimal remote-procedure-call (RPC) protocol on top of CBOR
• Implements Base64 encoders and decoders.
• Implements combining encoders and decoders
  • COBS <--> CBOR
  • COBS <--> CBOR <--> CBOR-RPC
  • COBS <--> CRC-16
  • COBS <--> CRC-16 <--> CBOR
  • COBS <--> CRC-16 <--> CBOR <--> CBOR-RPC
• Zero production dependencies
• High test coverage

Known issues

• Lack of documentation
  • Especially CBOR-RPC
• CBOR implementation does not support
  • Integers larger than 64-bit
  • Tags

Installation

yarn add cobs-crc16-cbor-core

Usage

Byte stream encoders

The library exports two byte stream encoder classes:

• CobsEncoder: packetizes a byte stream using COBS
• CobsCrc16Encoder: appends a CRC16 to a byte stream and packetizes that using COBS

Both call the onData callback passed to their constructor whenever they have encoded a chunk of bytes. The data gets fed in using the encodeData method, which can be called multiple times to incrementally deliver the byte stream to encode. Once a byte stream has reached its end, the encodeDelimiter method must be called to flush buffered data and reset the encoder/decoder for a new byte stream.

Value encoders

The library exports three value encoder classes:

• CborEncoder: encoded a value into its CBOR byte stream representation
• CobsCborEncoder: encodes a value into its CBOR byte stream representation and packetizes it using COBS (by feeding it through a CobsEncoder)
• CobsCrc16CborEncoder: encodes a value into is CBOR byte stream representation, appends a CRC16 and packetizes that using COBS (by feeding it through a CobsCrc16Encoder)

They also call the onData callback passed to their constructor whenever they have encoded a chunk of bytes.

Byte stream decoders

The library exports two byte stream decoder classes:

• CobsDecoder: decodes a COBS byte stream into packets
• CobsCrc16Decoder: decodes a COBS byte stream into packets, checking the appended CRC16

Both call the onPacket callback passed to their constructor whenever a packet was successfully decoded (and optionally its CRC was correct).

Value decoders

The library exports three value decoder classes:

• CborDecoder: decodes a CBOR value from its byte stream representation
• CobsCborDecoder: decodes a CBOR value from a COBS packet
• CobsCrc16CborDecoder: decodes a CBOR value from a COBS packet that included a CRC16 at the end

They also call the onPacket callback passed to their constructor whenever a value was sucessfully decoded.

Changelog

0.5.0

• BREAKING CHANGES:
  • Add support for 64-bit integers / BigInt.

0.4.0

• Add base64Decode and base64Encode.

0.3.0

• Add documentation and fix several API errors.
• BREAKING CHANGES:
  • Rename CobsCrc16CborRpcEncoder#cobsCborEncoder to CobsCrc16CborRpcEncoder#cobsCrc16CborEncoder

0.2.0

• Add modules for encoding and decoding CBOR-RPC.

0.1.1

• Fix bug where CobsCrc16CborEncoder did not call the provided callbacks.

0.1.0

• Initial release (ported from the Node.js-specific cobs-crc16-cbor-utils package)

License

The MIT License (MIT)

Copyright (c) 2024-present, Daniel Wippermann.

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.