SkypeComm

SkypeComm

---

1. Overview

The SkypeComm module enables remote interaction with the robot through a Skype session. It will read the commands sent to the robot through the Skype chat (either using a specific command syntax or trying to recognize the meaning of the message), perform certain actions and reply through the chat when necessary. It also provides a messaging service to all the other modules of OpenMORA.

2. Usage

2.1 Configuration file

The SkypeComm module reads its main configuration from the SkypeComm section of a mission file. The parameters read from this section are:
1. AppTick
2. CommsTick
3. SubscribeTo: comma separated list of the OpenMORA variables that SkypeComm can read and transmit to the remote user on demand.

The module also uses parts of pVoiceVerbio [TODO: link with the VoiceVerbio page when created]. Specifically it reads all the sentences that the VoiceVerbio module recognizes and their associated actions.

2.2 OpenMORA variables

In the role of a messaging provider, this module will publish all incoming messages in the SKYPE_RECV variable, where it can be accessed by any other module subscribed to it. The senders username is published in SKYPE_CONTACT. SkypeComm monitors the SKYPE_SEND variable and sends the message contained there to the user specified in SKYPE_CONTACT (note that SKYPE_CONTACT must be set before changing SKYPE_SEND). Over this simple messaging service, the client modules can use their own specific syntax or communications protocol.

2.3 Basic commands

SkypeComm provides its own set of predefined commands to the remote user through the chat. These commands are outlined in this section. These commands are case sensitive:
- PUBLISH {VARNAME} {VALUE} publish the variable given by VARNAME with the value given by VALUE in the OpenMORA board.
- GETVAL {VARNAME} return the value of the variable given by VARNAME. This command can only give the value of the variables that SkypeComm is subscribed to (see Section 2.1).
- HELP [COMMAND|TOPIC] provides help to the remote user. If no argument is given, it displays a list of available commands and topics along with a short description. If a command/topic argument is given, it will display the information that is available. Currently, the commands described in this list are supported and two topics: VIDEO (information about video calls to the robot) and FILE (information about file transfers -see TODO section).

2.4 "Chat recognition"

SkypeComm reads the sentences that VoiceVerbio [TODO: link with the VoiceVerbio page when created] recognizes as commands in its configuration section (pVoiceVerbio). It will inspect all incoming messages that are not recognized as SkypeComm commands, and see if they match any of the saved sentences. In case a match is found, it will execute the associated action. Otherwise, the module will do nothing, just publish the received message in SKYPE_RECV. (see TODO section)

3. Setup

SkypeComm has several dependencies that must be dealt with. This section describes the process of configuring the environment to compile and execute the module. Note that these instructions are subject to change (simplification) due to ongoing development.
1. Before compiling:
* Setup the Python environment. Download and follow the instructions in http://www.python.org for your platform. The version used by SkypeComm is 2.7. Earlier versions have not been tested; and Python 3.x might not work (See TODO section).
* In the process of building OpenMORA, make sure that the Python setup variables match your installation during the Cmake configuration.
* Install the Skype4Py package.
2. Before running:
* This module needs a Skype client running and logged in. Fortunately, the Skype client can be easily configured to start up and log in when Windows is started. It is strongly recommended to configure the client this way. The easiest way to do it is checking both options on the login window.
3. Additional setup:
* On the first run after each compilation, the Skype client will ask permission to allow the attachment of the module. The module is blocked until this access is granted. Check the Skype window once the module has been launched.
* It is recommended to configure Skype to automatically answer incoming calls and activate the video streaming. This will allow the remote user to see and hear what the environment of the robot. This is unrelated to the SkypeComm module, but quite useful.

4. Module development

This section contains all the information about the development of the module. Read it if you intend to gain insight about the implementation or you plan to improve or debug it.

4.1 Implementation

The basic structure of SkypeComm is that of a MOOS application (like any other OpenMORA module). It also acts as a Skype plugin, using the Skype public API. There are several libraries that allow the development of Skype plugins. SkypeComm uses Skype4Py, which is a Python package, because of its platform independence. In order to use this package, the Python code is embedded in the C++ code of the module, following the instructions in http://docs.python.org/extending/embedding.html .

The module uses a Python object to read and send messages through the Skype client. Each time that the Iterate() function is run, it will check if new messages where received. In case they are received, it will first check if it is a basic command and act accordingly. If it is not a command, it will determine if it matches one of the sentences recognized by VoiceVerbio [TODO: link with the VoiceVerbio page when created]. To do this, an index is obtained that reflects both the proportion of matching words in the saved and received sentence:
i = 0.5 * ((matches/saved_sentence_length)+(matches/received_sentence_length))
The sentence with the biggest index bigger than 0.5 is considered matching and the corresponding action taken. If no index is higher than 0.5, no match is found.
In any case, SkypeComm publishes the received text in SKYPE_RECV and the user that sent the message in SKYPE_CONTACT.
In OnNewMail(), SkypeComm reads the variables it is subscribed to and saves the values in a map, so it can be used by the GETVAL command. When the SKYPE_SEND variable is changed, SkypeComm will send a message to the user set in SKYPE_CONTACT. Note that both the last usernamefrom whom a message was received and the next to whom SkypeComm will send a message are set in SKYPE_CONTACT. This behavior can be modified in SkypeComm.h.

4.2 Limitations of the implementation

The Skype4Py package does not permit several actions:
- Starting a Skype client (anyway, that can be achieved without Skype4Py, although it is pointless due to the next limitation)
- Logging in a Skype account.
- Sending/receiving files: it only informs when an incoming file transfer has been completed.
- Controlling calls: the functionality regarding this aspect is incomplete. Anyway, the Skype client can automatically answer video calls, which is enough to see through the robot's camera.

4.3 Tests

The module has been extensively tested in isolation from other OpenMORA modules. Following the guidelines given in this document it will work stable. The basic commands and the interaction with the OpenMORA board are bug free (so far). The "chat recognition" still needs testing and can compromise the stability of the module (see Section 4.4) under certain known conditions. More testing needs to be done involving other modules, especially StateCharts [TODO: link with the StateCharts page when created]. The early development was done (and tested) in Linux, but major changes have been done to the module since then.

4.4 Bugs

This section is subject to change as new bugs are found and old ones solved
- When a chat message containing accents is received, the module will fail (and close) when finding matches with the VoiceVerbio sentences.
- The matching algorithm sometimes fails to find the correct match.
- When Skype loses connection, the module will fail and close.

4.5 Changelog

• 23-JUN-2011: (Revision 141): Added the SKYPE_CONTACT variable, to show the user from whom the last message was received and to command SkypeComm who to send the next message(s)
• 10-OCT-2011: (Revision 154): Fixed bug that caused SkypeComm to fail if Skype lost connection.
• 11-OCT-2011: (Revision 155): Fixed a memory leak.
• 14-FEB-2012: (Revision 199): Fixed a comment that caused Mooxygen to fail when generating the documentation

4.6 TODO

• Add an openmora variable that adjusts the user that the message will be delivered to (or use a special syntax in SKYPE_SEND/RECV)
• Add a command (or HELP option) that returns the variables that SkypeComm is subscribed to
• Create a section in the SkypeComm configuration for the sentences, that is independent of VoiceVerbio, or move the configuration of VoiceVerbio to pCommon.
• Test with different Python versions
• Improve the sentence recognition algorithm.
• Include the libraries that SkypeComm uses (Python and Skype4Py) in the OpenMORA distribution
• Change the HELP command so it gets the help strings from an external file so they can be easily modified.
• Further testing and debugging
• Clean and comment the code

4.7 Interesting links

• SkypeBot project