Библиотека API-функций для CANalyst-II Печать
Добавил(а) microsin   

С помощью этой библиотеки пользователь сам может писать приложения для адаптера CANalyst-II [1] (и для других CAN-адаптеров Zhuhai Chuangxin Technology Co., Ltd, которые можно купить на AliExpress). Библиотека и поставляемые с ней примеры кода позволяют писать приложения для LabVIEW, Visual Studio С++, Visual Studio C#, Visual Basic, Delphi, C++Builder.

Библиотеки поставляются в виде двоичного кода и файлов деклараций функций:

Таблица 1. Файлы, относящиеся к библиотеке.

Файл Назначение
ControlCAN.lib Двоичная библиотека для статической линковки кода в Visual Studio C++, CBuilder.
ControlCAN.h Заголовочный файл с декларацией функций для кода на C/C++.
ControlCAN.pas Файл с декларацией функций для Delphi.
ControlCAN.DLL Библиотека динамически загружаемых функций (может использоваться в коде C++, C#, Object Pascal, Visual Basic).
ControlCAN.bas Файл деклараций функций для Visual Basic.
ControlCAN.llb Модуль библиотеки LabVIEW.

[Типы данных и константы]

Таблица 2. Базовые типы.

Тип Аналог в C++ Аналог в C#
BYTE unsigned char Byte
CHAR char char
USHORT unsigned short UInt16
UINT unsigned int UInt32
ULONG unsigned long UInt64

Константы для поддерживаемых устройств (подставляется в параметр DevType API-функций) перечислены в таблице 3.

Таблица 3. Типы адаптеров, поддерживаемых библиотекой.

#define Значение Соответствует адаптеру
VCI_USBCAN1 3 USBCAN-1
VCI_USBCAN2 4 USBCAN-2A, USBCAN-2C, CANalyst-II

[Структуры данных]

Структура VCI_BOARD_INFO содержит информацию об интерфейсе адаптеров серии USB-CAN. Она заполняется вызовом функции VCI_ReadBoardInfo.

typedef struct _VCI_BOARD_INFO
{
   USHORT hw_Version;
   USHORT fw_Version;
   USHORT dr_Version;
   USHORT in_Version;
   USHORT irq_Num;
   BYTE can_Num;
   CHAR str_Serial_Num[20];
   CHAR str_hw_Type[40];
   USHORT Reserved[4];
} VCI_BOARD_INFO, *PVCI_BOARD_INFO;

hw_Version Номер версии аппаратуры в hex-представлении. Например, 0x0100 обозначает V1.00.

fw_Version Номер версии firmware в аналогичном hex-представлении.

dr_Version Номер версии драйвера USB в аналогичном hex-представлении.

in_Version Номер версии библиотеки функций в аналогичном hex-представлении.

irq_Num Зарезервировано системой.

can_Num Показывает общее количество каналов CAN, поддерживаемое адаптером.

str_Serial_Num Серийный номер адаптера.

str_hw_Type Описание типа адаптера, например "USBCAN V1.00" (это ASCIIZ-строка, завершающаяся '\0').

Reserved Зарезервировано системой.

В функциях передачи и приема (VCI_Transmit и VCI_Receive) структура VCI_CAN_OBJ используется для пересылки фрейма сообщения CAN.

typedef struct _VCI_CAN_OBJ
{
   UINT ID;
   UINT TimeStamp;
   BYTE TimeFlag;
   BYTE SendType;
   BYTE RemoteFlag;
   BYTE ExternFlag;
   BYTE DataLen;
   BYTE Data[8];
   BYTE Reserved[3];
}VCI_CAN_OBJ, *PVCI_CAN_OBJ;

ID Идентификатор сообщения, представленный в формате с выравниванием вправо.

TimeStamp Метка времени принятого фрейма, отсчитываемая от момента инициализации контроллера CAN, в единицах 0.1 мс.

TimeFlag В контексте использования метки времени 1 в этом поле показывает достоверность поля TimeStamp. Поля TimeFlag и TimeStamp имеют значение только для приема фрейма.

SendType Тип посылки. 0 показывает Normal, 1 показывает Single Send (одиночная отправка).

RemoteFlag Флаг запроса передачи удаленного хоста (remote flag). 1 показывает фрейм remote, 0 показывает фрейм данных.

ExternFlag Показывает тип идентификатора: 1 обозначает расширенный идентификатор (extern ID), 0 стандартный идентификтор (standard ID).

DataLen Длина данных фрейма (Data Length Code, DLC), значение в этом поле может быть больше или равно 8.

Data Данные пакета (полезная нагрузка фрейма).

Reserved Зарезервировано системой.

Структура VCI_INIT_CONFIG определяет инициализационную конфигурацию CAN. Она заполняется в функции VCI_InitCan.

typedef struct _INIT_CONFIG
{
   DWORD AccCode;
   DWORD AccMask;
   DWORD Reserved;
   UCHAR Filter;  // 0, 1 прием всех фреймов.
                  // 2 фильтрация стандартного фрейма (11-битный идентификатор ID).
                  // 3 фильтрация расширенного фрейма (29-битный идентификатор ID).
   UCHAR Timing0;
   UCHAR Timing1;
   UCHAR Mode;
} VCI_INIT_CONFIG, *PVCI_INIT_CONFIG;

AccCode Фильтруемый код принимаемого идентификатора.

AccMask Маска фильтра приема.

Reserved Зарезервировано.

Filter Метод фильтрации, допустимое значение 0 .. 3, подробнее см. описание функции VCI_InitCan и таблицу 5.

Timing0 Параметр для SJA1000, определяющий скорость (BTR0) [3, 4].

Timing1 Параметр для SJA1000, определяющий скорость (BTR1) [3, 4].

Mode Рабочий режим: 0 нормальное функционирование (обычный узел сети CAN), 1 только прослушивание (без передачи, никак не оказывается влияние на сеть CAN), 2 режим самотестирования (внутреннее закольцовывание потока данных с выхода на вход).

Поля Timing0 и Timing1 используется для установки стандартных скоростей шины CAN на стадии инициализации адаптера (см. таблицу 4).

Таблица 4. Константы для стандартных параметров скорости CAN (baud rate).

CAN Baud Rate Timing0 (BTR0) Timing1 (BTR1)
10 kbps 0xBF 0xFF
20 kbps 0x18 0x1С
40 kbps 0x87 0xFF
50 kbps 0x09 0x1С
80 kbps 0x83 0xFF
100 kbps 0x04 0x1С
125 kbps 0x03 0x1С
200 kbps 0x81 0xFA
250 kbps 0x01 0x1C
400 kbps 0x80 0xFA
500 kbps 0x00 0x1C
666 kbps 0x80 0xB6
800 kbps 0x00 0x16
1000 kbps 0x00 0x14

Примечания:

1. Пользователям нужно следовать рекомендациям для SJA1000 (16 МГц, см. [3, 4]) для установки параметра скорости.
2. Единица kbps означат физическую длительность бит шины (килобит/сек).
3. Адаптер не поддерживает скорости ниже 10 kbps.
4. Обычная скорость передачи данных может быть напрямую настроена в соответствии со значениями в таблице 4. Для других нетрадиционных скоростей передачи вы можете использовать подключенный инструмент определения скорости передачи, чтобы обнаружить и получить соответствующие параметры скорости передачи. Или используйте инструмент вычисления скорости передачи в каталоге установки USB_CAN TOOL. (См. документацию «6. Плагин 2: использование инструмента определения скорости передачи в бодах.pdf» [2]).

[API-функции]

Используется для подключения к адаптеру.

DWORD __stdcall VCI_OpenDevice(DWORD DevType, DWORD DevIndex, DWORD Reserved);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

Reserved Зарезервированный параметр, здесь должно быть значение 0.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера USB-CAN не существует или USB отключен.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
DWORD dwRel;
 
dwRel = VCI_OpenDevice(nDeviceType, nDeviceInd, 0);if(dwRel != 1)
{
   MessageBox(_T("Неудачное открытие устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для закрытия соединения.

DWORD __stdcall VCI_CloseDevice(DWORD DevType, DWORD DevIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
DWORD dwRel;
 
dwRel = VCI_CloseDevice(nDeviceType, nDeviceInd);if(dwRel != 1)
{
   MessageBox(_T("Неудачное закрытие устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для инициализации указанного адаптера CAN.

DWORD __stdcall VCI_InitCAN(DWORD DevType,
                            DWORD DevIndex,
                            DWORD CANIndex,
                            PVCI_INIT_CONFIG pInitConfig);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс (номер) канала CAN, начинающийся с 0. Если адаптер поддерживает 2 канала, то CANIndex может быть 0 или 1.

pInitConfig Указатель на структуру параметров инициализации типа VCI_INIT_CONFIG.

Поля PVCI_INIT_CONFIG:

pInitConfig->AccCode, pInitConfig->AccMask Поля AccCode и AccMask работают вместе, чтобы определить какие пакеты могут быть приняты, а какие отбрасываются. Эти два регистра используют значения ID, выравненные влево, т. е. самый старший бит (Bit31) полей AccCode и AccMask всегда соответствует самому старшему биту значения идентификатора ID.

Например, если значение AccCode установлено в 0x24600000 (т. е. это число 0x00000123, сдвинутое влево на 21 бит), AccMask установлено в 0x00000000, то тогда будут приниматься только те пакеты CAN, у которых ID фрейма сообщения равен 0x123 (значение AccMask 0x00000000 означает, что все биты в принятом идентификаторе важны и рассматриваются для фильтрации). Если значение AccCode установлено в 0x24600000, AccMask в 0x00600000 (0x00000003, сдвинутое влево на 21 бит), тогда будут приниматься только те сообщения CAN, у которых ID фрейма в диапазоне 0x120 .. 0x123 (значение AccMask 0x600000 показывает, что биты 0 и 1 идентификатора не используются для фильтрации, т. е. могут быть любыми).

Примечание: эти примеры настройки фильтра приведены для стандартного (11-битного фрейма), т. е. здесь самый значимый достоверный 11-й бит. Если используется расширенный фрейм, то у него используются для ID 29 бит, тогда AccCode и AccMask самым значимым будет 29-й бит идентификатора.

pInitConfig->Filter Это поле устанавливает режим фильтрации, см. таблицу 5.

Таблица 5. Режимы фильтрации.

Значение Работа фильтра
0, 1 Фильтр используется для всех типов фреймов, как стандартных, так и расширенных.
2 Фильтр фильтрует только стандартные фреймы, расширенные сразу отбрасываются.
3 Фильтр фильтрует только расширенные фреймы, стандартные сразу отбрасываются.

pInitConfig->Timing0, pInitConfig->Timing1 Устанавливают параметры скорости BTR0 и BTR1 для SJA1000 [3, 4].

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
DWORD dwRel;
VCI_INIT_CONFIG vic;
 
dwRel = VCI_OpenDevice(nDeviceType, nDeviceInd, 0);
if(dwRel != 1)
{
   MessageBox(_T("Ошибка открытия устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}
 
vic.AccCode=0x80000008;
vic.AccMask=0xFFFFFFFF;
vic.Filter=1;
vic.Timing0=0x00;
vic.Timing1=0x14;
vic.Mode=0;
 
dwRel = VCI_InitCAN(nDeviceType, nDeviceInd, nCANInd, &vic);
if(dwRel != 1)
{
   VCI_CloseDevice(nDeviceType, nDeviceInd);
   MessageBox(_T("Ошибка инициализации устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для чтения информации об адаптере. Использование этой функции для прикладных задач передачи данных не обязательно.

DWORD __stdcall VCI_ReadBoardInfo(DWORD DevType,
                                  DWORD DevIndex,
                                  PVCI_BOARD_INFO pInfo);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

pInfo Указатель на область памяти для VCI_BOARD_INFO, которая будет заполняться информацией об адаптере.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
VCI_BOARD_INFO vbi;
DWORD dwRel;
 
bRel = VCI_ReadBoardInfo(nDeviceType, nDeviceInd, nCANInd, &vbi);
if(dwRel != 1)
{
   MessageBox(_T("Ошибка получения информации об устройстве!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для определения, сколько еще в буфере принятых, но не прочитанных сообщений.

DWORD __stdcall VCI_GetReceiveNum(DWORD DevType,
                                  DWORD DevIndex,
                                  DWORD CANIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

Возвращаемое значение: количество кадров, которые приняты, но еще не были прочитаны. -1 означает, что устройство USB-CAN не существует или отключено.

#include "ControlCan.h"
 
int ret = VCI_GetReceiveNum(2,0,0);

Эта функция используется для очистки буфера приема и передачи указанного канала адаптера USB-CAN.

DWORD __stdcall VCI_ClearBuffer(DWORD DevType,
                                DWORD DevIndex,
                                DWORD CANIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
DWORD dwRel;
 
bRel = VCI_ClearBuffer(nDeviceType, nDeviceInd, nCANInd);

Функция используется для запуска контроллера CAN и внутреннего обработчика прерываний (ISR) CAN-адаптера.

DWORD __stdcall VCI_StartCAN(DWORD DevType, DWORD DevIndex, DWORD CANIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
DWORD dwRel;
VCI_INIT_CONFIG vic;
 
if(VCI_OpenDevice(nDeviceType, nDeviceInd, 0) != 1)
{
   MessageBox(_T("Ошибка открытия устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}
 
if(VCI_InitCAN(nDeviceType, nDeviceInd, nCANInd, &vic) != 1)
{
   VCI_CloseDevice(nDeviceType, nDeviceInd);
   MessageBox(_T("Ошибка инициализации устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
              return FALSE;
}
 
if(VCI_StartCAN(nDeviceType, nDeviceInd, nCANInd) != 1)
{
   VCI_CloseDevice(nDeviceType, nDeviceInd);
   MessageBox(_T("Ошибка старта устройства!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для сброса контроллера CAN.

DWORD __stdcall VCI_ResetCAN(DWORD DevType,
                             DWORD DevIndex,
                             DWORD CANIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

Возвращаемое значение: 1 означает, что операция прошла успешно; 0 означает, что операция завершилась неудачей; -1 означает, что устройство адаптера не существует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
DWORD dwRel;
 
bRel = VCI_ResetCAN(nDeviceType, nDeviceInd, nCANInd);
if(dwRel != 1)
{
   MessageBox(_T("Неудачный сброс!"),
              _T("warning"),
              MB_OK|MB_ICONQUESTION);
   return FALSE;
}

Функция используется для передачи CAN.

DWORD __stdcall VCI_Transmit(DWORD DeviceType,
                             DWORD DeviceInd,
                             DWORD CANInd,
                             PVCI_CAN_OBJ pSend,
                             DWORD Length);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

pSend Указатель на первую структуру VCI_CAN_OBJ для передаваемых фреймов данных.

Length Количество отправляемых фреймов данных, максимальное значение 1000, для больших скоростей рекомендуемое значение 48.

Возвращаемое значение: количество переданных фреймов, -1 означает ошибку устройства.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
DWORD dwRel;
VCI_CAN_OBJ vco[48];
 
memset (&vco, 0, sizeof(VCI_CAN_OBJ)*48);
for(int i = 0; i < 48; i++)
{
   vco[i].ID = i;
   vco[i].RemoteFlag = 0;
   vco[i].ExternFlag = 0;
   vco[i].DataLen = 8;
   for(int j = 0; j < 8; j++)
      vco.Data[j] = j;
}
dwRel = VCI_Transmit(nDeviceType,
                     nDeviceInd,
                     nCANInd,
                     &vco,
                     48);

Функция используется для приема CAN.

DWORD __stdcall VCI_Receive(DWORD DevType,
                            DWORD DevIndex,
                            DWORD CANIndex,
                            PVCI_CAN_OBJ pReceive,
                            ULONG Len,
                            INT WaitTime);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

pReceive Указатель на первую структуру VCI_CAN_OBJ в массиве для принимаемых фреймов данных.

Len Количество элементов в массиве данных для приема кадров (максимальное количество кадров, которое может быть принято, реальное количество принятых кадров может быть меньше этого значения). Значение Len показывает размер подготовленного пространства для хранения принимаемых данных, в единицах sizeof(VCI_CAN_OBJ). Адаптер устанавливает размер внутреннего буфера на 2000 фреймов для каждого канала. Пользователь выбирает подходящую длину приемного массива от 1 до 2000 в соответствии с потребностями своей системы и рабочей среды. Как правило, размер массива pReceive и Len оба могут быть установлены более 2000, например: 2500. Это может эффективно предотвратить конфликты данных, вызванные переполнением адреса. В то же время рекомендуется вызывать VCI_Receive каждые 30 мс. Для обеспечения своевременности обработки данных в приложении, постарайтесь максимально уменьшить (подобрать) частоту вызовов VCI_Receive. Пока внутренний буфер не переполняется, каждый раз считывается и обрабатывается больше фреймов, что может повысить эффективность работы.

WaitTime Время ожидания приема (таймаут) в миллисекундах. Обычно указывают здесь значение 10 .. 50, -1 означает бесконечное время ожидания.

Возвращаемое значение: количество фреймов, которые были реально прочитаны, -1 показывает ошибку устройства.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
long lRel;
VCI_CAN_OBJ vco[100];
 
lRel = VCI_Receive(nDeviceType, nDeviceInd, nCANInd, &vco, 100, 1000);
if(lRel > 0)
{
   ... /* Обработка данных */
}
else if (lRel == -1)
{
   /* Устройство USB-CAN не существует или отключено от USB.
      Вы можете вызвать VCI_CloseDevice и заново вызвать
      VCI_OpenDevice. Это может обеспечить эффект
      горячей замены устройства USB-CAN. */
}

[Другие функции и структуры данных]

В этой главе приведены дополнительные типы данных и описания функций, не совместимых с библиотекой интерфейса Zhou Ligong (ZLG), предоставленной в ControlCAN.dll адаптера USB-CAN. Если вы используете ZLG-совместимый режим для вторичной разработки, не вызывайте эти функции, чтобы не повлиять на совместимость.

Структура VCI_BOARD_INFO1 содержит информацию об устройстве и интерфейсе адаптера серии USB-CAN, находящемся в Вашем компьютере, когда к нему подключено одно или несколько таких устройств (поддерживается одновременное подключение до 4 устройств). Эта структура будет заполнена в функции VCI_FindUsbDevice.

typedef struct _VCI_BOARD_INFO1
{
   USHORT hw_Version;
   USHORT fw_Version;
   USHORT dr_Version;
   USHORT in_Version;
   USHORT irq_Num;
   BYTE can_Num;
   BYTE Reserved;
   CHAR str_Serial_Num[8];
   CHAR str_hw_Type[16];
   CHAR str_Usb_Serial [4][4];
}VCI_BOARD_INFO1, *PVCI_BOARD_INFO1;

Поля структуры:

hw_Version Номер версии аппаратуры, в hex-представлении. Например, 0x0100 показывает V1.00. Не используется.

fw_Version Номер версии firmware, в аналогичном hex-представлении. Не используется.

dr_Version Номер версии USB-драйвера, в аналогичном hex-представлении. Не используется.

in_Version Номер версии библиотеки интерфейса, в аналогичном hex-представлении. Не используется.

irq_Num Номер прерывания, используемый платой, зарезервированный параметр. Не используется.

can_Num Показывает общее количество каналов CAN. Не используется.

Reserved Зарезервировано системой.

str_Serial_Num Серийный номер платы. Не используется.

str_hw_Type Строка описания типа аппаратуры, например "USBCAN V1.00". Не используется.

str_Usb_Serial Серийный номер USB-CAN, возвратит 4 набора 4-символьных строк ASCII, каждая строка представляет серийный номер устройства. На одном компьютере может поддерживаться 4 устройства USB-CAN одновременно.

Основное назначение структуры:

1. Привязка программного и аппаратного обеспечения: когда пользователь разрабатывает программное обеспечение во второй раз, программное и аппаратное обеспечение может быть однозначно связано. Вызвав эту функцию, можно получить 4-значный серийный номер устройства по сравнению с серийным номером, предварительно установленным в приложении пользователя. Это позволяет реализовать уникальное связывание и шифрование программного и аппаратного обеспечения (параметр str_Serial_Num в структуре VCI_BOARD_INFO, заполненной функцией VCI_ReadBoardInfo, нельзя использовать для шифрования.

2. Когда несколько адаптеров находятся на одном компьютере, порядковый номер устройства совпадает с серийным номером, одно за другим. Т. е. если несколько устройств подключены к компьютеру одновременно, то для работы с соответствующим устройством вам необходимо знать его порядковый номер. При вызове этой функции серийные номера всех устройств могут быть сохранены в str_Usb_Serial[4][4], где номера устройств по порядку равны 0, 1, 2 и 3.

Примечание: все поля структуры VCI_BOARD_INFO1, кроме элементов str_Usb_Serial[4][4], не являются допустимыми параметрами. Эти параметры можно получить, вызвав VCI_ReadBoardInfo.

Функция VCI_ConnectDevice проверяет, корректно ли подключено устройство USB-CAN к компьютеру, чтобы с ним можно было обмениваться данными. Во время работы устройство USB-CAN может быть отключено от операционной системы из-за внешних помех или неправильного функционирования. Эта функция используется для определения состояния соединения. Если обнаружено отклонение от нормального состояния, может быть выполнено быстрое и соответствующее исправление ситуации.

DWORD __stdcall VCI_ConnectDevice(DWORD DevType, DWORD DevIndex);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

CANIndex Индекс канала CAN-адаптера.

Возвращаемое значение: 1 обмен с устройством возможен, 0 обмен невозможен.

Пример использования на C++:

#include "ControlCan.h"
 
int ret=VCI_ConnectDevice(2,0);
if(ret == 1)
   SetWindowText("Нормальный обмен данными");
else if (ret == 0)
{
   SetWindowText("Устройство отвалилось...");
   StopFlag=1;
   for(int i=0; i < 10; i++)
   {
      Sleep(1000);
      VCI_BOARD_INFO vbi;
      // Проверка, подключено ли устройство к порту USB компьютера:
      int temp = VCI_FindUsbDevice(&vbi);
      if(temp == 1)
      {
         SetWindowText("Запустите устройство на компьютере.");
         // Выполните функцию OpenDevice, чтобы снова открыть устройство.
      }
      else
         SetWindowText("Устройство отсутствует на компьютере.");
   }
}

Функция сбрасывает адаптер USB-CAN, после чего потребуется открыть его заново вызовом функции VCI_OpenDevice.

DWORD __stdcall VCI_UsbDeviceReset(DWORD DevType, DWORD DevIndex, DWORD Reserved);

Параметры:

DevType Тип адаптера (см. выше таблицу 3).

DevIndex Индекс устройства в операционной системе Windows. Например, если к компьютеру подключен только один адаптер USB-CAN, то значение индекса должно быть равно 0. Если подключено несколько адаптеров, то в параметре DevIndex указывается индекс (номер в системе) устройства, начинающийся с 0.

Reserved Зарезервировано.

Возвращаемое значение: 1 означает успешный результат выполнения функции, 0 показывает сбой вызова функции, -1 показывает, что устройство отсутствует.

Пример использования на C++:

#include "ControlCan.h"
 
int nDeviceType = 4; /* USB-CAN2.0 */
int nDeviceInd = 0;
int nCANInd = 0;
DWORD dwRel;
 
bRel = VCI_UsbDeviceReset(nDeviceType, nDeviceInd, 0);

Эта функция позволяет найти текущее устройство USB-CAN, когда к одному компьютеру подключено несколько таких устройств.

DWORD __stdcall VCI_FindUsbDevice(PVCI_BOARD_INFO1 pInfo);

Параметры:

pInfo Указатель на структуру, где сохраняются параметры найденных на компьютере устройств.

Возвращаемое значение: количество адаптеров USB-CAN, подключенное к компьютеру.

Пример использования на C++:

#include "ControlCan.h"
 
CString ProductSn[5];
VCI_BOARD_INFO1 vbi;
CString strtemp,str;
 
int num = VCI_FindUsbDevice(&vbi);
for(int i=0; i < num; i++)
{
   str="";
   for(int j=0; j < 4; j++)
   {
      strtemp.Format("%c", pData->str_Usb_Serial[i][j]);
      str+=strtemp;
   }
   ProductSn[i] = "USBCAN-" + str;
}

Для того, чтобы облегчить работу с несколькими устройствами на одном компьютере, разработчики предоставили дополнительные функции (показанные на диаграмме ниже зелеными прямоугольниками. Это функции VCI_FindUsbDevice, VCI_UsbDeviceReset, VCI_ResumeConfig, VCI_ConnectDevice, VCI_GetReference2 и VCI_SetReference2. Во время вторичной обработки эти функции вызывать не обязательно. Даже если эти функции не применять совсем, все равно можно воспользоваться всем возможностями адаптера USB-CAN.

USB CAN usage API process

Работа с CANalyst-II на языке C# основана на загрузке библиотеки ControlCAN.dll и вызове её функций.

private const string DllFilePath = @"ControlCAN.dll";
[DllImport(DllFilePath, CallingConvention = CallingConvention.StdCall)]
extern static UInt32 VCI_CloseDevice(UInt32 DeviceType, UInt32 DeviceInd);
[DllImport(DllFilePath, CallingConvention = CallingConvention.StdCall)]
extern static UInt32 VCI_OpenDevice(UInt32 DeviceType, UInt32 DeviceInd, UInt32 Reserved);
... 

Код примера сохранен максимально простым, чтобы был понятнее принцип работы с библиотекой.

CANalyst II simple Csharp example

Принимаемые данные и сообщения об ошибках пишутся в файл лога logapp.txt.

200225 04:01:35 [CANalyst.Form1] [START]
200225 04:01:47 [CANalyst.Form1] RX: ID:0x321 Тип фрейма:data станд. данные: 5C AD FF 3B FC D1 FF 2B
200225 04:01:50 [CANalyst.Form1] RX: ID:0x321 Тип фрейма:data станд. данные: 5D AD FF A5 FE F6 EF C8
200225 04:01:59 [CANalyst.Form1] RX: ID:0x321 Тип фрейма:data станд. данные: 5E AD FF AA B3 1B DF C8
200225 04:03:41 [CANalyst.Form1] [exit]

В архиве [5] можно скачать этот проект полностью.

[Ссылки]

1. CANalyst-II - средство диагностики CAN и CANopen.
2. 170627CANalyst-II.7z - содержимое диска CANalyst-II (драйвер, документация, библиотека API, примеры кода).
3. CAN Bit Time Calculation site:bittiming.can-wiki.info.
4. SJA1000 Timing Calculator site:esacademy.com.
5200226CANalyst-II-minimal-example.zip - простой пример использования API-функций ControlCAN.dll для управления CANalyst-II.