NHS31xx SW API
ucode : module to communicate with UCODE-I2C SL3S4011 or SL3S4021

Detailed Description

This module abstracts away the communication with the UCode-I2C over an I2C bus. Both the HW I2C block - using PIO4 and PIO5 for SCL and SDA respectively - and the I2C bit-banging module i2cbbm: I2C bit bang master driver are supported.

The module supports adjusting the 12-byte EPC code - using Ucode_SetNfcUid and Ucode_SetMark - and writing to the User Memory bank of the UCODE-I2C - using Ucode_WriteData. The module assumes the EPC code is a concatenation of:

There are no restrictions or assumptions on the User Memory bank imposed by this module.

Note
Each write action is verified by reading back the contents after being written first. This catches
  • possible I2C bus problems (unlikely),
  • possible UCode-I2C memory problems (unlikely),
  • UHF / NFC arbitration problems in the UCode-I2C (possible)
Multiple attempts are made to circumvent the arbitration problems: when an UHF field is present, it is necessary to wait until the field is gone before the UCODE-I2C can be written to via I2C. Each time a comparison fails, a few milliseconds are waited before a new attempt is initiated. Only if several attempts fail, the write is aborted.
Warning
The ICs have not been designed with mutual compatibility in mind. As a result, it is highly cumbersome to achieve functionalities as
  • Start trigger via UHF
  • Full data readout via UHF
  • Bidirectional communication via UHF
Even if the above could be achieved - by adding extra components, by restricting the use case, and/or by adding assumptions on real-life usage - they come with severe limitations.
Assuming immediate consumption is not required, typical information that can be conveyed:
  • from tag to host: label information, status reports, specific statistical information, the first n excursions, ...
  • from host to tag: handover data including timestamp, owner IDs, geolocation data, ...
Diversity
This module supports a number of diversity flags. Check the Message handler module diversity settings for a full list and their implications.

Modules

 Diversity Settings
 

Macros

#define UCODE_USER_MEMORY_SIZE   ((3328U /* bits */) / 8U)
 
#define UCODE_VERSION   'T'
 

Functions

void Ucode_Init (void)
 
bool Ucode_Reset (void)
 
void Ucode_DeInit (void)
 
bool Ucode_SetNfcUid (void)
 
bool Ucode_SetMark (unsigned int events)
 
bool Ucode_WriteData (unsigned int offset, const uint8_t *data, unsigned int len)
 
bool Ucode_ReadData (unsigned int offset, uint8_t *data, unsigned int len)
 

Macro Definition Documentation

◆ UCODE_USER_MEMORY_SIZE

#define UCODE_USER_MEMORY_SIZE   ((3328U /* bits */) / 8U)

Defines the size of the User Memory bank, where data can be read from or written to both via the I2C and the UHF interface.

◆ UCODE_VERSION

#define UCODE_VERSION   'T'

A single char indicating the version of the EPC code format.

  • the first 8 bytes of the EPC code form the NFC ID;
  • the last 4 bytes of the EPC code are as follows: state LSB, state 2nd byte, state 3rd byte, 'T'
  • The user memory is not used.

Function Documentation

◆ Ucode_Init()

void Ucode_Init ( void  )

This function must be the first function to call in this module after going to deep power down or power-off power save mode. Not calling this function will result in a hang.

Precondition
The I2C driver is not in use: Chip_I2C_Init has not yet been called, or Chip_I2C_DeInit was the last call to this driver.
Postcondition
The I2C driver is in exclusive use by the Ucode-I2C module

◆ Ucode_Reset()

bool Ucode_Reset ( void  )

Resets the memory contents of the Ucode-I2C. This includes:

Warning
Blocking call. Can potentially last multiple seconds - see retries.
Returns
True when the memory contents were successfully updated in the UCode-I2C memory.

◆ Ucode_DeInit()

void Ucode_DeInit ( void  )

De-initializes the Ucode-I2C and the I2C driver. No memory contents on the Ucode-I2C will be changed during this call.

Postcondition
The I2C driver is not claimed anymore.
All pins listed in UCODE_PULLUPS as reconfigured as output, outputting low.

◆ Ucode_SetNfcUid()

bool Ucode_SetNfcUid ( void  )

Writes the NFC UID as an EPC code in the Ucode-I2C.

Warning
Blocking call. Can potentially last multiple seconds - see retries.
Returns
True when the memory contents were successfully updated in the UCode-I2C memory.

◆ Ucode_SetMark()

bool Ucode_SetMark ( unsigned int  events)

Changes the EPC code to allow quick and easy identification of marked labels/products.

Parameters
eventsA bitmask. Each bit represents an application-specific event.
Warning
Blocking call. Can potentially last multiple seconds - see retries.
Returns
True when the memory contents were successfully updated in the UCode-I2C memory.

◆ Ucode_WriteData()

bool Ucode_WriteData ( unsigned int  offset,
const uint8_t *  data,
unsigned int  len 
)

Write data in the User Memory bank of the UCODE-I2C. This data is treated as raw bytes; meaning is to be given and interpretation is to be done by the NHS3100 and UHF reader applications.

Parameters
offsetDefines the starting location to write in the User Memory bank.
dataPointer to the array of bytes to write.
lenThe number of bytes to write.
Precondition
offset + len must not exceed the User Memory region bank (which is 3328 bits or 416 bytes in size).
Warning
Blocking call. Can potentially last multiple seconds - see retries.
Returns
True when the memory contents were successfully updated in the UCode-I2C memory.

◆ Ucode_ReadData()

bool Ucode_ReadData ( unsigned int  offset,
uint8_t *  data,
unsigned int  len 
)

Read data from the User Memory bank of the UCODE-I2C. This data is treated as raw bytes; meaning is to be given and interpretation is to be done by the NHS3100 and UHF reader applications.

Parameters
offsetDefines the starting location to read from the User Memory bank.
dataPointer to an array of bytes where the read data can be copied to.
lenThe number of bytes to read; the array pointed to by data must have at least this size.
Precondition
offset + len must not exceed the User Memory region bank (which is 3328 bits or 416 bytes in size).
Warning
Blocking call. Can potentially last multiple seconds - see retries.
Returns
True when the memory contents were successfully retrieved from the UCode-I2C memory.