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