note: last time updated with some minor changes 15 /04 /09
I have updated the interface to the Oracle and added some additional events that are send to the Oracle. Here is a description of the communication protocol used for later reference.
Basics- messages are sent individually
- messages are encoded in UTF-8
- message components are separated by single whitespaces
- every message is terminated with a null byte (\0)
Message Format (Input message)there are 2 types of messages input and event messages. An input message is always sent when the user uses one of the input devices. Input messages always have the following format:
USER inputActionName inputActionParameterwhere inputActionName is a placeHolder for the identifier of the type of inputAction and inputActionParameter stores the value. Refer to the list of possible input actions later in this post.
Message Format (Event actions)An event message is always sent when an action ends in the world. This action could be caused by the user or any character. The format for event messages is the following:
ORIENT subject action target parameter1 parameter2 parameter3 ...where subject is user or the name of the agent causing the action, action the name of the action, target the target of the action if there is any. Like the target all the parameters are optional, i.e. there dont have to be any and there can be many depending on the action. Further on in this post I list all actions plus the parameters they have. An exception to the message format are speech acts, those have an additional identifier for the meaning (the type of speech act). The speech act format looks like this:
ORIENT subject say-to meaning target parameter1 parameter2 parameter3Speech acts are identified through their action name, which is always "say-to". Speech acts also always have a target. They can have parameters or not, depending on the type/meaning. Also it is worth noting that the user cannot speak, the subject will never be "user" for a "say-to" action
Possible Input Actions and their parametersThe following input events are transmitted:
- action: "UserGestureAction" , means the system has recognized a Wii gesture performed by the user, possible parameter values are: "GreetBack", "EatDrink", "UserPick", "Accept", "Reject", "GiveAttentionFollow", "Ask", "Apologise" or "Give"
- action: "UserNavigationAction", means the user has stepped on a dancemat button, possible parameter values are: "F", "FR", "R", "BR", "B", "BL", "L", "FL" for the direction buttons (forward, left, right back and the 4 diagonals) or "START" for the start button or "SELECT" for the select button
- action: "UserItemSelectionAction" means the system has recognized an item scanned by RFID, parameter value can be any item category or topic, for the current scenarios can take the values: "liquid", "seedpod", "soil", "greenDrink", "recycling", "meal", "gardening"
- action: "UserSpeechRecogAction" means the system has recognized user speech / magic word, parameter value for the current training data is any character name: "Abbuk", "Ardoot", "Cerkith", "Errep", "Evui", "Ikop" or "Tigrit"
- action: "UserWiiButtonAction" means the user has pressed a button on the Wii, at the moment only button A is used to execute user commands, but possible parameter values are: "A", "B", "-", "+", "1", "2", "Home", "Up", "Left", "Right", "Down"
- action: "UserMobilePhoneButtonAction" means the user has pressed the start or back button on the phone, we need this because speech recognition or RFID might take some time and in the mean time we might want to react to the button press event to assure the user that something is happening. possible parameter values are: "Start" and "Back"
Possible Character Actions:for a list of possible character actions and their parameters please refer to the actions defined in the file rundir/data/characters/minds/Actions.xml, actions the user can carry out are also listed in this file
for the special case of speech acts, all possible meanings are listed in the file rundir/data/characters/minds/language/agent/en/language-set-1/templates.tdl
Failed User Actions:if needed for certain rules we are going to implement user action failures. That means the user wanted to execute a certain action but couldn't. At the moment only few failed user action areimplemented but it is now very easy to add more. The actions implemented are:
USER fail-UserPick seedpod noItemHere // failed because there was no seedpod near the user
USER fail-UserPick noItemSelected // failed because there was no item selected
USER fail-Ask noItemSelected // failed because there was no item selected
USER fail-Accept noItemSelected // failed because there was no item selected
USER fail-EatDrink noItemSelected // failed because there was no item selected
USER fail-Reject noItemSelected // failed because there was no item selected
Note that one of the parameters will always be the reason for failure.
User Entering Scene:
As discussed with Rui and Paola on Skype, there will now also be an event sent, when a new episode starts. This event is an Orient event with the following syntax
ORIENT user EnterScene place
Concrete this means the following events are generated when starting the following episodes
ORIENT user EnterScene village - for episode the Meal
ORIENT user EnterScene glade - for episode the Recycling
ORIENT user EnterScene garden - for episode the Gardening
ORIENT user EnterScene beach - for the transition episode at the beach (walking form one scene to the other)