DLE ASCII encoder for Python

This encoder provides a simple ASCII transport layer for serial data. It uses the C0 and C1 ASCII control characters for this. You can find a corresponding C++ implementation here.

Other pages (online)

This encoder supports two modes:

Escaped mode

The encoded stream starts with a STX marker and ends with an ETX marker. STX and ETX occurrences in the stream are escaped and internally encoded as well so the receiver side can simply check for STX and ETX markers as frame delimiters. When using a strictly char based reception of packets encoded with DLE, STX can be used to notify a reader that actual data will start to arrive while ETX can be used to notify the reader that the data has ended.

Example:

[0, STX, DLE] -> [STX, 0, 0, DLE, STX + 0x40, DLE, DLE, ETX]

Non-escaped mode

The encoded stream starts with DLE STX and ends with DLE ETX. All DLE occurrences in the stream are escaped with DLE. If the receiver detects a DLE char, it needs to read the next char to determine whether a start (STX) or end (ETX) of a frame has been detected.

Example:

[0, STX, DLE] -> [DLE, STX, 0, DLE, STX, DLE, DLE, DLE, ETX]

Examples

Here is an example on how to use the escaped mode

import dle_encoder

encoder = dle_encoder.DleEncoder()
test_array = bytearray([1, 2, 3])
encoded = encoder.encode(test_array)
retval, decoded, bytes_decoded = encoder.decode(encoded)

print(test_array)
print(encoded)
print(decoded)

The non-escaped mode can be used by passing escape_stx_etc=False to the dle_encoder.dle_encoder.DleEncoder constructor.

API Documentation

dle_encoder module

DLE ASCII Encoder Implementation

This encoder provides a simple ASCII transport layer for serial data. A give data stream is encoded by adding a STX char at the beginning and an ETX char at the end. All STX and ETX occurrences in the packet are encoded as well so the receiver can simply look for STX and ETX occurrences to identify packets. You can find a C++ implementation here: https://egit.irs.uni-stuttgart.de/fsfw/fsfw/src/branch/master/globalfunctions/DleEncoder.cpp

class dle_encoder.dle_encoder.DleEncoder(escape_stx_etx: bool = True, escape_cr: bool = False)

Bases: object

Create an encoder instance.

Parameters:

  • escape_stx_etx – Configure the encoder to run in the escaped mode. Currently, this is the only supported mode

  • escape_cr – If running is escaped mode, this flag can be used to escape CR occurrences as well

decode(source_packet: bytes) → Tuple[DleErrorCodes, bytearray, int]

Decodes a given DLE encoded data stream. This call only returns the first packet found.

It might be necessary to call this function multiple times, depending on the third return value.

Returns:

  • DleErrorCode - If decoding has failed, this will not be DleErrorCodes.OK. The function will still return the read length and the decoded bytearray, if any decoding was performed

  • Decoded bytearray - Decoded packet

  • Read length - Read length in the encoded stream. If this is smaller than the length of the passed bytearray, the decoding function should be called again.

encode(source_packet: bytes, add_stx_etx: bool = True) → bytearray

Encodes a given stream with DLE encoding.

Returns:

Encoded bytearray.

read(file: Union[RawIOBase, BytesIO]) → Tuple[DleErrorCodes, bytearray, int]

Read DLE encoded packets from a given file or byte stream

Parameters:

file –

Returns:

  • DleErrorCode - If decoding has failed, this will not be DleErrorCodes.OK. The function will still return the read length and the decoded bytearray, if any decoding was performed. DleErrorCodes.END_REACHED if all bytes have been read but not end marker was detected

  • Decoded bytearray - Decoded packet

  • Read length - Read length in the encoded stream. If this is smaller than the length of the passed bytearray, the decoding function should be called again.

class dle_encoder.dle_encoder.DleErrorCodes(value)

Bases: Enum

An enumeration.

DECODING_ERROR = 2
END_REACHED = 1
OK = 0

Indices and tables