Skip Headers
Oracle® Java ME Embedded Device Access API Guide
Release 3.3
  Go To Table Of Contents
Go To Index


3 AT Commands

The 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);

This is an example of using the name and interface, returns as either an ATDevice or an ATModem object.

 ATDevice device = (ATDevice)"MODEM", ATDevice.class,
     new String[] { "javax.deviceaccess.atcmd.psd=true",
    "javax.deviceaccess.atcmd.sms=true" }); 
 ATModem device = (ATModem)"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.


When done, the application should call the Peripheral.close() method to release AT device.


Example 3-1 shows how to use the AT Commands API to send an SMS message:

Example 3-1 Using the AT Commands API

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), 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 {
         } catch (IOException ex) {
             // Ignored

AT devices are opened by invoking one of the 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

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:


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

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:

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.

The DataConnectionHandler Interface

The DataConnectionHandler interface defines methods for handling connection state changes.

There are two methods in this interface.

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.