org.opennfc.hardware
Interface NfcController

public interface NfcController

This class controls the hardware features of the NFC Controller. Only a system-level application should use this class.

Since:

Open NFC 4.0

reset

void reset(NfcController.Mode mode)
           throws NfcException

Resets the NFC controller.

Parameters:

mode - the NFC controller mode be entered after the reset operation:

• Mode.MAINTENANCE for the maintenance mode, or
• Mode.ACTIVE for the active mode.

Throws:

IllegalArgumentException - if mode is null or has a wrong value.

IllegalStateException - reset() cannot be called while a reset is already pending.

NfcException - an error occured with the NFC Controller.

getFirmwareInfo

String getFirmwareInfo(byte[] firmware)
                       throws NfcException

Returns the name and the versio of a Firmware.

Parameters:

firmware - the firmware buffer.

Returns:

the property value.

Throws:

IllegalArgumentException - if firmware is null.

NfcException - if an error is detected in the firmware format.

See Also:

firmwareUpdate()

firmwareUpdate

void firmwareUpdate(byte[] firmware,
                    NfcController.Mode mode)
                    throws NfcException

Updates the firmware and/or the configuration of the NFC controller.

The NFC Controller firmware may be updated with a new version of the firmware software. The firmware file shall be provided by the NFC Controller manufacturer.

After a successful update operation, the NFC Controller is rebooted. The persistent information is reset to its default value.

The update operation may fail if it is not completed (due to a power loss for example) or if the new firmware is not validated by the NFC Controller (wrong format, wrong version, or wrong signature). In case of failed update, the previous version of the firmware or its persistent data may be corrupted. This may cause the NFC Controller invalidating the current firmware and the NFC Controller mode becomes Mode.NO_FIRMWARE. If the previous firmware and its persistent data are not corrupted, the NFC Controller is rebooted in the mode Mode.MAINTENANCE or Mode.ACTIVE.

The method getFirmwareInfo() retrieves the information of a firmware file.

The firmware update operation may require several seconds to complete. The method getFirmwareUpdateState() may be used to follow the progression of the operation.

Important Note

If a UICC is connected by SWP to the NFC Controller, the UICC should be rebooted after a Firmware update. Rebooting the UICC may require rebooting the NFC device. The explanation is the following: When a firmware is downloaded in the NFC Controller, the UICC configuration stored in the NFC Controller is lost. There is no message in the ETSI specification to inform the UICC of this configuration loss. The UICC can rebuild the configuration only during UICC power up sequence.

The firmware update is provided in firmware. The format of this buffer is proprietary.

firmwareUpdate() should be called from one of the maintenance modes.

Parameters:

firmware - the firmware binary value.

mode - the NFC controller mode to be entered after the update operation:

• Mode.MAINTENANCE for the maintenance mode, or
• Mode.ACTIVE for the active mode.

Throws:

IllegalArgumentException - if firmware is null.

IllegalArgumentException - if mode is null or has a wrong value.

IllegalStateException - firmwareUpdate() is called while the NFC controller is not in one the maintenance modes.

NfcException - with one of the following error code:

• NfcErrorCode.TIMEOUT A timeout occured during the communication with the NFC controller.
• NfcErrorCode.BAD_FIRMWARE_FORMAT An error is detected in the format of the firmware update buffer.
• NfcErrorCode.BAD_FIRMWARE_VERSION The firmware is not compliant with the NFC Controller type, with the NFC HAL Binding or with the current configuration of the NFC Controller.
• NfcErrorCode.BAD_FIRMWARE_SIGNATURE The signature of the firmware update buffer is not valid.
• NfcErrorCode.DURING_FIRMWARE_BOOT The new firmware does not boot correctly.

See Also:

getFirmwareUpdateState(), getFirmwareInfo()

getFirmwareUpdateState

int getFirmwareUpdateState()

Returns the current progress status of a firmware update operation.

Returns:

The progression value is the current number of bytes of the firmware buffer downloaded in the NFC Controller. This value is zero if no update operation is pending.

See Also:

firmwareUpdate()

getMode

NfcController.Mode getMode()

Returns the current mode of the NFC controller.

Returns:

The current mode as described in NFC Controller Modes.

registerExceptionEventHandler

void registerExceptionEventHandler(NfcControllerExceptionEventHandler handler)
                                   throws NfcException

Starts monitoring the NFC controller exceptions.

After a successful registration, the handler is called each time an exception is detected. unregisterExceptionEventHandler() should be called to unregister the listener.

Parameters:

handler - the NfcControllerExceptionEventHandler whose NfcControllerExceptionEventHandler.onExceptionOccured() method will be called when an exception is detected.

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is already registered.

NfcException - in case of a registration error occurs.

See Also:

unregisterExceptionEventHandler(), NfcControllerExceptionEventHandler

unregisterExceptionEventHandler

void unregisterExceptionEventHandler(NfcControllerExceptionEventHandler handler)

Stops monitoring NFC controller exceptions registered with registerExceptionEventHandler(org.opennfc.hardware.NfcControllerExceptionEventHandler).

Parameters:

handler - the handler in case of exception

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is not already registered.

See Also:

registerExceptionEventHandler()

selfTest

void selfTest()
              throws NfcException

Performs self-test of the NFC controller.

The test is executed and the method returns without exception if the test succeeds. The self-test must be executed when the NFC Controller is in maintenance mode. The precise description of the self test is provided in the documentation of the NFC Controller.

Throws:

NfcException - if the test fails or if an error occurs.

productionTest

byte[] productionTest(byte[] testCommand)
                      throws NfcException

Performs a NFC controller production test.

The test parameters are given in a buffer. A result buffer is provided to receive a result. Production tests do not always return a test result. The test result is obtained from the measurements performed by external test devices.

Production tests shall be executed when the NFC Controller is in maintenance mode. Any ongoing production test should be stopped before starting a new test.

The precise description of the production tests and the associated parameters is provided in the release notes of the NFC HAL implementation for each NFC Controller.

Parameters:

testCommand - the test command to be executed.

Returns:

the test command answer.

Throws:

NfcException - if an error occurs

switchStandbyMode

void switchStandbyMode(boolean standbyOn)
                       throws NfcException

Switches the forced standby mode on or off.

Calling switchStandbyMode() initiates the switch to the active mode or to the standby mode. The NFC Controller may need some time to switch to the requested mode after the return of the method. See NFC Controller Modes.

Should be called in one of the following modes:

• Mode.ACTIVE,
• Mode.SWITCH_TO_STANDBY,
• Mode.STANDBY, or
• Mode.SWITCH_TO_ACTIVE.

Parameters:

standbyOn - if forced standby mode is enabled or not.

Throws:

IllegalStateException - if the NFC Controller is not in a valid mode to call this method.

NfcException - if the standby mode is not supported by the NFC Controller.

registerCardCollisionHandler

void registerCardCollisionHandler(CollisionEventHandler handler)
                                  throws NfcException

Registers a new card collision handler.

A collision is detected when the following conditions are met:

• the NFC Device is listening on the NFC RF,
• a collision is detected, and
• collision-resolution is not supported or does not apply.

Then, an event is sent to the listener. The NFC Device firmware should handle this event and should display a message to the user such as "Multiple cards or tags detected, please present only one".

After a successful registration, the handler is called each time a new card collision is detected. unregisterCardCollisionHandler() should be called to unregister the listener.

Parameters:

handler - the CollisionEventHandler whose CollisionEventHandler.onCollisionDetected() method will be called when a collision has been detected.

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is already registered.

NfcException - in case of a registration error occurs.

See Also:

unregisterCardCollisionHandler(), CollisionEventHandler

unregisterCardCollisionHandler

void unregisterCardCollisionHandler(CollisionEventHandler handler)

Unregisters a card collision handler registered with registerCardCollisionHandler(org.opennfc.hardware.CollisionEventHandler).

Parameters:

handler - the card detection handler.

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is not already registered.

See Also:

registerCardCollisionHandler()

registerUnknownCardHandler

void registerUnknownCardHandler(boolean startDetection,
                                UnknownCardEventHandler handler)
                                throws NfcException

Registers a new unknown card handler.

After a successful registration, the handler is called each time a new new unknown card is detected. unregisterUnknownCardHandler() should be called to unregister the listener.

Parameters:

startDetection - forces a permanent detection.

handler - the UnknownCardEventHandler whose UnknownCardEventHandler.onUnknownCardDetected() method will be called when an unknown card has been presented.

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is already registered.

NfcException - in case of a registration error occurs.

See Also:

unregisterUnknownCardHandler(), UnknownCardEventHandler

unregisterUnknownCardHandler

void unregisterUnknownCardHandler(UnknownCardEventHandler handler)

Unregisters a unknown card handler registered with registerUnknownCardHandler(boolean, org.opennfc.hardware.UnknownCardEventHandler).

Parameters:

handler - the unknown card handler.

Throws:

IllegalArgumentException - if handler is null.

IllegalArgumentException - if handler is not already registered.

See Also:

registerUnknownCardHandler()