SP259 API Reference
This document details every function available in the SP259 device API. For each function, a description is provided along with its parameters and return values.
Library Instance Management
sp259api_create_new_handle
Description:
Creates a new handle that can be later used to call the functions of this API.
Parameters:
sp259api_handle *handle: Pointer to a handle variable where the newly created handle will be stored.sp259api_model_t model: Specifies the device model to be used when creating the handle.
Return Value:
Returns an ihwapi_err_code_t error code indicating the success or failure of the operation.
sp259api_free
Description:
Clears a handle by freeing all the memory used by it.
Parameters:
sp259api_handle handle: The handle to be freed.
Return Value:
Returns an ihwapi_err_code_t error code.
Device Listing Functions
sp259api_create_device_list
Description:
Creates (or updates) the list of SP259 devices that can be found on the USB.
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_free_device_list
Description:
Frees the memory used to store the list of current devices.
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_devices_count
Description:
Retrieves the number of devices that were found when the device list was created with sp259api_create_device_list.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint16_t *count: Pointer to a variable where the number of devices will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_device_descriptor
Description:
Obtains the device descriptor for a device on the bus. The function sp259api_create_device_list must be called before invoking this function. The device descriptor is required to open an SP259 device.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t device_number: The 0-based index of the device.device_descriptor_t *d: Pointer where the device descriptor will be written (the user does not need to allocate memory for this).
Return Value:
Returns an ihwapi_err_code_t error code.
General Device Commands
sp259api_device_open
Description:
Opens an SP259 device using a device descriptor.
Note: The function comment mentions a "variant" parameter for specifying the device operation mode (to support devices with custom firmware), but in the signature only the device descriptor is provided.
Parameters:
sp259api_handle handle: The handle associated with the API instance.device_descriptor_t desc: The device descriptor of the SP259 device to be opened.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_device_open_first
Description:
Opens the first available SP259 device found.
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_device_close
Description:
Closes the currently opened SP259 device.
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_fpga_version
Description:
Retrieves the FPGA version of the opened SP259 device.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t *v: Pointer to a variable where the FPGA version will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_hw_version
Description:
Retrieves the hardware version of the opened SP259 device.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t *v: Pointer to a variable where the hardware version will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_device_open_flag
Description:
Returns a boolean flag indicating whether the device is open (i.e., if the connection is still active).
Parameters:
sp259api_handle handle: The handle associated with the API instance.bool *f: Pointer to a boolean variable that will be set totrueif the device is open.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_request_abort
Description:
Requests that any pending operation be aborted. This function returns immediately without verifying whether the operation was effectively aborted.
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_launch_new_capture_simple_trigger
Description:
Starts a new capture of samples. Capture begins as soon as possible after the function is called. This function does not offer complex trigger options (like trigger on protocol, or multi-step trigger sequences that can only be defined via ScanaStudio for the time being).
Parameters:
sp259api_handle handle: The handle associated with the API instance.sp259api_trigger_description_t trig: The first trigger description to be used for this capture.sp259api_trigger_description_t trig_b: The second trigger description to be used for this capture.sp259api_settings_t settings: The settings to be used for the SP259 device capture.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_config_done_flag
Description:
Checks if the device has finished its internal configuration after a request to launch a new capture. Although the device usually configures in a few milliseconds, this function is available for feedback and monitoring purposes.
Parameters:
sp259api_handle handle: The handle associated with the API instance.bool *f: Pointer to a boolean variable that will be set totrueif configuration is done andfalseotherwise.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_triggered_flag
Description:
Retrieves a flag indicating whether the device has triggered.
Parameters:
sp259api_handle handle: The handle associated with the API instance.bool *f: Pointer to a boolean variable that will be set totrueif the device has triggered.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_trigger_position
Description:
Gets the trigger position expressed in samples.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint64_t *trig_pos: Pointer to a variable where the trigger position will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_available_samples
Description:
Retrieves the number of samples that have been read from the device, buffered, and are ready for readout. It provides both the total available samples and the number of samples after the trigger condition.
Parameters:
sp259api_handle handle: The handle associated with the API instance.int64_t *total_available_samples: Pointer to a variable to hold the total number of available samples.int64_t *post_trig_samples: Pointer to a variable to hold the number of samples captured after the trigger.
Return Value:
Returns an ihwapi_err_code_t error code.
Transitions Iterator Functions
sp259api_trs_reset
Description:
Resets the transitions iterator for the specified channel. After calling this function, the next call to trs_get_next() will retrieve the very first transition.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t channel_index: The index of the channel for which the iterator will be reset.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_trs_before
Description:
Resets the transitions iterator for the specified channel and positions it right before the given target sample. After this call, the next call to trs_get_next() will retrieve the first transition occurring after target_sample.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t channel_index: The index of the channel.uint64_t target_sample: The sample position before which the iterator will be reset.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_trs_get_next
Description:
Advances the transition iterator for the specified channel to the next transition and writes its details into the provided structure. Prior to calling this function, the user must call either trs_reset() or trs_before().
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t channel_index: The index of the channel.sp259api_trs_t *transition_data: Pointer to a structure where the details of the transition will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_trs_get_previous
Description:
Rewinds the transition iterator for the specified channel to the previous transition and writes the details into the provided structure. This function is similar to trs_get_next() but in reverse.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t channel_index: The index of the channel.sp259api_trs_t *transition_data: Pointer to a structure where the details of the transition will be stored.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_trs_is_not_last
Description:
Determines whether the current transition pointed to by the iterator for the specified channel is the last transition. The output flag is set to true if there are further transitions available.
Parameters:
sp259api_handle handle: The handle associated with the API instance.uint8_t channel_index: The index of the channel.bool *is_not_last_trs: Pointer to a boolean variable that will be set totrueif the current transition is not the last one.
Return Value:
Returns an ihwapi_err_code_t error code.
Capture Status Functions
sp259api_get_capture_done_flag
Description:
Checks if the current capture is finished and all data has been retrieved from the device. In the case of an error or an aborted capture, this flag will always return false.
Parameters:
sp259api_handle handle: The handle associated with the API instance.bool *f: Pointer to a boolean variable that will hold the state of thecapture doneflag.
Return Value:
Returns an ihwapi_err_code_t error code.
sp259api_get_ready_flag
Description:
Determines if the device is ready or if an operation is still in progress.
Parameters:
sp259api_handle handle: The handle associated with the API instance.bool *f: Pointer to a boolean variable that will hold the state of thereadyflag.
Return Value:
Returns an ihwapi_err_code_t error code.
Error management
sp259api_get_last_error
Description:
Returns the last error that may have been thrown by the API’s internal threads. This can be useful for diagnosing unexpected behavior or abnormal response times (for example, if the config_done flag never becomes true).
Parameters:
sp259api_handle handle: The handle associated with the API instance.
Return Value:
Returns an ihwapi_err_code_t error code.