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.
| Android OID | Message type | Message name |
|---|---|---|
| 0x00 | NCI_MT_CMD | NCI_ANDROID_GET_CAPS_CMD |
| NCI_MT_RSP | NCI_ANDROID_GET_CAPS_RSP | |
| 0x01 | NCI_MT_CMD | NCI_ANDROID_POWER_SAVING_CMD |
| NCI_MT_RSP | NCI_ANDROID_POWER_SAVING_RSP | |
| 0x02 | NCI_MT_CMD | NCI_ANDROID_PASSIVE_OBSERVE_MODE_CMD |
| NCI_MT_RSP | NCI_ANDROID_PASSIVE_OBSERVE_MODE_RSP | |
| 0x03 | NCI_MT_NTF | NCI_ANDROID_POLLING_FRAME_NTF |
| 0x04 | NCI_MT_CMD | NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_CMD |
| NCI_MT_RSP | NCI_ANDROID_QUERY_PASSIVE_OBSERVER_STATUS_RSP |
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 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 or 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 | |||||
| 0x04..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 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 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 NCI Specification, | |
| observe mode | 1 octet | 0x00 | Observe mode disabled |
| 0x01 | Observe mode enabled | ||