LXDeviceAPI

생체신호 기기 연동 “Open API ” Software 버전  : 1.0.4.0 ( 배포일자 : 2017-04-20 )

System Architecture LXDeviceAPI

LXDeviceAPI 특징.

• 생체신호 측정 기기와 응용 프로그램 연동 API(Application Programming Interface)
• 생체신호 측정 기기와 연동되는 새로운 소프트웨어 개발 가능.
• 생체신호의 고속실시간 스트리밍, 기기제어.
• 표준 C 함수 라이브러리와  메시지 기반..
• API  내장 UI기반기능은 별도 코딩없이도 활용가능.
  • 신호 필터 설정.
  • 전극-피부 임피던스 모니터링.
  • 기기의 자동보정 처리.
  • API  소프트웨어 원격 업데이트.
  • 기기 펌웨어 원격 업데이트.
  • 설정 정보의 기기저장.
• API 형식 : Regular DLL –  표준C함수와 메시지.
• API 제작툴: Visual C++ 2015 ,  MFC Regular DLL.
• 지원 플랫폼 : 32bit , 64bit 모두 지원.
• 지원 운영체제 : 윈도우 10, 8.1, 8, 7

지원기기

• QEEG-64FX.
  • Utra High Precision,
  • Available Channel Options from 8ch to 64ch.
    • 8ch, 16ch, 24ch, 32ch, 40ch, 48ch, 56ch, 64ch.
• QEEG-32FX.
  • Ultra High Precision.
  • Max 32channel (fixed) EEG.

LXDeviceAPI 압축파일 다운로드부터 Visual C++ 프로젝트에서 DLL 임포팅 처리 전체과정 상세.

단계1. zip 파일 다운로드  / 차단해제 / 압축풀기

단계1.1 다운로드

API 활용할 응용프로그램의 비트수와 동일한 비트수의 LXDeviceAPI  다운로드(아래 링크 클릭).

32bit 응용프로그램용 API  : LXDeviceAPI_32bit.zip

64bit 응용프로그램용 API : LXDeviceAPI_64bit.zip

단계1.2 차단해제

필수 : 다운받은 파일 압축풀기 전에 “차단해제” 부터 먼저 처리.

윈도우 탐색기에서 상기 단계1.1 다운로드 받은 파일 선택하고 우마우스 클릭 – 속성 클릭 하고 (아래그림)

파일 속성 클릭

 속성 창에서 버튼 “차단해제” 클릭하고, 버튼 OK 클릭. (아래그림)

차단해제 클릭

단계1.3 압축풀기

LXDeviceAPI files & folder

단계 2.  프로젝트 폴더로 API 파일들 복사하기.

단계3. Visual C++ 프로젝트에서 DLL 임포팅 하기.

DLL 임포팅 방법 중 가장 간단한 implicit linking 하고, LXDeviceAPI.h 인클루드 처리. (아래 코드)

#pragma comment(lib,"LXDeviceAPI.lib") // DLL implicit linking

#include "LXDeviceAPI.h"

상기 설정으로 LXDeviceAPI 에서 제공되는 모든 함수 및 메시지를 Visual C++ 프로젝트에서 활용가능한 상태 달성.

스트림 구조체 : ST_STREAMDATA_LXDAPI

API는 기기로부터 실시간 측정치들을 수집함과 동시에 이들 데이터들을 응용프로그램으로 스트림 데이터 전송한다. 응용프로그램 스트림 전송시 데이터 형식은 구조체 ST_STREAMDATA_LXDAPI 가 사용되며, LXDeviceAPI.h 에 아래처럼 선언되어있다.

// struct for stream. LXDeviceAPI.h

typedef struct _stStreamData_LXDAPI
{
...
  unsigned int*	Event_StreamData_CS; // array for event marking

  double*	Wave_StreamData_CS;  // array for measured multi channel bio signal
...


}ST_STREAMDATA_LXDAPI;

ST_STREAMDATA_LXDAPI 의 멤버 중 가장 중요한 변수는  2개의  1차원 스트림배열이다.

double * Wave_StreamData_CS

unsigned int* Event_StreamData_CS

기기에서 측정된 다채널 생체신호 샘플링 데이터 들은 Wave_StreamData_CS[] 에 기록되며, 이벤트 마킹 정보는 Event_StreamData_CS[] 에 저장된다.

스트림 구조체 사용방법.

응용프로그램에서 구조체 변수 선언하고 함수 OpenDevice 호출시 인자로 구조체 변수 주소 전달한다.

OpenDevice 호출되면 API내부적으로 구조체 변수 동적 메모리 할당 이뤄지며, 이때 메모리 크기는 OpenDevice 의 인자 int numsample_return 에 의하여 결정된다. API내부적으로 동적할당된 메모리는  CloseDevice 함수 호출시점에 API내부적으로 자동 제거 처리된다.

ST_STREAMDATA_LXDAPI stStreamData; 
int NumSampleReturn = 32 ; //available range 1~ 128. the number of samples to get the stream data per each message from LXDeviceAPI. 
OpenDevice_LXDeviceAPI( , &stStreamData,NumSampleReturn , );

메모리 맵.

Wave_StreamData_CS 데이터 배치.

아래 설명문의  Number of Samples 는 함수 OpenDevice 인자  int numsample_return 에 의하여 결정.

Event_StreamData_CS 데이터 배치.

스트림 배열 인덱싱.

기기에서 측정된 다채널 채널 생체신호중 특정 채널 1개의 샘플 데이터 획득하는 코드 예.

double one_sample_wave = stStreamData.Wave_StreamData_CS[sample_index + NumSampleReturn * channel_index ]

이벤트 데이터 1개의 샘플데이터 획득하는 코드예.

unsigned int one_sample_event = stStreamData.Event_StreamData_CS[ sample_index ]

channel_index 가능한 값의 범위 : 0 ~ (최대채널수-1). 최대채널수는 기기마다 다르며, QEEG-64FX (64ch)인 경우 최대 채널수 67.  API 지원기기들의 최대채널수는  본 문서 Appendix 1. 에서 제공.

sample_index  가능한 값의 범위 :  0 ~ ( NumSampleReturn -1 ).  NumSampleReturn 은 OpenDevice 호출시 인자 int numsample_return 에 입력한 값으로 결정된다.

스트림 데이터 표현예.

아래 응용프로그램의 챠트 출력은 sample_index 를 X축(시간)에 대응시키고, Wave채널1, 채널 2 , Event  표현한 예.

Stream Data Array Indexing Example

API 메시지 인자 wParam.

API에서 응용프로그램 측으로 메시지 전송시 API내부적으로 호출되는 win32 함수인  SendMessage(.,.,wParam, lParam) 의 인자  wParam 에는 unsigned int(4바이트) 형의 정수가 전달되며,   wParam 의 하위 바이트부터 wParam_Byte0, wParam_Byte1, wParam_Byte2, wParam_Byte3 이라고 하였을 때, 각 바이트에는 아래표와 같은 데이터가 기록되어 있다.

메시지 타입별 의미.

Code Examples

OpenDevice 함수 호출 이후 SetMessageDevice 호출하여 기기에서 발생하는 스트림 메시지 수신 설정해둔다. StartStream 호출하면 API내부적으로 기기로부터 실시간 수집된 데이터 수량이 지정수량 (OpenDevice 함수 호출시 지정한 int numsample_return )이 된 경우 응용프로그램 측으로 메시지 전송한다. 응용프로그램측의 메시지 핸들러 에서는 함수 GetStreamData 호출하여 스트림데이터 확보처리 한다.

Code Example1. function SetMessageDevice

#define WM_STREAM_DEVICE  WM_USER+203 // You must define the message without duplication with any other messages in your program.

void CLXDeviceAPI_Sample1View::OnMenuSetmessagedevice()
{
  // Mandatory for receiving the stream data from LXDeviceAPI.
  SetMessageDevice_LXDeviceAPI(m_iDeviceHandlingID, MSGTYPEID0_DEVICE_LXDAPI, this->m_hWnd, WM_STREAM_DEVICE,1); 
}

Code Example2. function StartStream

void CLXDeviceAPI_Sample1View::OnMenuStartstream()
{
  StartStream_LXDeviceAPI(m_iDeviceHandlingID);
}

Code Example3. Message Handler

afx_msg LRESULT CLXDeviceAPI_Sample1View::OnStreamData(WPARAM wParam, LPARAM lParam)
{
 unsigned int uintWPARAM = (unsigned int)wParam; 
 unsigned char msgtype_id = (unsigned char)(uintWPARAM >> 8)  ; //get the lowest 2'nd byte(message type id).
 unsigned char msgtype_subid = (unsigned char)(uintWPARAM); //get the lowest 1st byte(message type sub id).

 switch (msgtype_id)
 {
 case MSGTYPEID0_DEVICE_LXDAPI: // for real time stream type messages. 

  switch (msgtype_subid)
  {
  case 0:

   GetStreamData_LXDeviceAPI(uintWPARAM); 


   // After call GetStreamData, the new stream data is allocated on ST_STREAMDATA_LXDAPI variable.
   // use stream data here. plotting, saving, calculating, etc. 

   break;

  } // switch (msgtype_subid)

  break;  // case MSGTYPEID0_DEVICE_LXDAPI: // for real time stream type messages. 
 }// switch (msgtype_id)


 return 0;
}

Function Call Sequence LXDeviceAPI

OpenDevice 로 기기와 통신 개설된 상태에서,  StartStream과 StopStrem 은 필요에 따라 교번식으로 여러 번 반복 호출 가능하다.

StartStream 호출 이후에 API에서는 MSGTYPEID0_DEVICE_LXDAPI 의  메시지가 전송되며 응용 프로그램에서는  메시지 핸들러가 구현되어야 한다. 메시지 핸들러 내에서 메시지 수신될 때마다 GetStreamData 함수를 호출하여 스트림데이터를 확보하여 응용프로그램에서 활용한다. StopStream함수 호출하면 API는 Stream 메시지 발생하지 않는다.

CloseDevice 는 응용프로그램에서 해당 기기를 사용하지 않을 때( 예: 응용프로그램 종료시)점CloseDevice를 호출하고 이후  CloseApi 호출한다.

Definition

 

int OpenApi_LXDeviceAPI(int api_window, int api_selfupdate, int mode)

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuOpenapi()
{
  OpenApi_LXDeviceAPI(1,0,0);
}

Execution result.

If OpenApi is called successfully, LXDeviceAPI window & tray icon appears at the  bottom right.

Definition

 

int CloseApi_LXDeviceAPI();

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuCloseapi()
{
 CloseApi_LXDeviceAPI();
}

Definition

 

int OpenDevice_LXDeviceAPI(int LXDeviceID, ST_STREAMDATA_LXDAPI * p_streamdata,int numsample_return,int mode);

Parameters

ST_STREAMDATA_LXDAPI stStreamData; 
OpenDevice_LXDeviceAPI( , &stStreamData, , );

Return Values

Code Example 1

/*
 Device to open : QEEG-64FX max 64ch option, LXDeviceID = 16464
*/

void CLXDeviceAPI_Sample1View::OnMenuOpendevice()
{
  int retv = OpenDevice_LXDeviceAPI(16464, &stStreamData, NumSampleReturn, 0);

  if(retv > 0) // if success
  {
    m_iDeviceHandlingID = retv; 
  }
  else
  {
    AfxMessageBox(_T("Fail to OpenDevice"));
  }
}

Result.

After calling the function OpenDevice, the Device Control Panel appears on bottom right side.

Device Control Panel

Code Example 2

/*
OpenAPI-> OpenDevice -> StartStream at the same time 
Device to open : QEEG-64FX max 64ch option, LXDeviceID = 16464
*/

void CLXDeviceAPI_Sample1View::OnMenuOneclickstart()
{
  int retv_openapi, retv_opendevice; 

  retv_openapi = OpenApi_LXDeviceAPI(1, 0, 0); // API Open.

  if (retv_openapi > 0)
  {
    retv_opendevice = OpenDevice_LXDeviceAPI(16464, &stStreamData, NumSampleReturn, 0); 
    if (retv_opendevice > 0)
    {
      m_iDeviceHandlingID = retv_opendevice; 
      SetMessageDevice_LXDeviceAPI(m_iDeviceHandlingID, 0, this->m_hWnd, WM_LXDAPI_MSGTYPEID_0, 1);

      StartStream_LXDeviceAPI(m_iDeviceHandlingID);
    }
  }
}

Definition

 

int CloseDevice_LXDeviceAPI(int device_handling_id);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuClosedevice()
{
  CloseDevice_LXDeviceAPI(m_iDeviceHandlingID);
}

Definition

 

int StartStream_LXDeviceAPI(int device_handling_id, int mode);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuStartstream()
{

  StartStream_LXDeviceAPI(m_iDeviceHandlingID);
}

Definition

 

int StopStream_LXDeviceAPI (int device_handling_id);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuStopstream()
{
  StopStream_LXDeviceAPI(m_iDeviceHandlingID);
}

Definition

 

int GetStreamData_LXDeviceAPI(unsigned int message_wparam);

Parameters

Return Values

Code Example

afx_msg LRESULT CLXDeviceAPI_Sample1View::OnStreamData(WPARAM wParam, LPARAM lParam)
{
 unsigned int uintWPARAM = (unsigned int)wParam; 
 unsigned char msgtype_id = (unsigned char)(uintWPARAM >> 8)  ; //get the lowest 2'nd byte(message type id).
 unsigned char msgtype_subid = (unsigned char)(uintWPARAM); //get the lowest 1st byte(message type sub id).

 switch (msgtype_id)
 {
 case MSGTYPEID0_DEVICE_LXDAPI: // for real time stream type messages. 

  switch (msgtype_subid)
  {
  case 0:

   GetStreamData_LXDeviceAPI(uintWPARAM); // After call this function. the new stream data is allocated on stStreamData which is ST_STREAMDATA_LXDAPI type variable.  

   /// Data arrange for Wave Stream Data for plotting. 
   for (int i = 0; i < NumSampleReturn * NumChannel; i++)
   {
    testfloat_Wave[i] = (float)stStreamData.Wave_StreamData_CS[i];
   }

   /// Data arrange for Event Marking for plotting.
   for (int idx_event = 0; idx_event < NumSampleReturn; idx_event++)
    testfloat_Wave[NumSampleReturn * NumChannel + idx_event] = (float)stStreamData.Event_StreamData_CS[idx_event];

   // Plotting the wave and event marking. 
   ACQPLOT_DLL_Array_Datain_Strip(testfloat_Wave, NumChannel + 1, NumSampleReturn); //인자의미. 1번 :float형 파형 데이터배열의 포인터, 2번인자 : 총 채널수 +1 for Event Marking, 1채널당 샘플링 수량.


   break;

  } // switch (msgtype_subid)

  break;  // case MSGTYPEID0_DEVICE_LXDAPI: // for real time stream type messages. 
 }// switch (msgtype_id)


 return 0;
}

Definition

 

int EventMarkingOnStream_LXDeviceAPI(int device_handling_id, unsigned int event_id);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuEventmarkingonstream()
{
  EventMarkingOnStream_LXDeviceAPI(m_iDeviceHandlingID,20000);
}

Result

Definition

 

int SetMessageDevice_LXDeviceAPI(int device_handling_id,int msgtype_id,HWND hwnd_msgrcv,int msg_id,int onoff);

Parameters

Return Values

Code Example

#define WM_STREAM_DEVICE  WM_USER+203 // You must define the message without duplication with any other messages in your program.

void CLXDeviceAPI_Sample1View::OnMenuSetmessagedevice()
{
  // Mandatory for receiving the stream data from LXDeviceAPI.
  SetMessageDevice_LXDeviceAPI(m_iDeviceHandlingID, MSGTYPEID0_DEVICE_LXDAPI, this->m_hWnd, WM_STREAM_DEVICE,1); 
}

Definition

 

int SetSampleFrequency_LXDeviceAPI(int device_handling_id, unsigned int sample_frequency);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnSetsamplefrequency2000hz()
{
  SetSampleFrequency_LXDeviceAPI(m_iDeviceHandlingID, 500); //set as 500Hz 
}

Definition

 

int SetDeviceControlPanel_LXDeviceAPI(int device_handling_id,int para0, int para1);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuSetdevicecontrolpanel()
{
  static int para1=0; 
  SetDeviceControlPanel_LXDeviceAPI(m_iDeviceHandlingID, 0, para1);
  // toggling para1.
  if (para1) para1 = 0; 
  else para1 = 1; 
}

Result

Device Control Panel disabled.

Definition

 

int GetFilterFrequency_LXDeviceAPI(int device_handling_id,int signal_source, float * freq_hpf, float * freq_lpf, float * freq_notch);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuGetfilterfrequency()
{
  float f_hpf, f_lpf, f_notch;
  CString cst_hpf, cst_lpf, cst_notch;
  // Get EEG Filter info 
  if (GetFilterFrequency_LXDeviceAPI(m_iDeviceHandlingID,0, &f_hpf, &f_lpf, &f_notch) == 1) 
  {
    if (f_hpf < -1.f) 	cst_hpf = _T("HPF=off, ");
    else		cst_hpf.Format(_T("HPF=%.1fHz, "), f_hpf); 

    if (f_lpf < -1.f)	cst_lpf = _T("LPF=off, ");
    else		cst_lpf.Format(_T("LPF=%.1fHz, "), f_lpf);

    if (f_notch < -1.f)	cst_notch = _T("Notch=off");
    else		cst_notch.Format(_T("Notch=%.1fHz"), f_notch);

    AfxMessageBox(_T("EEG Filter : ") + cst_hpf + cst_lpf + cst_notch);
  }
}

Result

Signal Filter Frequencies

Definition

int GetSampleFrequency_LXDeviceAPI(int device_handling_id, int * sample_frequency);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuGetsamplefrequency()
{
  int sample_frequency; 
  CString cst; 

  if (GetSampleFrequency_LXDeviceAPI(m_iDeviceHandlingID, &sample_frequency) == 1)
  {
    cst.Format(_T("Sampling Frequency = %d Hz"), sample_frequency);

    AfxMessageBox(cst);
  }
}

Result

GetSampleFrequency

Definition

 

int GetEEGRefElectrode_LXDeviceAPI(int device_handling_id , int * eeg_refelectrode);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuGeteegrefelectrode()
{
  int eeg_refelectrode; 
  CString cst_eegref; 

  if (GetEEGRefElectrode_LXDeviceAPI(m_iDeviceHandlingID,&eeg_refelectrode) == 1)
  {
    if (eeg_refelectrode == 0)		cst_eegref = _T("A1");
    else if (eeg_refelectrode == 1)	cst_eegref = _T("A2");
    else if (eeg_refelectrode == 2)	cst_eegref = _T("A1+A2");
    else if (eeg_refelectrode == 3)	cst_eegref = _T("Cz(ch18)");

    AfxMessageBox(_T("EEG Reference Electode = ") + cst_eegref); 
  }
}

Result

EEG reference electode

Definition

 

int CheckForUpdate_LXDeviceAPI(int closeifnoupdate);

Parameters

Return Values

Code Example

void CLXDeviceAPI_Sample1View::OnMenuCheckforupdate()
{
 CheckForUpdate_LXDeviceAPI(0); // parameter 0 : No Auto Close 
 //CheckForUpdate_LXDeviceAPI(1); // parameter 1 : Auto close check program if there is no update.
}

Result

CheckForUpdate LXDeviceAPI

LXDeviceAPI provides the self-contained GUIs which are essential and necessary to handle the devices. Unlike the API Messages and API Functions, there is no need to control API GUIs by your application programs.

이 슬라이드 쇼에는 JavaScript가 필요합니다.

자동보정 따라하기.

단계1. 외부숏기기 연결.

외부숏기기(External Short Device. LXCON01) 를 입력 커넥터에 장착(아래사진).

External Short Device Connection QEEG-64FX

단계2. 프로그램 실행하여 “기기제어창” 에서 버튼 “Auto Calibration” 클릭.

단계3. 상기 단계2에서 뜬 새창에서 버튼 “Reset Calibration” 클릭후 5초정도 대기 (대기사유: 기기 보정데이터 초기화 완전히 이뤄지기까지 5초정도 소요됨.)

단계4. 버튼 “Start Calibration” 클릭. (이후는 자동으로 전채널 보정처리 진행됨. 소요시간 : 2분이내)

단계5. 상기 단계4 완료되면 버튼 “Close” 눌러 자동보정 기능 종료하기.

동영상. 상기 단계2에서 단계5까지의 전체과정 동영상(아래).

참고. 자동보정과정 중 기기의 LED 상태변화.

보정 전 상태 예시.

Before Auto Calibration

보정 완료된 상태.

Completed Auto Calibration

Quick guide for programming

Prerequisite

In this example, the s/w developing PC should be connected to QEEG-64FX via USB.

Quick Start – Using Sample Project.

The sample project “LXDeviceAPI_Sample1” is the simplest example source code made by Visual C++ 2015. The “LXDeviceAPI_Sample1” is downloadable from GitHub repository.

step 1. Let’s call function OpenApi and then CloseApi.

The LXDeviceAPI window appears after calling OpenApi, disappears after calling CloseApi.

step 2. Starting Stream for acquiring the real time bio signal.

Call the API functions OpenApi , OpenDevice, SetMessageDevice and StartStream.

After call StartStrem, LXDeviceAPI send a stream message to application program. Application’s message handler must call the GetStreamData to get the unit stream data. Now you can use a unit stream data for plotting, saving and any processing you need.

step 3. Closing  the LXDeviceAPI

If there is no need to use LXDeviceAPI anymore, call the functions StopStream, CloseDevice and CloseApi.

Overall procedure can be seen following video,

LXDeviceAPI

32비트 프로그램용 API다운로드

 LXDeviceAPI_32bit.zip download.

64비트 프로그램용 API다운로드

 LXDeviceAPI_64bit.zip download.

프로젝트 샘플

프로젝트이름	LXDeviceAPI_Sample1
설명	LXDeviceAPI 활용예를 보이는 가장 간단한 프로젝트 소스. Visual C++ 2015, MFC SDI Project. 1개의 프로젝트에서 32bit ,64bit 플랫폼 선택하여 빌드 가능.
다운로드	LXDeviceAPI_Sample1 zip 다운로드.
깃허브(GitHub)	https://github.com/LAXTHA/LXDeviceAPI_Sample1

LXDeviceAPI 문서.

 개발자용 메뉴얼. 다운로드 혹은 새창에서 바로보기. .