Во время установки на Windows появляется диалог для установки отдельных компонентов «КАСКАД Цифра» . Установите флажок для установки API. По умолчанию API устанавливается в <KASKAD>/api. Вы также можете указать любой другой целевой каталог, например, C:/ => API устанавливается в C:/api.
Linux
Во время установки на Linux появляется диалог для установки отдельных компонентов. Установите флажок для установки API. API устанавливается в каталог opt/KASKAD/<version>/api.
Этот менеджер является примером того, как написать простой API-менеджер. Это пример реализации алгоритмов CONTROL на C++, а не на CTRL или взаимодействия с простым оборудованием. В отличие от драйверов, API не может использовать конфигурации адресов.
Этот пример менеджера показывает, как подключиться к менеджерам данных и событий. Он также подключается к точке данных и каждый раз копирует новое значение в другую точку данных. Имена двух точек данных задаются в конфигурационном файле.
Подготовка менеджера API на ОС Windows
Создайте новый проект менеджера API с помощью скрипта newWCCILManager.cmd. Скрипт копирует исходный шаблон, содержащий демонстрационный менеджер.
Скомпилируйте проект и запустите его в обычном режиме (F7).
Если вы хотите запускать его из консоли, вам придется переименовать его (например, KASKADdemo.exe) и скопировать в каталог /bin проекта.
Подготовка менеджера API на ОС Linux
1. Укажите переменные окружения для API, как описано в разделе Installation/Linux (Установка/Linux).
2. Создайте новый проект с помощью сценария $API_ROOT/newWCCILManager.sh.
3. Скомпилируйте менеджер API с помощью следующей команды из каталога проекта:
make
Необходимо ввести эти данные в каталоге, в котором находится Makefile.api для драйвера. Как правило, это каталог, в котором находятся исходные данные (например, $API_ROOT/SampleDriver).
Исполняемый файл созданного менеджера называется DemoManager.
Настройки конфигурационных элементов
Разделы, считываемые менеджером, называются [demo] и [demo_<num>], например, если менеджер запускается с -num 1 [demo] и [demo_1], то:
В приведенной выше записи укажите точку данных, конфиг и атрибут, к которым должен подключиться менеджер. По умолчанию используется «ExampleDP_Arg2.:_online .._value».
Ниже укажите точку данных, конфигурацию и атрибут, в который нужно скопировать значения. Используйте тот же тип данных, так как автоматического преобразования не происходит. По умолчанию используется «ExampleDP_Arg1.:_original.._value».
Этот драйвер производит обмен информацией посредством протокола TCP или UDP. Соединение по протоколу TCP и UDP могут быть настроены вместе и отдельно. Каждое из этих соединений обозначается через » Communication Reference» brief kr, который указывается в конфигурационном файле. Для TCP и UDP необходимо задать конфигурацию для сервера и клиента.
Соединение работает только тогда, когда сервер запускается раньше клиента.
Данные могут быть переданы исключительно от клиента к серверу.
Настройка сервера
Сконфигурируйте адресную панель:
Скопируйте файлы userPara.ctl и userDrivers.ctl в каталог скриптов вашего проекта.
Скопируйте панель address_tcp.pnl в каталог panels/para вашего проекта.
Значения файла Config
Записи указываются в разделах [tcp] и/или [tcp_<num>].
В разделе [tcp_1] указываются настройки для сервера, а клиент конфигурируется в разделе [tcp_2]. Раздел [tcp] , в котором указываются записи для сервера и для клиента, не используется для драйвера TCP.
Конфигурация сервера
(драйвер с параметром -num 1 является сервером):
tcpServerSocket
[tcp_1] tcpServerSocket = 4242
tcpServerSocket — это номер порта, в котором клиент должен связаться с сервером с помощью TCP-соединения.
udpServerSocket
[tcp_1] udpServerSocket = 4241
udpServerSocket — это номер порта, в котором клиент должен связаться с сервером с помощью UDP-соединения.
Аргумент 1: kr — Это число должно соответствовать записи в [tcp_1] (настройки сервера). Если одно и то же число указывается для kr более одного раза, драйвер прекращает свою работу.
«127.0.0.1:4241» — локальный IP-адрес собственного компьютера
«localhost:1764» — имя хоста собственного компьютера
IP-адрес или имя хоста должно соответствовать указанию в конфигурации сервера.
«Serverport» — это номер порта, который используется клиентом для соединения. Оно должно существовать и при этом должно соответствовать tcpServerSocket или udpServerSocket.
Аргумент 3: Обозначение протокола «TCP» или «UDP»
Оно должно соответствовать указанию в конфигурации сервера.
Конфигурирование
Для конфигурирования должен работать хотя бы один драйвер (это может быть и имитационный драйвер).
В конфигурационном файле представлены следующие записи. Таким образом определяются соединения связи. Все элементы (сервер и клиент) находятся на одном и том же компьютере.
После создания конфигурационных элементов адресов необходимо выбрать тип драйвера. В случае драйвера протокола TCP — это образец драйвера протокола TCP.
Рисунок: Конфигурирование образца драйвера протокола TCP
После нажатия кнопки Configure… (Сконфигурировать…) необходимо заполнить поля следующим образом:
Справочные материалы: z.B. 1.67
1 = kr
67 = ix
Драйвер с -num 1 — это сервер, и, соответственно, получатель данных.
ix (может быть интерпретировано как адрес памяти в целевом аппаратном обеспечении) — это произвольное число, которое должно быть одним и тем же в отправленной и полученной ТД.
«Direction»: указание направления передачи
Для входных данных также можно настроить «Низкоуровневое сравнение старый–новый».
Тип данных: поддерживаются типы bool, integer, float и string.
Driver number: в примере 1 установлен для ввода (сервер) и 2 — для вывода (клиентское приложение).
Рисунок: Конфигурирование образца драйвера протокола TCP
Пока вы будете использовать задокументированные функции API, нет необходимости в тщательном знании сообщений: сообщения генерируются и отправляются функциями интерфейса API, поэтому пользователю не приходится иметь с ними дело.
Множество разных сообщений не принимается и не обрабатывается менеджерами в автоматическом режиме, например, сообщение о создании новой точки данных. Однако, если менеджер запрашивает определенные атрибуты (dpGet(), dpGetPeriod() и т.д.) или регистрируется для изменения атрибутов (dpConnect()), то он должен обработать входящие сообщения самостоятельно. Если он этого не сделает, они будут автоматически отклонены.
ПРИМЕЧАНИЕ
Если вы хотите получить информацию об элементе «root», вам необходимо использовать его вместе с точкой, например, «struct1.», потому что если вы будете использовать его без точки, то будет использоваться сама точка данных (data point = «.. El: 0 ..», root-element = «.. El: 1 ..»). Но такое может произойти только с «root»-элементом, а не с другими элементами точек данных.
Объекты WaitForAnswer
В случае большинства функций, связанных с доступом к точкам данных, сообщения обрабатываются с помощью объектов WaitForAnswer. Например, для dpConnect задается объект HotlinkWaitForAnswer.
Пользователь должен соответствующим образом перегрузить объект HotlinkWaitForAnswer и отредактировать ответ в перегруженной функции. Подробности см. в примере DemoManager.
Все шесть вариантов dpConnect() также существуют в виде dpConnectNoSource(). В принципе, эта функция делает то же самое, что и dpConnect(), с той разницей, что вместо сообщения DP_MSG_CONNECT_NOSOURCE отправляется сообщение DP_MSG_CONNECT.
Сообщение DP_MSG_CONNECT_NOSOURCE используется для того, чтобы не допустить отправку значений в цикле между драйвером и событием.
Если точка данных сконфигурирована как точка ввода-вывода, то для нее регистрируется драйвер. Если драйвер отправит данные об изменении значения менеджеру событий, то он повторно получит значение и повторно отправит его аппаратным средствам.
С помощью dpConnectNoSource() менеджер событий проверяет, получено ли уже значение от драйвера или еще откуда-нибудь перед тем, как отправить прямую ссылку, и отправляет ее только в том случае, если драйвер не был триггером.
doReceive()
Менеджер обрабатывает входящие сообщения в функции doReceive(). Функция doReceive() автоматически вызывается функцией dispatch() для каждого входящего сообщения. Есть два способа получения сообщения.
Внутри программы сначала вызывается doReceive(DpMsg *msg). В стандартной реализации после вызова doReceive(DpMsg &msg) сообщение удаляется.
В первом методе (doReceive(DpMsg *msg)) указатель на DpMsg передается в doReceive. Сообщение присваивается динамически, при этом менеджер отвечает за освобождение памяти от сообщения, как только больше не требуется.
Применение данного метода имеет смысл, если, например, сообщение стоит на очереди для последующей обработки. В таком случае указатель можно использовать напрямую, а также отпадает необходимость в копировании сообщения заранее.
Второй метод заключается в передаче ссылки на DpMsg. Как только функция выходит из функции doReceive, сообщение автоматически удаляется. Таким образом, если предполагается, что сообщение будет существовать дольше, чем функция doReceive, этот метод не подходит.
Обычно сообщения не нужно обрабатывать в doReceive, поскольку большая часть функций может быть проще реализована с помощью объектов WaitForAnswer.
Msg
Класс Msg class является абстрактным базовым классом для всехсообщений, используемых в «КАСКАД Цифра». Он содержит базовые функции сообщений.
Наиболее важной функцией Msg является isA(). Эта функция возвращает тип сообщения, что позволяет фильтровать те сообщения в doReceive(), которые предназначены для обработки в менеджере.
Все остальные сообщения должны быть переданы в функцию doReceive() базового класса менеджеров, Manager::doReceive(), чтобы можно было применить стандартную обработку.
Наиболее важные типы сообщений описаны ниже.
SysMsg
Производный от класса Msg, класс SysMsg является абстрактным базовым классом для всех системных сообщений. Используется главным образом при запуске «КАСКАД Цифра». Так как системные сообщения не имеют значения при нормальной работе «КАСКАД Цифра», они здесь не описываются.
DpMsg
Производный от класса Msg, класс DpMsg является абстрактным базовым классом для всех сообщений, относящихся к точкам данных. С момента запуска программы практически весь обмен информацией осуществляется с их помощью.
В программе «КАСКАД Цифра» представлен класс «Manager», который уже содержит в себе все базовые функции, необходимые для менеджера. Для каждого нового менеджера необходимо, на основе этого класса создать класс-наследник, в котором будут реализованы его специфические функции. Производный класс содержит ряд виртуальных функций, которые новый менеджер может, а в некоторых случаях и обязан реализовывать.
ПРИМЕЧАНИЕ
Если вы используете менеджер API или драйвер, в котором применяются библиотеки DLL вместе с новой версией «КАСКАД Цифра», его необходимо перекомпоновать.
При запуске такого менеджера, библиотеки DLL должны находиться в каталоге, указанном в пути поиска библиотек DLL.
ВНИМАНИЕ
Длина имени менеджера в консоли «КАСКАД Цифра» ограничена 19 символами.
ПРИМЕЧАНИЕ
Начиная с версии 3.9 программы «КАСКАД Цифра», функция dpQueryDisconnect() имеет только два параметра вместо обычных трех, параметр «del» был удален. Для обеспечения совместимости, значение третьего параметра (например, PVSS_FALSE) необходимо стереть из исходных данных.
Примечание для пути поиска библиотек DLL
Программа производит поиск библиотек DLL в следующих каталогах в таком порядке:
каталог, в котором находится исполняемый файл
системные каталоги Windows
все каталоги в переменной среды PATH (ПУТЬ)
Для примера см. DemoManager.
Инициализация, managerState, dispatch()
При создании собственного класса менеджера убедитесь, что конструктор правильно инициализирует базовый класс, иначе не удастся установить соединение.
Состояние переменной managerState необходимо принимать во внимание во всех случаях. Например, соединение с менеджером событий должно быть установлено только тогда, когда managerState имеет значение STATE_ADJUST. Дальнейшая обработка может происходить только при значении STATE_RUNNING. Эти состояния регулируются автоматически, и, при любых обстоятельствах, должны только считываться.
Сообщения принимаются и отправляются только тогда, когда вызывается dispatch(). (Однако сообщения всегда отправляются только в том случае, когда внутренний буфер сообщений полон (текущий размер: 4096 байт)). Если функция dispatch() вызывается неправильно, то связь с менеджером будет заблокирована и будет невозможно, например, получить какие-либо сообщения по прямой ссылке.
Использование псевдонимов в менеджере API
Если вы хотите использовать псевдонимы для точек данных(далее ТД) в менеджере API, то вы можете получить идентификаторы ТД или имена ТД для псевдонимов и наоборот, используя для этого следующие функции:
Alias —> Name:
Manager::getDpIdentificationPtr()->getName(const char> *alias, char *&name) //получает имя точки данных с помощью DPIdentifier
Alias —> DpIdentifier:
Manager::getId(const char *alias, DpIdentifier &dpId) //получает идентификатор точки данных (в таком случае псевдонимы должны начинаться с "@")
Name —> Alias:
Manager::getDpIdentificationPtr()->getDpAlias(const char *dp, CharString &alias) //получает псевдоним с помощью DpIdentifier
DpIdentifier —> Alias:
Manager::getDpIdentificationPtr()->getDpAlias( const DpIdentifier &dp, CharString &alias) //получает псевдоним с помощью DpIdentifier
Обработка ошибок
В программе «КАСКАД Цифра». существует общий класс обработчиков ошибок. В этом классе представлены обработчики ошибок, используемые в каждом менеджере. В зависимости от флажков -log, заданных при запуске менеджера, сообщения об ошибках записываются в файле PVSS_II.log и/или в stderr. Также ошибки могут записываться в базу данных, с помощью ExternErrHdl-Plug-in можно реализовать расширение, которое производит запись.
Если ErrHdl найдет совместно используемую библиотеку /dll с именем «ExternErrHdl» и одним из расширений «.so», «.shlib», «.dll» или «libExternErrHdl» (.dll — только для Windows, .so или .shlib — для других операционных систем) в каталоге bin текущего проекта, то она загрузит ее при запуске, вызовет extern «C» { ExternErrHdl *createExternErrHdl(); } для создания экземпляра класса ExternErrHdl, и вызовет его метод handleError(const ErrClass &errorClass) перед тем, как сделать запись в целевых объектах (лог-файл или stderr), указанных посредством опции -log.
Если вы захотите, например, записать ошибки в базу данных (в дополнение к лог-файлу PVSS_II), то можете использовать ExternErrHdl. Для этого нужно вывести класс из ExternErrHdl, скомпилировать его как shared libb/ и сохранить в каталоге bin как ExternErrHdl shared lib.
Примере получения класса из ExternErrHdl.
/* Пример внешнего обработчика ошибок, загруженного в качестве совместно используемой библиотеки/библиотеки dll посредством стандартного обработчика ошибок программы "КАСКАД Цифра" /*
/* При работе с LINUX данный класс записывает ошибки в syslog, а при работе с Windows - распечатывает ошибки в stderr/* #ifdef OS_LINUX #include <syslog.h> #endif #include <ExternErrHdl.hxx> #include <Resources.hxx> CharString name; class MyExternErrHdl : public ExternErrHdl { public: MyExternErrHdl() { #ifdef OS_LINUX name = Resources::getProgName() + "(" + CharString(Resources::getManNum()) + ")"; openlog((const char*)name, 0, LOG_USER); #else cerr << "Construct ExternErrHdl" << endl; #endif } virtual ~MyExternErrHdl() { #ifdef OS_LINUX closelog(); #else cerr << "Destruct ExternErrHdl" << endl; #endif } virtual void handleError(const ErrClass &errorClass) { #ifdef OS_LINUX int level = 0; switch ( errorClass.getPriority() ) { case ErrClass::PRIO_FATAL: level = LOG_CRIT; break; case ErrClass::PRIO_SEVERE: level = LOG_ERR; break; case ErrClass::PRIO_FATAL: level = LOG_WARNING; break; case ErrClass::PRIO_INFO: level = LOG_INFO; break; } syslog(LOG_USER + level, "%s", (const char*)(errorClass.getErrorText())); #else cerr << "ExternErrHdl: "; errorClass.outStream(cerr); #endif } }; //Данная функция создает объект ExternErrHdl extern "C" { __declspec(dllexport) ExternErrHdl *createExternErrHdl() { return new MyExternErrHdl(); } }
В этом примере показан драйвер «КАСКАД Цифра», который взаимодействует с другим посредством технологии «named Pipes». Один из них — сервер, который открывает «named Pipe» и отправляет сообщения, второй — клиент, который устанавливает соединение с сервером и получает сообщения.
Подготовка драйвера
Задайте свои переменные среды для API и PLATFORM, как это описано в разделе API installation (Установка API).
ПРИМЕЧАНИЕ
Если вы установили API во время установки «КАСКАД Цифра», то эти переменные уже заданы!
Скопируйте каталог SampleDriver из $API_ROOT.
Создайте каталог сборки и скомпилируйте драйвер, как описано в главе «Начало работы».
Исполняемые файлы находятся в подкаталогах «Release» или «Debug».
Если вы хотите запустить драйвер из консоли «КАСКАД Цифра», скопируйте исполняемые файлы в каталог /bin в своем проекте «КАСКАД Цифра» (PROJ_PATH/bin).
Имя исполняемого файла должно начинаться с «WCCOA», чтобы его можно было увидеть в списке менеджеров.
Настройки проекта
Перед использованием SampleDriver необходимо создать внутренние точки данных.
Запустите в консоли два имитатора драйвера с параметрами -num 1 и -num 2.
Импортируйте файл «SampleDriver.asc» с помощью менеджера ASCII. Вам нужно два имитатора, потому что этот файл указывает адреса периферийных устройств для драйвера с номером 1 и 2.
В файле «SampleDriver.asc» задайте «StartValue 20», чтобы точка данных была окончательно определена:
Запустите драйвер с параметром «-num 1» (сервер по умолчанию), чтобы установить соединение.
Запустите клиент.
Есть два примера точек данных «SampleTest_1» и «SampleTest_2», с помощью которых можно отправлять сообщения от сервера ( -num 1) к клиенту ( -num 2). Возможно только такое направление!
Клиент подсчитывает все сообщения и отображает их число во внутренней точке данных «_SampleDriver.Counter».
Используйте «_SampleDriver_2.ResetCounter» для обнуления счетчика.
Параметры конфигурации
Все настройки являются опциональными, так как они имеют настройки по умолчанию. Записи из следующего раздела применяются ко всем драйверам SampleDriver.
Для систем Windows:
[sample] pipeName = "\\\\.\\pipe\\SampleDriver"
Для Linux:
[sample] pipeName = "/tmp/SampleDriver"
Указывает имя соединения. Так как оба драйвера используют одинаковое имя, в этом разделе его необходимо указать для обоих драйверов.
Это раздел для драйвера -num 1:
[sample_1] server = "Yes" sampleDpName = "_SampleDriver_1"
Задайте этот драйвер в качестве сервера (устанавливает соединение). Возможные значения: «Yes» («Да») и «No» («Нет»).
Укажите имя внутренних точек данных. По умолчанию используется «_SampleDriver_1«.
Для резервной системы замените это значение на _SampleDriver_1_2 для host2.
Это раздел для драйвера -num 2:
[sample_2] server = "No" sampleDpName = "_SampleDriver_2"
Задайте сервер 2 в качестве клиента (подключается к серверу). Возможные значения: «Yes» («Да») и «No» («Нет»).
Укажите имя внутренних точек данных. По умолчанию используется «_SampleDriver_2«.
Для резервной системы замените это на «_SampleDriver_2_2» для host2.
API «КАСКАД Цифра» (Application Programming Interface — интерфейс программирования приложений) предлагает ряд функций, добавляющих специальных менеджеров к системе управления процессами. Менеджер — это программа, которая взаимодействует с системой по протоколу, определенному «КАСКАД Цифра».
Документацию по функциям API можно найти в каталоге вашей установки
<путь_КАСКАД>/api/docu
ПРИМЕЧАНИЕ
Документация доступна только в том случае, если в настройках «КАСКАД Цифра» была выбрана опция установки API.
Классы, подключение из файлов
Для того чтобы облегчить работу с большим количеством классов C++, доступных в «КАСКАД Цифра», все подключаемые файлы называются точно так же, как и имя класса, но имеют расширение «.hxx». Например, класс под названием «ManagerIdentifier» можно найти в файле «ManagerIdentifier.hxx». То есть, для использования класса необходимо включить соответствующий файл с помощью директивы #include.
Многие классы можно использовать и без явного #include, т.к., например, файл Manager.hxx уже включает множество других классов.
Менеджер событий и данных
Один из основных менеджеров в «КАСКАД Цифра» — менеджер событий. Он является центром коммуникаций системы управления и как только любой другой менеджер загружается, начинается обмен сообщениями с менеджером событий.
Второй ключевой менеджер — это Менеджер данных, т.к. он выполняет все задачи по управлению данными. При запуске программы каждый менеджер подключается к Менеджеру данных для инициализации. После успешной инициализации программа подключается к Менеджеру событий (за исключением, конечно, самого Менеджера событий). Соединения с менеджером данных и менеджером событий поддерживаются до тех пор, пока работа текущего менеджера не будет завершена.
Программа может подключиться к менеджерам данных и событий только в том случае, если нет другого подключенного менеджера с тем же идентификатором. Особенно при использовании менеджеров API убедитесь, что все они одного типа и отличаются только идентификационным номером.
ВНИМАНИЕ
ВСЕГДА перекомпилируйте пользовательские менеджеры, созданные с помощью определенной версии «КАСКАД Цифра», при переходе к более поздней версии (это относится и к «branch» версиям!).
Сообщения
Менеджеры обмениваются информацией друг с другом с помощью сообщений. «КАСКАД Цифра» имеет фиксированный набор сообщений, используемых для связи.
Большинство функций API используются для генерации и отправки сообщений. Менеджеры получают сообщения с помощью функции doReceive(), которая применяется ко всем входящим сообщениям.
Файл заголовков FunctionVar
Так же в «КАСКАД Цифра» присутствует файл заголовков FunctionVar.hxx. Однако следует учитывать, что в этот файл также включены заголовки Qt, которые не входят в API «КАСКАД Цифра». Таким образом, необходима отдельная установка Qt.
В данном примере показано, как менеджер подключается к менеджерам данных и событий. Также он подключается к точке данных и каждый раз копирует новое значение в другую точку данных.
Пока вы будете использовать задокументированные функции API, нет необходимости в тщательном знании сообщений: сообщения создаются и отправляются функциями интерфейса API, поэтому пользователю не приходится иметь с ними дело.
Общий драйвер является совокупностью классов, охватывающих функциональный диапазон, которым должен обладать каждый драйвер программы «КАСКАД Цифра». Также он определяет интерфейс для компонентов, относящихся к аппаратному обеспечению.
Подготовлено два примерных сценария, чтобы упростить вам интегрирование новых драйверов в программу «КАСКАД Цифра». Все, что вам необходимо сделать, — это добавить имя и тип в указанных точках в сценариях, и определить свои команды.
EWO (объект внешнего виджета) — это графический объект (виджет), который был создан сторонней организацией (заказчиком), и может быть встроен в любую панель «КАСКАД Цифра». Этот объект не зависит от платформы.
Под Windows статические библиотеки libBasics.lib, libConfigs.lib, libDatapoint.lib, libMessages.lib, libManager.lib были преобразованы в DLL.
Если необходимо воссоздать API-менеджеры или драйверы с версией API, начиная с 2.10, которые были созданы с использованием предыдущих версий, то при связывании необходимо внести следующие изменения:
Менеджер API: Вместо Config-Objs (DpConfig.obj, dpConfigManager.obj, GeneralConfig.obj) достаточно линковать libConfigs.lib.Drivers: Вместо библиотеки libDrvConfigs.lib подключите libConfigs.lib.
При конвертации других библиотек изменений нет, так как экспортные библиотеки DLL теперь располагаются в каталоге api/lib, в котором раньше находились статические библиотеки, поэтому при линковке разницы нет.
NOTE
Если вы используете менеджер API или драйвер, который использует библиотеки DLL с новой версией «КАСКАД Цифра», то их необходимо перелинковать. При запуске такого менеджера библиотеки DLL должны находиться в каталоге в пути поиска DLL.
Примечание по пути поиска DLL
Программа ищет библиотеки DLL в следующих каталогах в указанном порядке:
ПРИМЕЧАНИЕ
ВНИМАНИЕ