niswitch.Session methods¶

niswitch.Session.abort()¶: Aborts the scan in progress. Initiate a scan with niswitch.Session._initiate_scan(). If the switch module is not scanning, NISWITCH_ERROR_NO_SCAN_IN_PROGRESS error is returned.

niswitch.Session.can_connect(channel1, channel2)¶

Verifies that a path between channel 1 and channel 2 can be created. If a path is possible in the switch module, the availability of that path is returned given the existing connections. If the path is possible but in use, a NISWITCH_WARN_IMPLICIT_CONNECTION_EXISTS warning is returned.

Parameters:

channel1 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 2 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: “”
channel2 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 1 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: “”

Return type:

niswitch.PathCapability

Returns:

Indicates whether a path is valid. Possible values include: ———————————— NISWITCH_VAL_PATH_AVAILABLE 1 NISWITCH_VAL_PATH_EXISTS 2 NISWITCH_VAL_PATH_UNSUPPORTED 3 NISWITCH_VAL_RSRC_IN_USE 4 NISWITCH_VAL_SOURCE_CONFLICT 5 NISWITCH_VAL_CHANNEL_NOT_AVAILABLE 6 Notes: (1) NISWITCH_VAL_PATH_AVAILABLE indicates that the driver can create the path at this time. (2) NISWITCH_VAL_PATH_EXISTS indicates that the path already exists. (3) NISWITCH_VAL_PATH_UNSUPPORTED indicates that the instrument is not capable of creating a path between the channels you specify. (4) NISWITCH_VAL_RSRC_IN_USE indicates that although the path is valid, the driver cannot create the path at this moment because the switch device is currently using one or more of the required channels to create another path. You must destroy the other path before creating this one. (5) NISWITCH_VAL_SOURCE_CONFLICT indicates that the instrument cannot create a path because both channels are connected to a different source channel. (6) NISWITCH_VAL_CHANNEL_NOT_AVAILABLE indicates that the driver cannot create a path between the two channels because one of the channels is a configuration channel and thus unavailable for external connections.

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.

niswitch.Session.commit()¶: Downloads the configured scan list and trigger settings to hardware. Calling niswitch.Session.commit() optional as it is implicitly called during niswitch.Session._initiate_scan(). Use niswitch.Session.commit() to arm triggers in a given order or to control when expensive hardware operations are performed.

niswitch.Session.configure_scan_list(scanlist, scan_mode=niswitch.ScanMode.BREAK_BEFORE_MAKE)¶

Configures the scan list and scan mode used for scanning. Refer to Devices Overview to determine if the switch module supports scanning. The scan list is comprised of a list of channel connections separated by semi-colons. For example, the following scan list will scan the first three channels of a multiplexer: com0->ch0; com0->ch1; com0->ch2; Refer to Scan Lists for more information on scan list syntax To see the status of the scan, call either niswitch.Session.IsScanning() or niswitch.Session.wait_for_scan_complete(). Use the niswitch.Session.configure_scan_trigger() method to configure the scan trigger. Use the niswitch.Session._initiate_scan() method to start the scan.

Note

One or more of the referenced methods are not in the Python API for this driver.

Parameters:	scanlist (str) – The scan list to use. The driver uses this value to set the Scan List property. Default value: None scan_mode (`niswitch.ScanMode`) – Specifies how the switch module breaks existing connections when scanning. The driver uses this value to set the Scan Mode property. Refer to scan modes for more information. Default value: Break Before Make

niswitch.Session.configure_scan_trigger(trigger_input, scan_advanced_output, scan_delay=datetime.timedelta(seconds=0.0))¶

Configures the scan triggers for the scan list established with niswitch.Session.configure_scan_list(). Refer to Devices Overview to determine if the switch module supports scanning. niswitch.Session.configure_scan_trigger() sets the location that the switch expects to receive an input trigger to advance through the scan list. This method also sets the location where it outputs a scan advanced signal after it completes an entry in the scan list.

Parameters:

trigger_input (niswitch.TriggerInput) – Trigger source you want the switch module to use during scanning. The driver uses this value to set the niswitch.Session.trigger_input property. The switch device waits for the trigger you specify when it encounters a semicolon in the scanlist. When the trigger occurs, the switch device advances to the next entry in the scanlist. Refer to the niswitch.Session.trigger_input topic in the NI Switches Help for a list of valid values.
scan_advanced_output (niswitch.ScanAdvancedOutput) – Output destination of the scan advanced trigger signal. The driver uses this value to set the niswitch.Session.scan_advanced_output property. After the switch processes each entry in the scan list, it waits the length of time you specify in the Scan Delay parameter and then asserts a trigger on the line you specify with this parameter. Refer to the niswitch.Session.scan_advanced_output topic in the NI Switches Help for a list of valid values.
scan_delay (float in seconds or datetime.timedelta) – The minimum length of time you want the switch device to wait after it creates a path until it asserts a trigger on the scan advanced output line. The driver uses this value to set the Scan Delay property. The scan delay is in addition to the settling time.The driver uses this value to set the niswitch.Session.scan_delay property. Express this value in seconds. Default value: 0.0 s

niswitch.Session.connect(channel1, channel2)¶

Creates a path between channel 1 and channel 2. The driver calculates and uses the shortest path between the two channels. Refer to Immediate Operations for information about Channel Usage types. If a path is not available, the method returns one of the following errors: - NISWITCH_ERROR_EXPLICIT_CONNECTION_EXISTS, if the two channels are already explicitly connected by calling either the niswitch.Session.connect() or niswitch.Session.set_path() method. - NISWITCH_ERROR_IS_CONFIGURATION_CHANNEL, if a channel is a configuration channel. Error elaboration contains information about which of the two channels is a configuration channel. - NISWITCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES, if both channels are connected to a different source. Error elaboration contains information about sources channel 1 and 2 connect to. - NISWITCH_ERROR_CANNOT_CONNECT_TO_ITSELF, if channels 1 and 2 are one and the same channel. - NISWITCH_ERROR_PATH_NOT_FOUND, if the driver cannot find a path between the two channels. Note: Paths are bidirectional. For example, if a path exists between channels CH1 and CH2, then the path also exists between channels CH2 and CH1.

Parameters:

channel1 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 2 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: None
channel2 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 1 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: None

niswitch.Session.connect_multiple(connection_list)¶

Creates the connections between channels specified in Connection List. Specify connections with two endpoints only or the explicit path between two endpoints. NI-SWITCH calculates and uses the shortest path between the channels. Refer to Setting Source and Configuration Channels for information about channel usage types. In the event of an error, connecting stops at the point in the list where the error occurred. If a path is not available, the method returns one of the following errors: - NISWITCH_ERROR_EXPLICIT_CONNECTION_EXISTS, if the two channels are already explicitly connected. - NISWITCH_ERROR_IS_CONFIGURATION_CHANNEL, if a channel is a configuration channel. Error elaboration contains information about which of the two channels is a configuration channel. - NISWITCH_ERROR_ATTEMPT_TO_CONNECT_SOURCES, if both channels are connected to a different source. Error elaboration contains information about sources channel 1 and 2 to connect. - NISWITCH_ERROR_CANNOT_CONNECT_TO_ITSELF, if channels 1 and 2 are one and the same channel. - NISWITCH_ERROR_PATH_NOT_FOUND, if the driver cannot find a path between the two channels. Note: Paths are bidirectional. For example, if a path exists between channels ch1 and ch2, then the path also exists between channels ch1 and ch2.

Parameters: connection_list (str) – Connection List specifies a list of connections between channels to make. NI-SWITCH validates the connection list, and aborts execution of the list if errors are returned. Refer to Connection and Disconnection List Syntax for valid connection list syntax and examples. Refer to Devices Overview for valid channel names for the switch module. Example of a valid connection list: c0 -> r1, [c2 -> r2 -> c3] In this example, r2 is a configuration channel. Default value: None

niswitch.Session.disable()¶: Places the switch module in a quiescent state where it has minimal or no impact on the system to which it is connected. All channels are disconnected and any scan in progress is aborted.

niswitch.Session.disconnect(channel1, channel2)¶

This method destroys the path between two channels that you create with the niswitch.Session.connect() or niswitch.Session.set_path() method. If a path is not connected or not available, the method returns the IVISWTCH_ERROR_NO_SUCH_PATH error.

Parameters:

channel1 (str) – Input one of the channel names of the path to break. Pass the other channel name as the channel 2 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: None
channel2 (str) – Input one of the channel names of the path to break. Pass the other channel name as the channel 1 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: None

niswitch.Session.disconnect_all()¶: Breaks all existing paths. If the switch module cannot break all paths, NISWITCH_WARN_PATH_REMAINS warning is returned.

niswitch.Session.disconnect_multiple(disconnection_list)¶

Breaks the connections between channels specified in Disconnection List. If no connections exist between channels, NI-SWITCH returns an error. In the event of an error, the VI stops at the point in the list where the error occurred.

Parameters: disconnection_list (str) – Disconnection List specifies a list of connections between channels to break. NI-SWITCH validates the disconnection list, and aborts execution of the list if errors are returned. Refer to Connection and Disconnection List Syntax for valid disconnection list syntax and examples. Refer to Devices Overview for valid channel names for the switch module. Example of a valid disconnection list: c0 -> r1, [c2 -> r2 -> c3] In this example, r2 is a configuration channel. Default value: None

niswitch.Session.get_channel_name(index)¶

Returns the channel string that is in the channel table at the specified index. Use niswitch.Session.get_channel_name() in a For Loop to get a complete list of valid channel names for the switch module. Use the Channel Count property to determine the number of channels.

Parameters:	index (int) – A 1-based index into the channel table. Default value: 1 Maximum value: Value of Channel Count property.

niswitch.Session.get_path(channel1, channel2)¶

Returns a string that identifies the explicit path created with niswitch.Session.connect(). Pass this string to niswitch.Session.set_path() to establish the exact same path in future connections. In some cases, multiple paths are available between two channels. When you call niswitch.Session.connect(), the driver selects an available path. With niswitch.Session.connect(), there is no guarantee that the driver selected path will always be the same path through the switch module. niswitch.Session.get_path() only returns those paths explicitly created by niSwitch Connect Channels or niswitch.Session.set_path(). For example, if you connect channels CH1 and CH3,and then channels CH2 and CH3, an explicit path between channels CH1 and CH2 does not exist an error is returned

Parameters:

channel1 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 2 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: “”
channel2 (str) – Input one of the channel names of the desired path. Pass the other channel name as the channel 1 parameter. Refer to Devices Overview for valid channel names for the switch module. Examples of valid channel names: ch0, com0, ab0, r1, c2, cjtemp Default value: “”

niswitch.Session.get_relay_count(relay_name)¶

Returns the number of times the relay has changed from Closed to Open. Relay count is useful for tracking relay lifetime and usage. Call niswitch.Session.wait_for_debounce() before niswitch.Session.get_relay_count() to ensure an accurate count. Refer to the Relay Count topic in the NI Switches Help to determine if the switch module supports relay counting.

Parameters:	relay_name (str) – Name of the relay. Default value: None Examples of valid relay names: ch0, ab0, 1wire, hlselect Refer to Devices Overview for a list of valid relay names for the switch module.
Return type:	int
Returns:	The number of relay cycles.

niswitch.Session.get_relay_name(index)¶

Returns the relay name string that is in the relay list at the specified index. Use niswitch.Session.get_relay_name() in a For Loop to get a complete list of valid relay names for the switch module. Use the Number of Relays property to determine the number of relays.

Parameters:	index (int) – A 1-based index into the channel table. Default value: 1 Maximum value: Value of Channel Count property.

niswitch.Session.get_relay_position(relay_name)¶

Returns the relay position for the relay specified in the Relay Name parameter.

Parameters:	relay_name (str) – Name of the relay. Default value: None Examples of valid relay names: ch0, ab0, 1wire, hlselect Refer to Devices Overview for a list of valid relay names for the switch module.
Return type:	`niswitch.RelayPosition`
Returns:	Indicates whether the relay is open or closed. `NISWITCH_VAL_OPEN` 10 NIWITCH_VAL_CLOSED 11 Note One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.

niswitch.Session.relay_control(relay_name, relay_action)¶

Controls individual relays of the switch. When controlling individual relays, the protection offered by setting the usage of source channels and configuration channels, and by enabling or disabling analog bus sharing on the NI SwitchBlock, does not apply. Refer to the device book for your switch in the NI Switches Help to determine if the switch supports individual relay control.

Parameters:

relay_name (str) – Name of the relay. Default value: None Examples of valid relay names: ch0, ab0, 1wire, hlselect Refer to Devices Overview for a list of valid relay names for the switch module.
relay_action (niswitch.RelayAction) –
Specifies whether to open or close a given relay. Default value: Relay Close Defined values: NISWITCH_VAL_OPEN_RELAY NISWITCH_VAL_CLOSE_RELAY (Default Value)

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.

niswitch.Session.reset()¶: Disconnects all created paths and returns the switch module to the state at initialization. Configuration channel and source channel settings remain unchanged.

niswitch.Session.reset_with_defaults()¶: Resets the switch module and applies initial user specified settings from the logical name used to initialize the session. If the session was created without a logical name, this method is equivalent to niswitch.Session.reset().

niswitch.Session.route_scan_advanced_output(scan_advanced_output_connector, scan_advanced_output_bus_line, invert=False)¶

Routes the scan advanced output trigger from a trigger bus line (TTLx) to the front or rear connector.

Parameters:

scan_advanced_output_connector (niswitch.ScanAdvancedOutput) –
The scan advanced trigger destination. Valid locations are the FRONTCONNECTOR and REARCONNECTOR. Default value: FRONTCONNECTOR

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.
scan_advanced_output_bus_line (niswitch.ScanAdvancedOutput) –
The trigger line to route the scan advanced output trigger from the front or rear connector. Select NONE to break an existing route. Default value: None Valid Values: NONE TTL0 TTL1 TTL2 TTL3 TTL4 TTL5 TTL6 TTL7

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.
invert (bool) – If True, inverts the input trigger signal from falling to rising or vice versa. Default value: False

niswitch.Session.route_trigger_input(trigger_input_connector, trigger_input_bus_line, invert=False)¶

Routes the input trigger from the front or rear connector to a trigger bus line (TTLx). To disconnect the route, call this method again and specify None for trigger bus line parameter.

Parameters:

trigger_input_connector (niswitch.TriggerInput) –
The location of the input trigger source on the switch module. Valid locations are the FRONTCONNECTOR and REARCONNECTOR. Default value: FRONTCONNECTOR

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.
trigger_input_bus_line (niswitch.TriggerInput) –
The trigger line to route the input trigger. Select NISWITCH_VAL_NONE to break an existing route. Default value: None Valid Values: NISWITCH_VAL_NONE TTL0 TTL1 TTL2 TTL3 TTL4 TTL5 TTL6 TTL7

Note

One or more of the referenced values are not in the Python API for this driver. Enums that only define values, or represent True/False, have been removed.
invert (bool) – If True, inverts the input trigger signal from falling to rising or vice versa. Default value: False

niswitch.Session.self_test()¶

Verifies that the driver can communicate with the switch module.

Raises SelfTestError on self test failure. Properties on exception object:

code - failure code from driver
message - status message from driver

Self-Test Code	Description
0	Passed self-test
1	Self-test failed

niswitch.Session.send_software_trigger()¶: Sends a software trigger to the switch module specified in the NI-SWITCH session. When the trigger input is set to SOFTWARE_TRIG through either the niswitch.Session.configure_scan_trigger() or the niswitch.Session.trigger_input property, the scan does not proceed from a semi-colon (wait for trigger) until niswitch.Session.send_software_trigger() is called.

niswitch.Session.set_continuous_scan(continuous_scan)¶

Sets the to loop continuously through the scan list or to stop scanning after one pass through the scan list.

Parameters:	continuous_scan (bool) – If True, loops continuously through the scan list during scanning. If False, the scan stops after one pass through the scan list. Default value: False

niswitch.Session.set_path(path_list)¶

Connects two channels by specifying an explicit path in the path list parameter. niswitch.Session.set_path() is particularly useful where path repeatability is important, such as in calibrated signal paths. If this is not necessary, use niswitch.Session.connect().

Parameters: path_list (str) – A string composed of comma-separated paths between channel 1 and channel 2. The first and last names in the path are the endpoints of the path. Every other channel in the path are configuration channels. Example of a valid path list string: ch0->com0, com0->ab0. In this example, com0 is a configuration channel. Default value: None Obtain the path list for a previously created path with niswitch.Session.get_path().

niswitch.Session.wait_for_debounce(maximum_time_ms=datetime.timedelta(milliseconds=5000))¶

Pauses until all created paths have settled. If the time you specify with the Maximum Time (ms) parameter elapsed before the switch paths have settled, this method returns the NISWITCH_ERROR_MAX_TIME_EXCEEDED error.

Parameters:	maximum_time_ms (float in seconds or datetime.timedelta) – Specifies the maximum length of time to wait for all relays in the switch module to activate or deactivate. If the specified time elapses before all relays active or deactivate, a timeout error is returned. Default Value:5000 ms

niswitch.Session.wait_for_scan_complete(maximum_time_ms=datetime.timedelta(milliseconds=5000))¶

Pauses until the switch module stops scanning or the maximum time has elapsed and returns a timeout error. If the time you specify with the Maximum Time (ms) parameter elapsed before the scanning operation has finished, this method returns the NISWITCH_ERROR_MAX_TIME_EXCEEDED error.

Parameters:	maximum_time_ms (float in seconds or datetime.timedelta) – Specifies the maximum length of time to wait for the switch module to stop scanning. If the specified time elapses before the scan ends, NISWITCH_ERROR_MAX_TIME_EXCEEDED error is returned. Default Value:5000 ms