com.oracle.deviceaccess.atcmd

Interface ATDevice

All Superinterfaces:

Peripheral

All Known Subinterfaces:

ATModem

public interface ATDevice
extends Peripheral

The ATDevice interface provides methods for controlling a Data Communication Equipment such as a modem or a cellular module using AT commands.

Each AT device is identified by a numerical ID and optionally by a name and by a set of capabilities (properties). The defined property keywords include javax.deviceaccess.atcmd.config, javax.deviceaccess.atcmd.csd, javax.deviceaccess.atcmd.psd, javax.deviceaccess.atcmd.voice, javax.deviceaccess.atcmd.sms, javax.deviceaccess.atcmd.sim, javax.deviceaccess.atcmd.phonebook. Their meaning is defined as follows:

javax.deviceaccess.atcmd.config

Supports access to configuration, control and identification commands.

javax.deviceaccess.atcmd.csd

Supports access to circuit switched data (CSD) related AT commands.

javax.deviceaccess.atcmd.psd

Supports access to packet switched data, such as GPRS or EDGE, related AT commands.

javax.deviceaccess.atcmd.voice

Supports access to voice call related AT commands.

javax.deviceaccess.atcmd.sms

Supports access to SMS related AT commands.

javax.deviceaccess.atcmd.sim

Supports access to SIM related AT commands.

javax.deviceaccess.atcmd.phonebook

Supports access to phonebook related AT commands.

This list may be extended to designate other (possibly proprietary) capabilities (properties).

As per the convention, when one of this capabilities is supported by an AT device it must be assigned as a positively asserted boolean capability:
<keyword>=true
For example: javax.deviceaccess.atcmd.phonebook=true.
When a capability is not supported by an AT device negatively asserting the boolean capability is optional.

An ATDevice instance can be opened by a call to one of the PeripheralManager.open() methods.

Commands can be issued to an ATDevice either synchronously or asynchronously. When submitted synchronously using the sendCommand(String), the response string will be available as the return value to the call. When submitted asynchronously using the sendCommand(String, CommandResponseHandler) a CommandResponseHandler instance must be provided to handle the response when available.

Note that the command strings passed as parameter to the sendCommand() methods are the complete AT command lines including the AT prefix and a termination character.

An ATDevice can only handle one command at a time. Commands cannot be sent (or queued) while a command is already being handled. Nevertheless, if supported by the underlying AT device, several commands may be concatenated in a single command line.

An ATDevice may report responses that are either information text or result codes. A result code can be one of three types: final, intermediate, and unsolicited. A final result code (e.g; OK or ERROR) indicates the completion of command and the readiness for accepting new commands. An intermediate result code (e.g. CONNECT) is a report of the progress of a command. An unsolicited result code (e.g. RING) indicates the occurrence of an event not directly associated with the issuance of a command.
Information text, final result code and intermediate result code responses are reported as return values of calls to the sendCommand(String) method or as the parameter to the processResponse() method of a CommandResponseHandler instance provided as parameter to a call to sendCommand(String, CommandResponseHandler).
Note that such response strings may include command echos unless command echo has been disabled (such as with an ATE0 command).
Unsolicited result code responses are reported and passed as parameter to the processResponse() method of a UnsolicitedResponseHandler instance.

A data connection can be established by calling the openDataConnection(java.lang.String, com.oracle.deviceaccess.atcmd.CommandResponseHandler, com.oracle.deviceaccess.atcmd.DataConnectionHandler) with a dedicated AT command such as ATD. The state of the connection can be monitored by additionally providing an DataConnectionHandler instance..

When done, an application should call the ATDevice.close() method to release the AT device. Any further attempt to use an ATDevice instance which has been closed will result in a PeripheralNotAvailableException been thrown.

Note: The sendCommand() methods of ATDevice do not parse the provided AT commands. The AT command line should include the AT prefix and the proper termination character when and where needed.

See Also:

CommandResponseHandler, UnsolicitedResponseHandler, DataConnection

Field Summary

Fields inherited from interface com.oracle.deviceaccess.Peripheral

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID

Method Summary

Methods

Modifier and Type	Method and Description
void	abortCommand(java.lang.String abortSequence) Aborts the currently executing command by sending the provided abortSequence.
void	close() Closes and releases the underlying peripheral device, making it available to other applications.
void	escapeToCommandMode() When in data mode, calling this method will try to switch to command mode such as (depending on the underlying AT device) by sending "+++" escape sequence.
int	getMaxCommandLength() Returns the maximum length of the command string that can be processed by the underlying AT parser.
boolean	isConnected() Queries if this AT device has an opened data connection.
boolean	isInCommandMode() Queries if this AT device is in command mode.
DataConnection	openDataConnection(java.lang.String cmd, CommandResponseHandler crHandler, DataConnectionHandler dcHandler) Opens a data connection by issuing the specified AT command and optionally handles the response and the opened connection asynchronously.
java.lang.String	sendCommand(java.lang.String cmd) Sends an AT command and wait for the response.
void	sendCommand(java.lang.String cmd, CommandResponseHandler handler) Sends an AT command and handle the response asynchronously.
void	setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler) Registers a handler for handling Unsolicited Result Code responses.

Methods inherited from interface com.oracle.deviceaccess.Peripheral

getID, getName, getProperties, isOpen

Method Detail

abortCommand

void abortCommand(java.lang.String abortSequence)
                  throws java.io.IOException,
                         PeripheralNotAvailableException

Aborts the currently executing command by sending the provided abortSequence. Abortion depends on the command's definition (abortability). Calling this method does NOT guarantee abortion of the currently executing command. It only aborts if the command supports abortion and it is currently in a proper state for abortion.

Parameters:

abortSequence - the character sequence for aborting; if null the ESC (abort) character is sent out by default.

Throws:

java.lang.NullPointerException - if abortSequence is null.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

escapeToCommandMode

void escapeToCommandMode()
                         throws java.io.IOException,
                                PeripheralNotAvailableException

When in data mode, calling this method will try to switch to command mode such as (depending on the underlying AT device) by sending "+++" escape sequence.

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

getMaxCommandLength

int getMaxCommandLength()
                        throws java.io.IOException,
                               PeripheralNotAvailableException

Returns the maximum length of the command string that can be processed by the underlying AT parser. Command string exceeding this value may be cut off without warning as this is a default behavior of modems.

Returns:

maximum length of command line string that can be processed

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

isConnected

boolean isConnected()
                    throws java.io.IOException,
                           PeripheralNotAvailableException

Queries if this AT device has an opened data connection.

Returns:

true if connected; false otherwise.

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

isInCommandMode

boolean isInCommandMode()
                        throws java.io.IOException,
                               PeripheralNotAvailableException

Queries if this AT device is in command mode. When in command mode, a new command can be sent provided no command is currently being processed.

Returns:

true if in command mode; false otherwise.

Throws:

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

openDataConnection

DataConnection openDataConnection(java.lang.String cmd,
                                CommandResponseHandler crHandler,
                                DataConnectionHandler dcHandler)
                                  throws java.io.IOException,
                                         PeripheralNotAvailableException

Opens a data connection by issuing the specified AT command and optionally handles the response and the opened connection asynchronously. The call will return immediately and the provided CommandResponseHandler and DataConnectionHandler instances will be invoked to handle respectively the response (error or intermediate and final result codes) when available and the connection when opened then when subsequently closed.

Parameters:

cmd - the complete command line including the AT prefix and the termination character when and where needed.

crHandler - the CommandResponseHandler instance to handle the response to the command or null if notification of specific error, intermediate and final response codes are not requested.

dcHandler - the DataConnectionHandler instance to handle the data connection or null if notification of connection state is not requested.

Returns:

the opened data connection or null if no data connection has been opened.

Throws:

java.lang.NullPointerException - if cmd, crHandler or dcHandler is null.

com.oracle.deviceaccess.InvalidOperationException - if opening data connections is not supported by this device.

InvalidStateException - if in data mode or if a command is already being executed.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

java.lang.SecurityException - if the caller does not have the required permission.

sendCommand

java.lang.String sendCommand(java.lang.String cmd)
                             throws java.io.IOException,
                                    PeripheralNotAvailableException

Sends an AT command and wait for the response. If the command line includes payload text, it must be properly terminated with e.g. Ctrl-Z otherwise the operation may block. In which case it may be canceled by a call to abortCommand(java.lang.String).
Note that the return response string may include the command echo unless command echo has been disabled (such as with an ATE0 command).

Parameters:

cmd - the complete command line including the AT prefix and the termination character when and where needed.

Returns:

the response to the command.

Throws:

java.lang.NullPointerException - if cmd is null.

InvalidStateException - if in data mode or if a command is already being executed.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

sendCommand

void sendCommand(java.lang.String cmd,
               CommandResponseHandler handler)
                 throws java.io.IOException,
                        PeripheralNotAvailableException

Sends an AT command and handle the response asynchronously. The call will return immediately and the provided CommandResponseHandler instance will be invoked to handle the response when available. The command line may or may not include payload text (such as SMS body text); in which case the the provided CommandResponseHandler instance will be invoked to provide the additional input text (text prompt mode). If the command line includes payload text, it must be properly terminated with e.g. Ctrl-Z.

Parameters:

cmd - the complete command line including the AT prefix and the termination character when and where needed.

handler - the CommandResponseHandler instance to handle the response to the command.

Throws:

java.lang.NullPointerException - if cmd or handler is null.

InvalidStateException - if in data mode or if a command is already being executed.

java.io.IOException - if an IO error occurred.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

setUnsolicitedResponseHandler

void setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler)
                                   throws java.io.IOException,
                                          PeripheralNotAvailableException

Registers a handler for handling Unsolicited Result Code responses.

If handler is null then the previously registered handler will be removed.

Only one handler can be registered at a particular time.

Parameters:

handler - the UnsolicitedResponseHandler instance to handle Unsolicited Result Code responses.

Throws:

java.io.IOException - if an IO error occurred.

InvalidStateException - if handler is not null and a handler is already registered.

PeripheralNotAvailableException - if the peripheral is not currently available (has been closed).

close

void close()
           throws java.io.IOException

Closes and releases the underlying peripheral device, making it available to other applications. Once released, subsequent operations on that very same Peripheral instance will result in a PeripheralNotAvailableException being thrown.

This method has no effects if the peripheral device has already been closed.

Closing an ATDevice will also close the device's DataConnection and its InputStream and OutputStream.

Specified by:

close in interface Peripheral

Throws:

java.io.IOException - if an I/O error occurs.