public interface ATDevice extends Peripheral
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
javax.deviceaccess.atcmd.csd
javax.deviceaccess.atcmd.psd
javax.deviceaccess.atcmd.voice
javax.deviceaccess.atcmd.sms
javax.deviceaccess.atcmd.sim
javax.deviceaccess.atcmd.phonebook
=true
javax.deviceaccess.atcmd.phonebook=true
. 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. 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)
. ATE0
command). 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.BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN, UNDEFINED_ID
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.
|
getID, getName, getProperties, isOpen
void abortCommand(java.lang.String abortSequence) throws java.io.IOException, PeripheralNotAvailableException
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.abortSequence
- the character sequence for aborting; if null
the ESC
(abort) character is sent out by
default.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).void escapeToCommandMode() throws java.io.IOException, PeripheralNotAvailableException
"+++"
escape sequence.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).int getMaxCommandLength() throws java.io.IOException, PeripheralNotAvailableException
java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).boolean isConnected() throws java.io.IOException, PeripheralNotAvailableException
true
if connected; false
otherwise.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).boolean isInCommandMode() throws java.io.IOException, PeripheralNotAvailableException
true
if in command mode; false
otherwise.java.io.IOException
- if an IO error occurred.PeripheralNotAvailableException
- if the peripheral is not currently available (has been closed).DataConnection openDataConnection(java.lang.String cmd, CommandResponseHandler crHandler, DataConnectionHandler dcHandler) throws java.io.IOException, PeripheralNotAvailableException
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.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.null
if no data connection has been opened.java.lang.NullPointerException
- if cmd
, crHandler
or dcHandler
is null
.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.java.lang.String sendCommand(java.lang.String cmd) throws java.io.IOException, PeripheralNotAvailableException
Ctrl-Z
otherwise the operation may block. In which case it may be canceled by a call
to abortCommand(java.lang.String)
. ATE0
command).cmd
- the complete command line including the AT
prefix and the termination character when and where
needed.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).void sendCommand(java.lang.String cmd, CommandResponseHandler handler) throws java.io.IOException, PeripheralNotAvailableException
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
.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.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).void setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler) throws java.io.IOException, PeripheralNotAvailableException
handler
is null
then the previously registered handler will be removed.
Only one handler can be registered at a particular time.handler
- the UnsolicitedResponseHandler
instance to handle Unsolicited Result Code responses.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).void close() throws java.io.IOException
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
.close
in interface Peripheral
java.io.IOException
- if an I/O error occurs.Copyright (c) 2012, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.