API

Алгоритм и протокол работы контроллеров с сервером ОРС UA по протоколу JSON-RPC

  1. Общее описание
    1. Назначение
    2. Блок схема информационного взаимодействия
  2. Описание структур данных, используемых при передаче данных
    1. sDataValue — передача данных при изменении значений или аварии
    2. sWriteValue — передача данных для записи
    3. sWriteValueResponse — передача данных результатов операции записи
    4. sPropertyDescription — свойства устройства
    5. sPropertyValue — получение значений свойства
    6. sVariable — переменная
    7. sAlarm — тревоги и аварии
    8. sRole — роль переменной в группе
    9. sFunctionalGroup — функциональная группы
    10. sConfigDevice — конфигурация устройства
    11. sOpenDataResponse — информация о сессии
    12. sStatus — передача статуса
    13. sDataChange — передача устройству информации об опросе переменных, записи переменных и продолжении сессии обмена
  3. Функции OPC UA сервера
    1. Открытие сессии работы с устройством для обмена текущими данными
    2. Чтение конфигурации устройства
    3. Функции обмена данными
  1. Общее описание
    1. Назначение
      1. Алгоритм и протокол предназначен для создания  диспетчерских пунктов, собирающих текущие и архивные данные и передающих команды на распределенные объекты. Протокол оптимизирован для работы с устройствами, периодически выходящими на связь.
    2. Блок схема информационного взаимодействия
      1. На сервере OPC UA запускается серверная часть компонентов JSON-RPC,  клиентская часть запускается  на стороне контроллера. В качестве транспортного протокола используется TCP IP.
        JSON_packet_transfer_scheme
      2. Обмен ведётся кадрами следующего формата:
        json_frameгде:

        • «Заголовок пакета»  — 32 битное беззнаковое число, которое включает в себя 31 бит, указывающий размер  данных (0-30 биты) и 1 бит указывающий, признак сжатия пакета (31 бит).
        • «Данные JSON формата» – данные в формате JSON.

    Канальный уровень (протокол TCP IP) сжимается с помощью алгоритма DEFLATE, например, с использованием библиотеки zlib.

  2. Описание структур данных, используемых при передаче данных
    1. Передача данных при изменении значений или аварии
      sDataValue
         {
         ID;       // Идентификатор переменной
         Value;    // Значение переменной произвольного типа
         Status;   // Код статуса OPC UA
         DateTime; // Метка времени
         }

      где:

      • «ID» – уникальный, в пределах одного контроллера, идентификатор целочисленного типа. Идентификаторы переменных и тревог составляют одно множество.
      • «Value» – значения, которые передаются в строковом формате в инвариантной культуре;
      • «Status» — значения кода переменной: Bad = 2147483648; Good = 0.
    2. Передача данных для записи
      sWriteValue
         {
         ID; 	   // Идентификатор переменной
         Value;  // Значение
         }
    3. Передача данных результатов операции записи
      sWriteValueResponse
         {
         ID;     // Идентификатор переменной
         Status; // Код статуса OPC UA
         }
    4. Структура для описания свойств устройства
      sPropertyDescription
         {
         ID; 	  //Идентификатор свойства
         Name;  //Наименование свойства
         Value; //Статическое значение, неизменяемое для данной конфигурации (например: Версия прошивки, Модель контроллера и т.д.)
         }

      Ниже приведён неизменный перечень свойств и идентификаторов. Идентификаторы свойств формируют множество, отличное от множества переменных и тревог. Для различных устройств, перечень свойств может быть дополнен.

      «ID» «Название свойства»
      0 Производитель
      1 Код продукта
      2 Версия
      3 Гиперссылка
      4 Название продукта
      5 Название модели
      6 Пользовательское наименование
      7 Серийный номер устройства
      8 Режим работы
      9 Версия конфигурации
    5. Структура для получения значений свойства
      sPropertyValue
         {
         ID;    // Идентификатор свойства
         Value; // Значение
         }
    6. Структура описание переменной
      sVariable
         {
         Name; 	   //Название переменной
         ID; 		   //Идентификатор переменной
         AccessWrite;    //Флаг доступа на запись
         AccessRead 	   //Флаг доступа на чтение
         Archived        //Флаг ведения архива для переменной
         EngUnit;        //Инженерные единицы
         DataType        //тип данных 
         }

      где «DataType» может иметь следующие значения:

      • “BYTE”;
      • “UINT16”;
      • “UINT32”;
      • “INT16”;
      • “INT32”;
      • “BOOLEAN”;
      • “FLOAT”;
      • “DOUBLE”;
      • “DATETIME”
      • “STRING”.

      Флаги AccessWrite, AccessRead, Archived – определяют поведение сервера.
      Флаг Archived = true указывает серверу на необходимость архивирования данного параметра в базе данных сервера (исторические данные).
      Возможные комбинации флагов AccessRead и AccessWrite:

      • AccessRead = true, AccessWrite = false – переменная только на чтение;
      • AccessRead = true, AccessWrite = true – переменная доступна как на чтение, так и на запись;
      • AccessRead = false, AccessWrite = true – значение переменной «не видно», но она доступна для записи;
      • AccessRead = false, AccessWrite = false – конфигурация не имеет смысла.
    7. Структура описания тревоги и аварии
      sAlarm
         {
         Name;		      //Название
         ID;			      //Идентификатор аварии
         AlarmMessage; 	      //Текст при активном состоянии тревоги
         Priority; 		      //Приоритет аварии
         }

      где «Priority» – целочисленное значение (в данной версии не поддерживается).

    8. Структура описания роли переменной в группе
      sRole
         {
         ID; 			//Идентификатор роли
         Role; 		//тип роли
         }

      Возможные текстовые значения поля Role:

      • «Value» — текущее значение;
      • «StartValue» — начальное значение;
      • «Conversion» — вес импульса;
      • «HiSet» — срабатывание нижней уставки;
      • «LoSet» — срабатывание верхней уставки;
      • «HiLimit» — значение верхней уставки;
      • «LoLimit» — значение нижней уставки;
      • «MinEU» — минимум шкалы;
      • «MaxEU» — максимум шкалы;
      • «Failure» — отказ канала;
      • «Inversion» — инверсия;
      • «Reliability» — достоверность данных;
      • «Longitude» — долгота;
      • «Latitude» — широта;
      • «Null» — роль не определена.
    9. Структура описания функциональной группы
      Функциональная группа – это логическая организация переменных контроллера. Например, в функциональную группу «Аналоговые каналы» могут входить следующие переменные — значение, максимум и минимум шкалы, нижняя и верхняя уставки и т.д.

      sFunctionalGroup
         {
         Name; 			     //Название группы
         sFunctionalGroups[];	             //Вложенные функциональные группы
         sRole[];			     //Список переменных в группе с их ролями
         }
    10. Структура описывающая конфигурацию устройства
      sConfigDevice
         {
         sVariable[]; 	      //список всех переменных
         sAlarm[];		      //список всех тревог
         PropertyDescr[];	      //статический список всех свойств устройства
         sFunctionalGroup;	      //корневая группа устройства
         isPacked; 		      //поддержка устройством сжатия данных
         }
    11. Структура информации о сессии
      sOpenDataResponse
         {
         SessionID; 		//Идентификатор сессии
         isRequiredUpdate; 	//Флаг необходимости обновления конфигурации
         DataWriteValue;	//Массив структур, содержащих значения для записи, при отсутствии массива - null
         ReadIDs[] 		//Массив идентификаторов переменных на чтение
         }
    12. Структура передачи статуса
      sStatus
         {
         Messages []         //Массив строковых сообщений
         AlarmLevel          //Текущий статус тревоги на контроллере, который может принимать следующие значения:
                             //Good, Warning, Alarm, Error, CriticalError
         }
    13. Структура передачи устройству информации об опросе переменных, записи переменных и продолжении сессии обмена
      sDataChange
         {
         WriteValue [];    //Массив структур, содержащих значения для записи, при отсутствии массива -  null
         ReadIDs[]         //Массив идентификаторов переменных на чтение.
                           //Если массив ReadIDs пуст, то сервер применяет идентификаторы из предыдущего запроса
         isSessionContinue //Флаг продолжения сессии
         }
  3. Функции OPC UA сервера
    1. Открытие сессии работы с устройством для обмена текущими данными
      sOpenDataResponse  OpenData (SN, ConfigID, sStatus, sDataValue[ ])

      Входящие параметры:

      • «SN» — серийный номер устройства (длина серийного номера — не менее 36 символов);
      • «ConfigID» — версия конфигурации клиента;
      • «sStatus» — текущий статус устройства;
      • «sDataValue[ ]» — массив значений, содержащих информацию о текущих состояниях всех переменных и аварий (при наличии).

      При возникновении аварии, данные передаются серверу независимо от присутствия идентификатора данной аварии в массиве ReadIDs[] структуры sOpenDataResponse. Информация передается в хронологическом порядке изменения аварии.

      Например, если авария имеет идентификатор 5, авария возникла 2014-09-1 00:00:1, а сброс аварии произошел в 2014-09-1 00:00:30, то будет передан массив:

      {true, 2014-09-1 00:00:1 ,Good} {false, 2014-09-1 00:00:30,Good}

      Возвращаемое значение:

      «sOpenDataResponse» – структура данных, см. п. 2.11.

      Если в структуре sOpenDataResponse массив ReadIDs[] пуст, то сессия закрывается.

    2. Чтение конфигурации устройства
      SetMetaData(SessionID, sConfigDevice)

      Входящие параметры:

      • «SessionID» — идентификатор сессии.

      Пример конфигурации устройства:

      "sConfigDevice":
      {"sVariable":[
      		{"Name":"TypeBool","ID":1,"AccessWrite":true,"AccessRead":true,"EngUnit":"kwt","Archived":true,"DataType":"BOOLEAN"},				{"Name":"VarType.Int","ID":2,"AccessWrite":true,"AccessRead":true,"EngUnit":"","Archived":true,"DataType":"UINT32"},				{"Name":"VarType.UShort","ID":3,"AccessWrite":true,"AccessRead":true,"EngUnit":null,"Archived":true,"DataType":"UINT16"},				{"Name":"VarTypeFloat","ID":4,"AccessWrite":true,"AccessRead":true,"EngUnit":"kwt","Archived":true,"DataType":"FLOAT"},				{"Name":"VarType.Double","ID":5,"AccessWrite":true,"AccessRead":true,"EngUnit":"kwt","Archived":true,"DataType":"DOUBLE"},				{"Name":"Alarm1","ID":6,"AccessWrite":false,"AccessRead":true,"EngUnit":"celsiiii","Archived":false,"DataType":"BOOLEAN"}],
      	"sAlarm":[
      		{"Name":"авария 1","ID":6,"OnAlarmText":"2:Дверь закрылась","Priority":0},		
      		{"Name":"авария 2","ID":7,"OnAlarmText":"2:Упало бревно","Priority":0}],
      	"PropertyDescr":[
      		{"Id":0,"Name":"Производитель","Value":"val-0"},
      		{"Id":1,"Name":"Код продукта","Value":"val-1"},
      		{"Id":2,"Name":"Версия","Value":"val-2"},
      		{"Id":3,"Name":"Гиперссылка","Value":"val-3"},
      		{"Id":4,"Name":"Название продукта","Value":"val-4"},
      		{"Id":5,"Name":"Название модели","Value":"val-5"},
      		{"Id":6,"Name":"Пользовательское наименование","Value":"val-6"},
      		{"Id":8,"Name":"Режим работы","Value":"val-8"}],
      	"sFunctionalGroup":	
      		{
      			"Name":"Тестовое устройство",
      			"sFunctionalGroups":
      			[
      			  {
      				"Name":"Давление",
      				"sFunctionalGroups":[
      				{
      					"Name":"Давление",
      					"sFunctionalGroups":null,
      					"sRole":[
      						{"ID":1,"Role":"MinEU"},
      						{"ID":2,"Role":"LoLimit"}
      						]
      				}
      				"sRole":null
      			 },
      			 {
      				"Name":"Group2",
      				"sFunctionalGroups":null,
      				"sRole":[
      					{"ID":3,"Role":"Value"},
      					{"ID":4,"Role":"Value1"},
      					{"ID":5,"Role":"MaxEU"},
      					{"ID":6,"Role":"LoLimit"}
      				              ]
      			 }
      		                   ],
                                                                "sRole":null
                                                               },
                      "isPacked":true
      }
    3. Функции обмена данными
      sDataChange  DataChange(SessionID, sStatus, sWriteValueResponse, sDataValue[ ])

      Входящие параметры:

      • «SessionID» — идентификатор сессии;
      • «sStatus» — статус устройства, который поменялся в рамках текущей сессии, если изменений не было — null;
      • «sWriteValueResponse» — структура для информирования сервера о результатах записи;
      • «sDataValue»- массив значений, содержащих информацию о текущих состояниях переменных из списка опрашиваемых (список задаётся предыдущим ответом DataChange или OpenData ) и аварий (при наличии). Для оптимизации трафика переменные, у которых не изменилось состояние в рамках данной сессии, не передаются.

      При возникновении аварии, информация передаётся серверу независимо от присутствия идентификатора в массиве ReadIDs[] структуры sDataChange. Данные передаются в хронологическом порядке изменений по аварии.

      Например, если у аварии идентификатор 5 и авария возникла . 2014-09-1 00:00:1 и сбросилась в 2014-09-1 00:00:30 то будет передан массив

      { true, 2014-09-1 00:00:1 ,Good} { false, 2014-09-1 00:00:30,Good}

      Возвращаемое значение: «sDataChange»

      Если в структуре sOpenDataResponse массив ReadIDs[] пуст, то сессия закрывается.