# Amplifier Calibration

## Functions
DLLEXPORT TECELLA_ERRNUM CALL | tecella_calibrate_all (TECELLA_HNDL h)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_calibrate_save (TECELLA_HNDL h, const char *foldername, const char *filename=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_calibrate_load (TECELLA_HNDL h, const char *foldername, const char *filename=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_scale (TECELLA_HNDL h, bool enable, int unused_stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_scale_enable (TECELLA_HNDL h, bool enable)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_scale_enable_get (TECELLA_HNDL h, bool *enable)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_calibrate (TECELLA_HNDL h, bool enable, int unused_stimulus_index=0)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_calibrate_enable (TECELLA_HNDL h, bool enable)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_calibrate_enable_get (TECELLA_HNDL h, bool *enable)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_calibrate_get (TECELLA_HNDL h, int channel, int *offset)
DLLEXPORT TECELLA_ERRNUM CALL | tecella_auto_calibrate_set (TECELLA_HNDL h, int channel, int offset)

## Detailed Description

These functions help calibrate various parameters of the amplifier to account for the various hardware component tolerances.

Call tecella_calibrate_all() to calibrate the amplifier, then call tecella_calibrate_save() to save the calibration info of the amplifier. Then, in the future, you can just call tecella_calibrate_load() after tecella_initialize() to load the amplifier's calibration info.

Other functions documented below are available for more fine-grained control of the calibrations.

## Function Documentation

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_calibrate | ( | TECELLA_HNDL | h,
|  | bool | enable,
|  | int | unused_stimulus_index = `0` |
| ) |  |  |

This calibrates any input offsets due to component tolerances WITHIN the amplifier. Make sure source is set to OPEN to isolate any external interference. You should only need need to run this once after initialization. A 0mV stimulus is played to establish a "tare" value for acquisitions on a per-channel basis. Subsequent acquisitions are adjusted by these per-channel tare values. Only channels that are enabled by tecella_acquire_enable_channel() will be affected by a call to this function. This function may not be used while acquiring.

Parameters:

  | h | A handle to an initialized device.
  | enable | Indicates whether we are enabling/disabling the offset.
  | unused_stimulus_index | An unused stimulus that tecella_auto_calibrate can use. Only associated channels are calibrated.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_calibrate_enable | ( | TECELLA_HNDL | h,
|  | bool | enable |
| ) |  |  |

Enables or disables the auto calibration used from the most recent call to tecella_auto_calibrate(). Does not perform any calibration. If the offsets haven't been calibrated yet, this function has no effect.

Parameters:

  | h | A handle to an initialized device.
  | enable | Indicates whether we are enabling/disabling auto calibration. If disabled, the ideal scales will be used, whether or not they are correct.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_calibrate_enable_get | ( | TECELLA_HNDL | h,
|  | bool * | enable |
| ) |  |  |

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_calibrate_get | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | int * | offset |
| ) |  |  |

Returns the current offset added to the incomming waveform. To get the actual units of the offset multiply by the scale returned by tecella_acquire_i2d_scale().

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel for which to get the calibration of.
  | offset | A pointer for the returned offset.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_calibrate_set | ( | TECELLA_HNDL | h,
|  | int | channel,
|  | int | offset |
| ) |  |  |

Manually sets the offsets added to the incomming waveform. To get the actual units of the offset multiply by the scale returned by tecella_acquire_i2d_scale().

Parameters:

  | h | A handle to an initialized device.
  | channel | The channel for which to get the calibration of.
  | offset | A pointer for the returned offset.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_scale | ( | TECELLA_HNDL | h,
|  | bool | enable,
|  | int | unused_stimulus_index = `0` |
| ) |  |  |

Internally calibrates the gain settings to be within the tolerance speced for the amplifier. Some gain feedback resistors have large tolerances and must be calibrated to be within specification. Only channels that are enabled by tecella_acquire_enable_channel() will be affected by a call to this function. You should only need need to run this once after initialization. This function may not be used while acquiring.

Parameters:

  | h | A handle to an initialized device.
  | enable | Indicates whether we are enabling/disabling the auto scale. If disabled, the ideal scales will be used, whether or not they are correct.
  | unused_stimulus_index | An unused stimulus that tecella_auto_scale can use. Only associated channels are calibrated.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_scale_enable | ( | TECELLA_HNDL | h,
|  | bool | enable |
| ) |  |  |

Enables or disables the auto scale used from the most recent call to tecella_auto_scale(). Does not perform any calibration. If the scale hasn't been calibrated yet, this function has no effect.

Parameters:

  | h | A handle to an initialized device.
  | enable | Indicates whether we are enabling/disabling the auto scale. If disabled, the ideal scales will be used, whether or not they are correct.

DLLEXPORT TECELLA_ERRNUM CALL tecella_auto_scale_enable_get | ( | TECELLA_HNDL | h,
|  | bool * | enable |
| ) |  |  |

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

Calibrates the amplifier for various offsets and scale factors. Equivalent of calling tecella_auto_calibrate() and tecella_auto_scale() individually for each user_config separately.

Parameters:

  | h | A handle to an initialized device.

DLLEXPORT TECELLA_ERRNUM CALL tecella_calibrate_load | ( | TECELLA_HNDL | h,
|  | const char * | foldername,
|  | const char * | filename = `0` |
| ) |  |  |

Loads offset and scale calibration settings from a file.

Parameters:

  | h | A handle to an initialized device.
  | foldername | Folder in which to save the calibration file.
  | filename | The filename of the configuration file. If no filename is specified or if the pointer is NULL, filename will be "amplifier_calibration_<serial_number>".

DLLEXPORT TECELLA_ERRNUM CALL tecella_calibrate_save | ( | TECELLA_HNDL | h,
|  | const char * | foldername,
|  | const char * | filename = `0` |
| ) |  |  |

Saves the current offset and scale calibration settings to a file.

Parameters:

  | h | A handle to an initialized device.
  | foldername | Folder in which to save the calibration file.
  | filename | The filename of the configuration file. If no filename is specified or if the pointer is NULL, filename will be "amplifier_calibration_<serial_number>".