Morelia.Packets package

Submodules

Morelia.Packets.Binary module

class Morelia.Packets.Binary.PacketBinary(pkt: bytes, commands: CommandSet | None = None)

Bases: Packet

Container class that stores a standard binary command packet for a POD device. The format is STX (1 byte) + command number (4 bytes) + length of binary (4 bytes) + checksum (2 bytes) + ETX (1 bytes) + binary (LENGTH bytes) + checksum (2 bytes) + ETX (1 bytes)

binaryLength

Number of bytes of binary data from the packet.

Type:

bytes

binaryData

Variable length binary datafrom the packet.

Type:

bytes

BinaryLength() int

Translate the binary ASCII encoding of the binary data length into a readable integer

Returns:

Integer of the binary data length.

Return type:

int

static CheckIfPacketIsValid(msg: bytes)

Raises an Exception if the packet is incorrectly formatted.

Parameters:

msg (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:
  • Exception – Packet is too small to be a standard packet.

  • Exception – A standard binary packet must have an ETX before the binary bytes.

static GetBinaryData(pkt: bytes) bytes

Gets the binary data from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet.

Returns:

Bytes string containg binary data.

Return type:

bytes

static GetBinaryLength(pkt: bytes) bytes

Gets the length, or number of bytes, of the binary data in a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet.

Returns:

Bytes string of the length of the binary data.

Return type:

bytes

static GetMinimumLength() int

Gets the number of bytes in the smallest possible packet.

Returns:

integer representing the minimum length of a binary POD command packet. Format is STX (1 byte) + command number (4 bytes) + length of binary (4 bytes) + checksum (2 bytes) + ETX (1 bytes) + binary (LENGTH bytes) + checksum (2 bytes) + ETX (1 bytes)

Return type:

int

TranslateAll() dict[str, Any]

Builds a dictionary containing all parts of the POD packet in readable values.

Returns:

Dictionary with the command number, binary packet length, and binary data.

Return type:

dict[str,Any]

UnpackAll() dict[str, bytes]

Builds a dictionary containing all parts of the POD packet in bytes.

Returns:

Dictionary with the command number, binary packet length, and binary data.

Return type:

dict[str,bytes]

Morelia.Packets.Binary4 module

class Morelia.Packets.Binary4.PacketBinary4(pkt: bytes, preampGain: int, commands: CommandSet | None = None)

Bases: Packet

Container class that stores a binary4 command packet for a POD device. The format is STX (1 byte) + command (4 bytes) + packet number (1 byte) + TTL (1 byte) + CH0 (2 bytes) + CH1 (2 bytes) + CH2 (2 bytes) + checksum (2 bytes) + ETX (1 byte).

_preampGain

Preamplifier gain. This should be 10 or 100 for an 8206-HR device.

Type:

int

packetNumber

Packet number for this POD packet.

Type:

bytes

ttl

TTL data for this packet.

Type:

bytes

ch0

channel 0 data for this packet.

Type:

bytes

ch1

channel 1 data for this packet.

Type:

bytes

ch2

channel 2 data for this packet.

Type:

bytes

static BinaryBytesToVoltage(value: bytes, preampGain: int) float

Converts a binary bytes value read from POD device and converts it to the real voltage value at the preamplifier input.

Parameters:

value (bytes) – Bytes string containing voltage measurement.

Returns:

A number containing the voltage in Volts [V].

Return type:

float

Ch(n: int) float

Translates the binary channel n bytes into a voltage.

Parameters:

n (int) – Channel number. Should be 0, 1, or 2.

Raises:

Exception – Channel does not exist.

Returns:

Voltage of channel n in Volts.

Return type:

float

static CheckIfPacketIsValid(msg: bytes)

Raises an Exception if the packet is incorrectly formatted.

Parameters:

msg (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:

Exception – Packet the wrong size to be a binary4 packet.

static GetBinaryLength() int

Gets the number of bytes of binary data in a binary4 packet.

Returns:

Integer representing the number of binary encoded bytes in a binary4 packet.

Return type:

int

static GetCh(n: int, pkt: bytes) bytes

Gets the channel n bytes from a POD packet.

Parameters:
  • n (int) – Channel number. Should be 0, 1, or 2.

  • pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the channel 0 data.

Return type:

bytes

Returns:

Channel does not exist.

Return type:

bytes

static GetMinimumLength() int

Gets the number of bytes in the smallest possible binary4 packet; STX (1 byte) + command (4 bytes) + packet number (1 byte) + TTL (1 byte) + CH0 (2 bytes) + CH1 (2 bytes) + CH2 (2 bytes) + checksum (2 bytes) + ETX (1 byte).

Returns:

Integer representing the minimum length of a binary4 POD packet.

Return type:

int

static GetPacketNumber(pkt: bytes) bytes

Gets the packet number in bytes from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the packet number.

Return type:

bytes

static GetTTL(pkt: bytes) bytes

Gets the TTL bytes from a POD packet

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the TTL data.

Return type:

bytes

PacketNumber() int

Translates the binary packet number into a readable integer.

Returns:

Integer of the packet number.

Return type:

int

TranslateAll() dict[str, Any]

Builds a dictionary containing all parts of the POD packet in readable values.

Returns:

Dictionary with the command number, packet number, TTL and channels 0, 1, and 2.

Return type:

dict[str, Any]

static TranslateBinaryTTLbyte(ttlByte: bytes) dict[str, int]

Separates the bits of each TTL (0-3) from a binary encoded byte.

Parameters:

ttlByte (bytes) – One byte string for the TTL (binary encoded).

Returns:

Dictionary of the TTLs. Values are 1 when input, 0 when output.

Return type:

dict[str,int]

Ttl() dict[str, int]

Translates the binary TTL bytes into a dictionary containing each TTL value.

Returns:

Dictionary with TTL name keys and TTL data as values.

Return type:

dict[str,int]

UnpackAll() dict[str, bytes]

Builds a dictionary containing all parts of the POD packet in bytes.

Returns:

Dictionary with the command number, packet number, TTL and channels 0, 1, and 2.

Return type:

dict[str,bytes]

Morelia.Packets.Binary5 module

class Morelia.Packets.Binary5.PacketBinary5(pkt: bytes, ssGain: dict[str, int | None] = {'A': None, 'B': None, 'C': None, 'D': None}, preampGain: dict[str, int | None] = {'A': None, 'B': None, 'C': None, 'D': None}, commands: CommandSet | None = None)

Bases: Packet

Container class that stores a binary5 command packet for a POD device. The format is STX (1 byte) + command (4 bytes) + packet number (1 byte) + status (1 byte) + channels (9 bytes) + AEXT0 (2 bytes) + AEXT1 (2 bytes) + ATTL1 (2 bytes) + ATTL2 (2 bytes) + ATTL3 (2 bytes) + ATTL4 (2 bytes) + checksum (2 bytes) + EXT (1 byte)

_ssGain

Dictionary with A, B, C, D keys and second stage gain values (1, 5, or None).

Type:

dict[str,int|None]

_preampGain

Dictionary with A, B, C, D keys and preamplifier gain values (10, 100, or None).

Type:

dict[str,int|None]

packetNumber

Packet number for this POD packet.

Type:

bytes

status

Status for this POD packet.

Type:

bytes

channels

channel A, B, C, and D data for this POD packet.

Type:

bytes

aEXT0

Analog EXT0 data for this POD packet.

Type:

bytes

aEXT1

Analog EXT1 data for this POD packet.

Type:

bytes

aTTL1

Analog TTL1 data for this POD packet.

Type:

bytes

aTTL2

Analog TTL2 data for this POD packet.

Type:

bytes

aTTL3

Analog TTL3 data for this POD packet.

Type:

bytes

aTTL4

Analog TTL4 data for this POD packet.

Type:

bytes

AnalogEXT(n: int) float

Translates the analog EXT value into a voltage.

Parameters:

n (int) – Analog EXT number. Should be 0 or 1.

Raises:

Exception – AEXT does not exist.

Returns:

Analog EXT voltage in volts (V).

Return type:

float

AnalogTTL(n: int) float

Translates the analog TTL value into a voltage.

Parameters:

n (int) – Analog TTL number. Should be 1, 2, 3, or 4.

Raises:

Exception – ATTL does not exist.

Returns:

Analog TTL voltage in volts (v).

Return type:

float

Channel(c: str) float

Translates the channel data into a voltage.

Parameters:

c (str) – Channel character. Should be A, B, C, or D.

Raises:

Exception – Channel does not exist.

Returns:

Voltage of the channel in volts (V).

Return type:

float

static CheckIfPacketIsValid(msg: bytes)

Raises an Exception if the packet is incorrectly formatted.

Parameters:

msg (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:

Exception – Packet the wrong size to be a binary5 packet.

static GetAnalogEXT(n: int, pkt: bytes) bytes

Gets the analog EXT from a POD packet.

Parameters:
  • n (int) – Analog EXT number. Should be 0 or 1.

  • pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:

Exception – AEXT does not exist.

Returns:

Bytes string of the AEXT.

Return type:

bytes

static GetAnalogTTL(n: int, pkt: bytes) bytes

Gets the analog TTL from a POD packet.

Parameters:
  • n (int) – Analog TTL number. Should be 1, 2, 3, or 4.

  • pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:

Exception – ATTL does not exist.

Returns:

Bytes string of the ATTL.

Return type:

bytes

static GetBinaryLength() int

Gets the number of bytes of binary data in a binary5 packet.

Returns:

Integer representing the number of binary encoded bytes in a binary5 packet.

Return type:

int

static GetChannels(pkt: bytes) bytes

Gets the channel bytes for channels A, B, C, and D together from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the channels A, B, C, and D together.

Return type:

bytes

static GetMinimumLength() int

Gets the number of bytes in the smallest possible binary4 packet; STX (1 byte) + command (4 bytes) + packet number (1 byte) + status (1 byte) + channels (9 bytes) + AEXT0 (2 bytes) + AEXT1 (2 bytes) + ATTL1 (2 bytes) + ATTL2 (2 bytes) + ATTL3 (2 bytes) + ATTL4 (2 bytes) + checksum (2 bytes) + EXT (1 byte)

Returns:

Integer representing the minimum length of a binary5 POD packet.

Return type:

int

static GetPacketNumber(pkt: bytes) bytes

Gets the packet number in bytes from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the packet number.

Return type:

bytes

static GetStatus(pkt: bytes) bytes

Gets the status value in bytes from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the status.

Return type:

bytes

PacketNumber() int

Translates the binary packet number into a readable integer.

Returns:

Integer of the packet number.

Return type:

int

Status() int

Translates the binary status value into a readable integer

Returns:

Integer status value.

Return type:

int

TranslateAll() dict[str, Any]

Builds a dictionary containing all parts of the POD packet in readable values.

Returns:

Dictionary with the command number, packet number, status, channels, analog EXT, and analog TTL.

Return type:

dict[str, bytes]

UnpackAll() dict[str, bytes]

Builds a dictionary containing all parts of the POD packet in bytes.

Returns:

Dictionary with the command number, packet number, status, channels, analog EXT, and analog TTL.

Return type:

dict[str, bytes]

static _Voltage_PrimaryChannels(value: int, ssGain: int | None = None, PreampGain: int | None = None) float

Converts a value to a voltage for a primary channel.

Parameters:
  • value (int) – Value to be converted to voltage.

  • ssGain (int | None, optional) – Second stage gain. Defaults to None.

  • PreampGain (int | None, optional) – Preamplifier gain. Defaults to None.

Returns:

Number of the voltage in volts [V]. Returns value if no gain is given (no-connect).

Return type:

float

static _Voltage_PrimaryChannels_Biosensor(value: int, ssGain: int) float

Converts a value to a voltage for a biosensor primary channel.

Parameters:
  • value (int) – Value to be converted to voltage.

  • ssGain (int) – Second stage gain.

Returns:

Number of the voltage in volts [V].

Return type:

float

static _Voltage_PrimaryChannels_EEGEMG(value: int, ssGain: int, PreampGain: int) float

Converts a value to a voltage for an EEG/EMG primary channel.

Parameters:
  • value (int) – Value to be converted to voltage.

  • ssGain (int) – Second stage gain.

  • PreampGain (int) – Preamplifier gain.

Returns:

Number of the voltage in volts [V].

Return type:

float

static _Voltage_SecondaryChannels(value: int) float

Converts a value to a voltage for a secondary channel.

Parameters:

value (int) – Value to be converted to voltage.

Returns:

Number of the voltage in volts [V].

Return type:

float

Morelia.Packets.Packet module

class Morelia.Packets.Packet.Packet(pkt: bytes, commands: CommandSet | None = None)

Bases: object

Container class that stores a command packet for a POD device. The format is STX (1 byte) + command number (4 bytes) + data (? bytes) + ETX (1 byte). This class also has a collection of methods for creating and interpreting POD packets.

_commands

Available commands for a POD device.

Type:

POD_Commands | None

rawPacket

Bytes string containing a POD packet. Should begin with STX and end with ETX.

Type:

bytes

commandNumber

Command number from the Pod packet.

Type:

bytes | None

static ASCIIbytesToInt_Split(msg: bytes, keepTopBits: int, cutBottomBits: int) int

Converts a specific bit range in an ASCII-encoded bytes object to an integer.

Parameters:
  • msg (bytes) – Bytes message holding binary information to be converted into an integer.

  • keepTopBits (int) – Integer position of the msb of desired bit range.

  • cutBottomBits (int) – Integer number of lsb to remove.

Returns:

Integer result from the ASCII-encoded bytes message in a given bit range.

Return type:

int

static AsciiBytesToInt(msg_b: bytes, signed: bool = False) int

Converts a ASCII-encoded bytes message into an integer. It does this using a base-16 conversion. If the message is signed and the msb is ‘1’, the integer will be converted to it’s negative 2’s complement.

Parameters:
  • msg_b (bytes) – Bytes message to be converted to an integer. The bytes must be base-16 or the conversion will fail.

  • signed (bool, optional) – True if the message is signed, false if unsigned. Defaults to False.

Returns:

Integer result from the ASCII-encoded byte conversion.

Return type:

int

static BinaryBytesToInt(msg: bytes, byteorder: str = 'big', signed: bool = False) int

Converts binary-encoded bytes into an integer.

Parameters:
  • msg (bytes) – Bytes message holding binary information to be converted into an integer.

  • byteorder (str, optional) – Ordering of bytes. ‘big’ for big endian and ‘little’ for little endian. Defaults to ‘big’.

  • signed (bool, optional) – Boolean flag to mark if the msg is signed (True) or unsigned (False). Defaults to False.

Returns:

Integer result from the binary-encoded bytes message.

Return type:

int

static BinaryBytesToInt_Split(msg: bytes, keepTopBits: int, cutBottomBits: int, byteorder: str = 'big', signed: bool = False) int

Converts a specific bit range in a binary-encoded bytes object to an integer.

Parameters:
  • msg (bytes) – Bytes message holding binary information to be converted into an integer.

  • keepTopBits (int) – Integer position of the msb of desired bit range.

  • cutBottomBits (int) – Integer number of lsb to remove.

  • byteorder (str, optional) – Ordering of bytes. ‘big’ for big endian and ‘little’ for little endian. Defaults to ‘big’.

  • signed (bool, optional) – Boolean flag to mark if the msg is signed (True) or unsigned (False). Defaults to False.

Returns:

Integer result from the binary-encoded bytes message in a given bit range.

Return type:

int

static CheckIfPacketIsValid(msg: bytes)

Raises an Exception if the packet is incorrectly formatted.

Parameters:

msg (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:
  • Exception – Packet must begin with STX.

  • Exception – Packet must end in ETX

CommandNumber() int

Translate the binary ASCII encoding into a readable integer

Returns:

Integer of the command number.

Return type:

int

static ETX() bytes

Get end-of-transmission (ETX) character in bytes. ETX marks the end byte of a POD Packet.

Returns:

Bytes for ETX(0x03).

Return type:

bytes

static GetCommandNumber(pkt: bytes) bytes | None

Gets the command number bytes from a POD packet.

Parameters:

pkt (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Returns:

Bytes string of the command number, if available.

Return type:

bytes|None

static GetMinimumLength() int

Gets the number of bytes in the smallest possible packet; STX (1 byte) + something + ETX (1 byte).

Returns:

integer representing the minimum length of a generic bytes string.

Return type:

int

HasCommandNumber() bool

Checks if the packet has a command number.

Returns:

True if the packet has a command number, False otherwise.

Return type:

bool

HasCommands() bool

Checks if the Packet instance has commands set.

Returns:

True if the commands have been set, false otherwise.

Return type:

bool

static IntToAsciiBytes(value: int, numChars: int) bytes

Converts an integer value into ASCII-encoded bytes.

First, it converts the integer value into a usable uppercase hexadecimal string. Then it converts the ASCII code for each character into bytes. Lastly, it ensures that the final message is the desired length.

Example: if value=2 and numBytes=4, the returned ASCII will show b’0002’, which is ‘0x30 0x30 0x30 0x32’ in bytes. Uses the 2’s complement if the val is negative.

Parameters:
  • value (int) – Integer value to be converted into ASCII-encoded bytes.

  • numChars (int) – Number characters to be the length of the ASCII-encoded message.

Returns:

Bytes that are ASCII-encoded conversions of the value parameter.

Return type:

bytes

static STX() bytes

Get start-of-transmission (STX) character in bytes. STX marks the starting byte of a POD Packet.

Returns:

Bytes for STX (0x02).

Return type:

bytes

TranslateAll() dict[str, Any]

Builds a dictionary containing all parts of the POD packet in readable values.

Raises:

Exception – Nothing to translate.

Returns:

Dictionary with the command number.

Return type:

dict[str,Any]

static TwosComplement(val: int, nbits: int) int

Gets the 2’s complement of the argument value (negative int).

Parameters:
  • val (int) – Negative value to be complemented.

  • nbits (int) – Number of bits in the value.

Returns:

Integer of the 2’s complement for the val.

Return type:

int

UnpackAll() dict[str, bytes]

Builds a dictionary containing all parts of the POD packet in bytes.

Raises:

Exception – Nothing to unpack.

Returns:

Dictionary with the command number.

Return type:

dict[str,bytes]

Morelia.Packets.Standard module

class Morelia.Packets.Standard.PacketStandard(pkt: bytes, commands: CommandSet)

Bases: Packet

Container class that stores a standard command packet for a POD device. The format is STX (1 byte) + command number (4 bytes) + optional payload (? bytes) + checksum (2 bytes) + ETX (1 bytes)

_customPayload

Optional function to translate the payload.

Type:

Callable[[Any],tuple]|None

_customPayloadArgs

Optional arguments for the _customPayload.

Type:

tuple[Any]|None

payload

Optional payload from the packet.

Type:

bytes

static CheckIfPacketIsValid(msg: bytes)

Raises an Exception if the packet is incorrectly formatted.

Parameters:

msg (bytes) – Bytes string containing a POD packet. Should begin with STX and end with ETX.

Raises:

Exception – Packet is too small to be a standard packet.

DefaultPayload() tuple[int]

Splits the payload up into its components and translates the binary ASCII encoding into a readable integer.

Returns:

Tuple with integer values for each component of the payload.

Return type:

tuple[int]

static GetMinimumLength() int

Gets the number of bytes in the smallest possible packet.

Returns:

integer representing the minimum length of a standard POD command packet. Format is STX (1 byte) + command number (4 bytes) + optional packet (? bytes) + checksum (2 bytes) + ETX (1 bytes)

Return type:

int

static GetPayload(pkt: bytes) bytes | None

Gets the payload from a POD packet, if available.

Parameters:

pkt (bytes) – Bytes string containing a POD packet.

Returns:

Bytes string of the payload, if available.

Return type:

bytes|None

HasCustomPayload() bool

Checks if a custom payload has been set.

Returns:

True if there is a custom payload, False otherwise.

Return type:

bool

HasPayload() bool

Checks if this Packet_Standard instance has a payload.

Returns:

True if there is a payload, false otherwise.

Return type:

bool

Payload() tuple | None

Gets the payload as a readable tuple of values.

Returns:

Translated payload, if available.

Return type:

tuple|None

SetCustomPayload(func: Callable[[Any], tuple], args: tuple[Any] | None = None) None

Sets a custom function with optional arguments to translate the payload.

Parameters:
  • func (Callable[[Any],tuple]) – Function to translate the payload.

  • args (tuple[Any], optional) – Arguments . Defaults to None.

TranslateAll() dict[str, Any]

Builds a dictionary containing all parts of the POD packet in readable values.

Returns:

Dictionary with the command number and payload.

Return type:

dict[str,Any]

UnpackAll() dict[str, bytes]

Builds a dictionary containing all parts of the POD packet in bytes.

Returns:

Dictionary with the command number and payload.

Return type:

dict[str,bytes]

Module contents