3 AT Commands

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
`com.oracle.deviceaccess.atcmd`	Access to AT devices and modems (as a whole)
`com.oracle.deviceaccess.atcmd.ATDevice.openDataConnection`	Opening data connections

The ATDevice Interface

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
`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 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.
void close()

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 Interface

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

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:

java.lang.String processResponse(ATDevice atDevice, java.lang.String response)

This method is invoked to process an information text, final result code or intermediate result code response.

The DataConnection Interface

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

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 Class

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.

void processResponse(ATDevice atDevice,java.lang.String code)

This method is invoked to process an unsolicited result code response.