org.fosstrak.hal
Interface HardwareAbstraction

All Known Subinterfaces:

FeigController

All Known Implementing Classes:

FeigCOMController, FeigTCPIPController, FeigUSBController, ImpinjTCPIPController, SimulatorController

public interface HardwareAbstraction

The standardized interface defines an abstraction of the underlaying reader hardware. The HardwareAbstraction interface defines a set of methods that can be implemented by any so called HAL controller class. A class that implements the interface agrees to implement all the methods defined in the interface, thereby agreeing to certain behavior. The functionality provided by the interface is kept as generally as possible in order not to exclude certain readers. The hardware itself has to comply with the following minimal requirements in order to be supported by the framework. The minimal assumption about the proprietary RFID systems is that the reader allows the identification of tags by a unique serial number. The tag's unique serial number, i.e. identifier, has to be specified as a String representing a hexadecimal number. The hexadecimal digits are the ordinary, base-10 digits '0' through '9' plus the letters 'A' through 'F'. In the hexadecimal system, these digits represent the values 0 through 15, respectively. A hexadecimal integer is a sequence of hexadecimal digits, such as 34A7, FF8, 174204. Depending on the concrete hardware this String will be converted into a convenient format, for example a byte array. In the HAL model, the memory is devided into memory banks that can be addressed. In each memory bank the memory can be accessed in block units, whereas the blocksize has to be specified in a corresponding properties file. Despite the block size, memory is specified in bytes. Since Java does not support unsigned bytes as basic types the class UnsignedByteArray is used to represent array of bytes. In general, a HAL controller instance can offer it's own memory bank model, i.e. the number of memory banks and the content of certain memory banks such as EPCs, Tag IDs, or Passwords. To avoid confusion the following memory model is suggested which is given in the EPCglobal Class 1 Generation 2 specification: memory bank 0: protected memory bank 1: EPC (Electronic Product Code or other object IDs, read only) memory bank 2: Tag ID (factory programmed ID, read only) memory bank 3: user memory (read/write) In addition, more memory banks could be used for user memory or to retrieve values of sensors mounted on a tag. Even if the underlaying reader hardware does not support EPCs, the memory bank model could be implemented using the provided memory of the reader hardware. The HAL controller implementation has to decide which of the IDs should be the master ID of the tag that is returned when performing an identify command. In an Observation the type of ID has to be specified. HAL controller implementations have to take the memory block size of the underlaying reader hardware into account. When performing a read operation only the requested number of bytes should be returned to the client even if more bytes have to be read to satisfy the block size constraints. When writing data to tag memory a preceding read operation might be necessary to avoid overwriting of memory with empty data used to fit the block size.

Author:

Matthias Lampe, lampe@acm.org, Christian Floerkemeier, floerkem@mit.edu

Method Summary

void	addAsynchronousIdentifyListener(AsynchronousIdentifyListener listener) Adds an asynchronous identify listener.
java.lang.String[]	getAllParameterNames() Gets the names of the supported parameters.
java.lang.String	getHALName() Returns the HAL name.
java.lang.String	getParameter(java.lang.String param) Gets the value of a given parameter.
java.lang.String[]	getReadPointNames() Gets the names of all available read points.
int	getReadPointNoiseLevel(java.lang.String readPointName, boolean normalize) Returns the current noise level observed at a certain read point.
int	getReadPointPowerLevel(java.lang.String readPointName, boolean normalize) Returns the current transmit power level of a certain read point.
Observation[]	identify(java.lang.String[] readPointNames) Identifies the tags in a reader's field.
boolean	isAsynchronousIdentifyRunning() Checks whether asynchronous identify is running.
boolean	isReadPointReady(java.lang.String readPointName) Checks whether a read point is ready (i.e. it has been started up).
void	kill(java.lang.String readPointName, java.lang.String id, java.lang.String[] passwords) Kills the specified tag, if in range.
UnsignedByteArray	readBytes(java.lang.String readPointName, java.lang.String id, int memoryBank, int offset, int length, java.lang.String[] passwords) Reads data from a specified tag, if in range.
void	removeAsynchronousIdentifyListener(AsynchronousIdentifyListener listener) removes an asynchronous identify listener.
void	reset() Resets the reader.
void	setParameter(java.lang.String param, java.lang.String value) Sets a given parameter.
void	shutDownReadPoint(java.lang.String readPointName) Shuts down a read point.
void	startAsynchronousIdentify(java.lang.String[] readPointNames, Trigger trigger) Identifies the tags in a reader's field in a continuous way that operates asynchronously.
void	startUpReadPoint(java.lang.String readPointName) Starts up a read point.
void	stopAsynchronousIdentify() Stops the asynchronous identification for a specific listener.
boolean	supportsAsynchronousIdentify() Checks whether this HAL controller implementation supports the startAsynchronousIdentify(), stopAsynchronousIdentify(), isAsynchronousIdentifyRunning(), addAsynchronousIdentifyListener() and removeAsynchronousIdentifyListener() methods.
boolean	supportsGetReadPointNoiseLevel() Checks whether this HAL controller implementation supports the getReadPointNoiseLevel() method.
boolean	supportsGetReadPointPowerLevel() Checks whether this HAL controller implementation supports the getReadPointPowerLevel() method.
boolean	supportsIsReadPointReady() Checks whether this HAL controller implementation supports the isReadPointReady() method.
boolean	supportsKill() Checks whether this HAL controller implementation supports the kill() method.
boolean	supportsParameters() Checks whether the HAL controller implementation supports the getAllParameterNames(), getParameter() and setParameter() methods.
boolean	supportsReadBytes() Checks whether this HAL controller implementation supports the readBytes() method.
boolean	supportsReset() Checks whether this HAL controller implementation supports the reset() method.
boolean	supportsShutDownReadPoint() Checks whether this HAL controller implementation supports the shutDownReadPoint() method.
boolean	supportsStartUpReadPoint() Checks whether this HAL controller implementation supports the startUpReadPoint() method.
boolean	supportsWriteBytes() Checks whether this HAL controller implementation supports the writeBytes() method.
boolean	supportsWriteId() Checks whether this HAL controller implementation supports the writeId() method.
void	writeBytes(java.lang.String readPointName, java.lang.String id, int memoryBank, int offset, UnsignedByteArray data, java.lang.String[] passwords) Writes data to a specific tag, if in range.
void	writeId(java.lang.String readPointName, java.lang.String id, java.lang.String[] passwords) Writes the given ID onto a tag.

Method Detail

identify

Observation[] identify(java.lang.String[] readPointNames)
                       throws ReadPointNotFoundException,
                              HardwareException

Identifies the tags in a reader's field. The concrete behaviour of this method depends on the concrete implementation of the underlaying hardware. If the controller is a single-read-point-reader the array readPointNames should contain only one read point. Tags that have been locked during the identification can be reactivated by calling the reset() method.

Parameters:

readPointNames - Array that contains the names of all read points to be scanned

Returns:

An array that contains for each read point an Observation object

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

ReadPointNotFoundException

HardwareException

startAsynchronousIdentify

void startAsynchronousIdentify(java.lang.String[] readPointNames,
                               Trigger trigger)
                               throws ReadPointNotFoundException,
                                      HardwareException,
                                      UnsupportedOperationException

Identifies the tags in a reader's field in a continuous way that operates asynchronously. If the controller is a single-read-point-reader the array readPointNames should contain only one read point.

Parameters:

readPointNames - Assay that contains the names of all read points to be scanned

trigger - The trigger that indicates the type of asynchronous identify

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

stopAsynchronousIdentify

void stopAsynchronousIdentify()
                              throws HardwareException,
                                     UnsupportedOperationException

Stops the asynchronous identification for a specific listener.

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

isAsynchronousIdentifyRunning

boolean isAsynchronousIdentifyRunning()
                                      throws HardwareException,
                                             UnsupportedOperationException

Checks whether asynchronous identify is running.

Returns:

true, if asynchronous identify is running, false otherwise

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

addAsynchronousIdentifyListener

void addAsynchronousIdentifyListener(AsynchronousIdentifyListener listener)
                                     throws HardwareException,
                                            UnsupportedOperationException

Adds an asynchronous identify listener.

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

removeAsynchronousIdentifyListener

void removeAsynchronousIdentifyListener(AsynchronousIdentifyListener listener)
                                        throws HardwareException,
                                               UnsupportedOperationException

removes an asynchronous identify listener.

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

supportsAsynchronousIdentify

boolean supportsAsynchronousIdentify()

Checks whether this HAL controller implementation supports the startAsynchronousIdentify(), stopAsynchronousIdentify(), isAsynchronousIdentifyRunning(), addAsynchronousIdentifyListener() and removeAsynchronousIdentifyListener() methods.

Returns:

true, if methods are supported, false otherwise

readBytes

UnsignedByteArray readBytes(java.lang.String readPointName,
                            java.lang.String id,
                            int memoryBank,
                            int offset,
                            int length,
                            java.lang.String[] passwords)
                            throws ReadPointNotFoundException,
                                   OutOfBoundsException,
                                   HardwareException,
                                   UnsupportedOperationException

Reads data from a specified tag, if in range. The transponder id should be a result of a previous identify. The data on a tag's memory can be read in block units. Therefore the length parameter, that indicates the number of bytes that have to be read, has to contain a multiple of the blocksize.

Parameters:

readPointName - The name of the read point on which the read attempt will be done

id - ID of the tag from which the data will be read

memoryBank - The number of the memory bank of the data

offset - The offset of the data in bytes

length - The number of bytes to be read

passwords - An optional list of one or more passwords (or lock code)

Returns:

The data that has been read from the tag

Throws:

ReadPointNotFoundException, - if the read point can not be found.

OutOfBoundsException, - if memoryBank, offset or length exceeds the allowed number.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

OutOfBoundsException

HardwareException

UnsupportedOperationException

supportsReadBytes

boolean supportsReadBytes()

Checks whether this HAL controller implementation supports the readBytes() method.

Returns:

true, if method is supported, false otherwise

writeBytes

void writeBytes(java.lang.String readPointName,
                java.lang.String id,
                int memoryBank,
                int offset,
                UnsignedByteArray data,
                java.lang.String[] passwords)
                throws ReadPointNotFoundException,
                       OutOfBoundsException,
                       HardwareException,
                       UnsupportedOperationException

Writes data to a specific tag, if in range. The transponder id should be a result of a previous identify.

Parameters:

readPointName - The name of the read point on which the write attempt will be done

id - ID of the tag to which the data will be written

memoryBank - The number of the memory bank of the data

offset - The offset of the data in bytes

data - The byte data to be written to the tag

passwords - An optional list of one or more passwords (or lock code)

Throws:

ReadPointNotFoundException, - if the read point can not be found.

OutOfBoundsException, - if memoryBank, offset or length exceeds the allowed number.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

OutOfBoundsException

HardwareException

UnsupportedOperationException

supportsWriteBytes

boolean supportsWriteBytes()

Checks whether this HAL controller implementation supports the writeBytes() method.

Returns:

true, if method is supported, false otherwise

kill

void kill(java.lang.String readPointName,
          java.lang.String id,
          java.lang.String[] passwords)
          throws ReadPointNotFoundException,
                 HardwareException,
                 UnsupportedOperationException

Kills the specified tag, if in range. A killed tag doesn't respond to requests any longer.

Parameters:

readPointName - the name of the read point on which the kill attempt will be done

id - id of the tag that will be killed

passwords - an optional list of one or more passwords (or lock code)

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsKill

boolean supportsKill()

Checks whether this HAL controller implementation supports the kill() method.

Returns:

true, if method is supported, false otherwise

writeId

void writeId(java.lang.String readPointName,
             java.lang.String id,
             java.lang.String[] passwords)
             throws ReadPointNotFoundException,
                    HardwareException,
                    UnsupportedOperationException

Writes the given ID onto a tag. If the physical environment supports the setting of a new tag ID this method can be used to access the appropriate blocks within the memory.

Parameters:

readPointName - The name of the read point on which the write attempt will be done

id - the new ID for the tag

passwords - an optional list of one or more passwords (or lock code)

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsWriteId

boolean supportsWriteId()

Checks whether this HAL controller implementation supports the writeId() method.

Returns:

true, if method is supported, false otherwise

getHALName

java.lang.String getHALName()

Returns the HAL name. The HAL name identifies the HAL controller instance and should be specified in a properties file.

Returns:

The HAL name

getReadPointNames

java.lang.String[] getReadPointNames()

Gets the names of all available read points.

Returns:

An array containing the names of all available read points

getAllParameterNames

java.lang.String[] getAllParameterNames()
                                        throws HardwareException,
                                               UnsupportedOperationException

Gets the names of the supported parameters. The parameters which are configurable should be listed in the associated properties file.

Returns:

The parameter names of all supported paramters

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

getParameter

java.lang.String getParameter(java.lang.String param)
                              throws HardwareException,
                                     UnsupportedOperationException

Gets the value of a given parameter. A call of the getAllParameterNames() should precede this method in order not to request undefined parameters.

Parameters:

param - The parameter name to be read

Returns:

The parameter value

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

setParameter

void setParameter(java.lang.String param,
                  java.lang.String value)
                  throws HardwareException,
                         UnsupportedOperationException

Sets a given parameter. A call of the getAllParameterNames() should precede this method in order not to set undefined parameters.

Parameters:

param - The parameter name

value - The parameter value

Throws:

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

HardwareException

UnsupportedOperationException

supportsParameters

boolean supportsParameters()

Checks whether the HAL controller implementation supports the getAllParameterNames(), getParameter() and setParameter() methods.

Returns:

true, if methods are supported, false otherwise

reset

void reset()
           throws HardwareException

Resets the reader. This includes the unlocking of all previously locked (muted) tags. Furthermore, if anything should not work as desired due to any failures, this method reinitializes the hardware abstraction.

Throws:

HardwareException, - if the operation can not be performed.

HardwareException

supportsReset

boolean supportsReset()

Checks whether this HAL controller implementation supports the reset() method.

Returns:

true, if method is supported, false otherwise

getReadPointPowerLevel

int getReadPointPowerLevel(java.lang.String readPointName,
                           boolean normalize)
                           throws ReadPointNotFoundException,
                                  HardwareException,
                                  UnsupportedOperationException

Returns the current transmit power level of a certain read point.

Parameters:

readPointName - The name of the read point

normalize - Specifies whether the power level should be returned in a normalized form (i.e. in a range from 0 to 255)

Returns:

The current transmit power level of the read point

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsGetReadPointPowerLevel

boolean supportsGetReadPointPowerLevel()

Checks whether this HAL controller implementation supports the getReadPointPowerLevel() method.

Returns:

true, if method is supported, false otherwise

getReadPointNoiseLevel

int getReadPointNoiseLevel(java.lang.String readPointName,
                           boolean normalize)
                           throws ReadPointNotFoundException,
                                  HardwareException,
                                  UnsupportedOperationException

Returns the current noise level observed at a certain read point.

Parameters:

readPointName - The name of the read point

normalize - Specifies whether the noise level should be returned in a normalized form (i.e. in a range from 0 to 255)

Returns:

The current noise level observed at the read point

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsGetReadPointNoiseLevel

boolean supportsGetReadPointNoiseLevel()

Checks whether this HAL controller implementation supports the getReadPointNoiseLevel() method.

Returns:

true, if method is supported, false otherwise

startUpReadPoint

void startUpReadPoint(java.lang.String readPointName)
                      throws ReadPointNotFoundException,
                             HardwareException,
                             UnsupportedOperationException

Starts up a read point.

Parameters:

readPointName - The name of the read point

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsStartUpReadPoint

boolean supportsStartUpReadPoint()

Checks whether this HAL controller implementation supports the startUpReadPoint() method.

Returns:

true, if method is supported, false otherwise

shutDownReadPoint

void shutDownReadPoint(java.lang.String readPointName)
                       throws ReadPointNotFoundException,
                              HardwareException,
                              UnsupportedOperationException

Shuts down a read point.

Parameters:

readPointName - The name of the read point

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsShutDownReadPoint

boolean supportsShutDownReadPoint()

Checks whether this HAL controller implementation supports the shutDownReadPoint() method.

Returns:

true, if method is supported, false otherwise

isReadPointReady

boolean isReadPointReady(java.lang.String readPointName)
                         throws ReadPointNotFoundException,
                                HardwareException,
                                UnsupportedOperationException

Checks whether a read point is ready (i.e. it has been started up).

Parameters:

readPointName - The name of the read point

Returns:

true it the antenna is ready, false otherwise

Throws:

ReadPointNotFoundException, - if the read point can not be found.

HardwareException, - if the operation can not be performed.

UnsupportedOperationException, - if the operation is not supported by the controller implementation.

ReadPointNotFoundException

HardwareException

UnsupportedOperationException

supportsIsReadPointReady

boolean supportsIsReadPointReady()

Checks whether this HAL controller implementation supports the isReadPointReady() method.

Returns:

true, if method is supported, false otherwise