# Amplifier Initialization and Cleanup

## Functions
DLLEXPORT TECELLA_ERRNUM CALL | tecella_enumerate (int *device_count)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_enumerate_get (int device_index, TECELLA_HW_PROPS *description)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_initialize (TECELLA_HNDL *h, int device_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_initialize_pair (TECELLA_HNDL *h, TECELLA_HNDL hA, TECELLA_HNDL hB)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_finalize (TECELLA_HNDL h)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_user_config_get (TECELLA_HNDL h, int user_config, TECELLA_HW_PROPS *description)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_user_config_set (TECELLA_HNDL h, int user_config)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_user_config_get_current (TECELLA_HNDL h, int *user_config)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_initialize_from_file (TECELLA_HNDL *ph, char *filename)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_finalize_to_file (TECELLA_HNDL h, char *filename)

## Detailed Description

TecellaAmp makes it very easy to initialize the first available amplifier; just call tecella_initialize() with device_index=0 and you can start using the handle immediately. Then, when your program is done using the amplifier, call tecella_finalize() to allow other programs to use the amplifier.

Some amplifiers support multiple configurations, such as voltage clamp and current clamp modes. To enumerate and switch between these configurations, see tecella_user_config_get() and tecella_user_config_set().

More advanced features include amplifier enumeration (if you don't always want to use the first available amplifer) and amplifier pairing to control two or more amplifiers as if they were a single amplifier. For amplifier enumeration, see tecella_enumerate() and tecella_enumerate_get(). For amplifier pairing, see tecella_initialize_pair().

For some applications that use multiple processes, it may be useful if different processes can pass control of the amplifier around without having to do a full finalize and initialize. For this purpose, you may use the tecella_finalize_to_file() and tecella_initialize_from_file() functions to quickly passes calibration info and the current state of the amplifier between processes.

## Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_enumerate | ( | int * | device_count | ) |

Enumerates all Tecella amplifiers currently connected to the computer. Any subsequent calls to tecella_enumerate_descriptions() and tecella_initialize() will use the devices enumerated at the time of the last call to tecella_enumerate(). If a device has been connected after calling tecella_enumerate(), it will not affect initialization of the other amplifiers but will not have a corresponding device_index with which to initialize. If a device has been disconnected after calling tecella_enumerate(), it will not affect initialization of the other amplifiers but will fail to initialize.

Parameters:

  | device_count | A return pointer to hold the number of devices enumerated.

DLLEXPORT TECELLA_ERRNUM CALL tecella_enumerate_get | ( | int | device_index,
|  | TECELLA_HW_PROPS * | description |
| ) |  |  |

Returns the description of an amplifier as enumerated by the most recent call to tecella_enumerate().

Parameters:

  | device_index | A number >= 0 and < device_count as returned by tecella_enumerate().
  | description | A return pointer to a TECELLA_HW_PROPS structure that describes the device as indexed by device_index.

DLLEXPORT TECELLA_ERRNUM CALL tecella_finalize | ( | TECELLA_HNDL | h | ) |

Closes a device gracefully and deallocates any memory associated with it.

Parameters:

  | h | A handle to an initialized device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_finalize_to_file | ( | TECELLA_HNDL | h,
|  | char * | filename |
| ) |  |  |

Closes a device gracefully and deallocates any memory associated with it. Saves state to a file so another process can call tecella_initialize_from_file() to quickly transfer ownership of the amplifier.

Parameters:

  | h | A handle to an initialized device.
  | filename | Filename of the file to which the state will be stored.

DLLEXPORT TECELLA_ERRNUM CALL tecella_initialize | ( | TECELLA_HNDL * | h,
|  | int | device_index = `0` |
| ) |  |  |

Initializes the specified device and returns a handle for it. tecella_initialize() will automatically call tecella_enumerate() if it hasn't already been called by ther user. The default user configuration is used. After initialization you may change the user configuration via tecella_user_config_get() and tecella_user_config_set().

Parameters:

  | h | Pointer to a handle
  | device_index | The device index corresponding to the most recent call to tecella_enumerate().

Postcondition:
  Upon success, h will point to a valid handle for the requested device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_initialize_from_file | ( | TECELLA_HNDL * | ph,
|  | char * | filename |
| ) |  |  |

Returns a handle for a previously intialized device that was finalized via tecella_finalize_to_file(). All state and calibration info is loaded from the file.

Parameters:

  | ph | Pointer to a handle
  | filename | Filename of the file created by tecella_finalize_

Postcondition:
  Upon success, h will point to a valid handle for the requested device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_initialize_pair | ( | TECELLA_HNDL * | h,
|  | TECELLA_HNDL | hA,
|  | TECELLA_HNDL | hB |
| ) |  |  |

Takes two handles of already initilaized amplifiers and makes it look like a single amplifier. This is only supported if both amplifiers are the same. To comibine three or more amplifiers, you can chain multiple pairs together.

Parameters:

  | h | Pointer to a handle
  | hA | A handle previously returned by tecella_initialize()
  | hB | A handle previously returned by tecella_initialize(). Must be different than h1.

Postcondition:
  Upon success, h will point to a valid handle for the requested device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_user_config_get | ( | TECELLA_HNDL | h,
|  | int | user_config,
|  | TECELLA_HW_PROPS * | description |
| ) |  |  |

Returns details for a specific amplifier configuration.

Parameters:

  | h | A handle to an initialized device.
  | user_config | A valid user configuration index. Must be greater than or equal to 0 and less than the user_config_count field returned by tecella_get_hw_props() or tecella_enumerate_get().
  | description | A return pointer to a TECELLA_HW_PROPS structure that describes the device if it were configured with user_config.

DLLEXPORT TECELLA_ERRNUM CALL tecella_user_config_get_current | ( | TECELLA_HNDL | h,
|  | int * | user_config |
| ) |  |  |

If the amplifier supports a user selectable configuration, you may use this function to determine which configuration is currently used.

Parameters:

  | h | A handle to an initialized device.
  | user_config | A return pointer to hold the current user configuration index.

DLLEXPORT TECELLA_ERRNUM CALL tecella_user_config_set | ( | TECELLA_HNDL | h,
|  | int | user_config |
| ) |  |  |

If the amplifier supports a user selectable configuration, it may be set here. The configuration may only be set when not acquiring. This function will switch the amplifier between IClamp and VClamp modes if supported by the hardware. When in IClamp mode and supports_iclamp_enable is true, use tecella_chan_set_iclamp_enable() to swith between IClamp and Voltage Follower on a per-channel basis.

Parameters:

  | h | A handle to an initialized device.
  | user_config | A valid user configuration index. Must be greater than or equal to 0 and less than the user_config_count field returned by tecella_get_hw_props() or tecella_enumerate_get().