---------------------------------------------- ARDUINO-L3DGECOMM v0.2 README (released 16th October 2012) ---------------------------------------------- This document is part of arduino-l3dgecomm (http://caia.swin.edu.au/urp/l3dge/tools/). It gives an overview of arduino-l3dgecomm. OVERVIEW -------- The arduino-l3dgecomm module provides a simple to use Arduino [1] API to interface with L3DGEWorld 2.3 [2] (and compatible) servers, using the Arduino Ethernet shield and UDP/IP. Installation instructions can be found in INSTALL.txt An overview of the architecture of the L3DGEWorld system can be found in Fig.1 of [3] The arduino-l3dgecomm module allows for rapid and easy development of a new L3DGEWorld input and output daemon. The user does not need to be familiar with the l3dgecomm protocol. DOCUMENTATION ------------- For example usage of this module, see 'exampe-usage.ino', included with the module. Before using the module, its dependencies must be included: #include #include #include #include arduino-l3dgecomm depends on the built-in libraries EthernetUdp.h and SPI.h for network communication, and the 3rd party library Time.h [4] for rate limiting certain network actions. The Ethernet interface must then be initialised. byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xF9, 0xFF }; IPAddress ip (10, 0, 0, 1); Ethernet.begin(mac,ip); For each L3DGEWorld server, a new L3dge object must be instantiated: L3dge * L; L = new L3dge( IPAddress( 10,0,0,1), 27960); arduino-l3dgecomm will listen and transmit on UDP Port 27960 of the IP address configured. This can be changed by altering localPort in the constructor of the L3dge class. The object then provides the following methods: void sendUpdate(int entityID, int metricID, char[] field, char[] payload) Sends an update to the L3DGEWorld server. int entityID: the ID of the entity the update is for int metricID: the metric ID to update (see table 1 of [2]) char[] field: One of 'r','v','n'. Sets what the payload represents. 'r' is a number used to apply the metric in-game. 'v' is an arbitrary string describing the 'r' value. 'n' is a human readable name of the metric. eg, 'r': 50, 'v': "100 packets per second", 'n': "Network I/O" char[] payload: The data for the metric, eg "40". There is no guarantee the update will be received by the L3DGEWorld server. The update will not be sent if there is no valid token for server communication. If the token is invalid, the only way to discover this is to send an update and check if an 'invalidtoken' message is returned (this is managed by checkPackets() ). If there is no valid token, arduino-l3dgecomm will automatically send a gettoken request every 5 seconds. void updatePos(int entityID) int entityID: the ID of the entity to trigger an update for Requests the server to re-read the position of the entity from its configuration files. void updateMultiplePos( int[] entityIDs ) int[] entityIDs: An array of ints of each of the entities to reread the position configuration for Requests the server to re-read the position of >= 1 entities from its configuration files. Action * checkPackets() Checks the incoming packet queue and processes as many packets as it can. It is a non-blocking function. If there is an action packet in the receive queue, it will stop processing the queue and return an action struct. To make sure the incoming queue is kept as low as possible, it is advisable to call this function in a loop, such as: Action * act; while ( act = checkPackets() ) if ( act == null ) break; else doThingsWithAction( act ) ; If checkPackets() finds an invalidtoken() or gettoken() packet in the queue, it will automatically handle these as required. The Action struct is defined as follows: struct Action { unsigned int entityId; unsigned int toolId; char entity [UDP_TX_PACKET_MAX_SIZE]; }; entityId is the entity that the action was triggered on toolId is the tool that was used to trigger the action ( There is no specification as to which tool does what ) entity is a string of entity properties. The entity string is copied verbatim from the received packet. The format of the string is expected to be, but not verified to be, each of the name/value pairs, in the format "name=value", each separated by a \n. To make the sendUpdate() calls simpler, there are a number of constants available to you: L3DGE_FIELD_RATE L3DGE_FIELD_VALUE L3DGE_FIELD_NAME L3DGE_METRIC_SPIN L3DGE_METRIC_BOUNCE_HEIGHT L3DGE_METRIC_SCALE L3DGE_METRIC_ROLL L3DGE_METRIC_COLOUR L3DGE_METRIC_BOUNCE_RATE L3DGE_METRIC_SOUND L3DGE_METRIC_ALT_SKIN L3DGE_METRIC_ALT_MODEL L3DGE_METRIC_INFO For more in-depth information on the design and use of the l3dgecomms protocol 2.3 see [3]. arduino-l3dgecomm is distributed as an Arduino libary. INSTALL.txt describes how to install the arduino-l3dgecomm library. REFERENCES ---------- [1] http://www.arduino.cc Arduino Home Page [2] http://caia.swin.edu.au/urp/l3dge/download.html L3DGE - Downloads [3] 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. [4] http://arduino.cc/playground/Code/Time Arduino Playground - Arduino Time Library LICENSE ------- arduino-l3dgecomm 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 arduino-l3dgecomm 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