Ekahau::Base - Low-level interface to Ekahau location sensing system
The Ekahau::Base class provides a low-level interface to the Ekahau location sensing system's YAX protocol. In general you don't want to use this class directly; instead the subclasses Ekahau and Ekahau::Events provide a nicer interface.
Ekahau::Base
This class implements methods for querying the Ekahau Positioning Engine, and processing the responses. Each object represents a connection to the Ekahau server. Some methods send queries to the server, while others receive responses. Continuous queries generate data until they are asked to stop, so the protocol is not strictly request-response. To deal with this, queries can have a "tag" associated with them, which allows the response to that specific command to be identified.
The new constructor creates a new Ekahau object. It takes a series of parameters as arguments, in the Name = Value> style. The following parameters are recognized:
new
Name =
The maximum length of time to wait for a response or connection.
The name or IP address of the Ekahau server you'd like to communicate with. This is passed along to the IO::Socket::INET module, and you can use the alias PeerHost if you prefer. It defaults to localhost.
PeerHost
localhost
The TCP port where the Ekahau server you'd like to communicate with is running. It defaults to 8548.
8548
The password to talk to the Ekahau server. The default password is Llama, which is what the server will use if you haven't configured a password.
Llama
The XML file containing your Ekahau license. If you don't specify a LicenseFile, and anonymous connection will be used, which may be limited by the software.
LicenseFile
Properly shut down the connection to the Ekahau engine, by sending a CLOSE command then closing the socket.
CLOSE
Abort the connection to the Ekahau engine, by closing the socket.
Read some data from the network into the read buffer. This is the buffer where readpending gets pending events from. This call blocks, so if you don't want to wait for events, you should either select on the handles returned by the select_handles method, or call the can_read method to determine if data is available to read.
select
Returns the next pending event, or undef if no events are pending. The event returned is an Ekahau::Response object.
undef
Pending events come from the buffer filled by readsome.
Returns true if the network socket becomes readable within $timeout seconds; otherwise returns false.
$timeout
Returns a list of filehandles suitable for use with select. If you're multiplexing I/O from this module and other sources, you can select these filehandles for readability, then call the readsome method to read the available data, and finally call getpending in a loop to get all of the pending events. Note that these handles become selectable for read only when there is data on the network; if multiple events come in at once (which is common), the handle will become selectable once, and you'll have to retreive all of the events with getpending; it won't be selectable again until there is more data to read.
Requests a list of all devices connected to the system. Returns the command tag that was sent (which can be used to identify the response).
An optional hash reference can be supplied with a list of properties. The special property Tag will be used to set the command tag if given (otherwise a tag will be generated). Other properties will be sent along in the Ekahau request. Properties currently recognized are:
Tag
The MAC address of the device you'd like to look for, in colon-seperated format. For example:
'NETWORK.MAC' => '00:E0:63:82:65:76'
The IP address of the device you'd like to look for, in dotted-quad format. For example:
'NETWORK.IP-ADDRESS' => '10.0.0.1'
Request the property list for device $device_id.
$device_id
The first parameter can be a hash reference containing additional request properties to be sent, but none are documented by Ekahau for this command. The one exception is the special property Tag, which will be used to set the command tag if given (otherwise a tag will be generated).
Request information about logical area $location_id.
$location_id
Request a map of logical area $area_id. Returns an Ekahau::Response::MapImage object.
$area_id
Request information about all logical areas known to the Ekahau engine.
Ask the Ekahau engine to start sending location information about device $device_id. You can get responses with getpending.
Interval at which wireless LAN devices should scan. See documentation for more information.
Wireless LAN scan mode. See documentation for more information.
Set to the string true to have all locations correspond to positions on tracking rails, or false to allow any location.
true
false
Set to the string true if you would like an expected error estimate, or false to avoid this calculation.
Set to 1 for realtime positioning, or 2 for more accurate positioining.
How often you'd like an update on the device's position.
Ask the Ekahau engine to stop sending location information about device $device_id.
Alias for request_stop_location_track.
request_stop_location_track
Ask the Ekahau engine to start sending area information about device $device_id. You can get responses with getpending.
An optional hash reference can be supplied with a list of properties. The special property Tag will be used to set the command tag if given (otherwise a tag will be generated). Other properties will be sent along in the Ekahau request. This command recognizes all of the parameters used by start_location_track, and also these:
How many areas you'd like returned with each area response. Each will come with a probability that the user is in that area.
Ask the Ekahau engine to stop sending area information about device $device_id.
Alias for request_stop_area_track.
request_stop_area_track
This is a fairly low-level routine, and shouldn't be needed in normal use. It is the only way to send an arbitrary command to the YAX engine, however, so it is available and documented.
YAX commands look like this:
<#$tag command arguments property1=value1 property2=value2 ... >
For clarity, we'll call the string sent at the very beginning of first line command the tag, the next whitespace-seperated word the command, and the remainder of the first line a space-seperated list called arguments. Additional information on other lines we'll call properties.
$cmd is a list reference containing the command and arguments to send. It can also be a string, which is the same as specifying a list with just that string.
$cmd
$props is a hash reference containing the properties to be sent with the command. If it is empty or undef, no properties are sent.
$props
$tag is the command's tag, which allows the response to be picked out of the data coming back from the server.
$tag
Here are some examples:
$self->command(['GET_DEVICE_PROPERTIES',1], {}, 'A1'); $self->command('GET_DEVICE_LIST',{'NETWORK.IP-ADDRESS' => '10.1.1.1'}, 'B2');
Returns the last error generated by this object, or when called as a class method the last constructor error that prevented an object from being created. The return value is a string describing the error, suitable for display to the ser.
When an Ekahau::Base object is destroyed, its connection is closed using the close method.
Constructors and most methods return undef on error. To find out details about the error, you can call the lasterr method, which will return a string. If the error happened in the constructor and so you don't have an object to call a method on, call it as a class method:
my $errstr = Ekahau::Base->lasterr;
Scott Gifford <gifford@umich.edu>, <sgifford@suspectclass.com>
Copyright (C) 2005 The Regents of the University of Michigan.
See the file LICENSE included with the distribution for license information.
http://www.ekahau.com/, Ekahau Positioning Engine User Guide, Ekahau, Ekahau::Events, Ekahau::Response, Ekahau::License, IO::Socket::INET, IO::Select.
To install Ekahau::Base, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ekahau::Base
CPAN shell
perl -MCPAN -e shell install Ekahau::Base
For more information on module installation, please visit the detailed CPAN module installation guide.