Functions for changing Local Settings. More...

Functions
FF_Error_t	STFF::STFishFinder::SetNumInputSamples (uint16_t numInputSamples)
	Setter function to establish the number of samples that will be provided by the black box when transferring each column of image data to the API. More...

FF_Error_t	STFF::STFishFinder::SetFrequencyMode (FF_FrequencyMode_t frequencyMode)
	Setter function to specify the Frequency Mode setting for the black box and the API. More...

FF_Error_t	STFF::STFishFinder::SetAutoGainSetting (FF_AutoGainSetting_t autoGainSetting)
	Setter function to specify the Auto Gain setting for the black box and the API. More...

FF_Error_t	STFF::STFishFinder::SetAutoRangeSetting (FF_AutoRangeSetting_t autoRangeSetting, FF_DepthUnits_t units)
	Setter function to specify the Auto Range setting for the black box and the API. More...

FF_Error_t	STFF::STFishFinder::SetRange (const FF_RangeSetting_t *pRangeSetting)
	Setter function to "manually" specify the Range setting for the black box and the API. More...

FF_Error_t	STFF::STFishFinder::SetGain (FF_Frequency_t frequency, uint16_t gainSetting)
	Setter function to "manually" specify the Gain setting for the black box. More...

FF_Error_t	STFF::STFishFinder::SetGainOffset (FF_Frequency_t frequency, int16_t gainOffset)
	Setter function to specify the Gain Offset setting for the black box. More...

FF_Error_t	STFF::STFishFinder::SetGainColorOffsets (FF_Frequency_t frequency, uint16_t numColors, const uint16_t *pGainColorOffsets)
	Setter function to specify the number of colors the API should provide in the STFF::ImageColumn data, and the table of gain offset steps to use for separating the received sonar signal into its colors. More...

FF_Error_t	STFF::STFishFinder::SetFishIdSetting (FF_Frequency_t frequency, const FF_FishIdSetting_t *pFishIdSetting)
	Setter function to specify the Fish ID setting for the black box and the API. More...

Detailed Description

Functions for changing Local Settings.

These are member functions of the STFishFinder class.

Local Settings (unlike Master Settings) do not affect other displays and applications that are simultaneously connected to the same black box. Local Settings are volatile, and are not retained by the black box through disconnect/reconnect cycles. It is therefore recommended that the application program store Local Settings in persistent storage (e.g. flash memory, hard drive, etc.), and call the various setter functions upon each reconnection to the black box.

See also: Getters for Local Settings; Setters for Master Settings

Function Documentation

STFF::STFishFinder::SetAutoGainSetting ( FF_AutoGainSetting_t autoGainSetting )

#include <STFF-FishFinder.h>

Setter function to specify the Auto Gain setting for the black box and the API.

The Auto Gain setting can have one of two values: Auto or Manual.

The Auto Gain setting applies to both the 200 kHz and 50 kHz frequency contexts.

In addition to changing the Auto Gain setting to Auto or Manual, this function also affects the Gain and/or Gain Offset values for both frequencies as follows:

If Auto Gain is being changed from Manual to Auto, then the Gain Offset value for each frequency is reset to 0 upon entering Auto mode.
If Auto Gain is being changed from Auto to Manual, then the Gain value for each frequency is increased or decreased by the corresponding current setting of the Gain Offset value, so as to maintain the same effective level of gain.

The Auto Gain setting is a Local Setting .

Parameters

[in] autoGainSetting the requested Auto Gain setting.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the `autoGainSetting` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_AUTO_GAIN_SETTING
FF_Frequency_t	FF_INVALID_FREQUENCY
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetAutoGainSetting(); FF_AutoGainSetting_t; SetGain(); SetGainOffset(); Setters

STFF::STFishFinder::SetAutoRangeSetting	(	FF_AutoRangeSetting_t	autoRangeSetting,
		FF_DepthUnits_t	units
	)

#include <STFF-FishFinder.h>

Setter function to specify the Auto Range setting for the black box and the API.

The Auto Range setting can have one of three values: Auto Range, Auto Shift, or Manual.

In Auto Range mode, the shallow range limit is fixed at 0, and the deep range limit is adjusted automatically to keep the seabed visible in the lower part of the image column.
In Auto Shift mode, the delta between the shallow and deep range limits is fixed, and they are adjusted automatically in tandem to keep the seabed visible. The amount of delta is established as the delta at the time the Auto Range setting is changed to Auto Shift mode.
In Manual mode, the shallow and deep range limits are fixed and may be specified by calling SetRange().

The Auto Range setting applies to both the 200 kHz and 50 kHz frequency contexts.

The Auto Range setting is a Local Setting .

Parameters

[in]	autoRangeSetting	the requested Auto Range setting.
[in]	units	the depth units that the Auto Range or Auto Shift modes should use when automatically changing the range. This parameter is ignored when the `autoRangeSetting` parameter is set to FF_AUTO_RANGE_SETTING_MANUAL.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the `autoRangeSetting` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_AUTO_RANGE_SETTING
FF_Frequency_t	FF_INVALID_FREQUENCY
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetAutoRangeSetting(); FF_AutoRangeSetting_t; SetRange(); Setters

STFF::STFishFinder::SetFishIdSetting	(	FF_Frequency_t	frequency,
		const FF_FishIdSetting_t *	pFishIdSetting
	)

#include <STFF-FishFinder.h>

Setter function to specify the Fish ID setting for the black box and the API.

Separate Fish ID settings are used for the 200 kHz and 50 kHz frequency contexts.

The Fish ID setting is a Local Setting .

Parameters

[in]	frequency	The frequency context for which the Fish ID setting will apply.
[in]	pFishIdSetting	pointer to a location containing the requested Fish ID setting. The `*pFishIdSetting` value is a struct of type FF_FishIdSetting_t. [Further description TBD]

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_INVALID_FREQUENCY	if the provided `frequency` parameter has an invalid value (see FF_Frequency_t)
FF_ERR_ARGUMENT_OUT_OF_RANGE	if any of the members of the FF_FishIdSetting_t struct pointed to by the `pFishIdSetting` parameter are outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_FISH_ID_SETTING
FF_Frequency_t	the value of the `frequency` argument in the call to SetFishIdSetting()
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetFishIdSetting(); Setters

STFF::STFishFinder::SetFrequencyMode ( FF_FrequencyMode_t frequencyMode )

#include <STFF-FishFinder.h>

Setter function to specify the Frequency Mode setting for the black box and the API.

The Frequency Mode specifies whether the black box should provide image data for 200 kHz only, 50 kHz only, or alternating 200 kHz / 50 kHz.

The Frequency Mode setting is a Local Setting .

Parameters

[in] frequencyMode the requested Frequency Mode setting.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the `frequencyMode` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_FREQUENCY_MODE
FF_Frequency_t	FF_INVALID_FREQUENCY
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetFrequencyMode(); FF_FrequencyMode_t; Setters

STFF::STFishFinder::SetGain	(	FF_Frequency_t	frequency,
		uint16_t	gainSetting
	)

#include <STFF-FishFinder.h>

Setter function to "manually" specify the Gain setting for the black box.

Separate Gain settings are used for the 200 kHz and 50 kHz frequency contexts.

The Gain setting is a Local Setting .

Note: If the Auto Gain setting is not already in Manual mode prior to calling this function (i.e. FF_AUTO_GAIN_SETTING_MANUAL), then the call to this function SetGain() shall change the Auto Gain setting to Manual as a consequence of setting the gain.

Parameters

[in]	frequency	The frequency context for which the Gain is to be set.
[in]	gainSetting	the requested Gain setting. The value of the `gainSetting` parameter must fall within the range of values specified by the GetGainLimits() function.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_INVALID_FREQUENCY	if the provided `frequency` parameter has an invalid value (see FF_Frequency_t)
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the provided `gainSetting` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_GAIN
FF_Frequency_t	the value of the `frequency` argument in the call to SetGain()
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetGain(); GetGainLimits(); SetAutoGainSetting(); Setters

STFF::STFishFinder::SetGainColorOffsets	(	FF_Frequency_t	frequency,
		uint16_t	numColors,
		const uint16_t *	pGainColorOffsets
	)

#include <STFF-FishFinder.h>

Setter function to specify the number of colors the API should provide in the STFF::ImageColumn data, and the table of gain offset steps to use for separating the received sonar signal into its colors.

The table of gain offset steps establishes the total dynamic range of the displayed image, and plays a significant role in defining the 'personality' of the fish finder. A wider dynamic range tends to provide more information on the fish finder display (i.e. more signal, and possibly more clutter).

The number of colors must be the same for both 200 kHz and 50 kHz frequency contexts, but the tables of gain offset steps are specified separately for the two frequencies.

The Gain Color Offsets settings are Local Settings .

Parameters

[in]	frequency	the frequency context for which the Gain Color Offsets are to be set.
[in]	numColors	the total number of colors in the spectrum within STFF::ImageColumn objects generated by the API. This value must be between 2 and 2^(bit depth) inclusive. Therefore:

For bit depth 4: 2 <= numColors <= 16
For bit depth 8: 2 <= numColors <= 256

Important Note: The same value must be used for the numColors parameter in both 200 kHz and 50 kHz frequency contexts. Do not specify a different value for numColors for 50 kHz than for 200 kHz.

Parameters

[in] pGainColorOffsets pointer to the start of an array of Gain Color Offset values. The number of values in the array must be (numColors - 2). Each value in the array corresponds to a relative threshold of signal strength that divides two adjacent colors in the spectrum. With the total number of colors being numColors, the total number of boundaries between adjacent colors is (numColors - 1). The boundary between the strongest color and the second-strongest color is defined to have an offset of 0. All other offsets are relative to this specific boundary. Since this first offset is fixed at 0, it doesn't need to be expressly provided in the pGainColorOffsets array. The array therefore consists of the offsets for the remaining (numColors - 2) color boundaries. Each value in the array is a signal strength offset, measured in gain steps, from the lowest threshold (0) to the current threshold. The first provided element in the array (at array index 0) must contain the difference in signal strength (measured in gain steps) between the lowest threshold (0) and the threshold between the second-strongest color and the third-strongest color. Each subsequent element in the array must be >= the previous element in the array. The values near the beginning of the array correspond to color offsets for strong signals, and the values near the end of the array correspond to color offsets for weak signals.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_INVALID_FREQUENCY	if the provided `frequency` parameter has an invalid value (see FF_Frequency_t)
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the provided `numColors` value is outside the range of 2 <= `numColors` <= 2^(bit depth), or if the provided values in the pGainColorOffsets array do not follow the rule pGainColorOffsets[n] >= pGainColorOffsets[n-1] for all n, 0 < n < (numColors-2)
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_GAIN_COLOR_OFFSETS
FF_Frequency_t	the value of the `frequency` argument in the call to SetGainOffset()
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetGainColorOffsets(); GetGainColorOffsetsLimits(); Setters

STFF::STFishFinder::SetGainOffset	(	FF_Frequency_t	frequency,
		int16_t	gainOffset
	)

#include <STFF-FishFinder.h>

Setter function to specify the Gain Offset setting for the black box.

Separate Gain Offset settings are used for the 200 kHz and 50 kHz frequency contexts.

The Gain Offset setting is a Local Setting .

Parameters

[in]	frequency	The frequency context for which the Gain Offset is to be set.
[in]	gainOffset	the requested Gain Offset setting. The value of the `gainOffset` parameter must fall within the range of values specified by the GetGainOffsetLimits() function.

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_INVALID_FREQUENCY	if the provided `frequency` parameter has an invalid value (see FF_Frequency_t)
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the provided `gainOffset` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_GAIN_OFFSET
FF_Frequency_t	the value of the `frequency` argument in the call to SetGainOffset()
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetGainOffset(); GetGainOffsetLimits(); SetAutoGainSetting(); Setters

STFF::STFishFinder::SetNumInputSamples ( uint16_t numInputSamples )

#include <STFF-FishFinder.h>

Setter function to establish the number of samples that will be provided by the black box when transferring each column of image data to the API.

A single Number of Input Samples setting applies to both the 200 kHz and 50 kHz frequency contexts.

The Number of Input Samples setting is a Local Setting .

Note

The value to be used in the parameter to this function should be chosen carefully. Higher values increase the resolution of the image that may be displayed, but also increase the amount of data that must be transferred and the amount of data that must be processed by the API and by the application program. It is suggested that performance benchmark testing be conducted in a loaded system to determine an optimum value for numInputSamples to achieve a good balance between scrolling speed, responsiveness, and image resolution.
The value provided in the numInputSamples parameter should be regarded as a request. It is possible that the black box might override the value requested with a different value. This can happen if this function is called with an illegal value, or the black box may attempt to balance the needs of multiple connected display devices by adjusting some of the settings values. Therefore, it is recommended that after the black box has responded to the setting change, the GetNumInputSamples() function be called to verify the new setting. This can be done in the Callback_SettingChanged_t callback function.

Parameters

[in] numInputSamples the number of samples per column requested to be provided by the black box when it transfers image data to the API. This value must fall within the range of values established by a prior call to GetInputSamplesLimits(), such that MinInputSamples <= numInputSamples <= MaxInputSamples

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_ARGUMENT_OUT_OF_RANGE	if the `numInputSamples` parameter is outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_NUM_INPUT_SAMPLES
FF_Frequency_t	FF_INVALID_FREQUENCY
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetNumInputSamples(); GetInputSamplesLimits(); Setters

STFF::STFishFinder::SetRange ( const FF_RangeSetting_t * pRangeSetting )

#include <STFF-FishFinder.h>

Setter function to "manually" specify the Range setting for the black box and the API.

The Range setting applies to both the 200 kHz and 50 kHz frequency contexts.

The Range setting is a Local Setting .

Note: If the Auto Range setting is not already in Manual mode prior to calling this function (i.e. FF_AUTO_RANGE_SETTING_MANUAL), then the call to this function SetRange() shall change the Auto Range setting to Manual as a consequence of setting the range.

Parameters

[in] pRangeSetting pointer to a location containing the requested Range setting. The *pRangeSetting value is a struct of type FF_RangeSetting_t that specifies the shallow and deep limits to be used for subsequently transmitted ImageColumn objects. The struct contains a shallow depth value corresponding to the first sample in the ImageColumn buffer, a deep depth value corresponding to the last sample, and a depth units specifier indicating whether the depth values are in units of feet, meters, or fathoms.

The depth values must be provided in hundredths of the specified depth units. For example, for a 20 to 40 foot range, the rangeShallow member should contain 2000, the rangeDeep member should contain 4000, and the units member should contain FF_DEPTH_UNITS_FEET.

The value of the rangeDeep member must fall within the range of values specified by the GetRangeLimits() function. The value of the rangeShallow member must obey the following rule: 0 <= rangeShallow < rangeDeep

Return values

FF_ERR_NO_ERROR	if the operation completed successfully
FF_ERR_ARGUMENT_OUT_OF_RANGE	if any of the members of the FF_RangeSetting_t struct pointed to by the `pRangeSetting` parameter are outside the range of allowable values.
FF_ERR_API_NOT_INITIALIZED	if the API status is not FF_API_STATUS_READY prior to calling this function
FF_ERR_BAD_DATABASE	if the API encounters an internal error

Callback: This function will cause the Callback_SettingChanged_t callback function to be invoked. The parameters to that callback will be as follows:

Callback Parameter	Value
FF_SettingType_t	FF_SETTING_TYPE_RANGE
FF_Frequency_t	FF_INVALID_FREQUENCY
const STFishFinder*	pointer to the present instance of the STFishFinder class

Note: Do not call this function before the API status has reached FF_API_STATUS_READY. See How To Connect to a Black Box Fish Finder for details.

Refer to Setters for a general description of the actions performed by setters such as this function, and the subsequent events that result.

See also: GetRange(); GetRangeLimits(); FF_RangeSetting_t; SetAutoRangeSetting(); Setters