The NFC Controller Interface (NCI) is used for interacting with an NFC controller (NFCC). This page describes the specifications of Android proprietary NCI commands.
NCI definitions
The Android proprietary NCI commands use the proprietary group ID (GID) 0xF
and the Android opcode identifier (OID) code space of 0xC.
Common packet format
The Android NCI packet format follows the NCI specification for control packets
using the proprietary Group_ID 0xFand Opcode_ID 0x0C. For each Android
proprietary message, the first byte of the packet payload must be set to the
Android opcode (0x0C). The Android control packets use Message_Type and
PBF for identifying commands, responses, and notifications similarly to
standard commands.
The Android packet format is shown in the following table:
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
Message_Type
|
PBF
|
Group_ID = 0xF (PROPRIETARY)
|
|||||
| reserved for future use (RFU) | Opcode_ID = 0x0C (ANDROID)
|
||||||
Payload_Length
|
|||||||
Android_Opcode_ID
|
|||||||
Android_Payload
|
|||||||
Assigned Android opcode identifiers are listed in the following table. The specification for each packet follows in the next sections.
Get capabilities command
The host uses NCI_ANDROID_GET_CAPS_CMD to query the list of Android
proprietary features supported by the NFCC. The NCI_ANDROID_GET_CAPS_CMD
command doesn't take any parameters.
The NFCC must respond with the NCI_ANDROID_GET_CAPS_RSP response with a status
of STATUS_OK and the list of supported capabilities and features.
If the NFCC doesn't support NCI_ANDROID_GET_CAPS_CMD, the host must assume
that the capabilities each take the default specified value. If a specified
capability isn't returned by the NFCC in the response, the host must assume that
the capability has the default specified value.
NCI_ANDROID_GET_CAPS_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
NCI_ANDROID_GET_CAPS_RSP
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification. | |||||
Android_Version
|
2 octets | Identifies the version of the Android requirements that is implemented by the NFCC. | |||||
| 0x0000 | Android 15 | ||||||
| Number of capabilities | 1 octet | Number (n) of supported capabilities | |||||
| Capabilities[0..n] | (m + 2) * n octets | Supported capabilities | |||||
| Type | 1 octet | The identifier of the capability | |||||
| Len | 1 octet | Length (m) of the value | |||||
| Value | m octets | The value of the capability | |||||
Android proprietary capabilities
| Capability name | ID | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|---|
| Observe mode | 0x00 | 1 octet | Support for the observe mode.
0x00 (default) - Doesn't support this feature. 0x01 - Supports the feature with RF deactivation from host (required for Android 15). 0x02 - Supports the feature without RF deactivation from host (required for Android 16 and higher). All other values are RFU. |
|||||
| Polling frame notification | 0x01 | 1 octet | Support for the polling frame notifications. 0x01 if supported, 0x00 (default) if not supported. All other values are RFU. | |||||
| Power saving mode | 0x02 | 1 octet | Support for the power saving mode. 0x01 if supported, 0x00 (default) if not supported. All other values are RFU. | |||||
| Auotransact polling loop filter | 0x03 | 1 octet | Support for polling loop filters in the firmware to bypass observe mode for specific patterns when observe mode is globally enabled.
0x00 (default) - Doesn't support this feature 0x01 - Supports polling loop filters All other values are RFU |
|||||
| Number of exit frame entries supported | 0x04 | 1 octet | Number of exit frame entries supported. A minimum of five exit frame entries are required. | |||||
| Reader mode annotation | 0x05 | 1 octet | Support for Reader mode annotation.
0x00 (default) - Doesn't support this feature. 0x01 - Supports this feature. All other values are RFU. |
|||||
| 0x06..0xFF | 0 octets | Reserved for future use | ||||||
Power saving command
To transition the NFCC to power saving mode, the host can use the
NCI_ANDROID_POWER_SAVING_CMD command. The NFCC must respond with
NCI_ANDROID_POWER_SAVING_RSP with a status code indicating success or failure.
While in power saving mode, the host must not send any command to the NFCC and the NFCC must not send any notification or response to the host. The NFCC or embeded Secure Element (eSE) can automatically accept incoming payment requests according to the routing configuration set before enabling the power saving mode.
To return to full power mode, the host can reset or reinitialize the NFCC.
NCI_ANDROID_POWER_SAVING_CMD
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Power saving mode | 1 octet | 0x00 | Disable power saving mode |
| 0x01 | Enable power saving mode |
NCI_ANDROID_POWER_SAVING_RSP
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |||||
Set observe mode command
To activate or deactivate observe mode, the host can use the
NCI_ANDROID_PASSIVE_OBSERVE_MODE_CMD command. The NFCC must respond with
NCI_ANDROID_PASSIVE_OBSERVE_MODE_RSP with a status code indicating success or
failure.
When the observe mode is disabled, the NFCC must implement the standard listen mode activity as per the Activity Technical Specification.
When the observe mode is active, the NFCC must not respond to any poll requests
during the polling loop in listen mode, until explicitly authorized by the host.
The NFCC must send the RF_FIELD_INFO_NTF notification (as defined by section
5.3 of the NCI
specification)
when it detects field activation. If poll mode discovery is active, the NFCC
must implement poll mode activity as per the Activity Technical
Specification.
The NFCC can cache the poll information so as to proceed immediately with device
activation as soon as the observe mode is deactivated.
The NFCC should turn off observe mode if the host shuts down for any reason (for example, out of battery or user initiated shutdown) so that SE transactions can proceed.
NCI_ANDROID_PASSIVE_OBSERVE_MODE_CMD
| Payload fields | Size | Value/description | |
|---|---|---|---|
| observe mode | 1 octet | 0x00 | Disable observe mode (default) |
| 0x01 | Enable observe mode |
NCI_ANDROID_PASSIVE_OBSERVE_MODE_RSP
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification. | |||||
Polling loop notification
The NFCC must send the NCI_ANDROID_POLLING_FRAME_NTF notification to the host
after each polling loop frame. When both the RF_FIELD_INFO_NTF and
NCI_ANDROID_POLLING_FRAME_NTF notifications are generated, the NFCC must send
NCI_ANDROID_POLLING_FRAME_NTF after RF_FIELD_INFO_NTF.
The NCI_ANDROID_POLLING_FRAME_NTF notification is independent of whether
observe mode is active or not. When observe mode is active, the NFCC must always
send a NCI_ANDROID_POLLING_FRAME_NTF notification before proceeding with the
transaction.
NCI_ANDROID_POLLING_FRAME_NTF
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Polling Data[0..n] | (m +3) * n octets | List of polling requests received since the last notification. Each result gives the type (technology) of the received requests and identifiable data from the request depending on the technology. | |||||
| Type | 1 octet | See frame types. | |||||
| Flags | 1 octet | See flag byte. | |||||
| Length | 1 octet | Length (m) of polling data report including timestamp and gain fields. | |||||
| Timestamp | 4 octets | Timestamp measured in milliseconds of the reception of the polling requests, big endian. | |||||
| Gain | 1 octet | Strength of the polling request.
0xFF indicates that the value is not available. |
|||||
| Data | m - 5 octets | Returns the identifiable data present in the polling request | |||||
Frame types
| Polling frame | Type | Size | Value/Description | |
|---|---|---|---|---|
| Remote field | 0x00 | 1 octet | 0x00 | Field off |
| 0x01 | Field on | |||
| 0x02..0xFF | RFU | |||
| NFC-A | 0x01 | n octets | Value must include an ISO 14443-3 command (for example, REQ or WUP) | |
| NFC-B | 0x02 | n octets | Value must include an AIF byte and an ISO 14443-3 command (for example, REQ or WUP) | |
| NFC-F | 0x03 | n octets | Value must include an ISO 14443-3 command (for example, REQ or WUP) | |
| NFC-V | 0x04 | n octets | Value must include an ISO 14443-3 command (for example, REQ or WUP) | |
| Unknown | 0x07 | n octets | Raw frame data | |
Flag byte definition
| Flags | ||||||||
|---|---|---|---|---|---|---|---|---|
| b0 | b1 | b2 | b3 | b4 | b5 | b6 | b7 | |
| 0 | Short frame | RFU | RFU | RFU | RFU | RFU | RFU | RFU |
| 1 | Long frame | |||||||
Query observe mode status command
To retrieve the current status of the passive order mode, the host can use the
NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_CMD command. The NFCC must respond
with NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_RSP with a status code
indicating success of failure.
NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |
| Technology Mask | 1 octet | Bit mask indicating which technologies observe mode is enabled for:
|
|
Set passive observer technologies command
To set passive observer technologies, the host can use the
NCI_ANDROID_SET_PASSIVE_OBSERVER_TECH_CMD command. This command enables or
disables observe mode for the specified technologies without requiring
RF_DEACTIVATE_CMD. The NFCC must respond with
NCI_ANDROID_SET_PASSIVE_OBSERVER_TECH_RSP with a status code indicating
success of failure.
NCI_ANDROID_SET_PASSIVE_OBSERVER_TECH_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Technology Mask | 1 octet | Bit mask indicating which technologies to enable observe mode for:
|
|||||
NCI_ANDROID_SET_PASSIVE_OBSERVER_TECH_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification. | |
Set passive observer exit frame command
To configure the observe mode exit frame table, the host can use the
NCI_ANDROID_SET_PASSIVE_OBSERVER_EXIT_FRAME_CMD command. This command
specifies RF frames that trigger an exit from observe mode. This command can
only be sent in RFST_IDLE. The NFCC must respond with
NCI_ANDROID_SET_PASSIVE_OBSERVER_EXIT_FRAME_RSP with a status code indicating
success of failure.
NCI_ANDROID_SET_PASSIVE_OBSERVER_EXIT_FRAME_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| More | 1 octet | 0x00 - Last message 0x01 - More messages to follow |
|||||
| Timeout | 2 octets | Timeout in ms to restore observe mode (little endian). | |||||
| Number of RF Frame entries | 1 octet | Number of RF Frame entry fields to follow (n). 0x00 resets the table. | |||||
| RF Frame entry [0..n] | (2+x)*n octets | ||||||
| Qualifier-Type | 1 octet | Defines frame type and matching options. | |||||
| Length of Value | 1 octet | Length 'x' of Value field. | |||||
| Value | x octets | Power State (1), Reference Data (n), Mask (n). 1 <= n <= 16. | |||||
NCI_ANDROID_SET_PASSIVE_OBSERVER_EXIT_FRAME_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |
Get passive observer exit frame command
To retrieve the current configuration of the observe mode exit frame table, the
host can use the NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_CMD command. The
NFCC must respond with NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_RSP,
followed by NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_NTF.
NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |
NCI_ANDROID_GET_PASSIVE_OBSERVER_EXIT_FRAME_NTF
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Number of observe mode exit frame entries | 1 octet | The number of observe mode exit frame entry fields to follow (n). | |
| Entry [0..n] | x+2 octets | Qualifier-Type (1), Length (1), Value (x). | |
Blank NCI command
To blank NCI, the host can use the NCI_ANDROID_BLANK_NCI_CMD command. The NFCC
must respond with NCI_ANDROID_BLANK_NCI_RSP with a status code indicating
success of failure.
NCI_ANDROID_BLANK_NCI_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Frame Length | 1 octet | Length of frame data | |||||
| Frame Data | n octets | Frame data | |||||
NCI_ANDROID_BLANK_NCI_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |
Set polling loop annotation command
To set polling loop annotation, the host can use the
NCI_ANDROID_SET_POLLING_LOOP_ANNOTATION_CMD command to fill the custom polling
frame table. This table defines custom RF frames to be inserted inside a
standard discovery loop. This command can only be sent in RFST_IDLE. The NFCC
must respond with NCI_ANDROID_SET_POLLING_LOOP_ANNOTATION_RSP with a status
code indicating success of failure.
NCI_ANDROID_SET_POLLING_LOOP_ANNOTATION_CMD
| Payload fields | Size | Value/description | ||
|---|---|---|---|---|
| Number of RF frame entries | 1 octet | Number of entries to follow (n), between 0 and 4. n=0 disables the feature. | ||
| RF frame entry [1..n] | 2+x octets | |||
| Qualifier-Type | 1 octet | Defines frame type, technology, and position in discovery loop. | ||
| Length | 1 octet | Length of Value (x). | ||
| Value | x octets | Waiting time (1 byte) and RF Frame (1-16 bytes). | ||
NCI_ANDROID_SET_POLLING_LOOP_ANNOTATION_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of the NCI Specification, | |
Query power saving command
To query power saving mode, the host can use the
NCI_ANDROID_QUERY_POWER_SAVING_CMD command. The NFCC must respond with
NCI_ANDROID_QUERY_POWER_SAVING_RSP with a status code indicating success of
failure.
NCI_ANDROID_QUERY_POWER_SAVING_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
NCI_ANDROID_QUERY_POWER_SAVING_RSP
| Payload fields | Size | Value/description | |
|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of NCI Specification, | |
Passive observer suspended notification
The NFCC must send the NCI_ANDROID_PASSIVE_OBSERVER_SUSPENDED_NTF notification
to the host when an exit frame is detected, causing observe mode to be
suspended.
NCI_ANDROID_PASSIVE_OBSERVER_SUSPENDED_NTF
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| Type | 1 octet | Frame type: 0x00=Type-A, 0x01=Type-B | |||||
| Length | 1 octet | Length of Value (n) | |||||
| Value | n octets | Received frame that matched an exit frame entry. | |||||
Passive observer resumed notification
The NFCC must send the NCI_ANDROID_PASSIVE_OBSERVER_RESUMED_NTF notification
to the host when the passive observer is resumed after a timeout or other
conditions.
NCI_ANDROID_PASSIVE_OBSERVER_RESUMED_NTF
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
Get polling loop annotation command
To read the NFCC's custom polling frame table, the host can use the
NCI_ANDROID_GET_POLLING_LOOP_ANNOTATION_CMD command. This command can only be
sent in RFST_IDLE. The NFCC must respond with
NCI_ANDROID_GET_POLLING_LOOP_ANNOTATION_RSP with a status code indicating
success or failure and the custom polling frame information.
NCI_ANDROID_GET_POLLING_LOOP_ANNOTATION_CMD
| Payload fields | Size | Value/description | |||||
|---|---|---|---|---|---|---|---|
| N/A | 0 octets | ||||||
NCI_ANDROID_GET_POLLING_LOOP_ANNOTATION_RSP
| Payload fields | Size | Value/description | ||
|---|---|---|---|---|
| Status | 1 octet | See status codes in table 140 of NCI Specification, | ||
| Number of RF frame entries | 1 octet | Number of entries to follow (n), between 0 and 4. n=0 disables the feature. | ||
| RF frame entry [1..n] | 2+x octets | Qualifier-Type | 1 octet | Defines frame type, technology, and position in discovery loop. |
| Length | 1 octet | Length of Value (x). | ||
| Value | x octets | Waiting time (1 byte) and RF Frame (1-16 bytes). | ||
Implementation
For reference implementations, see the following: