2541
правка
Изменения
Перейти к навигации
Перейти к поиску
Новая страница: «__TOC__ =Дата изменения документации= 09.08.2017 года. =Общие сведения о протоколе= Протокол…»
__TOC__
=Дата изменения документации=
09.08.2017 года.
=Общие сведения о протоколе=
Протокол основан на запросах/ответах передаваемых в формате JSON <ref>Описание стандарта JSON можно найти [http://www.json.org/ на сайте].</ref>.
[http://json.parser.online.fr/ 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
=Примеры запросов/команд=
Пример запроса (команда установки связи):
<source lang="json">
{
"id" : 1,
"command" : "Link",
"data" : {
"application" : "R1 protocol tester",
"version" : "1.0.0.0",
"compile-date" : "26-08-2015"
}
}
</source>
Пример ответа (команда выполнена):
<source lang="json">
{
"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"
}
}
</source>
Пакет соединения с сервером:
Сервер выдает при подсоединении к нему клиента.
В ответ на этот пакет в течении 30 секунд необходимо передать пакет установки связи.
В случае истечения таймаута весы закрывают соединение.
Пример:
<source lang="json">
{
"id" : 1,
"response" : "ConnectOk",
"response-code" : 0,
"data" : {
"application" : "R1 Self Service Soft.",
"version" : "1.0.0.0",
"compile-date" : "01-01-2015"
}
}
</source>
=Запросы/команды=
==Установка связи==
Передается от клиента серверу после соединения с последним.
Первая команда, необходимая для дальнейшей работы.
Запрос:
"command" : "Link"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Проверка связи==
Эта команда ничего не выполняет.
Используется либо для проверки связи, либо для поддержания связи - не реже чем раз в 30 секунд.
Запрос:
"command" : "TestLink"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Получение и установка даты и времени на весах==
При запросе в объекте "data" возвращаются дата/время с весов.
При установке в объекте "data" передаются дата/время с весов.
Запрос:
"command" : "GetDateTime"
"command" : "SetDateTime"
Ответ:
"response" : "Ok"
"response-code" : 0
"data" : { "date" : "21-08-2015", "time" : "12:00:00" }
Пример:
<source lang="json">
{ "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" } }
</source>
==Начало и окончание загрузки товаров и групп==
Команда "BeginUpdate" подается перед загрузкой товаров и/или групп внутренний буфер приема данных в этот момент очищается и весы готовы к приему данных, если команда подается повторно - данные, уже приняты на тот момент удаляются.
Команда "EndUpdate" подается после передачи всех данных. После передачи этой команды данные анализируются, сохраняются во внутреннюю базу весов и происходит обновление информации на экране.
Изначально включается режим обновления/добавления товаров и групп. Если после команды "BeginUpdate" передать команду "ClearGoodsAndGropus", то включается режим замены базы данных (перед обработкой загруженных данных база данных в весах очищается).
Запрос:
"command" : "BeginUpdate"
"command" : "EndUpdate"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Получение статуса весов==
Данная команда позволяет получить текущее состояние весов: заблокированы или нет, текущий вес, состояние ошибки и др. информацию о весах.
При запросе в объекте "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
Пример:
<source lang="json">
{ "id" : 1, "command" : "RotateLog", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
</source>
==Получение текущего протокола работы весов==
Данная команда позволяет получить текущий файл протокола работы весов.
Данные могут быть предварительно запакованы архиватором 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" проводимую операцию (изменяется в настройках весов).
Запрос:
"command" : "Reboot"
"command" : "Shutdown"
"data" : { "password" : "239" }
Ответ:
"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-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-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" передается имя файла картинки для товара или группы. Указанный файл должен присутсвовать в каталоге "./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
=Техническая поддержка=
Для получения технической поддержки можно обращаться:
по телефону: +7 (812) 640-2965 доб. 331 или 332
в сети интернет: http://www.aclas.ru/
по электронной почте: e-support@aclas.ru
В случае обнаружения ошибок или недостатков, просьба сообщать о них техническим специалистам ЗАО "ЭТИМ".
=Дата изменения документации=
09.08.2017 года.
=Общие сведения о протоколе=
Протокол основан на запросах/ответах передаваемых в формате JSON <ref>Описание стандарта JSON можно найти [http://www.json.org/ на сайте].</ref>.
[http://json.parser.online.fr/ 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
=Примеры запросов/команд=
Пример запроса (команда установки связи):
<source lang="json">
{
"id" : 1,
"command" : "Link",
"data" : {
"application" : "R1 protocol tester",
"version" : "1.0.0.0",
"compile-date" : "26-08-2015"
}
}
</source>
Пример ответа (команда выполнена):
<source lang="json">
{
"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"
}
}
</source>
Пакет соединения с сервером:
Сервер выдает при подсоединении к нему клиента.
В ответ на этот пакет в течении 30 секунд необходимо передать пакет установки связи.
В случае истечения таймаута весы закрывают соединение.
Пример:
<source lang="json">
{
"id" : 1,
"response" : "ConnectOk",
"response-code" : 0,
"data" : {
"application" : "R1 Self Service Soft.",
"version" : "1.0.0.0",
"compile-date" : "01-01-2015"
}
}
</source>
=Запросы/команды=
==Установка связи==
Передается от клиента серверу после соединения с последним.
Первая команда, необходимая для дальнейшей работы.
Запрос:
"command" : "Link"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Проверка связи==
Эта команда ничего не выполняет.
Используется либо для проверки связи, либо для поддержания связи - не реже чем раз в 30 секунд.
Запрос:
"command" : "TestLink"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Получение и установка даты и времени на весах==
При запросе в объекте "data" возвращаются дата/время с весов.
При установке в объекте "data" передаются дата/время с весов.
Запрос:
"command" : "GetDateTime"
"command" : "SetDateTime"
Ответ:
"response" : "Ok"
"response-code" : 0
"data" : { "date" : "21-08-2015", "time" : "12:00:00" }
Пример:
<source lang="json">
{ "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" } }
</source>
==Начало и окончание загрузки товаров и групп==
Команда "BeginUpdate" подается перед загрузкой товаров и/или групп внутренний буфер приема данных в этот момент очищается и весы готовы к приему данных, если команда подается повторно - данные, уже приняты на тот момент удаляются.
Команда "EndUpdate" подается после передачи всех данных. После передачи этой команды данные анализируются, сохраняются во внутреннюю базу весов и происходит обновление информации на экране.
Изначально включается режим обновления/добавления товаров и групп. Если после команды "BeginUpdate" передать команду "ClearGoodsAndGropus", то включается режим замены базы данных (перед обработкой загруженных данных база данных в весах очищается).
Запрос:
"command" : "BeginUpdate"
"command" : "EndUpdate"
Ответ:
"response" : "Ok"
"response-code" : 0
Пример:
<source lang="json">
{ "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" } }
</source>
==Получение статуса весов==
Данная команда позволяет получить текущее состояние весов: заблокированы или нет, текущий вес, состояние ошибки и др. информацию о весах.
При запросе в объекте "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
Пример:
<source lang="json">
{ "id" : 1, "command" : "RotateLog", "data" : { "application" : "R1ScaleTester", "version" : "0.0.0.1", "compile-date" : "09-08-2017" } }
</source>
==Получение текущего протокола работы весов==
Данная команда позволяет получить текущий файл протокола работы весов.
Данные могут быть предварительно запакованы архиватором 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" проводимую операцию (изменяется в настройках весов).
Запрос:
"command" : "Reboot"
"command" : "Shutdown"
"data" : { "password" : "239" }
Ответ:
"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-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-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" передается имя файла картинки для товара или группы. Указанный файл должен присутсвовать в каталоге "./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
=Техническая поддержка=
Для получения технической поддержки можно обращаться:
по телефону: +7 (812) 640-2965 доб. 331 или 332
в сети интернет: http://www.aclas.ru/
по электронной почте: e-support@aclas.ru
В случае обнаружения ошибок или недостатков, просьба сообщать о них техническим специалистам ЗАО "ЭТИМ".
