System

Provides access to the system in hardware interfaces that have access to cameras.

Exceptions:

SpinnakerAPIException

An exception that represents an error raised from the Spinnaker API.

Classes:

`EventHandlerBase`	Base class for all event handlers.
`LoggingEventHandler`	A system log event handler that is returned by `attach_log_event_handler()` that handles callbacks for internal Spinnaker logging events.
`SystemEventHandler`	A system interface arrival/removal handler that is returned by `attach_event_handler()` that handles callbacks for when a new hardware interface to which cameras may be attached (e.g.
`InterfaceEventHandler`	A system/interface camera arrival/removal handler that is returned by `attach_interface_event_handler()` and `attach_event_handler()` that handles callbacks for when a camera is added or removed from the system or specific interface.
`SpinSystem`	A `SpinSystem` provides access to interfaces and cameras attached to these interfaces across the system.
`InterfaceDeviceList`	Provides access to a list of the interface devices to which cameras can be attached e.g.
`InterfaceDevice`	A hardware interface to which cameras such as GigE, USB2/3 can be attached.

exception SpinnakerAPIException(*args, spin_what='', spin_full_msg='', spin_msg='', spin_file_name='', spin_func_name='', spin_build_date='', spin_build_time='', spin_line_num=0, spin_error_code=0)

Bases: Exception

An exception that represents an error raised from the Spinnaker API.

class EventHandlerBase

Bases: object

Base class for all event handlers.

class LoggingEventHandler

Bases: EventHandlerBase

A system log event handler that is returned by attach_log_event_handler() that handles callbacks for internal Spinnaker logging events.

This represents a callback function that is called on each log event with 3 positional arguments: this instance, the SpinSystem instance that created this, and a dict with the log data.

Some dict keys are the error category, the error message, the ndc (Nested Diagnostic Context), the thread in which it happened, the timestamp string, the priority name, and the priority_num.

class SystemEventHandler

Bases: EventHandlerBase

A system interface arrival/removal handler that is returned by attach_event_handler() that handles callbacks for when a new hardware interface to which cameras may be attached (e.g. USB port) is added or removed from the system.

This represents an arrival and removal callback function that is each called respectively (if provided when it’s created), on each arrival/removal event with 3 positional arguments: this instance, the SpinSystem instance that created this, and a string representing the interface name.

class InterfaceEventHandler

Bases: EventHandlerBase

A system/interface camera arrival/removal handler that is returned by attach_interface_event_handler() and attach_event_handler() that handles callbacks for when a camera is added or removed from the system or specific interface.

This represents an arrival and removal callback function that is each called respectively (if provided when it’s created), on each arrival/removal event with 3 positional arguments: this instance, the SpinSystem or InterfaceDevice instance that created this, and an integer representing the camera serial number.

class SpinSystem

Bases: object

A SpinSystem provides access to interfaces and cameras attached to these interfaces across the system.

Methods:

`attach_event_handler`	Registers the system callbacks to get interface arrival/removal events.
`attach_interface_event_handler`	Registers device arrival and removal events for all interfaces that are found on the system.
`attach_log_event_handler`	Registers the callback to get logging events from system.
`create_interface_list`	Creates and returns a new `InterfaceDeviceList` for accessing interfaces on the system.
`detach_all_log_handlers`	Detaches all the attached log event handlers that have been previously attached.
`detach_event_handler`	Detaches the event handler returned by `attach_event_handler()`.
`detach_interface_event_handler`	Detaches the event handler previously returned by `attach_interface_event_handler()`.
`detach_log_event_handler`	Detaches an event handler returned by `attach_log_event_handler()`.
`get_in_use`	Checks if the system is in use by any interface or camera objects.
`get_library_version`	Gets the current Spinnaker library version as a 4 tuple of `(major, minor, type, build)`.
`get_logging_level`	Gets the logging level (as listed in `log_level_names`) for all logging events on the system.
`get_tl_node_map`	Gets the transport layer nodemap from the system.
`send_command`	Broadcast an Action Command to all devices on the system.
`set_logging_level`	Sets the logging level for all logging events on the system.
`update_camera_list`	Updates the internal list of cameras on the system, returning a bool indicating whether there has been any changes and cameras have arrived or been removed.
`update_interface_list`	Updates the internal list of interfaces on the system.

Attributes:

system_nodes

system_nodes: rotpy.system_nodes.SystemNodes The pre-listed system nodes from SystemNodes.

attach_event_handler(self, callback_arrival=None, callback_removal=None)

Registers the system callbacks to get interface arrival/removal events.

Parameters

callback_arrival – A function that will be called upon interface arrival events. If it’s None, arrival events will be ignored. See SystemEventHandler for the function signature.
callback_removal – A function that will be called upon interface removal events. If it’s None, removal events will be ignored. See SystemEventHandler for the function signature.

Returns

A SystemEventHandler instance representing the callbacks.

The callbacks will receive the system events while they are registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

attach_interface_event_handler(self, callback_arrival=None, callback_removal=None, bool update=True)

Registers device arrival and removal events for all interfaces that are found on the system. If new interfaces are detected by the system after this call, those interfaces will be automatically registered with this event.

Parameters

callback_arrival – A function that will be called upon device arrival events. If it’s None, arrival events will be ignored. See InterfaceEventHandler for the function signature.
callback_removal – A function that will be called upon device removal events. If it’s None, removal events will be ignored. See InterfaceEventHandler for the function signature.
update – Whether to update the interface list before attaching event for the available interfaces on the system.

Returns

A InterfaceEventHandler instance representing the callbacks.

Note

Only GEV interface arrivals and removals are currently handled.

The callbacks will receive the interface events while they are registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

attach_log_event_handler(self, callback)

Registers the callback to get logging events from system.

Parameters: callback – A function that will be called upon logging events. See LoggingEventHandler for the function signature.
Returns: A LoggingEventHandler instance representing the callback.

The callback will receive the events while it is registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

create_interface_list(self, bool update_interfaces=True)

Creates and returns a new InterfaceDeviceList for accessing interfaces on the system.

This returns GigE and USB2 and USB3 interfaces. Note that on MacOS only active GigE interfaces will be stored in the returned interface list.

Parameters: update_interfaces – Whether to update the internal interface list before getting the available interfaces list.
Returns: A InterfaceDeviceList.

detach_all_log_handlers(self): Detaches all the attached log event handlers that have been previously attached.

detach_event_handler(self, SystemEventHandler handler)

Detaches the event handler returned by attach_event_handler().

Parameters: handler – The SystemEventHandler that handled the events.

detach_interface_event_handler(self, InterfaceEventHandler handler)

Detaches the event handler previously returned by attach_interface_event_handler().

Parameters: handler – The InterfaceEventHandler that handled the events.

detach_log_event_handler(self, LoggingEventHandler handler)

Detaches an event handler returned by attach_log_event_handler().

Parameters: handler – The LoggingEventHandler that handled the events.

get_in_use(self): Checks if the system is in use by any interface or camera objects.

get_library_version(self): Gets the current Spinnaker library version as a 4 tuple of (major, minor, type, build).

get_logging_level(self): Gets the logging level (as listed in log_level_names) for all logging events on the system.

get_tl_node_map(self)

Gets the transport layer nodemap from the system.

Returns: A NodeMap.

send_command(self, unsigned int device_key, unsigned int group_key, unsigned int group_mask, unsigned long long action_time=0, unsigned int num_results=0)

Broadcast an Action Command to all devices on the system.

Parameters

device_key – The action command’s device key.
group_key – The action command’s group key.
group_mask – The action command’s group mask.
action_time – Time when to assert a future action. Zero (default) means immediate action.
num_results – The number of results expected in the return list. The value passed should be equal to the expected number of devices that acknowledge the command. The returned list will be the actual number of received results. If this is 0, the function will return as soon as the command has been broadcasted.

Returns

A list of tuples, one tuple for each item in the result. Each tuple is (address, status), where address is the device address and status is the status string from cmd_status_names.

set_logging_level(self, unicode level)

Sets the logging level for all logging events on the system. Logging events below such level will not trigger callbacks

Parameters: level – The name of the level as listed in log_level_names.

system_nodes: system_nodes: rotpy.system_nodes.SystemNodes The pre-listed system nodes from SystemNodes.

Use this property to get a pre-instantiated SystemNodes because SystemNodes is not user instantiable.

Note

Remember to check whether each of the pre-listed nodes are is_available(), is_readable(), is_writable() etc.

update_camera_list(self, bool update_interfaces=True)

Updates the internal list of cameras on the system, returning a bool indicating whether there has been any changes and cameras have arrived or been removed.

Parameters: update_interfaces – If True, the interface lists will also be updated.
Returns: True if cameras changed on interface and False otherwise.

If desired to get the new interfaces or cameras, call create_interface_list() or create_from_system(), respectively because existing CameraList will not reflect the updates.

update_interface_list(self)

Updates the internal list of interfaces on the system.

If desired to get the new interfaces, call create_interface_list(), existing InterfaceDeviceList will not reflect the updates.

class InterfaceDeviceList

Bases: object

Provides access to a list of the interface devices to which cameras can be attached e.g. GigE and USB2 and USB3 interfaces.

Warning

Do not create a InterfaceDeviceList manually, rather get it from create_interface_list().

Once a InterfaceDeviceList is created from the system, updating the system so it detects new interface will not be reflected in existing InterfaceDeviceList. Instead, create new one to access those new interfaces.

Note

On MacOS only active GigE interfaces will be stored in the returned InterfaceDeviceList.

Methods:

`create_interface`	Retrieves an interface device from this interface device list using using a zero-based index that is less than `get_size()`.
`extend`	Extends this interface list with a copy of the other interface list.
`get_size`	Retrieves the number of detected interface devices in the list.

create_interface(self, unsigned int index)

Retrieves an interface device from this interface device list using using a zero-based index that is less than get_size().

Parameters: index – The index of the interface device.
Returns: A InterfaceDevice.

extend(self, InterfaceDeviceList other)

Extends this interface list with a copy of the other interface list.

Parameters: other – The other InterfaceDeviceList to add to us.

get_size(self): Retrieves the number of detected interface devices in the list.

class InterfaceDevice

Bases: object

A hardware interface to which cameras such as GigE, USB2/3 can be attached.

Warning

Do not create a InterfaceDevice manually, rather get it from InterfaceDeviceList.create_interface().

Methods:

`attach_event_handler`	Registers device arrival and removal events for this interface.
`detach_event_handler`	Detaches the event handler previously returned by `attach_event_handler()`.
`get_in_use`	Returns whether this interface is in use by any camera objects.
`get_is_valid`	Returns whether this interface is still valid for use.
`get_tl_node_map`	Gets the transport layer nodemap from this interface.
`release`	Releases the interface's resources, including its nodes.
`send_command`	Broadcast an Action Command to all devices on this interface.
`update_camera_list`	Updates the internal list of cameras on this interface, returning a bool indicating whether there has been any changes and cameras have arrived or been removed.

Attributes:

interface_nodes

interface_nodes: rotpy.system_nodes.InterfaceNodes The pre-listed interface nodes from InterfaceNodes.

attach_event_handler(self, callback_arrival=None, callback_removal=None)

Registers device arrival and removal events for this interface.

Parameters

callback_arrival – A function that will be called upon device arrival events. If it’s None, arrival events will be ignored. See InterfaceEventHandler for the function signature.
callback_removal – A function that will be called upon device removal events. If it’s None, removal events will be ignored. See InterfaceEventHandler for the function signature.

Returns

A InterfaceEventHandler instance representing the callbacks.

The callbacks will receive the interface events while they are registered, possibly even before this function returns(?) and could potentially be called by external threads. It’s best not to do any work in it.

Event handlers are automatically cleaned up when an interface is removed, and must be registered to interfaces as they arrive. Note that GEV interfaces experience arrival/removal events when the IP information changes, similar to GEV cameras.

detach_event_handler(self, InterfaceEventHandler handler)

Detaches the event handler previously returned by attach_event_handler().

Parameters: handler – The InterfaceEventHandler that handled the events.

get_in_use(self): Returns whether this interface is in use by any camera objects.

get_is_valid(self): Returns whether this interface is still valid for use.

get_tl_node_map(self)

Gets the transport layer nodemap from this interface.

Returns: A NodeMap.

interface_nodes: interface_nodes: rotpy.system_nodes.InterfaceNodes The pre-listed interface nodes from InterfaceNodes.

Use this property to get a pre-instantiated InterfaceNodes because InterfaceNodes is not user instantiable.

Note

Remember to check whether each of the pre-listed nodes are is_available(), is_readable(), is_writable() etc.

release(self)

Releases the interface’s resources, including its nodes.

Once called, non of the pre-listed node are valid and other interface methods should not be called.

send_command(self, unsigned int device_key, unsigned int group_key, unsigned int group_mask, unsigned long long action_time=0, unsigned int num_results=0)

Broadcast an Action Command to all devices on this interface.

Parameters

device_key – The action command’s device key.
group_key – The action command’s group key.
group_mask – The action command’s group mask.
action_time – Time when to assert a future action. Zero (default) means immediate action.
num_results – The number of results expected in the return list. The value passed should be equal to the expected number of devices that acknowledge the command. The returned list will be the actual number of received results. If this is 0, the function will return as soon as the command has been broadcasted.

Returns

A list of tuples, one tuple for each item in the result. Each tuple is (address, status), where address is the device address and status is the status string from cmd_status_names.

update_camera_list(self)

Updates the internal list of cameras on this interface, returning a bool indicating whether there has been any changes and cameras have arrived or been removed.

Returns: True if cameras changed on interface and False otherwise.

If desired to get the new cameras, call create_from_interface() because existing CameraList will not reflect the updates.