View source for Pyogp/Documentation/Specification/pyogp.interop

=Interop Tests=
Pyogp is currently broken down into three parts pyogp.lib.base, pyogp.interop, pyogp.agentdomain. This section discusses pyogp.interop. <br>
The interop package of Pyogp is designed to be used to test interoperability between OGP grids. This means that we want to be able to run tests that determine if an implementation of the open-grid protocols is correct, and so can become a part of the other grids. <br>
However, right now we have a mix of different types of tests in interop. We have tests that are like unittests, that check functionality to make sure its working. We also have tests that implement some protocols but aren’t asserted and so cannot be used in automated testing (note: these tests should be moved out into a new package probably called ‘pyogp.client’). Below you will find a listing of the tests that we have at the moment as well as a description of what they do and how to use them. They are semi-ordered in that the tests that are listed first are really the basis of the tests that come after (for instance, we must first login to obtain presence, and we must obtain presence to teleport). 

==Caps==
#test_cap_agent_info
#test_cap_region_info
#test_cap_rez_avatar_derez
#test_cap_rez_avatar_place
#test_cap_rez_avatar_request
#test_cap_rez_avatar_rez

These tests are used to test each of the capabilities that can be gotten from the Agent Domain seedcap. They make sure that what we get back from some POSTS to the seedcaps are correct. Be aware that there are some tests in here that are not just viewer-to-sim tests but also ad-to-sim tests.

==Login==
#test_ogp_login

Login works by taking a set of credentials (such as avatar First and Last name, login server uri, and target region uri), post to the login uri, get a seedcap, and start posting to the seedcap. 

==Presence==
#test_ogp_presence
#test_ogp_event_queue

The way we do presence is by going through the UDPDispatcher. After login is done and we have successfully been placed onto a sim (through place_avatar) we can begin communicating with the sim through udp messages. In order to establish presence, there are a few special packets we must send to get the sim to recognize us as a client to communicate with. In order to maintain presence on the sim there are certain packets that we receive from the sim that we have to respond in a particular way, and there are some that we just have to send an ack as a reply. In our test scripts, we use the UDPDispatcher to send the necessary messages to the sim to establish the connection (using the sim ip and port received from place_avatar). Then, we again use the dispatcher’s process_acks function to send all the acks so the sim knows we are receiving them. Finally, there is a very basic packet-handling mechanism in place. After we have received a message, a series of bytes, we decode the message and deserialize it into a packet. We have a simple switch-like statement for the packet handling based on packet name. Every time we receive a packet, we check its name. If it is a packet that we are interested in, then we have specialized functions to process the message accordingly. 

We also have scripts to communicate with the sim’s event queue. To communicate with the event queue, we receive the EventQueueGet capability for the sim’s seed capability. 
Then, to get the messages from the sim’s event queue, we create a new thread. In the thread, we have an infinite loop that continually posts to the EQG capability and prints the results. The messages are NOT currently handled at all. 

Now, to maintain presence we also have to maintain presence on the Agent Domain and not just the sim. We simply have to keep a heartbeat with the AD, otherwise it will delete our agent presence info and revoke all of our caps. To do this, we take the same approach as we did for the sim EQG. We receive the event queue capability from the AD’s seedcap, create a thread, and continually post to the event queue cap in the thread. Note that this post currently returns nothing, as it is not implemented for anything other than maintaining presence.

The reason the event queue posting is done in threads is because the posts can take some time to finish (say, if the queue has nothing in it). So, rather than stalling the script, we create a new thread to run this code, essentially doing a long-poll-like technique. Other methods would be to do an actual long-poll, or to do something like non-blocking IO operations (maybe using Eventlet).

==Teleport==
#test_ogp_teleport
#test_teleport_inter – WINDOWS ONLY

Pyogp also allows teleporting. There are a series of steps we have to take in order to teleport (listed in the documentation section of the Client Lib). In order to teleport using Pyogp, we have a configuration set up for testing purposes. In the testconfig.cfg file, the user specifies the starting region uri and the target region uri. The code will then log the user onto the starting region uri, then, once the proper steps are taken, it will use the target region uri to teleport to. This method has no way to specify a position in the region to teleport to, but only the region.

We also have another way to do teleport, the teleport_inter, or interactive teleport. For this, we have created another thread that waits for user input (using a windows-only input library). Once the ‘t’ key is pressed, the script will import another script, called teleport_region.py, and use the variables called “region” and “position”. The agent will then be teleport to the region at the given position. The teleport_region script is reloaded every time the user presses the ‘t’ button. This means that if you were to change the target region or position, the agent will teleport to a different location. This can be used in real-time to specify where you would like to teleport to. 

KEYS:<br>
‘t’ – teleport based on the region/position specified in the teleport_region script

==Movement==
#test_ogp_movement – WINDOWS ONLY

The way an avatar gets to move is by sending keypresses to the simulator. The sim will then determine how the avatar should be moved based on what keys have been pressed (is the agent pushing the forward button, the backward button, the fly or stop button?). 

The normal routine of maintaining presence includes sending the “AgentUpdate” message to the simulator. This message updates the sim of how the agent’s data has changed, including the camera position and orientation as well as the keys that the user is pressing. So, to make the avatar move, we use the same thread from the teleport script and wait for other keys, specifically the arrow keys. When the user presses on of the arrow keys, it sets the control flag for the avatar, which will get sent during the next AgentUpdate messages. Note that the thread that maintains presence (and so sends the AgentUpdate message) is not the same thread as that which handles keypresses. This has some drawbacks. For one, in order to get an avatar to move, we must first send a NUDGE message, then the following messages must be MOVE messages. So, the NUDGE must precede the MOVE messages. Due to the thread timing, the input thread may be updating faster than the presence thread, so without some organization we will send the MOVE message before the NUDGE, and so movement will fail. To get this to work, the input thread simply sets a global variable (if nothing was pressed, it sets to NUDGE. if it is NUDGE, it sets it to MOVE). That change doesn’t actually get propagated until we actually send the message in the other thread, so even if the user keeps pressing the input button, it won’t change the message being sent.

Also, the sim continues moving the avatar with the last keypress it received. So, if the last message received was the FORWARD MOVE message, the avatar will continue moving forward even if the user releases the keys. To get the avatar to stop moving, we must send a STOP keypress update. To do this, hit the space bar.

KEYS:<br>
Arrow keys – move the avatar in the direction (left and right strafes)<br>
Space bar – stops the avatar from moving<br>
‘t’ – teleport (carried over from teleport script)<br>

==Chatting==
#test_chat – WINDOWS ONLY

Pyogp currently has local chatting functioning. A Pyogp avatar can both send a message into the public chat channel as well as receive chat messages from the public chat channel.

In order to chat the client has to send a ChatFromViewer message. This message has a few options that are important (other than the message). It has a variable called “Type”. The Type is HOW the avatar is speaking, either whispering, talking, shouting, simply typing on his keyboard or stopped typing (search for ChatFromViewer to find the details). For now, the chat script only has the avatar talking normally. Another important field is the “Channel” field. This is used to specify where we are chatting to. Again, we currently only use the public chat channel (0), which allows the avatar to speak to those avatars that are in close proximity to him or her. 

The way chatting works is that we have created a basic chat GUI (using Tkinter, a Windows only library). The GUI is a scrolling text box with a text box input field and send button. When the user sends or receives a chat message, the sender’s name and message is displayed in the scrolling text box. However, there are different types of chat messages received. Some of the messages just indicate that the other avatar is typing on the keyboard or has stopped typing (and so doesn’t have a message with it). For these, no chat message is displayed into the chat box (but the messages are still received and can be used if someone want to). To send a message, the user enters the message into the text input field and either presses ENTER or hits the SEND button. Both do the exact same thing. 

Keys:<br>
Type into the chatbox and press either ENTER or the SEND button<br>
Arrow keys – move the avatar in the direction (left and right strafes)<br>
Space bar – stops the avatar from moving<br>
‘t’ – teleport (carried over from teleport script)<br>


=Things to Do=
This is a list of things that could be done. 
#Make a client package in Pyogp that is a high-level package that can be used to create a Pyogp client, or run a Pyogp bot. 
#*Move out the following files into the package: test_chat, test_ogp_movement, test_teleport_inter
#Make the tests that remain in pyogp.interop more test-driven, or more like unit tests that can be automated to check status of an OGP implementation. 
#Make the tests that remain in pyogp.interop better by not duplicating code (such as login) that is common to doing some sort of functionality. This means we may be able to split out some things like login or maintaining presence into high-level classes and putting it in either pyogp.lib.base or into pyogp.client. This is so that we don’t have to duplicate the code for every test we want to run (like we currently do). 
#Fix and extend test_ogp_movement
#*find a way to get the bot to stop when the arrow keys are released (rather than pushing the SPACE bar everytime)
#*find a way to rotate the bot. Currently, only movement is allowed, not rotation, so when the bots eventually get avatars, they will be strafing and such.
#*strip out some of this functionality so that it can be controlled by an automated script
#*give the bot the ability to fly (AWESOME)
#Fix test_teleport_inter and test_chat
#*To teleport in either of these, the user must change a config file (which can be done in real-time). A better approach would be to have the ChatWindow have a text box the user could type in which could be processed to find out what commands the user is trying to send. 
#Make cross-platform
#*the teleporting, movement, and chatting code is currently windows only due to the input and gui libraries that were used. 


[[Category:Pyogp_Documentation]]
[[Category:Pyogp_Kitchen_Sink]]