jdk.dio.atcmd

Interface ATDevice

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, Device<ATDevice>

All Known Subinterfaces:

ATModem

public interface ATDevice
extends Device<ATDevice>

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

An AT device may be identified by the numeric ID, by the name (if any defined) and by an optional set of capabilities (properties) that correspond to its registered configuration. An ATDevice instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name and capabilities.
The defined property keywords include jdk.dio.atcmd.config, jdk.dio.atcmd.csd, jdk.dio.atcmd.psd, jdk.dio.atcmd.voice, jdk.dio.atcmd.sms, jdk.dio.atcmd.sim, jdk.dio.atcmd.phonebook. Their meaning is defined as follows:

jdk.dio.atcmd.config

Supports access to configuration, control and identification commands.

jdk.dio.atcmd.csd

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

jdk.dio.atcmd.psd

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

jdk.dio.atcmd.voice

Supports access to voice call related AT commands.

jdk.dio.atcmd.sms

Supports access to SMS related AT commands.

jdk.dio.atcmd.sim

Supports access to SIM related AT commands.

jdk.dio.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: jdk.dio.atcmd.phonebook=true.
When a capability is not supported by an AT device negatively asserting the boolean capability is optional.

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.

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).
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 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 close method to close the AT device. Any further attempt to use an ATDevice instance which has been closed will result in a ClosedDeviceException been thrown.

Opening an ATDevice instance is subject to permission checks (see ATPermission).

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.

Since:

1.0

See Also:

ATPermission, CommandResponseHandler, UnsolicitedResponseHandler, DataConnection

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
void	abortCommand(java.lang.String abortSequence) Deprecated. As of 1.1, replaced by tryAbortCommand.
void	close() Closes this device, relinquishing the underlying device resource and making it available to other applications.
void	escapeToCommandMode() Deprecated. As of 1.1, replaced by tryEscapeToCommandMode.
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.
java.lang.String	tryAbortCommand(java.lang.String abortSequence) Aborts the currently executing command by sending the provided abortSequence.
java.lang.String	tryEscapeToCommandMode() 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.

Methods inherited from interface jdk.dio.Device

getByteOrder, getDescriptor, isOpen, tryLock, unlock

Method Detail

abortCommand

@Deprecated
void abortCommand(java.lang.String abortSequence)
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Deprecated. As of 1.1, replaced by tryAbortCommand.

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.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

tryAbortCommand

java.lang.String tryAbortCommand(java.lang.String abortSequence)
                                 throws java.io.IOException,
                                        UnavailableDeviceException,
                                        ClosedDeviceException

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. The response from the AT device is returned; the application should use this response to determine if the command was successfully aborted or not. An OK result code is typically returned upon success but the response may vary.

Parameters:

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

Returns:

the response.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

Since:

1.1

escapeToCommandMode

@Deprecated
void escapeToCommandMode()
                         throws java.io.IOException,
                                UnavailableDeviceException,
                                ClosedDeviceException

Deprecated. As of 1.1, replaced by tryEscapeToCommandMode.

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 some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

tryEscapeToCommandMode

java.lang.String tryEscapeToCommandMode()
                                        throws java.io.IOException,
                                               UnavailableDeviceException,
                                               ClosedDeviceException

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. The response from the AT device is returned; the application should use this response to determine if the AT device successfully escaped to command mode. An OK result code is typically returned upon success but the response may vary.

Returns:

the response.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

Since:

1.1

getMaxCommandLength

int getMaxCommandLength()
                        throws java.io.IOException,
                               UnavailableDeviceException,
                               ClosedDeviceException

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 some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

isConnected

boolean isConnected()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Queries if this AT device has an opened data connection.

Returns:

true if connected; false otherwise.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

isInCommandMode

boolean isInCommandMode()
                        throws java.io.IOException,
                               UnavailableDeviceException,
                               ClosedDeviceException

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 some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

openDataConnection

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

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.UnsupportedOperationException - if opening data connections is not supported by this device.

java.lang.IllegalStateException - if in data mode or if a command is already being executed.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device 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,
                                    UnavailableDeviceException,
                                    ClosedDeviceException

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.
The returned 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.IllegalStateException - if in data mode or if a command is already being executed.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

sendCommand

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

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 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.

java.lang.IllegalStateException - if in data mode or if a command is already being executed.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

setUnsolicitedResponseHandler

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

Registers a handler for handling Unsolicited Result Code responses.

If this ATDevice is open in DeviceManager.SHARED access mode the handlers registered by all the applications sharing the underlying device will get invoked to handle 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.lang.NullPointerException - if handler is null.

java.lang.IllegalStateException - if handler is not null and a handler is already registered.

ClosedDeviceException - if the device has been closed.

java.io.IOException - if some other I/O error occurs.

close

void close()
           throws java.io.IOException

Closes this device, relinquishing the underlying device resource and making it available to other applications. Upon closing the underlying device resource MUST be set to the state (power state and configuration) it was in prior to opening it.

Once closed, subsequent operations on that very same Device instance will result in a ClosedDeviceException being thrown.

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

Closing an ATDevice will also close the device's DataConnection.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.nio.channels.Channel

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface Device<ATDevice>

Throws:

java.io.IOException - if some other I/O error occurs.