RFC - Event Extras & Girder2Girder

[JohnHind]

Request For Comment: Event Extras & Girder2Girder

Updated to B4 26 October 2005

WARNING: There is a minor breaking change in this Beta - The old SetPassword has been replaced with ClientSetPassword and a new SetPassword added taking password only. This makes for consistency with the other functions.

This is something I've been tinkering with for a couple of weeks now. It provides an alternative and perhaps more flexible method of mapping events using GML files and a way of distributing events to other Girder machines over a network. No scripting is necessary, but it is there under the hood if you want something more flexible.

A beta is available for download. Please post any comments/suggestions here.

Installation:

Girder2Girder.lua -> %girder%luascript\
EventExtras.lua -> %girder%plugins\treescript\
EventExtras.xml -> %girder%plugins\UI\

Actions and Conditionals:

Event Translation (Event Extras Action Group): This action can generate a new event which may optionally include elements from the triggering event. For example, you
can map one eventstring onto another or change the device number.

Event Filter (Conditional): You can attach this to any node to block events from specified devices getting down that part of the tree. For example, you could block events from all mapping devices except one specified one, then you can change the mapping by editing just one node!

Event Pump (Event Extras Action Group): This action sends (pumps) any events which trigger it to another Girder machine. It can also broadcast events to all connected
machines. Use Event Translation to generate custom events to send, or just send all
the events from a remote to another machine.

Comserv Conditional: This conditional can switch actions on or off depending on
whether a specified remote Girder machine is on-line and available to the Event Pump.

Lua High-level Functions:

The Actions and Conditionals use a Lua library Girder2Girder.lua as an easy front end for the comserv plugin. This can also be used directly from scripting.

Put the command "require('Girder2Girder')" at the top of your script to ensure the
library is loaded. Now the following commands are available:

g2g.SendEvent([event], [device], [mod], [p1], [p2], [p3], [p4])
g2g.ClientSendEvent([name], [event], [device], [mod], [p1], [p2], [p3], [p4])

g2g.SendTable([table], [destname])
g2g.ClientSendTable([name],[table],[destname])

g2g.RunLua([chunk])
g2g.ClientRunLua([name],[chunk])

g2g.Ping()
g2g.ClientPing([name])

g2g.SetPassword([password])
g2g.ClientSetPassword([name],[password])

g2g.IsClientAvailable([name])
g2g.GetClients([all])

name: This can be the Server Name of the remote Girder machine, or the IP address.

SendEvent generates an event in the remote Girder(s) per the remaining parameters. ClientSendEvent targets a named machine, SendEvent broadcasts to all.

SendTable sends a table to the remote Girder(s) where it gets stored under
destname. ClientSendTable targets a named machine, SendTable broadcasts to all.

RunLua sends a chunk of Lua (in source text form) to the remote Girder(s)
where it gets run. ClientRunLua targets an named machine, RunLua broadcasts to all.

Ping is not normally needed, but ensures that the information about on-line clients
is up to date
.
SetPassword By default, the password "girder" is used which matches the default installation, but this can be changed prior to the first transaction using this function.

IsClientAvailable returns true if the named client is online.

GetClients returns a list (number-keyed table) of Server Names. With "all" false or
missing, the list contains only clients which are on-line. With "all" true, the list
contains all clients that are known about.

Lua Low-level Functions:

The g2g Lua library also includes a lower level interface to comserv which can be used
to send any of the Girder to Girder transactions asynchronously with automatic
connection management. See the source file for details.


John Hind