SP209 API Documentation
Download
The API can be downloaded via this GitHub repository
This repository includes all required header files, the latest binary files in “dependency” folder, as well a fully functional, yet minimal example to help you get started with the API.
Documented C header file
Below is the latest version of the file sp209api_types.h
#ifndef SP209API_TYPES_H
#define SP209API_TYPES_H
#include <stdint.h>
#include "ihwapi_common_types.h"
#if defined(GENERATE_API_WIN)
#define SCANA_API __declspec(dllexport)
#elif defined(GENERATE_API_UNIX)
#define SCANA_API __attribute__((visibility("default")))
#elif defined(GENERATE_API_MAC)
#include "ftd2xxUNIX.h"
#include "WinTypes.h"
#define SCANA_API __attribute__((visibility("default")))
#elif defined(OS_WIN)
#define SCANA_API __declspec(dllimport)
#else
#define SCANA_API
#endif
#define API_VER_MAJ 2
#define API_VER_MIN 0
#define API_VER_PAT 0
#define SP209_CHANNELS_COUNT (9)
#define SP209_TRIG_ENGINES_COUNT (2)
#define SP209_THRESHOLDS_COUNT (3)
#define SP209_MAX_TRIG_STEPS_COUNT (128)
/**
* @brief sp209api_handle Pointer to SP209API
*/
typedef void* sp209api_handle;
/**
* @brief The sp209api_variant_t enum is used to determine which firmware is loaded when openning a device
*/
enum sp209api_variant_t
{
SP209API_VARIANT_STD = 0, ///< Standard SP209 firmware
SP209API_VARIANT_NEXUS = 1, ///< Custom firmware reserved for Nexus bus analyzer
SP209API_VARIANT_TPIU = 2, ///< Custom firmware reserved for TPIU bus analyzer
};
/**
* @brief The sp209api_clock_pol_t enum defines the clock polarity
* of the external clock (if used)
*/
enum sp209api_clock_pol_t
{
CLK_POL_RISING = 1, ///< Rising edge
CLK_POL_FALLING = 0, ///< Falling edge
CLK_POL_DUAL = 2, ///< Dual edge (any rising or falling edge)
};
/**
* @brief The sp209api_device_model_t enum defines the model of the device within SP209 family
* of logic analyzer devices
*/
enum sp209api_device_model_t
{
SP209API_MODEL_NONE = 0, ///< Should never be used.
SP209API_MODEL_209 = 360, ///< Standard SP209
SP209API_MODEL_209I = 370, ///< Industrial SP209i
};
/**
* @brief The sp209api_threshold_t enum defines the thresholds supported by SP209 devices
*/
enum sp209api_threshold_t
{
SP209API_TH_1V8 = 0, ///< 1.8V logic level
SP209API_X_TH_2V5 = 1, ///< 2.5V logic level
SP209API_X_TH_3V3 = 2, ///< 3.3V logic level
SP209API_TH_5V0 = 4, ///< 5.0V logic level
};
/**
* @brief The sp209api_trigger_type_t enum lists the different kind of trigger supported by the API
*/
enum sp209api_trigger_type_t
{
SP209API_TRG_NOTRIG = 0,
SP209API_TRG_RISING,
SP209API_TRG_FALLING,
SP209API_TRG_CHANGE,
SP209API_TRG_EXT_RISING,
SP209API_TRG_EXT_FALLING
};
#pragma pack(push, 4) //Ensure known packing on all platforms
struct sp209api_trigger_description_t
{
/**
* @brief type is the type of trigger (e.g. falling edge, rising edge or logic change).
*/
sp209api_trigger_type_t type;
/**
* @brief channel set to the number of the channel concerned by the trigger,
* or -1 if you wish to target all channels. (-1 is only valid for Logic Change
* type of trigger)
* @note channel is a 0 based index, i.e. first channel is 0.
*/
int8_t channel;
};
/**
* @brief The spx_settings_t struct exposes the options that need to be configured by the user via
* various GUI options.
*/
struct sp209api_settings_t
{
/**
* @brief Total number of samples requested by the user
*/
int64_t sampling_depth;
/**
* @brief Total number of samples after the trigger
*/
int64_t post_trig_depth;
/**
* @brief Trigger clock expressed in HZ
*/
uint32_t t_clk[SP209_TRIG_ENGINES_COUNT];
/**
* @brief An array of thresholds
* @details can be 3, 6, or 12, for SP209, SP218, and SP236
*/
sp209api_threshold_t thresh_cfg[SP209_THRESHOLDS_COUNT];
/**
* @brief enable the use of external (AKA State mode)
*/
bool ext_clk;
/**
* @brief External clock polarity (active edge selection)
*/
sp209api_clock_pol_t ext_clk_pol;
/**
* @brief activate the 50R input resistor on Ext. Trig input
*/
bool ext_trig_50r;
/**
* @brief enable (and use) Ext Trig In as trigger source
*/
bool ext_trig_in[SP209_TRIG_ENGINES_COUNT];
/**
* @brief ext_trig_in_polarity selects the active edge for the external trigger
* 0: Faling edge
* 1: Rising edge
*/
uint8_t ext_trig_in_polarity[SP209_TRIG_ENGINES_COUNT];
uint8_t ext_trig_out_polarity;
/**
* @brief 2 bits describing the operation of the dual trigger engine
* @details the 2 LSB bits describe the operation of the dual trigger engine
* as the following:
* - 00: Trig 0 or Trig 1 (any of the two trigger engines will cause the trigger to be valid)
* - 01: Trig 0 then Trig 1 (Trig 1 is only enabled after Trig 1 occures)
* - 10: Trig 1 then Trig 0 (Trig 0 is only enabled after Trig 0 occures)
* - 11: Trig 0 and Trig 1, in any order.
*/
uint8_t trig_order;
//********
//Industrial version (SP209I) only related settings
//********
/**
* @brief Multiplexing enable for each pin
* @details when enabled an input pin uses the multiplexed (auxiliary input)
* instead of the standard single ended input.
* @note This is only applicable to SP209i (industrial) version
*/
bool mux[SP209_CHANNELS_COUNT];
/**
* @brief can_term when TRUE, CAN bus termination resistor is enabled
* @note This is only applicable to SP209i (industrial) version
*/
bool can_term;
/**
* @brief rs485_1_term when TRUE, RS485 bus number 1's termination resistor is enabled
* @note This is only applicable to SP209i (industrial) version
*/
bool rs485_1_term;
/**
* @brief rs485_2_term when TRUE, RS485 bus bumber 2's termination resistor is enabled
* @note This is only applicable to SP209i (industrial) version
*/
bool rs485_2_term;
};
/**
* @brief The sp209api_transition_t struct describes an SP209 transition
* @details SP209 API provides captured samples in minimal structures called "transition".
* During a transition, a chanel's logic level change. This structure describes this
* transition.
*/
struct sp209api_trs_t
{
uint8_t value; //Line value
/**
* @brief delta_samples Number of samples since the previous transition
*/
int64_t sampple_index; //index of the same associated with that transition
};
#pragma pack(pop)
#endif // SP209API_TYPES_H
Below is the latest version of the file sp209api.h
#pragma once
#include <cstddef>
#include "sp209api_types.h"
#ifdef __cplusplus
extern "C"
{
#endif
// library instance management
/**
* @brief sp209api_create_new_handle This functions creates a new handle that can be
* later used to call the functions of this API.
* @return the newly created handle.
*/
SCANA_API
ihwapi_err_code_t sp209api_create_new_handle(sp209api_handle *h, sp209api_device_model_t model);
/**
* @brief sp209api_free is used to clear a handle (freeing all the memory used).
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp209api_free(sp209api_handle handle);
// Device listing functions
/**
* @brief sp209api_create_device_list is used to create (or update the list
* of SP209 devices that can be found on the USB).
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp209api_create_device_list(sp209api_handle handle);
/**
* @brief sp209api_free_device_list is used to free the memory used to
* store the list of current devices.
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp209api_free_device_list(sp209api_handle handle);
/**
* @brief sp209api_get_devices_count is used to get the list of device
* that was created using the sp209api_create_device_list function.
* @param handle
* @return the number of devices
*/
SCANA_API
ihwapi_err_code_t sp209api_get_devices_count(sp209api_handle handle, uint16_t *count);
/**
* @brief sp209api_get_device_descriptor is used to get the device descriptor
* for a device on the bus. The funciton sp209api_create_device_list must be called
* prior to calling this function. The device descriptor is needed to open an SP209
* device.
* @param handle
* @param device_number, 0-based index.
* @param where device descriptor will be written (no need to be allocated by the user)
* @return error code
*/
SCANA_API
ihwapi_err_code_t sp209api_get_device_descriptor(sp209api_handle handle, uint8_t device_number, device_descriptor_t *d);
// General Device Commands (common to all variants)
/**
* @brief sp209api_device_open Open SP209 device using a device descriptor.
* @param handle
* @param device: the device descriptor
* @param variant: the device variant (or operation mode). Some devices ship with custom,
* application speicifc firmware (like Nexus or TPIU) that are loaded next to the standard (Logic Analyzer)
* firmware. The variant must be specified when openning a device.
* @return error code, see ihwapi_err_code_t type.
*/
SCANA_API
ihwapi_err_code_t sp209api_device_open(sp209api_handle handle, device_descriptor_t device, sp209api_variant_t variant);
SCANA_API
ihwapi_err_code_t sp209api_device_open_first(sp209api_handle handle, sp209api_variant_t variant);
/**
* @brief sp209api_device_power_off is used to switch off SP209 device (effectively
* loosing any configuration made to the device).
* @param handle
* @return error code, see ihwapi_err_code_t type.
*/
SCANA_API
ihwapi_err_code_t sp209api_device_power_off(sp209api_handle handle);
/**
* @brief sp209api_get_firmware_version_major returns the major version of the firmware
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp209api_get_firmware_version_major(sp209api_handle handle, uint8_t *v);
/**
* @brief sp209api_get_firmware_version_minor returns the minor version of the firmware
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp209api_get_firmware_version_minor(sp209api_handle handle, uint8_t *v);
/**
* @brief sp209api_get_bootloader_version_major return the major version of the bootloader
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp209api_get_bootloader_version_major(sp209api_handle handle, uint8_t *v);
/**
* @brief sp209api_get_bootloader_version_minor returns the minor version of the bootloader
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp209api_get_bootloader_version_minor(sp209api_handle handle, uint8_t *v);
/**
* @brief sp209api_get_device_open_flag returns TRUE if the device is open (connection is still active)
* @param handle
* @return
*/
SCANA_API
ihwapi_err_code_t sp209api_get_device_open_flag(sp209api_handle handle, bool* f);
/**
* @brief sp209api_launch_fw_update is used to launch a firmware update
* @param handle
* @param fw_data a pointer to the an array containing the firmware (loaded from *.bin file)
* @param fw_size the size of the array (number of bytes).
* @return error code, see ihwapi_err_code_t type.
*/
SCANA_API
ihwapi_err_code_t sp209api_launch_fw_update(sp209api_handle handle, uint8_t *fw_data, size_t fw_size, sp209api_variant_t variant);
/**
* @brief sp209api_request_abort request any pending operation to abort.
* This function returns without verifying if the operation was effectiely aborted
* @param handle
*/
SCANA_API
ihwapi_err_code_t sp209api_request_abort(sp209api_handle handle);
/**
* @brief sp209api_launch_new_capture is used to start a new capture of samples.
* @param handle
* @param settings the SP209 device settings to be used for this capture
* @return error code.
* @details This function does not offer any trigger options, capture will start as soon as possible
* after this function is called.
* @see sp209api_launch_new_capture_complex_trigger
*/
SCANA_API
ihwapi_err_code_t sp209api_launch_new_capture_simple_trigger(sp209api_handle handle,
sp209api_trigger_description_t trig,
sp209api_settings_t settings);
/**
* @brief sp209api_get_config_done_flag is used to check if the device have finished its internal
* configuration after a request to launch a new capture.
* @details There is no any obligation to use this function, as the configuration of the device
* usually takes a few milliseconds. This function is mainly here for feedback and monitoring purposes.
* @param handle
* @param f pointer to bool type varaible to hold the result
* @return TRUE if configuration is done, FALSE if configuration is still in progress.
*/
SCANA_API
ihwapi_err_code_t sp209api_get_config_done_flag(sp209api_handle handle, bool *f);
/**
* @brief Gets the device have triggered flag
*
* @param handle
* @param f pointer to bool type varaible to hold the result which will be true if
* the device has triggered
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_get_triggered_flag(sp209api_handle handle, bool *f);
/**
* @brief Gets the trigger position expressed in samples.
*
* @param handle
* @param trig_pos Pointer to uint64_t variable where the result will be stored
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_get_trigger_position(sp209api_handle handle, uint64_t *trig_pos);
/**
* @brief Gets the samples that have been read from device, that are buffered
* and are ready for readout.
*
* @param handle
* @param total_available_samples Pointer to int64_t to hold the total number of available samples
* @param post_trig_samples Pointer to int64_t to hold the number of samples after the trigger condition
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_get_available_samples(sp209api_handle handle, int64_t *total_available_samples, int64_t *post_trig_samples);
/**
* @brief Resets the transitions iterator for the channel with index `channel_index`
* After calling this function, the next call to trs_get_next() will get the very first transition
*
* @param handle
* @param channel_index
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_trs_reset(sp209api_handle handle, uint8_t channel_index);
/**
* @brief Resets the transitions iterator for the channel with index `channel_index` and
* make it point right before `target_sample`.
* After calling this function, the next call to trs_get_next() will get the very first transition
* after `target_sample`
*
* @param handle
* @param channel_index
* @param target_sample
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_trs_before(sp209api_handle handle, uint8_t channel_index, uint64_t target_sample);
/**
* @brief Advances the transition iterator for `channel_index` to the next transition and writes the details of that
* last transition in `transition_data`. Prior to calling this function, user must either call trs_reset() or
* trs_before().
*
* @param handle
* @param channel_index
* @param transition_data Pointer to structure of type sp209api_trs_t to hold the transition description
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_trs_get_next(sp209api_handle handle, uint8_t channel_index, sp209api_trs_t *transition_data);
/**
* @brief Same as trs_get_before() except that the transition iterator rewinds to the previous transition.
*
* @param handle
* @param channel_index
* @param transition_data
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_trs_get_previous(sp209api_handle handle, uint8_t channel_index, sp209api_trs_t *transition_data);
/**
* @brief This functions determines if the transition pointed be the iterator for the channel `channel_index`
* is pointing at the last transition.
*
* @param handle
* @param channel_index
* @param is_not_last_trs Pointer to a bool variable that is writte;n to True if current transition is
* not that last one, and further calls to trs_get_next() are valid.
* @return error code.
*/
SCANA_API
ihwapi_err_code_t sp209api_trs_is_not_last(sp209api_handle handle, uint8_t channel_index, bool *is_not_last_trs);
/**
* @brief This function is used to determin if the current capture is done and all data have been retrieved
* from the device. This function
* @note In case of an error or aborted capture, the flag will always return false.
*
* @param handle
* @param f Pointer to bool variable to hold the state of the `capture done` flag.
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp209api_get_capture_done_flag(sp209api_handle handle, bool *f);
/**
* @brief This function is used to check if the device is ready or if an operation is in
* progress.
*
* @param handle
* @param f pointer to bool type variable to hold the state of the `ready` flag
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp209api_get_ready_flag(sp209api_handle handle, bool *f);
/**
* @brief Calling this function returns the last error that may have been thrown
* by API internal threads. it's wise to use this in case of unxpected behavior
* or abnormal response times (e.g. config_done flag never equals true)
*
* @param handle
* @return SCANA_API
*/
SCANA_API
ihwapi_err_code_t sp209api_get_last_error(sp209api_handle handle);
#ifdef __cplusplus
}
#endif