----------------------------------------------
PYL3DGECOMM v0.2 README (released 16th October 2012)
----------------------------------------------

This document is part of pyl3dgecomm (http://caia.swin.edu.au/urp/l3dge/tools/).
It gives an overview of pyl3dgecomm.


OVERVIEW
--------

The pyl3dgecomm module provides a simple Python API to interface with 
L3DGEWorld 2.3 [1] (and compatible) servers.  Installation instructions can be
found in INSTALL.txt

An overview of the architecture of the L3DGEWorld system can be found in Fig.1 
of [2]

The pyl3dgecomm module allows for rapid and easy development of a new 
L3DGEWorld input or output daemon. The user does not need to be familiar 
with the l3dgecomm protocol.

DOCUMENTATION
-------------

For example usage of this module, see 'exampe-usage.py', included with the package.

Before using the module, it must be imported
    
    import pyl3dgecomm

For each L3DGEWorld server, a new l3dgecomm object must be instantiated:

    serv = pyl3dgecomm.l3dgecomm(Remote IP, Remote Port, Local IP [optional])

The object then provides the following methods:
	
    sendFeedback(message)
	
        Shows a text message on any L3DGEWorld clients connected to the server
		
    triggerMultiEntityCoordUpdate(entityids)
	
        For each ID in the tuple entityids, the L3DGEworld server will 
        re-read the location of the entity from its data store
		
    triggerEntityCoordUpdate(entity ID)
    
        Instruct the L3DGEworld server to re-read the location of the 
        entity from its data store
	
    sendEntityUpdate(entityid,metric,field,value)
    
        Send an entity update message to the L3DGEworld server for a
        given entity. The metric correlates to Table 1 in [2].
        
        The field argument is one of 'r', 'n' or 'v'. 'n' and 'v' are
        name and value, and are arbitrary strings describing this metric
        and its value (eg, "Network traffic" and "5000 PPS"). 'r' is the 
        value used by the L3DGEworld server to apply the characteristic.
        (Eg, an 'r' of 50 for metric 1 [spin] would have the entity 
        rotate 10 degrees every frame)
        
    checkIncoming()
    
        Checks the UDP socket for any incoming packets and parses them.
        If it reaches an action packet, it will return the action. If
        there are no actions in the queue, or the queue is empty, it 
        returns False. It is a non-blocking function. 
        
        You must call this function regularly, regardless of whether 
        you expect actions or not - it checks for and handles 
        invalidtoken, gettoken and tokenreply packets. 
        
        The action is returned as a tuple:
            [
              entity ID,
              tool ID,
              string of entity state
            ]
        
        The entity ID is the entity that the action was triggered by. 
        
        The tool ID is the tool used to trigger the action. There is no
        specification regarding which tool ID does what. 
        
        The string of entity state is passed on in the same format as 
        the L3DGEWorld server sends it. For example:
        
            pps=50.6.number of attackers=1.number of unique ports hit \
            =323.protocol percentage breakdown=icmp:0 tcp:99 udp:0.last \
            attacker=10.10.10.10 .
        
        
        
        If the function returns an action, there is possibly more 
        actions waiting in the queue, so using a while loop to check
        is advisable. 
        
            action = conn.checkIncoming()
            while action != False:
                doSomethingWithAction(action)
                action = conn.checkIncoming()
        
        



For more in-depth information on the design and use of the l3dgecomms 
protocol 2.3 see [2]

pyl3dgecomm is distributed as Python module. INSTALL.txt 
describes how to install the pyl3dgecomm module. 


REFERENCES
----------

[1] http://caia.swin.edu.au/urp/l3dge/download.html
    L3DGE - Downloads

[2] http://caia.swin.edu.au/reports/080222C/CAIA-TR-080222C.pdf
    L.Parry, "L3DGEWorld 2.3 Input & Output Specifications," CAIA Technical
    Report 080222C, February 2008.

LICENSE
-------

pyl3dgecomm is distributed under the FreeBSD license.

Copyright (c) 2012 Centre for Advanced Internet Architectures,
Swinburne University of Technology. 

Authors: Greville Armitage ( garmitage@swin.edu.au ) 
         Chris Holman ( 6963420@student.swin.edu.au )

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.




CONTACT
-------

The py3dgecomms module is part of the L3DGEworld project, whose 
website is: http://www.caia.swin.edu.au/urp/l3dge/

If you have any questions or want to report any bugs please contact
Grenville Armitage (garmitage@swin.edu.au).

Centre for Advanced Internet Architectures
Swinburne University of Technology
Melbourne, Australia
CRICOS number 00111D
http://www.caia.swin.edu.au