.. _sourcehandles:

Source Handles
===============

A Source is a transient object. They are created when they are discovered, so for instance when our hardware driver informs us of a new device, it will be cleaned up when the device is unplugged. From a user's point of view, it is almost always desirable to have a non-transient object to work with. A user wants to describe the hardware they expect to be attached and how it connects with other objects in the topology in a way that can be created from the scripting engine or UI. This is where the :py:class:`vspyx.Communication.SourceHandle` comes in.

A "source description" is a string provided to the SourceHandle, and the SourceHandle will search for a source matching the description on your behalf. Sources will have a description which matches them directly, usually something like the serial number or MAC address. For a ValueCAN 4-2 with serial number "V20012", the description is `"icsneo V20012"`. The `"icsneo"`` portion is used to denote that the Intrepid hardware driver should handle this request. 

Wildcards are also supported in source descriptions. They are denoted with two stars and a number. So if, for instance, you wanted the first ValueCAN 4-2 found by the software, you could put a description of `"icsneo V2**1"` into your handle. If you wanted the first intrepid device of any kind, you could use `"icsneo **1"`.

The SourceHandle now handes the state of the Sources in your setup or script. When you start the simulation, the Sources will automatically be enabled. If a Source disappears, for instance if the USB cable is unexpectedly removed, the SourceHandle will handle automatically reconnecting the Source when it reappears.