API «ядра» на C

RF62X-CORE - основная библиотека («Ядро») с базовым набором функций и типов для работы с лазерными сканерами серии RF62X. Библиотека написана на языке программирования CИ в соответствии со стандартом C99 (ISO / IEC 9899: 1999) и является кросс-платформенной. Для использования данной библиотеки необходима реализация платформозависимых функций (работа с памятью, работа с сетью, функции ввода/вывода).

Для скачивания библиотеки см. последние выпуски «ядра» на C.

Для компиляции библиотеки см. компиляция и запуск «ядра» на C.

Инициализация «ядра»

При желании использовать библиотеку RF62X-CORE вместо предоставляемых библиотек-«обёрток» разработчику необходимо самостоятельно реализовать платформозависимую часть «ядра» (см. компиляция и запуск «ядра»).

Файл rf62X_core.h является заголовочным файлом с описанием функций для запуска «ядра». Этот файл содержит определения основных функций, используемых при его инициализации:

init_platform_dependent_methods()

Функция инициализация платформозависимой части «ядра»

void init_platform_dependent_methods(memory_platform_dependent_methods_t *memory_methods, iostream_platform_dependent_methods_t *iostream_methods, network_platform_dependent_methods_t *network_methods, network_platform_dependent_settings_t *adapter_settings)

Init platform dependent methods and settings.

Parameters

• memory_methods: Structure with platform-specific methods for work with memory

• iostream_methods: Structure with platform-specific methods for work with iostream

• network_methods: Structure with platform-specific methods for work with network

• adapter_settings: Structure with adapter settings

core_version()

Функция для получения текущей версии «ядра»:

rfChar *core_version()

core_version - Return rf627 sdk version.

Return

ptr to rfChar

Обзор программного интерфейса

Файл rf62X_sdk.h является основным файлом программного интерфейса (API) «ядра» и определяет его функциональность. rf62X_sdk.h содержит следующий набор базовых функций для разработки:

set_platform_adapter_settings()

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

void set_platform_adapter_settings(rfUint32 subnet_mask, rfUint32 host_ip_addr)

change_platform_adapter_settings - change adapter’s settings

Parameters

• [in] subnet_mask: Subnet mask on your local machine. A subnet mask is a number that defines a range of IP addresses that can be used in a network.

• [in] host_ip_addr: IP address of your network adapter(card)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));

//Initialization vector
vector_init(&scanners);


// Iterate over all available network adapters in the current operating
// system to send "Hello" requests.
for (int i=0; i<GetAdaptersCount(); i++)
{
   // get another IP Addr and set this changes in network adapter settings.
   uint32_t host_ip_addr = ntohl(inet_addr(GetAdapterAddress(i)));
   uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
   // call the function to change adapter settings inside the library.
   set_platform_adapter_settings(host_mask, host_ip_addr);

   // Search for RF627Old devices over network by Service Protocol.
   search_scanners(scanners, kRF627_OLD, kSERVICE);
}

search_scanners()

Функция для поиска устройств RF62X по сети

rfUint8 search_scanners(vector_t *list, scanner_types_t type, rfUint32 timeout, protocol_types_t protocol)

search_scanners - Search for RF62X devices over network

Return

TRUE on success

Parameters

• [out] list: Ptr to list of rf627 objects. If not null list will be filled with found devices

• [in] type: Scanner’s type (RF627-old, RF627-smart)

• [in] timeout: Time to search

• [in] protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

get_info_about_scanner()

Функция для получения информации о сканере из пакета приветствия (Hello-пакет)

hello_information get_info_about_scanner(scanner_base_t *device, protocol_types_t protocol)

get_info_about_scanner - Get information about scanner from hello packet

Return

hello_information on success

Parameters

• [in] device: Ptr to scanner

• [in] protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and get info.
for(size_t i = 0; i < vector_count(scanners); i++)
   hello_information info = get_info_about_scanner(
                                 (scanner_base_t*)vector_get(scanners,i), kSERVICE);

connect_to_scanner()

Функция для установки соединения со сканером серии RF62X

rfUint8 connect_to_scanner(scanner_base_t *device, protocol_types_t protocol)

connect_to_scanner - Establish connection to the RF62X device

Return

TRUE on success

Parameters

• [in] device: Ptr to scanner

• [in] protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
   connect_to_scanner((scanner_base_t*)vector_get(scanners,i), kSERVICE);

disconnect_from_scanner()

Функция для закрытия ранее установленного соединения со сканером серии RF62X

rfUint8 disconnect_from_scanner(scanner_base_t *device, protocol_types_t protocol)

disconnect_from_scanner - Close connection to the device

Return

TRUE on success

Parameters

• [in] device: Prt to scanner

• [in] protocol: Protocol’s type (Service, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
   connect_to_scanner((scanner_base_t*)vector_get(scanners,i), kSERVICE);

// Iterate over all discovered RF627Old in network for Disabling connection.
for(size_t i = 0; i < vector_count(scanners); i++)
   disconnect_from_scanner((scanner_base_t*)vector_get(scanners,i), kSERVICE);

get_profile2D_from_scanner()

Функция для получения профиля со сканеров серии RF62X

rf627_profile2D_t *get_profile2D_from_scanner(scanner_base_t *device, rfBool zero_points, rfBool realtime, protocol_types_t protocol)

get_profile2D_from_scanner - Get measurement from scanner’s data stream

Return

ptr to rf627_profile_t structure

Parameters

• [in] device: - ptr to scanner

• [in] zero_points: Enable zero points in return profile2D

• [in] realtime: Enable getting profile in real time (buffering disabled)

• [in] protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
{
   scanner_base_t* scanner = vector_get(scanners,i);
   connect_to_scanner(scanner, kSERVICE);

   // Flag for included zero points in return profile2D
   bool zero_points = true;
   // Get profile from scanner's data stream by Service Protocol.
   rf627_profile2D_t* profile = get_profile2D_from_scanner(scanner, zero_points, kSERVICE);

   {
      // some actions with profile
   }

   disconnect_from_scanner(scanner, kSERVICE);

   // Freeing memory after using profile structure
   free(profile->rf627_profile2D->intensity);
   free(profile->rf627_profile2D->pixels_format.pixels);
   free(profile->rf627_profile2D);
   free(profile);
}

read_params_from_scanner()

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

rfUint8 read_params_from_scanner(scanner_base_t *device, rfUint32 timeout, protocol_types_t protocol)

read_params_from_scanner - Read parameters from device to rfInternal structure.

Return

TRUE on success

Parameters

• device: Ptr to scanner

• timeout: Time to read parameters

• protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
{
   scanner_base_t* scanner = vector_get(scanners,i);
   connect_to_scanner(scanner, kSERVICE);

   // Read parameters from device to the internal structure of the core
   read_params_from_scanner(scanner, kSERVICE);

   {
      // some actions with params
   }

   disconnect_from_scanner(scanner, kSERVICE);
}

get_parameter()

Функция получения конкретного параметра по его имени (ключу). При вызове данной функции «ядро» осуществляет поиск нужного параметра из последних прочитанных при вызове функции read_params_from_scanner. В случае, если запрашиваемый параметр отсутствует в конкретном сканере, функция вернёт null.

parameter_t *get_parameter(scanner_base_t *device, const rfChar *param_name)

get_parameter - Search parameters by his name

Return

param on success, else - null

Parameters

• device: - ptr to scanner

• param_name: - name of parameter

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
{
   scanner_base_t* scanner = vector_get(scanners,i);
   connect_to_scanner(scanner, kSERVICE);

   // Read parameters from device to the internal structure of the core
   read_params_from_scanner(scanner, kSERVICE);

   // Get parameter of Device Name
   parameter_t* name = get_parameter(scanner, "user_general_deviceName");
   if ((name != NULL) && (strcmp(name->type, "string_t")==0)
   {
      char* str_name = name->val_str->value;
      printf("Current Device Name: %s\n", str_name);
   }

   disconnect_from_scanner(scanner, kSERVICE);
}

Для более удобной работы с параметрами можно использовать соответствующие «ключи» (ключ имени параметра, тип параметра и доступ к параметру). Для этого в файле rt62X_types.h находятся следующие enum:

Предупреждение

doxygenenum: Cannot find enum «paramValueType_t» in doxygen xml output for project «RF62XSDK» from directory: D:/Work/RIFTEK LLC/RF62X-SDK/RF62X-SDK/Docs/build/doxygen/xml/

Предупреждение

doxygenenum: Cannot find enum «paramAccessType_t» in doxygen xml output for project «RF62XSDK» from directory: D:/Work/RIFTEK LLC/RF62X-SDK/RF62X-SDK/Docs/build/doxygen/xml/

Предупреждение

doxygenenum: Cannot find enum «parameter_name_keys_t» in doxygen xml output for project «RF62XSDK» from directory: D:/Work/RIFTEK LLC/RF62X-SDK/RF62X-SDK/Docs/build/doxygen/xml/

Пример использования с ключами:

{
...Search devices
...Establish connections
...Read parameters
}

// Get parameter of Device Name
parameter_t* name = get_parameter(scanner, parameter_names_array[USER_GENERAL_DEVICENAME]);
if ((name != NULL) && (strcmp(name->type, parameter_value_types[PVT_STRING])==0)
{
   char* str_name = name->val_str->value;
   printf("Current Device Name: %s\n", str_name);
}

Для более детального описания каждого параметра и его свойств см. PARAMETERS

set_parameter()

Функция установки конкретного параметра. При вызове данной функции происходит установка передаваемого параметра в локальном списке параметров в «ядре». Для отправки изменений в сканер необходимо вызвать функцию write_params_to_scanner.

rfUint8 set_parameter(scanner_base_t *device, parameter_t *param)

set_parameter - Set parameter

Return

TRUE on success

Parameters

• device: Ptr to scanner

• param: Parameter name

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

// Create value for scanners vector's type
vector_t* scanners = (vector_t*)calloc(1, sizeof (vector_t));
//Initialization vector
vector_init(&scanners);

// set IP Addr and NetMask for setting in network adapter settings.
uint32_t host_ip_addr = ntohl(inet_addr("192.168.1.2"));
uint32_t host_mask = ntohl(inet_addr("255.255.255.0"));
// call the function to change adapter settings inside the library.
set_platform_adapter_settings(host_mask, host_ip_addr);

// Search for RF627Old devices over network by Service Protocol.
search_scanners(scanners, kRF627_OLD, kSERVICE);

// Iterate over all discovered RF627Old in network and Establish connection.
for(size_t i = 0; i < vector_count(scanners); i++)
{
   scanner_base_t* scanner = vector_get(scanners,i);
   connect_to_scanner(scanner, kSERVICE);

   // Read parameters from device to the internal structure of the core
   read_params_from_scanner(scanner, kSERVICE);

   // Get parameter of Device Name
   parameter_t* name = get_parameter(scanner, "user_general_deviceName");
   if ((name != NULL) && (strcmp(name->type, "string_t")==0)
   {
      char* str_name = name->val_str->value;
      printf("Current Device Name: %s\n", str_name);

      char* new_name = "NEW NAME";
      memcpy(name->val_str->value, new_name, strlen(new_name)+1);
      set_parameter(scanner, name);
   }

   //  Write changes parameters to the device's memory
   write_params_to_scanner(scanner, kSERVICE);

   disconnect_from_scanner(scanner, kSERVICE);
}

write_params_to_scanner()

Функция записи локальных параметров из «ядра» в сканер. При вызове данной функции происходит отправка списка локальных параметров из «ядра» в сканер.

rfUint8 write_params_to_scanner(scanner_base_t *device, rfUint32 timeout, protocol_types_t protocol)

write_params_to_scanner - Send current parameters to device

Return

TRUE on success

Parameters

• device: Ptr to scanner

• timeout: Time to send parameters

• protocol: Protocol’s type (Service Protocol, ENIP, Modbus-TCP)

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

{
...Search devices
...Establish connections
...Read parameters
}

// Get parameter of Laser Enabled
parameter_t* laser_enabled = get_parameter(scanner, "user_laser_enabled");
if ((name != NULL) && (strcmp(name->type, "uint32_t")==0)
{
   uint32_t is_enabled = laser_enabled->val_uint32->value;
   printf("Current Laser State: %s\n", is_enabled == 0 ? "OFF" : "ON");

   uint32_t new_state;
   if (is_enabled == 1)
      new_state = 0;
   else
      new_state = 1;

   laser_enabled->val_uint32->value = new_state;

   set_parameter(scanner, laser_enabled);
}

//  Write changes parameters to the device's memory
write_params_to_scanner(scanner, kSERVICE);

send_command()

Функция отправки команд в сканер

rfUint8 send_command(scanner_base_t *device, command_t *command)

set_parameter - Search parameters by his name

TODO

Return

param on success, else - null

Parameters

• device: - ptr to scanner

• param_name: - name of parameter

Для более детального описания команд и их свойств см. General device commands