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.

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:

Timeout

The maximum length of time to wait for a response or connection.

PeerAddr

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.

PeerPort

The TCP port where the Ekahau server you'd like to communicate with is running. It defaults to 8548.

Password

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.

LicenseFile

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.

Properly shut down the connection to the Ekahau engine, by sending a CLOSE command then closing the socket.

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.

Returns the next pending event, or undef if no events are pending. The event returned is an Ekahau::Response object.

Pending events come from the buffer filled by readsome.

Returns true if the network socket becomes readable within $timeout seconds; otherwise returns false.

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:

NETWORK.MAC

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'

NETWORK.IP-ADDRESS

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.

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.

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 a map of logical area $area_id. Returns an Ekahau::Response::MapImage object.

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.

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:

EPE.WLAN_SCAN_INTERVAL

Interval at which wireless LAN devices should scan. See documentation for more information.

EPE.WLAN_SCAN_MODE

Wireless LAN scan mode. See documentation for more information.

EPE.SNAP_TO_RAIL

Set to the string true to have all locations correspond to positions on tracking rails, or false to allow any location.

EPE.EXPECTED_ERROR

Set to the string true if you would like an expected error estimate, or false to avoid this calculation.

EPE.POSITIONING_MODE

Set to 1 for realtime positioning, or 2 for more accurate positioining.

EPE.LOCATION_UPDATE_INTERVAL

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.

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:

EPE.NUMBER_OF_AREAS

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.

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.

$props is a hash reference containing the properties to be sent with the command. If it is empty or undef, no properties are sent.

$tag is the command's tag, which allows the response to be picked out of the data coming back from the server.

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.