Morelia.Devices package

Subpackages

Submodules

Morelia.Devices.BasicPodProtocol module

class Morelia.Devices.BasicPodProtocol.Pod(port, baudrate=9600, device_name=None)

Bases: object

Pod handles basic communication with a generic POD device, including reading and writing packets and packet interpretation. This is the parent class for any device that communcates using the POD protocol.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • baudrate (int) – Baud rate of the opened serial port. Default value is 9600.

  • device_name (str | None) – Virtual Name used to indentify device.

static build_pod_packet_standard(command_number, payload=None)

Builds a standard POD packet (control packet) as bytes: STX (1 byte) + command number (4 bytes) + optional packet (? bytes) + checksum (2 bytes)+ ETX (1 bytes).

Parameters:

  • command_number (int) – Integer representing the command number. This will be converted into a 4 byte long ASCII-encoded bytes string.

  • payload (bytes | None) – bytes string containing the payload. Defaults to None.

Return type:

bytes

Returns:

Bytes string of a complete standard POD packet.

static checksum(bytes_in)

Calculates the checksum of a given bytes message. This is achieved by summing each byte in the message, inverting, and taking the last byte.

Parameters:

bytes_in (bytes) – Bytes message containing POD packet data.

Return type:

bytes

Returns:

Two ASCII-encoded bytes containing the checksum for bytes_in.

static choose_port(forbidden=[])

Checks user’s Operating System, and chooses ports accordingly.

Parameters:

forbidden (list[str]) – List of port names that are already used. Defaults to an empty list.

Return type:

str

Returns:

Name of the port.

property device_name: str

The virtual device name.

flush_port()

Reset the input and output serial port buffer.

Return type:

bool

Returns:

True of the buffers are flushed, False otherwise.

get_device_commands()

Gets the dictionary containing the class instance’s available POD commands.

Return type:

dict[int, list[str | tuple[int] | bool]]

Returns:

Dictionary containing the available commands and their information.Formatted as key(command number) : value([command name, number of argument ASCII bytes, number of return bytes, binary flag ])

get_pod_packet(cmd, payload=None)

Builds a POD packet and writes it to a POD device via COM port. If an integer payload is give, the method will convert it into a bytes string of the length expected by the command. If a bytes payload is given, it must be the correct length.

Parameters:

  • cmd (str | int) – Command number.

  • payload (int | bytes | tuple[int | bytes]) – None when there is no payload. If there is a payload, set to an integer value, bytes string, or tuple. Defaults to None.

Return type:

bytes

Returns:

Bytes string of the POD packet.

static get_u(u)

Number of hexadecimal characters for an unsigned u-bit value.

Parameters:

u (int) – 8, 16, or 32 bits. Enter any other number for NO_VALUE.

Return type:

int

Returns:

number of hexadecimal characters for an unsigned u-bit value.

static payload_to_bytes(payload, arg_sizes)

Converts a payload into a bytes string (assuming that the payload is for a valid command).

Parameters:

  • payload (int | bytes | tuple[int | bytes]) – Integer, bytes, or tuple containing the payload.

  • arg_sizes (tuple[int]) – Tuple of the argument sizes.

Return type:

bytes

Returns:

Bytes string of the payload.

read_pod_packet(validate_checksum=True, timeout_sec=5)

Reads a complete POD packet, either in standard or binary format, beginning with STX and ending with ETX. Reads first STX and then starts recursion.

Parameters:

  • validate_checksum (bool) – Set to True to validate the checksum. Set to False to skip validation. Defaults to True.

  • timeout_sec (int | float) – Time in seconds to wait for serial data. Defaults to 5.

Return type:

PodPacket

Returns:

POD packet beginning with STX and ending with ETX. This may be a control packet, data packet, or an unformatted packet (STX+something+ETX).

set_baudrate_of_device(baudrate)

If the port is open, it will change the baud rate to the parameter’s value.

Parameters:

baudrate (int) – Baud rate to set for the open serial port.

Return type:

bool

Returns:

True if successful at setting the baud rate, false otherwise.

test_connection(ping_cmd='PING')

Tests if a POD device can be read from or written. Sends a PING command.

Parameters:

ping_cmd (str | int) – Command name or number to ping. Defaults to β€˜PING’.

Return type:

bool

Returns:

True for successful connection, false otherwise.

write_packet(cmd, payload=None)

Builds a POD packet and writes it to the POD device.

Parameters:

  • cmd (str | int) – Command number.

  • payload (int | bytes | tuple[int | bytes]) – None when there is no payload. If there is a payload, set to an integer value, bytes string, or tuple. Defaults to None.

Return type:

ControlPacket

Returns:

Packet that was written to the POD device.

write_read(cmd, payload=None, validate_checksum=True, timeout_sec=5)

Writes a command with optional payload to POD device, then reads (once) the device response.

Parameters:

  • cmd (str | int) – Command number.

  • payload (int | bytes | tuple[int | bytes]) – None when there is no payload. If there is a payload, set to an integer value or a bytes string. Defaults to None.

  • validate_checksum (bool) – Set to True to validate the checksum. Set to False to skip validation. Defaults to True.

Return type:

PodPacket

Returns:

POD packet beginning with STX and ending with ETX. This may be a control packet, data packet, or an unformatted packet (STX+something+ETX).

Morelia.Devices.PodDevice_8206HR module

class Morelia.Devices.PodDevice_8206HR.Pod8206HR(port, preamp_gain, baudrate=9600, device_name=None)

Bases: AquisitionDevice

Pod8206HR is used to interact with a 8206HR data aquisition device.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • preamp_gain (int) – A unitless number used to add gain to vlues recived from the preamplifier. Used in converting streaming data from the device into something human-readable. Must be 10 or 100.

  • baudrate (int) – Baud rate of the opened serial port. Default value is 9600.

  • device_name (str | None) – Virtual name used to indentify device.

Morelia.Devices.PodDevice_8229 module

class Morelia.Devices.PodDevice_8229.Pod8229(port, baudrate=19200, device_name=None)

Bases: Pod

POD8229 handles communication with a 8229 POD device.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • baudrate (int) – Integer baud rate of the opened serial port. Used when initializing the COM_io instance. Defaults to 19200.

  • device_name (str | None) – Virtual name used to identify device.

static build_set_day_schedule_argument(day, hours, speed)

Appends the day of the week code to the front of the encoded hourly schedule. this tuple is formatted to be used as the #141 SET DAY SCHEDULE argument.

Parameters:

  • day (str | int) – Day of the week. Can be either the name of the day (i.e. Sunday, Monday, etc.) or the 0-6 day code (0 for Sunday increacing to 6 for Saturday).

  • hours (list | tuple[bool | int]) – Array of 24 items. The value is 1 for motor on and 0 for motor off.

  • speed (int | list | tuple[int]) – Speed of the motor (0-100). This is an integer of all hours are the same speed. If there are multiple speeds, this should be an array of 24 items.

Return type:

tuple[int]

Returns:

Argument to pass with packet for SET DAY SCHEDULE.

static code_day_of_week(day)

Converts the day of the week to an integer code understandable by the POD device. The day is determined by the first 1-2 characters of the string, which supports multiple abbreviations for days of the week.

Parameters:

day (str) – Day of the week.

Return type:

int

Returns:

Code for the day of the week. Values are 0-6, with 0 for Saturday, 1 for Monday, …, and 6 for Saturday.

static code_day_schedule(hours, speed)

Bitmasks the day schedule to encode the motor on/off status and the motor speed. Use this for getting the command #141 SET DAY SCHEDULE UINT8x24 argument component.

Parameters:

  • hours (list | tuple[bool | int]) – Array of 24 items. The value is 1 for motor on and 0 for motor off.

  • speed (int | list | tuple[int]) – Speed of the motor (0-100). This is an integer of all hours are the same speed. If there are multiple speeds, this should be an array of 24 items.

Return type:

list[int]

Returns:

List of 24 integer items. The msb is the motor on/off flag and the remaining 7 bits are the speed.

static decode_day_and_schedule(dayschedule)

Decode the packet payload returned by the SET DAY SCHEDULE.

Parameters:

dayschedule (bytes) – Raw payload of packet.

Return type:

tuple[int, dict[str, int | tuple[int]]]

Returns:

Tupke containg day and schedule for day.

static decode_day_of_week(day)

Converts the integer code for a day of the week to a human-readable string.

Parameters:

day (int) – Day of the week code must be 0-6.

Return type:

str

Returns:

Day of the week (β€˜Sunday’, β€˜Monday’, etc.).

static decode_day_schedule(schedule)

Interprets the return bytes from the command #142 β€˜GET DAY SCHEDULE’.

Parameters:

schedule (bytes) – 24 byte long bitstring with one UINT8 per hour in a day.

Return type:

dict[str, int | tuple[int]]

Returns:

Dictionary with β€˜Hour’ as a tuple of 24 0/1 values (0 is motor off and 1 is motor on) and β€˜Speed’ as the motor speed (0-100). If the motor speed is the same every hour, β€˜Speed’ will be an integer; otherwise, β€˜Speed’ will be a tuple of 24 items.

static decode_lcd_schedule(schedule)

Interprets the return bytes from the command #202 β€˜LCD SET DAY SCHEDULE’.

Parameters:

schedule (bytes) – 4 Byte long bitstring. Byte 3 is weekday, Byte 2 is hours 0-7, Byte 1 is hours 8-15, and byte 0 is hours 16-23.

Return type:

dict[str, str | list[int]]

Returns:

Dictionary with Day as the day of the week, and Hours containing a list of 24 0/1 values (one for each hour). Each bit represents the motor state in that hour, 1 for on and 0 for off.

static get_current_time()

Gets a tuple to use as the argument for command #140 SET TIME containing values for the current time.

Return type:

tuple[int]

Returns:

Tuple of 7 integer values. The format is (Seconds, Minutes, Hours, Day, Month, Year (without century, so 23 for 2023), Weekday (0 for Sunday))

Morelia.Devices.PodDevice_8274D module

class Morelia.Devices.PodDevice_8274D.Pod8274D(port, baudrate=921600, device_name=None)

Bases: AquisitionDevice

POD_8274D handles communication using an 8274D POD device. Currently under construction and is unreliable.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • baudrate (int) – Baud rate of the opened serial port. Default value is 9600.

  • device_name (str | None) – Virtual name used to indentify device.

Morelia.Devices.PodDevice_8401HR module

class Morelia.Devices.PodDevice_8401HR.Pod8401HR(port, preamp, primary_channel_modes, secondary_channel_modes, ss_gain=(None, None, None, None), preamp_gain=(None, None, None, None), baudrate=9600, device_name=None)

Bases: AquisitionDevice

Pod8401HR handles communication using an 8401HR POD device.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • preamp (Preamp) – Device/sensor connected to the the 8401HR.

  • primary_channel_mode – A tuple containing the mode of operation for each primary channel (EEG/EMG or Biosensor).

  • secondary_channel_modes (tuple[SecondaryChannelMode]) – A tuple containing the mode of operation for each secondary (TTL/AEXT) channel (analog or digital).

  • ss_gain (tuple[int | None]) – Tuple storing the second-stage gain for all four channels. Defaults to (None, None, None, None).

  • preamp_gain (tuple[int | None]) – Tuple storing the pramplifier gain for all four channels. Defaults to (None, None, None, None).

  • baudrate (int) – Integer baud rate of the opened serial port. Used when initializing the COM_io instance. Defaults to 9600.

  • device_name (str | None) – Virtual name used to indentify device.

static calculate_bias_dac_get_dac_value(vout)

Calculates the DAC value given the output voltage. Used for GET/SET BIAS commands.

Parameters:

vout (int | float) – Output voltage (+/- 2.048 V).

Return type:

int

Returns:

Integer of the DAC value (16 bit 2’s complement).

static calculate_bias_dac_get_vout(value)

Calculates the output voltage given the DAC value. Used for GET/SET BIAS commands.

Parameters:

value (int) – DAC value (16 bit 2’s complement).

Return type:

float

Returns:

Float of the output bias voltage [V].

static decode_channel_bitmask(channels)

Converts the channel bitmask byte to a dictionary with each channel value. Use for GET INPUT GROUND command payloads.

Parameters:

channels (bytes) – UINT8 byte containing the channel configuration.

Return type:

dict[str, int]

Returns:

Dictionary with the channels as keys and values as the state. 0=Grounded and 1=Connected to Preamp.

static decode_ss_config_bitmask(config)

Converts the SS configuration byte to a dictionary with the high-pass and gain. Use for GET SS CONFIG command payloads.

Parameters:

config (bytes) – UINT8 byte containing the SS configurtation. Bit 0 = 0 for 0.5Hz Highpass, 1 for DC Highpass. Bit 1 = 0 for 5x gain, 1 for 1x gain.

Return type:

dict[str, Union[float, int]]

static decode_ttl_byte(ttl_byte)

Converts the TTL bytes argument into a dictionary of integer TTL values.

Parameters:

ttl_byte (bytes) – UINT8 byte containing the TTL bitmask.

Return type:

dict[str, int]

Returns:

Dictinoary with TTL name keys and integer TTL values.

static decode_ttl_payload(payload)

Decodes a paylaod with the two TTL bytes.

Parameters:

payload (bytes) – Bytes string of the POD packet payload.

Return type:

tuple[dict[str, int]]

Returns:

Tuple with two TTL dictionaries.

static get_channel_bitmask(a, b, c, d)

Gets a bitmask, represented by an unsigned integer, used for SET INPUT GROUND command.

Parameters:

  • a (bool) – State for channel A, 0=Grounded and 1=Connected to Preamp.

  • b (bool) – State for channel B, 0=Grounded and 1=Connected to Preamp.

  • c (bool) – State for channel C, 0=Grounded and 1=Connected to Preamp.

  • d (bool) – State for channel D, 0=Grounded and 1=Connected to Preamp.

Return type:

int

Returns:

Integer representing a bitmask.

static get_channel_map_for_preamp_device(preamp_name)

Get the channel mapping (channel labels for A,B,C,D) for a given device.

Parameters:

preamp_name (Preamp) – Device/sensor for lookup.

Return type:

dict[str, str] | None

Returns:

Dictionary with keys A,B,C,D with values of the channel names. Returns None if the device name does not exist.

static get_ss_config_bitmask(gain, highpass)

Gets a bitmask, represented by an unsigned integer, used for SET SS CONFIG command.

Parameters:

gain (int) – 1 for 1x gain. else for 5x gain. highpass (float): 0 for DC highpass, else for 0.5Hz highpass.

Return type:

int

Returns:

Integer representing a bitmask.

static get_ttl_bitmask(ext0=0, ext1=0, ttl4=0, ttl3=0, ttl2=0, ttl1=0)

Builds an integer, which represents a binary mask, that can be used for TTL command arguments.

Parameters:

  • ext0 (int) – boolean bit for ext0. Defaults to 0.

  • ext1 (int) – boolean bit for ext1. Defaults to 0.

  • ttl4 (int) – boolean bit for ttl4. Defaults to 0.

  • ttl3 (int) – boolean bit for ttl3. Defaults to 0.

  • ttl2 (int) – boolean bit for ttl2. Defaults to 0.

  • ttl1 (int) – boolean bit for ttl1. Defaults to 0.

Return type:

int

Returns:

Integer number to be used as a bit mask.

property preamp: Preamp

Preamp connected to device.

Morelia.Devices.PodDevice_8480SC module

class Morelia.Devices.PodDevice_8480SC.Pod8480SC(port, baudrate=9600, device_name=None)

Bases: Pod

POD_8480SC handles communication using an 8480-SC POD device.

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • baudrate (int) – Baud rate of the opened serial port. Default value is 9600.

  • device_name (str | None) – Virtual name used to indentify device.

static decode_stimulus_config_bits(config)

Converts an integer into 3 values, representing 3 individual bits of the Stimulus Config Bits.

Parameters:

config (int) – an integer is passed in, and it represents the Config Flag byte.

Return type:

dict

Returns:

Keys as the names of the bits, the values representing values at each bit.

static decode_sync_config_bits(config)

Converts an integer into 3 values, representing 3 individual bits of the Sync Config Bits.

Parameters:

config (int) – an integer is passed in, and it represents the Sync Config Flag byte.

Return type:

dict

Returns:

Keys as the names of the bits, the values representing values at each bit.

static decode_ttl_config_bits(config)

Converts an interger into 3 values, representing 3 individual bits of the TTL Config Bits.

Parameters:

config (int) – an integer is passed in, and it represents the TTL Setup Config Flag Byte.

Return type:

dict

Returns:

Keys as the names of the bits, the values representing values at each bit.

static stimulus_config_bits(optoElec, monoBiphasic, Simul)

Incoming inputs are bitmasked into an integer value. This value is later given as part of a payload to command #102 β€˜SET STIMULUS’.

Parameters:

  • optoElec (bool) – Bit is Opto/Electrical.

  • monoBiphasic (bool) – Bit 1 is Monophasic/Biphasic.

  • Simul (bool) – Bit 2 is Simultaneous.

Return type:

int

Returns:

which represents the Config flag byte in the Stimulus Command. The return value is the seventh item in the payload for command β€˜SET STIMULUS’.

static sync_config_bits(sync_level, sync_idle, signal_trigger)

Incoming inputs are bitmasked into an integer value. This value is later given as the payload to command #127 β€˜SET SYNC CONFIG’.

Parameters:

  • sync_level (bool) – Bit 0 is Sync Level.

  • sync_idle (bool) – Bit 1 is Stimulus Triggering.

  • signal_trigger (bool) – Bit 2 is Signal/Trigger.

Return type:

int

Returns:

which represents the Sync Config Bits format value.

static ttl_config_bits(trigger, stimtrig, input_sync)

Incoming inputs are bitmasked into an integer value. This value is later given as part of the payload to command #109 β€˜SET TTL SETUP’. This commands accepts 3 items in the payload, and the return value of this function is given as the second item.

Parameters:

  • trigger (bool) – Bit 0 is 0 for rising edge, 1 for falling edge.

  • stimtrig (bool) – Bit 1 is 0 for TTL event notifications, 1 for TTL inputs as triggers.

  • input_sync (bool) – Bit 7 is 0 for normal TTL operation, 1 for TTL pin operates as a sync output.

Return type:

int

Returns:

which represents the TTL Config Bits Format value.

Morelia.Devices.aquisition_device module

POD device that streams data.

class Morelia.Devices.aquisition_device.AquisitionDevice(port, max_sample_rate, baudrate=9600, device_name=None, get_sample_rate_cmd_no=100, set_sample_rate_cmd_no=101)

Bases: Pod

This class is the parent of any device that can stream (i.e. data aquisiton devices).

Parameters:

  • port (str | int) – Serial port to be opened. Used when initializing the COM_io instance.

  • max_sample_rate (int) – Maximum sample rate supported by the device (in Hz).

  • baudrate (int) – Baud rate of the opened serial port. Default value is 9600.

  • device_name (str | None) – Virtual Name used to indentify device.

  • get_sample_rate_cmd_no (int) – Command number for the GET SAMPLE RATE command on the device.

  • set_sample_rate_cmd_no (int) – Command number for the SET SAMPLE RATE command on the device.

property max_sample_rate: int

Maximum allowable sample rate.

property sample_rate: int

Currently set sample rate.

Morelia.Devices.preamp module

class Morelia.Devices.preamp.Preamp(*values)

Bases: Enum

Preamp8406_2BIO = 10
Preamp8406_BIO = 9
Preamp8406_EEG2BIO = 11
Preamp8406_SE = 12
Preamp8406_SE3 = 14
Preamp8406_SE31M = 8
Preamp8406_SE4 = 15
Preamp8406_SL = 13
Preamp8407_SE = 1
Preamp8407_SE3 = 3
Preamp8407_SE31M = 5
Preamp8407_SE4 = 4
Preamp8407_SE_2BIO = 6
Preamp8407_SL = 2
Preamp8407_SL_2BIO = 7

Module contents