Робот
Устройство и подключение робота
Управляющее программное обеспечение
Описание поведения на языке BML
API
Использование системы диалога DialogFlow
Локализация роботом лица пользователя
Когнитивный компонент
Как устроена обработка текста?
Синтаксический парсер
Обработка массива текстов
База данных результатов разбора

API

Создание новых модулей для управления роботом – это способ разнообразить поведение робота, а также возможность адаптировать робота под свои проекты и задачи. В этой статье описаны функции API, упрощающие разработку модулей для робота, также на странице приведены примеры использования этих методов. Пользоваться API можно напрямую или с помощью библиотеки communication для языка python.

Взаимодействие через сокет

API робота для обмена данными между роботом и управляющими модулями использует сокеты. При работе в локальной сети в качестве сетевого адреса используется стандартный локальный хост: 127.0.0.1. Номера портов: слушающего, предназначенного для получения сообщений от модулей, и посылающего – для отправки сообщений о статусе выполнения пакетов – доступны в настройках управляющей роботом программы.

Функции

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

add

Функция add позволяет отправить роботу в очередь на исполнение сценарий. Соответствует методу add библиотеки communication. Для того, чтобы послать сценарий, необходимо сформировать строку вида:

(add, <сценарий>);;

Где <сценарий> – это строковое представление XML-описания сценария:

<scenario name="ВЕСЕЛЬЕ" weight="500">
  <bml id="1">
    <figure id="1" lexeme="happy1"/>
  </bml>
  <bml id="2">
    <head id="1" lexeme="appeal1"/>
    <speech id="2">Hello!</speech>
  </bml>
</scenario>

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

Пример использования функции add на языке python:

from socket import *

scenario = '<scenario name="ВЕСЕЛЬЕ" weight="500"> <bml id="1"> <figure id="1" lexeme="happy1"/> </bml> <bml id="2"> <head id="1" lexeme="appeal1"/> <speech id="2">Hello!</speech> </bml> </scenario>'

sock = socket(AF_INET, SOCK_STREAM)
sock.connect(('127.0.0.1', 6061))

bytemsg = ("(add,{0});;".format(scenario).encode('utf-8')
sock.send(bytemsg)
sock.close()
remove

Функцией remove из очереди можно удалить сценарий целиком, отдельный BML-пакет из сценария или множество BML-пакетов.

Удаление одного сценария соответствует методу remove библиотеки communication. Для того, чтобы удалить сценарий, необходимо сформировать строку вида:

(remove, <имя сценария>);;

Пример удаления сценария на языке python:

from socket import *

sock = socket(AF_INET, SOCK_STREAM)
sock.connect(('127.0.0.1', 6061))

scenario_name = 'ВЕСЕЛЬЕ'

bytemsg = ("(remove,{0});;".format(scenario_name)).encode('utf-8')

sock.send(bytemsg)
sock.close()

Удаление одного BML-пакета соответствует методу removebml библиотеки communication. Для того, чтобы удалить конкретный BML-пакет, в строку нужно также добавить идентификатор этого пакета:

(remove, <имя сценария>, <идентификатор пакета BML>);;

Также возможно удаление множества BML-пакетов внутри одного сценария. Это соответствует методу removemany библиотеки communication. Для этого нужно сформировать строку:

(remove, <имя сценария>, [<список идентификаторов пакетов BML>]);;

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

Пример удаления пакета BML из сценария на языке python:

from socket import *

sock = socket(AF_INET, SOCK_STREAM)
sock.connect(('127.0.0.1', 6061))

scenario_name = 'ВЕСЕЛЬЕ'
bml_id = '2'

bytemsg = ("(remove,{0},{1});;".format(scenario_name, bml_id)).encode('utf-8')

sock.send(bytemsg)
sock.close()

Обратная связь

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

Сообщение о состоянии тега из пакета BML

Пакет BML состоит из тегов, при выполнении пакета робот посылает в модули сообщения о выполнении каждого тега каждого пакета. Такие сообщения содержат информацию о том, на каком этапе обработки находится тег.

Сообщение приходит в байтовом виде, его нужно преобразовать в строку в кодировке utf-8. Полученная строка имеет вид:

(<время>,<сценарий>,<bml>,<тег>,<название тега>,<статус>,meta=(<список метаданных>))

Где

Параметр Описание
<время> время получения статуса
<сценарий> идентификатор сценария
<bml> идентификатор пакета BML
<тег> идентификатор тега
<название тега> название тега (gaze, figure, speech, head и др.)
<статус> статус тега:
Running – тег запущен
Error – ошибка во время выполнения или подготовки тега
Complete – тег выполнен>
<список метаданных> список дополнительной информации о теге:
turn=True – робот совершил поворот глазами или головой (для определения, что робот отвернулся от точки/пользователя)
text=<выражение> – слова, которые произнес робот
stroke=<время в мс> – время от начала речи до ударной точки

Пример сообщения:

(19:15:37.192,GazeModel,7776886,3,pupils,Complete,meta=(turn=True))
Сообщение о состоянии пакета BML

После завершения выполнения пакета (планового или в связи с возникшей ошибкой) на модули приходит сообщение от управляющей программы.

Сообщение приходит в байтовом виде, его нужно преобразовать в строку в кодировке utf-8. Полученная строка имеет вид:

(<время>,<сценарий>,<bml>,<статус>)

Где

Параметр Описание
<время> время получения статуса
<сценарий> идентификатор сценария
идентификатор пакета BML
<статус> статус пакета
Error – ошибка при обработке пакета
Ended – обработка пакета завершена и он удален из очереди

Пример сообщения:

(19:22:28.508,GazeModel,8188466,Ended)

Взаимодействие через библиотеку communication

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

Библиотека содержит два класса: Sender и Listener. Класс Sender отвечает за отправку команд от модулей к управляющей программе, а класс Listener – за получение модулями сообщений от робота.

Скачать файл communication.py

Методы класса Sender

Класс Sender необходим для того, чтобы модуль отправлял роботу сообщения о добавлении или удалении сценариев и пакетов BML. Для этого он должен знать, куда эти данные отправлять, то есть номер слушающего порта на роботе. Этот номер нужно указать в парамете SENDPORT файла settings.ini:

[Settings]
SENDPORT = 6061
add

Метод add позволяет отправить роботу в очередь на исполнение сценарий. Соответствует функции add при взаимодействии через сокет.

Параметры:

  • сценарий – строковое представление XML-описания сценария:
<scenario name="ВЕСЕЛЬЕ" weight="500">
  <bml id="1">
    <figure id="1" lexeme="happy1"/>
  </bml>
  <bml id="2">
    <head id="1" lexeme="appeal1"/>
    <speech id="2">Hello!</speech>
  </bml>
</scenario>

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

from communication import Sender

scenario = '<scenario name="ВЕСЕЛЬЕ" weight="500"> <bml id="1"> <figure id="1" lexeme="happy1"/> </bml> <bml id="2"> <head id="1" lexeme="appeal1"/> <speech id="2">Hello!</speech> </bml> </scenario>'

with Sender() as sender:
    sender.add(scenario)

remove

Метод remove позволяет удалить сценарий из очереди. Соответствует одному из представления функции remove при взаимодействии через сокет.

Параметры:

  • имя сценария – строка. Имя сценария указано в xml-структуре сценария в теге scenario в аргументе name.

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

from communication import Sender

scenario_name = 'ВЕСЕЛЬЕ'

with Sender() as sender:
    sender.remove(scenario_name)

removebml

Метод removebml позволяет удалить конкретный BML-пакет конкретного сценария из очереди. Соответствует одному из представления функции remove при взаимодействии через сокет.

Параметры:

  • имя сценария – строка. Имя сценария указано в scenario в аргументе name;
  • идентификатор пакета BML – строка. Идентификатор пакета указан в xml-структуре сценария в теге bml в аргументе id.

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

from communication import Sender

scenario_name = 'ВЕСЕЛЬЕ'
bml_id = '2'

with Sender() as sender:
	sender.removebml(scenario_name, bml_id)

removemany

Метод removemany позволяет удалить несколько BML-пакетов одного сценария из очереди. Соответствует одному из представления функции remove при взаимодействии через сокет.

Параметры:

  • имя сценария – строка. Имя сценария указано в scenario в аргументе name;
  • список идентификаторов пакета BML – список. Идентификатор пакета указан в xml-структуре сценария в теге bml в аргументе id.

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

from communication import Sender

scenario_name = 'ВЕСЕЛЬЕ'
bml_ids = ['2', '1']

with Sender() as sender:
	sender.removemany(scenario_name, bml_ids)

Методы класса Listener

Класс Listener отвечает за получение модулем сообщений от робота о статусе вполнения пакетов BML и тегов BML. Класс Listener создает сокет и начинает слушать порт, на который робот будет отправлять сообщения. Номер этого порта необходимо указать в настройках: в параметре LISTENPORT файла settings.ini:

[Settings]
LISTENPORT = 6060
listen

Начало прослушки заданного в настройках порта. Метод без параметров.

receive

Получение сообщений от робота. Сообщения приходят в виде строк, внутри строки сообщения разделяются символами ;;. Метод без параметров.

Существует два вида сообщений от робота:

  • Сообщение о состоянии тега из пакета BML, формат сообщений описан выше.
  • Сообщение о состоянии пакета BML, формат описан выше.



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

Подробнее про DialogFlow