Introduction to logic analyzer API

The logic analyzer API (also called IHWAPI, short for Ikalogic Hardware API) is an ecosystem of libraries (DLL or SO for linux/Mac) that allows a user to interface with our Logic Analyzer devices from their own software. The libraries are ABI compatible, meaning that it can be interfaced with a wide range of programming languages and environments, like C, C++, C# or Visual Basic. That being said, we Currently only provide C header files. If other formats are needed, we’re glad to hear from you and see how it can be ported to other languages.

Note: This API is a work in progress, and not all logic analyzer devices are supported. That being said, we’re actively working on it, so don’t hesitate to check back regularly or subscribe to newsletter to be informed when new APIs are released.

In general, we try to have a homogeneous and consistent set of APIs that are similar to each others. That being said, given the differences between different devices, this is not always possible.

Principle of operation of the API

The life cycle of the interactions with the device (via the API) usually follow this scheme:

  1. List the device(s) available on the USB bus
  2. Open the device (or a device from the list if there are several ones connected to the computer)
  3. Start a capture
  4. retrieve captured samples
  5. Close the device.

It is not mandatory to close the device after retrieving captured samples. If you intend to repeat the operation of capturing samples several times, you can keep the device open for as long as it’s needed. It’s also possible to poll the status of the device to ensure it’s still connected to the USB port when a capture is requested.

Retrieving the captured samples

Since version 2.0 of the API, the way captured samples are retrieved have been modified in order to match the same principle used in the ScanaStudio scripting API. It’s recommended to read this chapter in the scripting API documentation to get a better overview of the way logic signals are stored and retrieved in ScanaStudio:

Logic signals in ScanaStudio

Captured samples are stored in a compressed, memory efficient way. ScanaStudio does not store each and every sample captured. Only transitions are stored using this format:

  • Transition polarity (also referred to as “transition value”)
  • Sample index associated with that transition

logic samples and transitions

Behind the hood, the API have an iterator attached to each logic channel. The job of the iterator is to fetch the log transitions (i.e. logic change) from the compressed storage, and provide it the user of the API. As with the scripting API, the iterator for each channel needs to be reset, before it can be used to navigate to the first transition. (using the function DEVICEAPI_trs_reset() or DEVICEAPI_trs_fore(), where DEVICEAPI_ is to be replaced with your actual device api name).

Then, the proper way to retrieve captured samples is to call DEVICEAPI_trs_next() until the very last transition is reached for a specific channel.

Transitions can be retrieved simultaneously on all channels, or sequentially, one after the other.

Here is an example C code that illustrates the usage of the API to retrieve captured samples on channel 1:


sp209api_handle h;
sp209api_trs_t trs;
int64_t post_trig_samples = 0;
int64_t samples_count = 0;
sp209api_create_new_handle(&h,sp209api_device_model_t::SP209API_MODEL_209I);

//Note: This is not a complete working example
//More code is needed to List connected devices, open a device, configure it
// and start a new capture.

bool capt_done = false;
while(capt_done == false)
{
    sp209api_get_capture_done_flag(h,&capt_done);
    msleep(200);
}

const uint8_t ch = 1;
sp209api_get_available_samples(h,&samples_count,&post_trig_samples);
sp209api_trs_reset(h,ch);
trs.sampple_index = 0;
DBG << "Capture done, total captured samples = " << samples_count;
bool is_not_last = true;
while (is_not_last)
{
    sp209api_trs_get_next(h,ch,&trs);
    DBG << "TRS @" << trs.sampple_index << "[" << int(trs.value) << "]";
    sp209api_trs_is_not_last(h,ch,&is_not_last);
}

Header files

Each device has 3 header files that need to be included in your project to use the library correctly:

  1. ihwapi_common_types.h As its name implies this file is the same for all logic analyzer devices. it groups the C declarations of custom types and structures that are needed across all different APIs
  2. *DEVICE*_types.h where *DEVICE* is to be replaced by the name of the specific device. This file includes C declarations of the custom types and structures that are specific to a particular device.
  3. *DEVICE*api.h where *DEVICE* is to be replaced by the name of the specific device. This header file list all the functions that are included in the API.

Thread safety

Unless stated otherwise, all function call are thread safe.

API Common types →