STFishFinder API  API version 0.0.0, Documentation version 3 -PRELIMINARY-
Best Practices when Using the STFishFinder API


1. Check returned FF_Error_t error codes.
When calling API functions having a return error code (FF_Error_t), always check the return code, and perform appropriate action if the value is not FF_ERR_NO_ERROR.
2. Be aware of the behavior of Setter functions.

When a call to a Setter function returns, the setting may not yet be activated within the black box. Your code can call a Settings Getter function, and check the returned FF_SettingStatus_t parameter to determine the status of the setting at any time.

Also know that when calling Setter functions, sometimes the API or the black box will coerce the setting to a different value than what was specified in the argument list. When this happens, the displayed setting in the user interface should be adjusted to agree with the setting value provided by the API Settings Getter function. See Setters.

3. Check parameters for validity before calling an API function.
Use the limit values provided by the Limits getter functions and Valid functions to check parameters for validity before calling API functions. Your code should already know that parameters being passed are valid.
4. Don't mislead the user.
When displaying simulated data, make sure the user interface prominently displays a notice to the user that the displayed data is only a simulation.
5. Don't mislead the user here either.
When playing back previously recorded data (using a STFF::Replay obect), make sure the user interface prominently displays a notice to the user that the displayed data is not live.
6. Always display the water depth.
Try to design your user interface to always display the current depth of the water under the boat, regardless of what else is being shown on the screen. See STFF::STFishFinder::GetDepth().
7. Don't show the user invalid data.
Use the FF_DataStatus_t value returned from Data Getter functions to determine the validity of received data before displaying the data.
8. Always indicate whether data being displayed is current.
When displaying live data (especially water depth), always indicate clearly whether the displayed data is current. For example, if valid depth data has not been received from the black box within the past 3 seconds, the displayed digital depth indicator should either dim or start flashing at a steady 1 Hz rate. If it has been more than 10 seconds since valid depth data has been received from the black box, the displayed digital depth indicator should be blanked, or show something like "--.-".
9. Enable the user to update the firmware in the black box.
10. Don't call Setters for Master Settings unless initiated by the user.
Master Settings are stored in non-volatile memory within the black box, and affect all display devices that connect to the black box. They should be changed infrequently, and only at the request of the user.