Fork for the GitHub

Embed: (wiki syntax)

« Back to documentation index

NDEF Handover library

NDEF Handover library

This module is used to manage the NDEF Handover messages, to negociate the switch to a non-nfc protocol of communication. More...

Enumerations

enum  Ndef_Handover_ac_cps_t { NDEF_HANDOVER_AC_CPS_INACTIVE = 0x0, NDEF_HANDOVER_AC_CPS_ACTIVE = 0x1, NDEF_HANDOVER_AC_CPS_ACTIVATING = 0x2, NDEF_HANDOVER_AC_CPS_UNKNOWN = 0x3 }
 

Enumerates the NFC Forum Power States possible values.

More...

Functions

uint16_t NDEF_ReadAuxData (uint8_t aux_data_nb, Ndef_Handover_alternative_carrier_t *pAC, sRecordInfo_t *pRecord)
 This function searches the NDEF message to retrieve the nth Auxiliary Data record if present.
uint16_t NDEF_ReadAC (uint8_t ac_nb, Ndef_Handover_t *pHandover, Ndef_Handover_alternative_carrier_t *pAC)
 This function reads the NDEF message and retrieves the nth Alternative Carrier record if present.
uint16_t NDEF_ReadHandover (sRecordInfo_t *pRecord, Ndef_Handover_t *pHandover)
 This function reads a record and retrieves the Handover information if present.
uint16_t NDEF_CreateHandover (Ndef_Handover_t *pHandover, sRecordInfo_t *pRecord)
 This function prepares the Handover record with the data given in the Handover structure.
uint16_t NDEF_AddAlternativeCarrier (Ndef_Handover_alternative_carrier_t *pAC, char *CarrierDataRef, char **AuxDataRefID, sRecordInfo_t *pRecord, I2C *mi2cChannel)
 This function adds an Alternative Carrier record to a Handover record using the data given in the AC structure.
uint32_t NDEF_GetACDataLength (Ndef_Handover_alternative_carrier_t *pAC, char *CarrierDataRef, char **AuxDataRefID)
 This function returns the length of an Alternative Carrier record data (excluding the record metadata).
uint16_t NDEF_WriteHandover (sRecordInfo_t *pRecord, uint8_t *pNdef, I2C *mi2cChannel)
 This function writes the Handover record into the memory.

Detailed Description

This module is used to manage the NDEF Handover messages, to negociate the switch to a non-nfc protocol of communication.

The NDEF Handover process is described by the NFC Forum Connection Handover specification. It consists in a specific NDEF message construct, as:

  • NDEF 1st record: Handover Request or Handover Select record
    • Version
    • Collision Resolution (nested record, optional)
      • Random number
    • Alternative Carrier 1 (nested record)
      • Power state
      • Reference Data
      • Auxiliary Data Reference 1
      • ...
      • Auxiliary Data Reference N
    • ...
    • Alternative Carrier N (nested record)
  • NDEF record 2+: Alternative Carrier or Auxiliary Data: Connection details for one of the AC (record ID is the AC Reference Data or an Auxiliary Data Reference).
  • ...
  • NDEF record N: Alternative Carrier or Auxiliary Data: Connection details for one of the AC (record ID is the AC Reference Data or an Auxiliary Data Reference). _________________

NDEF Handover Library usage:

Static Handover

The Static Handover is used when a device is only equipped with a NFC Tag (no peer-to-peer) to directly propose a set of Alternative Carriers (ACs: bluetooth, wifi,...) without running the full handover request-select process.
The Handover Select record use in that case is similar to the one used during a regular Handover negociation.
1. Declare & initialize an instance of `Ndef_Handover_t`, such as:

Ndef_Handover_t wHandover = {.type = NDEF_HANDOVER_SELECT_TYPE, .version = NDEF_HANDOVER_VERSION_1_2}; 2. Declare a `sRecordInfo_t` instance:

sRecordInfo_t HandoverRecord; 3. Call the `NDEF_CreateHandover` function, to start preparing the Handover Select record

NDEF_CreateHandover(&wHandover,&HandoverRecord); 4. Call the `NDEF_AddAlternativeCarrier` for each Alternative Carrier (such as Bluetooth, Wifi, ...) 5. Declare and initialize as many `Ndef_Handover_alternative_carrier_t` instances as the number of non-NFC protocol available. And then call the `NDEF_AddAlternativeCarrier` for each of them.

Ndef_Handover_alternative_carrier_t wAC_BREDR = {.cps = NDEF_HANDOVER_AC_CPS_ACTIVE, .aux_data_ref_count = 0}; Ndef_Handover_alternative_carrier_t wAC_BLE = {.cps = NDEF_HANDOVER_AC_CPS_ACTIVE, .aux_data_ref_count = 0}; Ndef_Handover_alternative_carrier_t wAC_Wifi = {.cps = NDEF_HANDOVER_AC_CPS_ACTIVE, .aux_data_ref_count = 0};

NDEF_AddAlternativeCarrier(&wAC_BREDR,"urn:nfc:handover:bredr", NULL,&HandoverRecord ); NDEF_AddAlternativeCarrier(&wAC_BLE,"urn:nfc:handover:ble", NULL,&HandoverRecord ); NDEF_AddAlternativeCarrier(&wAC_Wifi,"urn:nfc:handover:wifi", NULL,&HandoverRecord );

Note:
1. In this example a single `Ndef_Handover_alternative_carrier_t` could have been used, as the parameters are the same for all ACs. 2. If more than one NDEF record is required to provide the AC connection details, the `aux_data_ref_count` must specify the number of additional records.

Ndef_Handover_alternative_carrier_t wAC_Wifi = {.cps = NDEF_HANDOVER_AC_CPS_ACTIVE, .aux_data_ref_count = 2}; Then, it's required to initialize an array of pointers to these Auxiliary Data Reference, as:

char *aux_data_ref1 = "urn:nfc:handover:wifi:aux_data_ref1"; char *aux_data_ref2 = "urn:nfc:handover:wifi:aux_data_ref2"; char *wifi_aux_ref_data_array[2] = {aux_data_ref1,aux_data_ref2}; And then provide this array as the 3rd argument to the 'NDEF_AddAlternativeCarrier' function:

NDEF_AddAlternativeCarrier(&wAC_Wifi,"urn:nfc:handover:wifi", wifi_aux_ref_data_array,&HandoverRecord ); 6. Call the `NDEF_WriteHandover` function to finalize the NDEF message and write it to the tag.

NDEF_WriteHandover(&HandoverRecord, NDEF_Buffer); 7. Then call other functions (from the libNDEF or not) to add records, describing the Alternative Carriers, to the NDEF message:

NDEF_AppendBluetoothOOB ( &w_ble_oob, "urn:nfc:handover:ble" ); NDEF_AppendBluetoothOOB ( &w_bredr_oob, "urn:nfc:handover:bredr" );

Note:
1. The ID of these additional records (2nd argument in the above example) must match the Data Reference provided within the Handover record. 2. If Auxiliary Data References are expected they must also be added to the NDEF message, with their ID matching the ID provided to the Alternative Carrier record.

Reading through a Handover Request message

1. Read the 1st record of the NDEF message:

sRecordInfo_t rRecord; NDEF_ReadNDEF(NDEF_Buffer); NDEF_IdentifyBuffer(rRecord,NDEF_Buffer); 2. Decode the handover:

Ndef_Handover_t rHandover; NDEF_ReadHandover(&rRecord , &rHandover ); 3. Read all Alternative Carrier records, and their Auxiliary Data References if any.

uint8_t ac_index, aux_index; for(ac_index=0;ac_index<rHandover.nb_alternative_carrier;ac_index++) { Ndef_Handover_alternative_carrier_t rAC; NDEF_ReadAC( ac_index, &rHandover , &rAC ); for(aux_index = 0; aux_index < rAC.aux_data_ref_count; aux_index++) { sRecordInfo_t AuxRecord; NDEF_ReadAuxData( aux_index, &rAC, &AuxRecord ); // Do something with this Auxiliary Data } // Process this AC (Extract OOB/or whatever data), and decide if this Carrier is supported or not. } 4. Choose the prefered Carrier and write a Handover Select record with the prefered AC as described in the Static Handover section.


Enumeration Type Documentation

Enumerates the NFC Forum Power States possible values.

Enumerator:
NDEF_HANDOVER_AC_CPS_INACTIVE 

The HW for this Alternative Carrier has to be switch on before proceeding.

NDEF_HANDOVER_AC_CPS_ACTIVE 

The HW for this Alternative Carrier is currently running.

NDEF_HANDOVER_AC_CPS_ACTIVATING 

The HW for this Alternative Carrier is being activated.

NDEF_HANDOVER_AC_CPS_UNKNOWN 

The HW for this Alternative Carrier is unknown.

Definition at line 67 of file lib_NDEF_Handover.h.


Function Documentation

uint16_t NDEF_AddAlternativeCarrier ( Ndef_Handover_alternative_carrier_t *  pAC,
char *  CarrierDataRef,
char **  AuxDataRefID,
sRecordInfo_t *  pRecord,
I2C *  mi2cChannel 
)

This function adds an Alternative Carrier record to a Handover record using the data given in the AC structure.

Parameters:
pACPointer on input AC structure.
CarrierDataRefString with the Alternative Carrier Data Reference (ID of the corresponding record in the NDEF message).
AuxDataRefIDArray with pointers to the Auxiliary Data References (as many as defined in pAC structure).
pRecordPointer on the Handover record to be filled with the AC data, must have been previously initialized with the NDEF_CreateHandover function.
Return values:
NDEF_OKThe Handover record has been updated with AC information.
NDEF_ERRORThe Handover record cannot be updated with the AC information.
NDEF_ERROR_MEMORY_INTERNALThe internal buffer for records is too small to add the AC information.

Definition at line 411 of file lib_NDEF_Handover.cpp.

uint16_t NDEF_CreateHandover ( Ndef_Handover_t *  pHandover,
sRecordInfo_t *  pRecord 
)

This function prepares the Handover record with the data given in the Handover structure.

Parameters:
pHandoverPointer on structure containing the handover basic information.
pRecordPointer used to return the prepared Handover record.
Return values:
NDEF_OKThe record has been prepared.
NDEF_ERRORThe record has not been prepared.

Definition at line 365 of file lib_NDEF_Handover.cpp.

uint32_t NDEF_GetACDataLength ( Ndef_Handover_alternative_carrier_t *  pAC,
char *  CarrierDataRef,
char **  AuxDataRefID 
)

This function returns the length of an Alternative Carrier record data (excluding the record metadata).

Parameters:
pACPointer on the input AC structure.
CarrierDataRefString with the Alternative Carrier Data Reference.
AuxDataRefIDArray with the Auxiliary Data References (as many as defined in the pAC structure).
Returns:
The computed length in bytes corresponding to the provided Alternative Carrier information.

Definition at line 467 of file lib_NDEF_Handover.cpp.

uint16_t NDEF_ReadAC ( uint8_t  ac_nb,
Ndef_Handover_t *  pHandover,
Ndef_Handover_alternative_carrier_t *  pAC 
)

This function reads the NDEF message and retrieves the nth Alternative Carrier record if present.

Parameters:
ac_nbPosition of the Alternative Carrier Reference in the Handover record.
pHandoverPointer to the Handover record where to find the AC Reference Data.
pACPointer used to return the output Alternative Carrier record.
Return values:
NDEF_OKThe Alternative Carrier record has been retrieved.
NDEF_ERRORNot able to find the Alternative Carrier in the NDEF message.

Definition at line 207 of file lib_NDEF_Handover.cpp.

uint16_t NDEF_ReadAuxData ( uint8_t  aux_data_nb,
Ndef_Handover_alternative_carrier_t *  pAC,
sRecordInfo_t *  pRecord 
)

This function searches the NDEF message to retrieve the nth Auxiliary Data record if present.

Parameters:
aux_data_nbPosition of the Auxiliary Data Reference in the Alternative Carrier.
pACPointer on the Alternative Carrier structure where to find the Auxiliary Data Reference.
pRecordPointer to return the output Auxiliary Data record.
Return values:
NDEF_OKThe Auxiliary Data record has been retrieved.
NDEF_ERRORNot able to find the Auxiliary Data in the NDEF message.

Definition at line 147 of file lib_NDEF_Handover.cpp.

uint16_t NDEF_ReadHandover ( sRecordInfo_t *  pRecord,
Ndef_Handover_t *  pHandover 
)

This function reads a record and retrieves the Handover information if present.

Parameters:
pRecordPointer on the record structure to be read.
pHandoverPointer used to return the Handover information.
Return values:
NDEF_OKHandover information has been retrieved from the record.
NDEF_ERRORNot able to read the Handover information from the record.

Definition at line 286 of file lib_NDEF_Handover.cpp.

uint16_t NDEF_WriteHandover ( sRecordInfo_t *  pRecord,
uint8_t *  pNdef,
I2C *  mi2cChannel 
)

This function writes the Handover record into the memory.

Parameters:
pRecordPointer on the input Handover record.
pNdefPointer to a NDEF buffer (used to prepare the data before actual writing to the memory).
Return values:
NDEF_OKThe memory has been written.
NDEF_ERROR_MEMORY_INTERNALCannot write to tag.
NDEF_ERROR_NOT_FORMATEDCCFile data not supported or not present.
NDEF_ERROR_MEMORY_TAGSize not compatible with memory.
NDEF_ERROR_LOCKEDTag locked, cannot be write.

Definition at line 497 of file lib_NDEF_Handover.cpp.