The com.oracle.deviceaccess.atcmd
package contains interfaces and classes for controlling data communication equipment such as a modem or a cellular module using AT commands. AT commands for GSM phone or modem are standardized through ETSI GSM 07.07 and ETSI GSM 07.05 specifications. A typical modem or an cellular module supports most of its features through AT commands and many manufactures provide additional features by adding proprietary extensions to the AT commands set.
In this specification, a device that can be controlled using AT commands is generically referred to as an AT device. To control a specific AT device, an application should first open and obtain an ATDevice
or ATModem
instance for the device using its numerical ID, name, type (interface) and properties:
This example obtains an ATDevice
using its ID:
ATDevice device = (ATDevice) PeripheralManager.open(15);
This is an example of using the name and interface, returns as either an ATDevice
or an ATModem
object.
ATDevice device = (ATDevice) PeripheralManager.open("MODEM", ATDevice.class, new String[] { "javax.deviceaccess.atcmd.psd=true", "javax.deviceaccess.atcmd.sms=true" }); ATModem device = (ATModem) PeripheralManager.open("MODEM", ATModem.class, new String[] { "javax.deviceaccess.atcmd.psd=true", "javax.deviceaccess.atcmd.sms=true" });
Once the peripheral opened, the application can issue AT commands to the peripheral using methods of the ATDevice
interface such as the sendCommand()
methods.
device.sendCommand("AT\n");
When done, the application should call the Peripheral.close()
method to release AT device.
device.close();
Example 3-1 shows how to use the AT Commands API to send an SMS message:
Example 3-1 Using the AT Commands API
import com.oracle.deviceaccess.PeripheralManager; import com.oracle.deviceaccess.PeripheralNotAvailableException; import com.oracle.deviceaccess.PeripheralNotFoundException; import com.oracle.deviceaccess.PeripheralTypeNotSupportedException; import com.oracle.deviceaccess.atcmd.ATDevice; import com.oracle.deviceaccess.atcmd.CommandResponseHandler; import java.io.IOException; public class SMSExample { public static final int SUBMITTED = 1; public static final int SENT = 2; public static final int ERROR = 3; private ATDevice modem = null; private int status = 0; private class SMSHandler implements CommandResponseHandler { String text; public SMSHandler(String text) { this.text = text; } public String processResponse(ATDevice modem, String response) { // Assume that command echo has been previously disabled // (such as with an ATE0 command). if (response.equals("> \n")) { // Prompt for text return text; } else if (response.equals("OK\n")) { status = SENT; // Sent succesfully } else if (response.indexOf("ERROR") >= 0) { status = ERROR; // Failed to send } return null; } } public boolean sendSMS(final String number, final String text) { // Acquire a modem with "sms" properties try { if (modem == null) { modem = (ATDevice) PeripheralManager.open(null, ATDevice.class, new String[] { "javax.deviceaccess.atcmd.sms=true" }); } // Send SMS command SMSHandler sh = new SMSHandler(text); modem.sendCommand("AT+CMGS=\"" + number + "\"\n", sh); status = SUBMITTED; return true; // Submitted succesfully } catch (IOException ex) { } catch (PeripheralNotFoundException ex) { } catch (PeripheralTypeNotSupportedException ex) { } catch (PeripheralNotAvailableException ex) { } return false; } public int getStatus() { return status; } public void close() { if (modem != null) { try { modem.close(); } catch (IOException ex) { // Ignored } } } }
AT devices are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open()
methods. The permissions shown in Table 3-1 allow access to be granted to AT devices as a whole or to only some of their protected functions. These permissions must be requested in the JAD file under MIDlet-Permissions
or MIDlet-Permissions-Opt
, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permissions may be allowed for all applications in the untrusted
domain of the security policy file (policy.txt
).
Table 3-1 Permissions for Using the AT Command APIs
Permissions | Description |
---|---|
Access to AT devices and modems (as a whole) |
|
Opening data connections |
The ATDevice
interface provides methods for controlling data communication equipment. Each AT device is identified by a numerical ID and optionally by a name and by a set of capabilities (properties), as shown in Table 3-2.
Table 3-2 Properties of the ATDevice Interface
Permissions | Description |
---|---|
|
Supports access to configuration, control, and identification commands. |
|
Supports access to circuit switched data (CSD) related AT commands. |
|
Supports access to packet switched data, such as GPRS or EDGE, related AT commands. |
|
Supports access to voice call related AT commands. |
|
Supports access to SMS related AT commands. |
|
Supports access to SIM related AT commands. |
|
Supports access to phonebook related AT commands. |
This list may be extended to designate other, possibly proprietary, capabilities (properties). As per 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 it becomes 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, such as OK
or ERROR
, indicates the completion of command and the readiness for accepting new commands. An intermediate result code (such as CONNECT
) is a report of the progress of a command. An unsolicited result code (such as 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 echoes, 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 that 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 it is needed.
The ATDevice
interface contains several command-related methods.
void sendCommand(java.lang.String cmd, CommandResponseHandler handler) throws java.io.IOException, PeripheralNotAvailableException
This method 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.
java.lang.String sendCommand(java.lang.String cmd) throws java.io.IOException,PeripheralNotAvailableException
This method sends an AT command and waits for the response. If the command line includes payload text, it must be properly terminated, otherwise the operation may block. A blocked call 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.
void abortCommand(java.lang.String abortSequence) throws java.io.IOException,PeripheralNotAvailableException
This method aborts the currently executing command by sending the provided abortSequence
string. Abortion depends on the command's definition, or more accurately, if it supports cancellation. Note that calling this method does not guarantee abortion of the currently executing command. It only aborts if the command supports cancellation and it is currently in a proper state for it.
void escapeToCommandMode() throws java.io.IOException, PeripheralNotAvailableException
When in data mode, calling this method will try to switch to command mode such as sending "+++" escape sequence.
boolean isInCommandMode() throws java.io.IOException, PeripheralNotAvailableException
This method queries if this AT device is in command mode. When the device is in command mode, a new command can be sent, provided no command is currently being processed.
boolean isConnected() throws java.io.IOException, PeripheralNotAvailableException
This method queries if this AT device has an opened data connection.
void setUnsolicitedResponseHandler(UnsolicitedResponseHandler handler) throws java.io.IOException, PeripheralNotAvailableException
This method 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.
DataConnection openDataConnection(java.lang.String cmd, CommandResponseHandler crHandler, DataConnectionHandler dcHandler) throws java.io.IOException, PeripheralNotAvailableException
This method 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 the error or intermediate and final result response, respectively, when available. Finally, the connection will be subsequently closed.
int getMaxCommandLength() throws java.io.IOException, PeripheralNotAvailableException
This method 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.
This method closes and releases the underlying peripheral device, making it available to other applications. Once released, subsequent operations on the same Peripheral
instance will throw a PeripheralNotAvailableException
.This method has no effects if the peripheral device has already been closed. Note that closing an ATDevice
will also close the device's DataConnection
as well as its InputStream
and OutputStream
.
The ATModem
provides methods for controlling data communication equipment such as a modem or a cellular module using AT commands and modem control signals. It extends the ATDevice
and ModemSignalsControl
interfaces, but otherwise does not define any methods of its own.
The CommandResponseHandler
interface defines methods for handling responses to AT commands. When commands are submitted asynchronously using the sendCommand(String, CommandResponseHandler)
method, a CommandResponseHandler
instance must be provided to handle the response when it becomes available.
Only information text, final result code, and intermediate result code responses can be handled by a CommandResponseHandler
instance. Unsolicited result code responses can be handled by a UnsolicitedResponseHandler
instance.
The CommandResponseHandler
interface consists of only one method:
The DataConnection
interface provides methods for retrieving the underlying input and output streams of a data connection opened by issuing an AT command (such as ATD).
There are three methods in this interface.
java.io.InputStream getInputStream() throws java.io.IOException
This method returns this data connection's input stream. The same InputStream
instance is returned upon subsequent calls. Note that if this data connection's input stream has been previously closed, the method returns the same closed input stream without attempting to re-open it.
java.io.OutputStream getOutputStream() throws java.io.IOException
This method returns this data connection's output stream. The same OutputStream
instance is returned upon subsequent calls. Note that if this data connection's output stream has been previously closed, the method returns the same closed output stream without attempting to re-open it.
void close() throws java.io.IOException
This method closes this data connection. When a connection has been closed, accessing any of its methods that involve an I/O operation will throw an IOException
. Closing an already closed connection has no effect. Closing a connection will also close the connection's InputStream
and OutputStream
.
The DataConnectionHandler
interface defines methods for handling connection state changes.
There are two methods in this interface.
void handleOpenedDataConnection(ATDevice atDevice, DataConnection connection)
This method is invoked to handle a data connection when first opened.
void handleClosedDataConnection(ATDevice atDevice, DataConnection connection)
This method is invoked to handle a data connection when it has been closed.
The UnsolicitedResponseHandler
interface defines methods for handling unsolicited result code responses from an AT device. Unsolicited result codes (such as RING
) indicate the occurrence of an event not directly associated with the issuance of an AT command. To receive unsolicited result codes an UnsolicitedResponseHandler
instance must be registered with the AT device using the ATDevice.setUnsolicitedResponseHandler(UnsolicitedResponseHandler)
method.
The UnsolicitedResponseHandler
class consists of one method.