Fork for the GitHub
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:
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:
-
pAC Pointer on input AC structure. CarrierDataRef String with the Alternative Carrier Data Reference (ID of the corresponding record in the NDEF message). AuxDataRefID Array with pointers to the Auxiliary Data References (as many as defined in pAC structure). pRecord Pointer on the Handover record to be filled with the AC data, must have been previously initialized with the NDEF_CreateHandover function.
- Return values:
-
NDEF_OK The Handover record has been updated with AC information. NDEF_ERROR The Handover record cannot be updated with the AC information. NDEF_ERROR_MEMORY_INTERNAL The 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:
-
pHandover Pointer on structure containing the handover basic information. pRecord Pointer used to return the prepared Handover record.
- Return values:
-
NDEF_OK The record has been prepared. NDEF_ERROR The 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:
-
pAC Pointer on the input AC structure. CarrierDataRef String with the Alternative Carrier Data Reference. AuxDataRefID Array 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_nb Position of the Alternative Carrier Reference in the Handover record. pHandover Pointer to the Handover record where to find the AC Reference Data. pAC Pointer used to return the output Alternative Carrier record.
- Return values:
-
NDEF_OK The Alternative Carrier record has been retrieved. NDEF_ERROR Not 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_nb Position of the Auxiliary Data Reference in the Alternative Carrier. pAC Pointer on the Alternative Carrier structure where to find the Auxiliary Data Reference. pRecord Pointer to return the output Auxiliary Data record.
- Return values:
-
NDEF_OK The Auxiliary Data record has been retrieved. NDEF_ERROR Not 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:
-
pRecord Pointer on the record structure to be read. pHandover Pointer used to return the Handover information.
- Return values:
-
NDEF_OK Handover information has been retrieved from the record. NDEF_ERROR Not 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:
-
pRecord Pointer on the input Handover record. pNdef Pointer to a NDEF buffer (used to prepare the data before actual writing to the memory).
- Return values:
-
NDEF_OK The memory has been written. NDEF_ERROR_MEMORY_INTERNAL Cannot write to tag. NDEF_ERROR_NOT_FORMATED CCFile data not supported or not present. NDEF_ERROR_MEMORY_TAG Size not compatible with memory. NDEF_ERROR_LOCKED Tag locked, cannot be write.
Definition at line 497 of file lib_NDEF_Handover.cpp.
Generated on Fri Jul 15 2022 10:08:35 by
1.7.2