Импорт данных по протоколу R1Sensor

Дата изменения документации

09.08.2017 года.

Общие сведения о протоколе

Протокол основан на запросах/ответах передаваемых в формате JSON .

On-line парсер формата JSON.

Для коммуникации между весовым комплексом и управляющим компьютером используется протокол TCP/IP.

На весовом комплексе запущена серверная часть, прослушивающая порт 27706. Данный порт можно поменять через настройки весового комплекса.

Весы допускают множественные одновременные подсоединение к прослушиваемому порту.

!	запрещается одновременно обновлять базу товаров в параллельных сессиях.

Допускается параллельное выполнение таких операций как копирование файлов или копирование файлов и обновление базы товаров.

Алгоритм взаимодействия:

При подсоединении к весам, они выдают пакет соединения.

В ответ на этот пакет в течении 30 секунд необходимо передать пакет установки связи. В случае истечения таймаута весы закрывают соединение.

В дальнейшей работе весам необходимо раз в 30 секунд передавать любую команду (например: тест связи).

Если этого не происходит весы разрываются соединение (данная возможность отключается через настройки весов).

На каждый запрос или команду весовой комплекс выдает подтверждающий пакет, либо пакет с запрошенными данными.

Запросы к весовому комплексу:

Запрос обязательно должен содержать следующие поля: "id" - идентификатор запроса. Можно использовать для проверки, что ответ идет на ту команду, на которую посылался запрос. "command" - выполняемый запрос или команда. объект "data" - в данном объекте передаются дополнительные данные, необходимые для выполнения запроса или команды. Так же в этом поле содержится информация о ПО которое сформировало запрос.

Ответы от весового комплекса:

Ответ обязательно содержать следующие поля: "id" - идентификатор запроса. "response" - текстовое описание ответа весов (результат выполнения команды или запроса). "response-code" - цифровое код ответа весов (результат выполнения команды или запроса) объект "data" - в данном объекте передаются дополнительные данные, являющиеся результатом выполнения команды. Так же в этом поле содержится информация о ПО весов.

Объект "data": 

В объекте "data" передаются дополнительные данные, необходимые для выполнения или являющиееся результатом выполнения команд. Постоянно в объекте дата присутствуют поля "application" "version" "compile-date", в которых содержится информация о ПО, которое их сформировало. Данная информация используется в информационных целях. Так же в случае возникновения ошибки присутсвует поле "response-ext", в котором содержится расширенное описание ошибки.

Порядок следования полей и объектов в пакетах JSON не важен.

Все двоичные данные пересылаются в кодировке BASE64.

В некоторых командах, пересылающих большие объемы данных, данные предварительно могут быть запакованы архиватором GZip (см. описание команд).

Данная возможность отключается через настройки весового комплекса или в флагом "use-compress" объекте "data".

Кодировка русских символов: UTF-8

Примеры запросов/команд

Пример запроса (команда установки связи):

{
  "id" : 1,
  "command" : "Link",
  "data" : {
    "application" : "R1 protocol tester",
    "version" : "1.0.0.0",
    "compile-date" : "26-08-2015"
  }
}

Пример ответа (команда выполнена):

{
  "id" : 1,
  "response" : "Ok",
  "response-code" : 0,
  "data" : {
    "application" : "R1 Self Service Soft.",
    "version" : "1.0.2.11",
    "compile-date" : "09-08-2017",
    "response-ext" : "Extended error description"
  }
}

Пакет соединения с сервером:

Сервер выдает при подсоединении к нему клиента.

В ответ на этот пакет в течении 30 секунд необходимо передать пакет установки связи.

В случае истечения таймаута весы закрывают соединение.

Пример:

{
  "id" : 1,
  "response" : "ConnectOk",
  "response-code" : 0,
  "data" : {
    "application" : "R1 Self Service Soft.",
    "version" : "1.0.0.0",
    "compile-date" : "01-01-2015"
  }
}

Запросы/команды

Установка связи

Передается от клиента серверу после соединения с последним.

Первая команда, необходимая для дальнейшей работы.

Запрос:

"command" : "Link"

Ответ:

"response" : "Ok"

"response-code" : 0

Пример:

{ "id" : 1, "command" : "Link", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "application" : "R1 Self Service Soft.", "version" : "1.0.2.11", "compile-date" : "09-08-2017" } }

Проверка связи

Эта команда ничего не выполняет.

Используется либо для проверки связи, либо для поддержания связи - не реже чем раз в 30 секунд.

Запрос:

"command" : "TestLink"

Ответ:

"response" : "Ok"

"response-code" : 0

Пример:

{ "id" : 1, "command" : "TestLink", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "application" : "R1 Self Service Soft.", "version" : "1.0.2.11", "compile-date" : "09-08-2017" } }

Получение и установка даты и времени на весах

При запросе в объекте "data" возвращаются дата/время с весов.

При установке в объекте "data" передаются дата/время с весов.

Запрос:

"command" : "GetDateTime"

"command" : "SetDateTime"

Ответ:

"response" : "Ok"

"response-code" : 0

"data" : { "date" : "21-08-2015", "time" : "12:00:00" }

Пример:

{ "id" : 1, "command" : "GetDateTime", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "date" : "21-08-2015", "time" : "12:00:00", "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }

{ "id" : 1, "command" : "SetDateTime", "data" : { "date" : "21-08-2015", "time" : "12:00:00", "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "application" : "R1 Self Service Soft.", "version" : "1.0.2.11", "compile-date" : "09-08-2017" } }

Начало и окончание загрузки товаров и групп

Команда "BeginUpdate" подается перед загрузкой товаров и/или групп внутренний буфер приема данных в этот момент очищается и весы готовы к приему данных, если команда подается повторно - данные, уже приняты на тот момент удаляются.

Команда "EndUpdate" подается после передачи всех данных. После передачи этой команды данные анализируются, сохраняются во внутреннюю базу весов и происходит обновление информации на экране.

Изначально включается режим обновления/добавления товаров и групп. Если после команды "BeginUpdate" передать команду "ClearGoodsAndGropus", то включается режим замены базы данных (перед обработкой загруженных данных база данных в весах очищается).

Запрос:

"command" : "BeginUpdate"

"command" : "EndUpdate"

Ответ:

"response" : "Ok"

"response-code" : 0

Пример:

{ "id" : 1, "command" : "BeginUpdate", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }

{ "id" : 1, "command" : "EndUpdate", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
{ "id" : 1, "response" : "Ok", "response-code" : 0, "data" : { "application" : "R1 Self Service Soft.", "version" : "1.0.2.11", "compile-date" : "09-08-2017" } }

Получение статуса весов

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

При запросе в объекте "data" данные статуса весов.

Запрос:

"command" : "GetState",

Ответ:

"response" : "Ok"

"response-code" : 0

Пример: { "id" : 1, "command" : "GetState", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }

"error-state" - флаг наличия ошибки на весах;

"error" - код ошибки;

"error-text" - текстовое описание ошибки;

"lock-state" - флаг ручной блокировки весов;

"packing-mode" - флаг включения режима фасовки;

"user-inactive-time" - время с последней активности весов (нажатия на тач-экран);

"licensed" - флаг состояния лицензии;

"database-type" - тип внутренней базы данных (0 - xml, 1 - sqlite);

"weight" - текущий вес;

"weight-tare" - текущая тара;

"weight-stability" - флаг стабильности веса;

"scale-model" - модель весов;

"scale-version" - версия весового модуля;

"scale-serial-number" - заводской номер;

"operation-system" - тип операционной системы;

"hostname" - имя хоста весов;

"user-name" - имя пользователя, под которым запущено ПО весов;

"current-time-date" - текущее время и дата;

"disks" - перечень дисков (актуально для Windows версии);

"free-system-disk" - свободного места на системном диске;

"free-work-disk" - свободного места на рабочем диске;

"free-memory" - свободно оперативной памяти;

"screen-resolution" - разрешение экрана;

"system-up-time" - время со старта системы;

Запуск ротации логов программы и архивов, создаваемых программой

Данная команда позволяет получить в ручную запустить процесс ротации лог-файлов программы и архивов (базы данных, обработанных и ошибочных файлов импорта).

Запрос:

"command" : "RotateLog",

Ответ:

"response" : "Ok"

"response-code" : 0

Пример:

{ "id" : 1, "command" : "RotateLog", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }

Получение текущего протокола работы весов

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

Данные могут быть предварительно запакованы архиватором GZip (отключается в настройках весов). Так же флаг использования компрессии можно предать в объекте "data": "use-compress" : 1 или 0. Далее данные кодируются в BASE-64. В объекте "data" возвращаются данные лог файла "log-file-data" и размер файла "log-file-size".

Запрос:

"command" : "GetLog"

Ответ:

"response" : "Ok"

"response-code" : 0

"data" : { "log-file-size" : "120000", "log-file-data" : "данные-лог-файла" }

Блокировка и разблокировка работы весов

Данная команда позволяет выполнить удаленную блокировку "LockScale" и разблокировку "UnlockScale" работы весов, например в случае поломок принтера.

В объекте "data" передается пароль "password" на проводимую операцию (изменяется в настройках весов).

Запрос:

"command" : "LockScale"

"command" : "UnlockScale"

"data" : { "password" : "239" }

Ответ:

"response" : "Ok"

"response-code" : 0

Обнуление веса и тарирование весов

Данная команда позволяет удаленно выполнить обнуление веса "ZeroWeight" или произвести тарирование "TareWeight" весов.

В объекте "data" передается пароль "password" на проводимую операцию (изменяется в настройках весов).

Запрос:

"command" : "ZeroWeight"

"command" : "TareWeight"

"data" : { "password" : "239" }

Ответ:

"response" : "Ok"

"response-code" : 0

Перезагрузка и выключение весов

Данная команда позволяет удаленно выполнить перезагрузку "Reboot" или произвести выключение "Shutdown" весов.

В объекте "data" передается пароль "password" проводимую операцию (изменяется в настройках весов).

Стандартный пароль для перезагрузки и выключения: 255

Запрос:

"command" : "Reboot",
"command" : "Shutdown",
"data" : { "password" : "255" }

Ответ:

"response" : "Ok",
"response-code" : 0

Получение информации о файле, картинке, шаблоне этикетки или других файла в каталоге программы на весах, удаление и добавление файлов

Данная команда позволяет получить информацию о файле. Начальным путем для поиска файлов является каталог программы.

Для получение информации о файле, находящимся в подкаталогах, необходимо в имя файла включить путь до необходимого файла.

Вне каталога программы можно получить доступ только к каталогу "Exchange", в котором содержится протокол работы, данные для импорта, отчеты и т.д.

Например: для получения информации о картинке имя файла должно быть таким "file-name" : "./Data/Images/goods.no.picture.png".

В объекте "data" передается имя необходимого файла "file-name", а возвращается информация о файле: "file-name", "file-size" - размер файла в байтах, "file-date" - дата/время последнего изменения файла, "file-md5" - контрольная сумма файла расчитанная по алгоритму MD5.

При добавлении файла в объекте "data" в поле "file-data" передаются данные файла, а в поле "file-md5" - контрольная сумма файла расчитанная по алгоритму MD5.

Данные могут быть предварительно запакованы архиватором GZip (отключается в настройках весов). Так же флаг использования компрессии можно предать в объекте "data": "use-compress" : 1 или 0.

Далее данные кодируются в BASE-64.

Стандартные пути к файлам:

./Data/Images/ - картинки, используемые программой

./Data/Labels/ - шаблоны этикеток

./Data/Media/ - звуки, используемые программой

./Data/Lic/ - лицензии для программы

./Settings/ - настройки программы и экранные формы

../Exchange/Flags/ - флаги создаваемые программой в результате событий на весах

../Exchange/Import/ - импортируемые данные

../Exchange/Log/ - протокол работы программы

../Exchange/Log/ProcessedFiles/ - протоколы обработки успешно импортированных данных

../Exchange/Log/BadFiles/ - протоколы обработки неуспешно импортированных данных

../Exchange/Reports/ - отчеты, создаваемые программой

Запрос:

"command" : "GetFileInfo"

"command" : "RemoveFile"

"command" : "AddFile"

"data" : { "file-name" : "./Data/Images/goods.no.picture.png" "file-data" : "данные-файла" "use-compress" : 1 }

Ответ:

"response" : "Ok"

"response-code" : 0

"data" : { "file-name" : "./Data/Images/goods.no.picture.png", "file-size" : "12332", "file-md5" : "e455d2b43b6157b50e8f502ac77aad13" }

Выполнение команды весами

Данная команда позволяет выполнить команды на весах.

Данная команда пока не реализована.

Запрос:

"command" : "ExecuteCommand"

Ответ:

"response" : "Ok"

"response-code" : 0

Очистка базы товаров и групп

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

Данная команда должна быть передана после команды "BeginUpdate".

Если данная команда не передается, то включается режим обновления/добавления товаров.

Очистка данных производится только если добавляется хотя бы один товар.

Запрос:

"command" : "ClearGoodsAndGroups"

Ответ:

"response" : "Ok"

"response-code" : 0

Добавление товаров, обновление или удаление товаров и групп товаров

Данные команды служат для изменение базы товаров в весах.

Перед использование данных команд, необходимо передать на весы команду "BeginUpdate", а по окончании работы с товарами передается команда "EndUpdate". При необходимости очистки базы товаров на весах, между передачами команд "BeginUpdate/EndUpdate", так же необходимо передать команду "ClearGoodsAndGroups".

При использовании команд обновления ("UpdateGoods" и "UpdateGroups"), если товара или группы нет в базе весов - товар или группа создаются и сообщение об ошибке не передается.

Разница между командами "UpdateХХХ" и "AddXXX" заключается в минимальном наборе параметров, которые необходимо передаются на весы, что бы не возникло ошибки при приеме команды. Так для для команды "AddGoods" необходимо передать: номер товара, название товар, группу-владелец и цену. Для команды "UpdateGoods": только номер товара.

Если при использовании команд удаления ("RemoveGoods" и "RemoveGroups") товар или группа не найден - передается ошибка "товар не найден".

В объекте "data" передаются все необходимые параметры товара или группы.

Команды "Remove..." обрабатываются в последнюю очередь. Т.е. сначала производится очистка базы дынных, далее производится добавление товаров/групп и потом удаление товаров/групп.

Поля данных товара:

"goods-no" - номер товара. Номер должен быть уникален. Поиск товара при добавлении/обновлении ведется по этому полю.

"goods-add-code" - дополнительный номер товар. Может использоваться при формировании штрих-кода товара.

"goods-display-number" - дополнительный номер товара. Данный номер можно вывести на кнопку товара. По данному номеру возможно сортировать товары внутри группы.

"goods-name" - название товара для печати на этикетке.

"goods-full-name" - название товара для вывода на кнопку товара. Если данное поле не задано, значение берется из поля "goods-name".

"goods-price" - цена товара. Можно передавать как строку: "123.55", можно как число: 123.55

"goods-dep" - отдел товара. Используется при формировании штрих-кода товара.

"goods-barcode-type" - тип структуры штрих-кода товара.

"goods-action" - признак акционности товара.

"goods-is-popular" - признак популярности товара.

"goods-ice-percent" - процент "ледяной глазури" в весе товара.

"goods-label" - номер шаблона этикетки.

"goods-label2" - номер шаблона 2-го этикетки.

"goods-discount-label" - номер шаблона этикетки для печати скидочных товаров.

"goods-discount-price" - цена со скидкой.

"goods-discount-type" - тип скидки (0 - нет скидки).

"goods-owner-group" - группа-владелец товара.

"goods-picture-bytes" - картинка товара (массив байт).

"goods-picture-filename" - имя файла картинки товара.

"goods-second-picture-filename" - имя файла дополнительной картинки товара.

"goods-produced-date" - дата производства.

"goods-shelf-life" - срок годности.

"goods-weight-unit" - весовая еденица товара.

"goods-tare" - вес тары товара.

"goods-message-x" - текстовые сообщения для печати на этикетке.

Для успешного добавления товара необходимо передать как минимум следующие поля:

"goods-no", "goods-name", "goods-price",

Формат даты производства: "dd.MM.yyyy hh:mm"

В поле "goods-picture-filename" и "goods-second-picture-filename" передается имя файла картинки для товара или группы. Указанный файл должен присутсвовать в каталоге "./Data/Pictures/". Можно располагать файлы в подкаталогах.

Данные могут быть предварительно запакованы архиватором GZip (отключается в настройках весов). Так же флаг использования компрессии можно предать в объекте "data": "use-compress" : 1 или 0.

Далее данные кодируются в BASE-64.

Срок годности товара имеет следующие значение:

0 - срок годности не задан

-х - срок годности указан часах

х - срок годности указан в днях

Поля "goods-message-x" служат для передачи дополнительной текстовой информации, печатаемой на этикетке.

Перечень соответсвия сообщений и элементов шаблона этикетки:

"goods-message-1" - текстовое сообшение

"goods-message-2" - ингридиенты

"goods-message-3" - страна происхождения

"goods-message-4" - реклама

Поля данных группы:

"group-no" - номер группы.

"group-name" - название группы.

"group-picture-filename" - имя файла картинки группы.

"group-picture-bytes" - картинка товара (массив байт).

"group-owner-group" - номер группы-владельца.

Для успешного добавления группы необходимо передать как минимум следующие поля:

"group-no", "group-name"

Запрос:

"command" : "AddGoods"

"command" : "UpdateGoods"

"command" : "RemoveGoods"

"command" : "AddGroups"

"command" : "UpdateGroups"

"command" : "RemoveGroups"

Ответ:

"response" : "Ok"

"response-code" : 0

Добавление или связывание шаблонов этикеток

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

При установке связи между именем файла шаблона этикетки, необходимо предварительно загрузить файл на весы в каталог ./Data/Labels

Если файл отсутвует - связь не будет установлена.

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

Перед использование данной команды, необходимо передать на весы команду "BeginUpdate", а по окончании работы с товарами передается команда "EndUpdate". Можно использовать эти команду в едином цикле с обновление информации о товарах.

Данные шаблонов, если передаются прямо в команде, могут быть предварительно запакованы архиватором GZip (отключается в настройках весов).

Так же флаг использования компрессии можно предать в объекте "data": "use-compress" : 1 или 0.

Далее данные кодируются в BASE-64.

Запрос:

"command" : "AddLabel"

Ответ:

"response" : "Ok"

"response-code" : 0

Поля данных этикетки:

"label-no" - номер шаблона этикетки.

"label-filename-format" - имя файла c форматом шаблона этикетки. Файл должен находится в каталоге ./Data/Labels

"label-filename-map" - имя файла с задним фоном шаблона этикетки. Файл должен находится в каталоге ./Data/Labels

"label-format-bytes" - данные формата шаблона этикетки (массив байт).

"label-map-bytes" - данные заднего фона шаблона этикетки (массив байт).

"label-filename" - номер группы-владельца. Только для использования с весами LS215.

"label-bytes" - данные шаблона этикетки (массив байт). Только для использования с весами LS215.

"use-compress" - флаг использования компрессии данных

Изменение номера и названия магазина

Данная команда служат для передачи на весы данных о номере и названии магазина.

Возможна передача до 4-х строк названия магазина.

Перед использование данной команды, необходимо передать на весы команду "BeginUpdate", а по окончании работы передается команда "EndUpdate". Можно использовать эти команду в едином цикле с обновление информации о товарах.

Запрос:

"command" : "AddStoreParams"

Ответ:

"response" : "Ok"

"response-code" : 0

Поля данных этикетки:

"store-no" - номер магазина.

"store-name-1 - название магазина строка 1

"store-name-2 - название магазина строка 2

"store-name-3 - название магазина строка 3

"store-name-4 - название магазина строка 4

Перечень ошибок

При возникновении ошибок в ответе содержится текстовый ответ и код, сообщающие о возникшей ошибке.

Так же в объект "data" добавляется поле с расширенным описание ошибки "response-ext".

При работе с весами возможны следующие ошибки:

Ошибок нет, команда выполнена успешно:

"response" : "Ok"

"response-code" : 0

"data"

Истек таймаут соединения при установке связи или во время работы:

"response" : "Abort"

"response-code" : -1

Ошибка данных команды или некорректные данные:

"response" : "Error"

"response-code" : -2

Ошибка выполнения команды (например: при установке даты/времени):

"response" : "ExecError"

"response-code" : -3