protocol¶

Wire-level encoding: hex-ASCII ⇄ word/short/dword/long/float, and message framing. Used internally by bus; most users won’t need to call these directly.

Low-level wire encoding for the Elliptec ELLx ASCII-hex protocol.

Every message is ASCII text: a 1-character device address, a 2-character command mnemonic, and (for some commands) a variable-length hex-ASCII data payload. Multi-byte values are big-endian (“Motorola format”) except the current-curve measurement payload (C1/C2), which the manual specifies as little-endian.

See the manufacturer manual, sections 4-7, for the authoritative description.

tl_elliptec.protocol.is_valid_address(address)[source]¶

Check whether a value is a valid single-hex-digit device address.

Parameters:: address (str) – Candidate address, e.g. "0" or "F".
Returns:: True if address is a one-character string whose upper-cased value is one of 0-9/A-F, else False.
Return type:: bool

tl_elliptec.protocol.encode_int(value, nbytes, signed=False)[source]¶

Encode an integer as big-endian hex-ASCII.

Parameters:

value (int) – The integer to encode.
nbytes (int) – Width of the encoded value, in bytes (the resulting string is 2 * nbytes hex characters).
signed (bool) – If True, encode as 2’s-complement; otherwise unsigned.

Returns:

Upper-case, zero-padded hex-ASCII string, e.g. "003039" for encode_int(12345, 3).

Raises:

ValueError – If value doesn’t fit in nbytes bytes given signed.

Return type:

str

tl_elliptec.protocol.decode_int(hexstr, signed=False)[source]¶

Decode a big-endian hex-ASCII string back to an integer.

Parameters:

hexstr (str) – Hex-ASCII string, e.g. "3039".
signed (bool) – If True, interpret as 2’s-complement; otherwise unsigned.

Returns:

The decoded integer.

Return type:

int

tl_elliptec.protocol.encode_char(value)[source]¶

Encode an unsigned 8-bit value (the protocol’s “char” format).

Parameters:: value (int) – Integer in range 0-255.
Returns:: 2-character upper-case hex-ASCII string, e.g. "0A" for 10.
Return type:: str

tl_elliptec.protocol.decode_char(hexstr)[source]¶

Decode a 2-character hex-ASCII “char” value.

Parameters:: hexstr (str) – 2-character hex-ASCII string, e.g. "0A".
Returns:: The decoded unsigned integer, e.g. 10.
Return type:: int

tl_elliptec.protocol.encode_word(value)[source]¶

Encode an unsigned 16-bit big-endian value (the protocol’s “word” format).

Parameters:: value (int) – Integer in range 0-65535.
Returns:: 4-character upper-case hex-ASCII string, e.g. "3039" for 12345.
Return type:: str

tl_elliptec.protocol.decode_word(hexstr)[source]¶

Decode a 4-character hex-ASCII “word” value.

Parameters:: hexstr (str) – 4-character hex-ASCII string, e.g. "3039".
Returns:: The decoded unsigned integer, e.g. 12345.
Return type:: int

tl_elliptec.protocol.encode_short(value)[source]¶

Encode a signed 16-bit big-endian value (the protocol’s “short” format), 2’s complement.

Parameters:: value (int) – Integer in range -32768 to 32767.
Returns:: 4-character upper-case hex-ASCII string, e.g. "FFFF" for -1.
Return type:: str

tl_elliptec.protocol.decode_short(hexstr)[source]¶

Decode a 4-character hex-ASCII “short” value (signed, 2’s complement).

Parameters:: hexstr (str) – 4-character hex-ASCII string, e.g. "FFFF".
Returns:: The decoded signed integer, e.g. -1.
Return type:: int

tl_elliptec.protocol.encode_dword(value)[source]¶

Encode an unsigned 32-bit big-endian value (the protocol’s “dword” format).

Parameters:: value (int) – Integer in range 0 to 2**32 - 1.
Returns:: 8-character upper-case hex-ASCII string, e.g. "075BCD15" for 123456789.
Return type:: str

tl_elliptec.protocol.decode_dword(hexstr)[source]¶

Decode an 8-character hex-ASCII “dword” value.

Parameters:: hexstr (str) – 8-character hex-ASCII string, e.g. "075BCD15".
Returns:: The decoded unsigned integer, e.g. 123456789.
Return type:: int

tl_elliptec.protocol.encode_long(value)[source]¶

Encode a signed 32-bit big-endian value (the protocol’s “long” format), 2’s complement.

Used for position/offset fields (ma, mr, go/so, gj/ sj, gp/PO, …).

Parameters:: value (int) – Integer in range -2**31 to 2**31 - 1.
Returns:: 8-character upper-case hex-ASCII string, e.g. "FFFFFFFF" for -1.
Return type:: str

tl_elliptec.protocol.decode_long(hexstr)[source]¶

Decode an 8-character hex-ASCII “long” value (signed, 2’s complement).

Parameters:: hexstr (str) – 8-character hex-ASCII string, e.g. "FFFFFFFF".
Returns:: The decoded signed integer, e.g. -1.
Return type:: int

tl_elliptec.protocol.encode_float(value)[source]¶

Encode a float as IEEE-754 single precision, big-endian.

Parameters:: value (float) – The float to encode.
Returns:: 8-character upper-case hex-ASCII string.
Return type:: str

tl_elliptec.protocol.decode_float(hexstr)[source]¶

Decode an 8-character hex-ASCII IEEE-754 single-precision float.

Parameters:: hexstr (str) – 8-character hex-ASCII string.
Returns:: The decoded float.
Return type:: float

tl_elliptec.protocol.encode_le_word(value)[source]¶

Encode an unsigned 16-bit little-endian value.

Only used for the current-curve measurement payload (C1/C2), which the manual specifies as little-endian unlike every other field.

Parameters:: value (int) – Integer in range 0-65535.
Returns:: 4-character upper-case hex-ASCII string.
Return type:: str

tl_elliptec.protocol.decode_le_word(hexstr)[source]¶

Decode a 4-character hex-ASCII little-endian “word” value.

Parameters:: hexstr (str) – 4-character hex-ASCII string.
Returns:: The decoded unsigned integer.
Return type:: int

tl_elliptec.protocol.decode_le_dword(hexstr)[source]¶

Decode an 8-character hex-ASCII little-endian “dword” value.

Parameters:: hexstr (str) – 8-character hex-ASCII string.
Returns:: The decoded unsigned integer.
Return type:: int

tl_elliptec.protocol.build_message(address, command, data='')[source]¶

Build a raw outgoing frame: ADDRESS + COMMAND + DATA (no terminator needed on TX).

Parameters:

address (str) – Single hex-digit device address, e.g. "0".
command (str) – 2-character command mnemonic, e.g. "in".
data (str) – Optional hex-ASCII data payload.

Returns:

The ASCII-encoded frame bytes, e.g. b"0in".

Raises:

ValueError – If address isn’t a valid single hex digit, or command isn’t exactly 2 characters.

Return type:

bytes

tl_elliptec.protocol.parse_message(raw)[source]¶

Split a received frame (terminator already stripped) into (address, command, data).

Parameters:: raw (bytes) – Raw frame bytes, e.g. b"0GS00".
Returns:: A (address, command, data) tuple, e.g. ("0", "GS", "00").
Raises:: ValueError – If raw decodes to fewer than 3 characters.
Return type:: tuple[str, str, str]