`psychopy.tools.systemtools`¶

Tools for interacting with the system PsychoPy is installed on. This involves things such as getting information about installed devices and software.

Overview¶

`getAudioDevices`()	Get all audio devices.
`getAudioCaptureDevices`()	Get audio capture devices (i.e.
`getAudioPlaybackDevices`()	Get audio playback devices (i.e.
`getCameras`()	Get information about installed cameras and their formats on this system.
`getKeyboards`()	Get information about attached keyboards.
`getSerialPorts`()	Get serial ports attached to this system.
`systemProfilerMacOS`([dataTypes, ...])	Call the MacOS system profiler and return data in a JSON format.

Details¶

psychopy.tools.systemtools.getAudioDevices()[source]¶

Get all audio devices.

This function gets all audio devices attached to the system, either playback or capture. Uses the psychtoolbox library to obtain the relevant information.

This command is supported on Windows, MacOSX and Linux. On Windows, WASAPI devices are preferred to achieve precise timing and will be returned by default. To get all audio devices (including non-WASAPI ones), set the preference audioForceWASAPI to False.

Returns:: Dictionary where the keys are devices names and values are mappings whose fields contain information about the device.
Return type:: dict

Examples

Get audio devices installed on this system:

allDevs = getAudioDevices()

The following dictionary is returned by the above command when called on an Apple MacBook Pro (2022):

{
    'MacBook Pro Microphone': {   # audio capture device
        'index': 0,
        'name': 'MacBook Pro Microphone',
        'hostAPI': 'Core Audio',
        'outputChannels': 0,
        'outputLatency': (0.01, 0.1),
        'inputChannels': 1,
        'inputLatency': (0.0326984126984127, 0.04285714285714286),
        'defaultSampleRate': 44100.0,
        'audioLib': 'ptb'
    },
    'MacBook Pro Speakers': {    # audio playback device
        'index': 1,
        'name': 'MacBook Pro Speakers',
        'hostAPI': 'Core Audio',
        'outputChannels': 2,
        'outputLatency': (0.008480725623582767, 0.018639455782312925),
        'inputChannels': 0,
        'inputLatency': (0.01, 0.1),
        'defaultSampleRate': 44100.0,
        'audioLib': 'ptb'
    }
}

To determine whether something is a playback or capture device, check the number of output and input channels, respectively:

# determine if a device is for audio capture
isCapture = allDevs['MacBook Pro Microphone']['inputChannels'] > 0

# determine if a device is for audio playback
isPlayback = allDevs['MacBook Pro Microphone']['outputChannels'] > 0

You may also call getAudioCaptureDevices() and getAudioPlaybackDevices() to get just audio capture and playback devices.

psychopy.tools.systemtools.getAudioCaptureDevices()[source]¶

Get audio capture devices (i.e. microphones) installed on the system.

This command is supported on Windows, MacOSX and Linux. On Windows, WASAPI devices are preferred to achieve precise timing and will be returned by default. To get all audio capture devices (including non-WASAPI ones), set the preference audioForceWASAPI to False.

Uses the psychtoolbox library to obtain the relevant information.

Returns:: Dictionary where the keys are devices names and values are mappings whose fields contain information about the capture device. See getAudioDevices() examples to see the format of the output.
Return type:: dict

psychopy.tools.systemtools.getAudioPlaybackDevices()[source]¶

Get audio playback devices (i.e. speakers) installed on the system.

This command is supported on Windows, MacOSX and Linux. On Windows, WASAPI devices are preferred to achieve precise timing and will be returned by default. To get all audio playback devices (including non-WASAPI ones), set the preference audioForceWASAPI to False.

Uses the psychtoolbox library to obtain the relevant information.

Returns:: Dictionary where the keys are devices names and values are mappings whose fields contain information about the playback device. See getAudioDevices() examples to see the format of the output.
Return type:: dict

psychopy.tools.systemtools.getCameras()[source]¶

Get information about installed cameras and their formats on this system.

The command presently only works on Window and MacOSX. Linux support for cameras is not available yet.

Returns:: Mapping where camera names (str) are keys and values are and array of CameraInfo objects.
Return type:: dict

psychopy.tools.systemtools.getKeyboards()[source]¶

Get information about attached keyboards.

This command works on Windows, MacOSX and Linux.

Returns:: Dictionary where the keys are device names and values are mappings whose fields contain information about that device. See the Examples section for field names.
Return type:: dict

Notes

Keyboard names are generated (taking the form of “Generic Keyboard n”) if the OS does not report the name.

Examples

Get keyboards attached to this system:

installedKeyboards = getKeyboards()

Running the previous command on an Apple MacBook Pro (2022) returns the following dictionary:

{
    'TouchBarUserDevice': {
        'usagePageValue': 1,
        'usageValue': 6,
        'usageName': 'Keyboard',
        'index': 4,
        'transport': '',
        'vendorID': 1452,
        'productID': 34304,
        'version': 0.0,
        'manufacturer': '',
        'product': 'TouchBarUserDevice',
        'serialNumber': '',
        'locationID': 0,
        'interfaceID': -1,
        'totalElements': 1046,
        'features': 0,
        'inputs': 1046,
        'outputs': 0,
        'collections': 1,
        'axes': 0,
        'buttons': 0,
        'hats': 0,
        'sliders': 0,
        'dials': 0,
        'wheels': 0,
        'touchDeviceType': -1,
        'maxTouchpoints': -1},
    'Generic Keyboard 0': {
        'usagePageValue': 1,
        'usageValue': 6,
        'usageName': 'Keyboard',
        'index': 13,
        # snip ...
        'dials': 0,
        'wheels': 0,
        'touchDeviceType': -1,
        'maxTouchpoints': -1
    }
}

psychopy.tools.systemtools.getSerialPorts()[source]¶

Get serial ports attached to this system.

Serial ports are used for inter-device communication using the RS-232/432 protocol. This function gets a list of available ports and their default configurations as specified by the OS. Ports that are in use by another process are not returned.

This command is supported on Windows, MacOSX and Linux. On Windows, all available ports are returned regardless if anything is connected to them, so long as they aren’t in use. On Unix(-likes) such as MacOSX and Linux, port are only returned if there is a device attached and is not being accessed by some other process. MacOSX and Linux also have no guarantee port names are persistent, where a physical port may not always be assigned the same name or enum index when a device is connected or after a system reboot.

Returns:: Mapping (dict) where keys are serial port names (str) and values are mappings of the default settings of the port (dict). See Examples below for the format of the returned data.
Return type:: dict

Examples

Getting available serial ports:

allPorts = getSerialPorts()

On a MacBook Pro (2022) with an Arduino Mega (2560) connected to the USB-C port, the following dictionary is returned:

{
    '/dev/cu.Bluetooth-Incoming-Port': {
        'index': 0,
        'port': '/dev/cu.Bluetooth-Incoming-Port',
        'baudrate': 9600,
        'bytesize': 8,
        'parity': 'N',
        'stopbits': 1,
        'xonxoff': False,
        'rtscts': False,
        'dsrdtr': False
    },
    '/dev/cu.usbmodem11101': {
        'index': 1,
        # ... snip ...
        'dsrdtr': False
    },
    '/dev/tty.Bluetooth-Incoming-Port': {
        'index': 2,
        # ... snip ...
    },
    '/dev/tty.usbmodem11101': {
        'index': 3,
        # ... snip ...
    }
}

psychopy.tools.systemtools.systemProfilerMacOS(dataTypes=None, detailLevel='basic', timeout=180)[source]¶

Call the MacOS system profiler and return data in a JSON format.

Parameters:

dataTypes (str, list or None) – Identifier(s) for the data to retrieve. All data types available will be returned if None. See output of shell command system_profiler -listDataTypes for all possible values. Specifying data types also speeds up the time it takes for this function to return as superfluous information is not queried.
detailLevel (int or str) – Level of detail for the report. Possible values are ‘mini’, ‘basic’, or ‘full’. Note that increasing the level of detail will expose personally identifying information in the resulting report. Best practice is to use the lowest level of detail needed to obtain the desired information, or use dataTypes to limit what information is returned.
timeout (float or int) – Amount of time to spend gathering data in seconds. Default is 180 seconds, while specifying 0 means no timeout.

Returns:

Result of the system_profiler call as a JSON formatted string. You can pass the string to a JSON library to parse out what information is desired.

Return type:

str

Examples

Get details about cameras attached to this system:

dataTypes = "SPCameraDataType"  # data to query
systemReportJSON = systemProfilerMacOS(dataTypes, detailLevel='basic')
# >>> print(systemReportJSON)
# {
#   "SPCameraDataType" : [
#     ...
#   ]
# }

Parse the result using a JSON library:

import json
systemReportJSON = systemProfilerMacOS(
    "SPCameraDataType", detailLevel='mini')
cameraInfo = json.loads(systemReportJSON)
# >>> print(cameraInfo)
# {'SPCameraDataType': [{'_name': 'Live! Cam Sync 1080p',
# 'spcamera_model-id': 'UVC Camera VendorID_1054 ProductID_16541',
# 'spcamera_unique-id': '0x2200000041e409d'}]

psychopy.tools.systemtools¶

Overview¶

Details¶

`psychopy.tools.systemtools`¶