Core.perso

This API serves personalization commands which allow accessing items memory with read and write commands. It uses gRPC technology.

API core.perso access rights inherites from Software solution it is included to. Moreover, this API may not be installed by default. Contact technical support if the API is unavailable.

Different packages for different development technologies (npm, pypi, nuget, go) are available. Please check solution documentation to access it.

Data format

At the moment, only raw and NDEF formats are supported in both read and write operations for NFC type 5 tags.

raw format requires address and data to be written. The size is deduced from the data length.
ndef format requires a more complete description.

⚠️ If you attempt to write NDEF data in an empty or raw programmed tag, the API will first format the memory content for NDEF prior to write NDEF content.

Operation flow (important)

The initial step for any operation is to locate an item. This is done automatically by Centiloc surfaces.

Personalization operation requires a lot more power than geolocation. This has an impact on the way to operate the read or write; indeed, the volume geolocating the item will not be fully functional for personalization operation.

As a consequence, read and write request requires the board to find the best path to performs the operation (meaning finding the best antenna to communicate the request).

While looking for the best path, this may result in unsuccessful or partially successfull attempts. The board will then look for another option (if possible), to retry the operation. Then, note that when requesting to read or write an item content, the operation can be done several times until it is 100% successful, or until there is no more path to try.

flowchart TD;

classDef class_blue fill:#00aec2,color:#fff,stroke-width:0px;
classDef class_start fill:#00aec2,color:#fff,stroke:#4a4a49,stroke-width:2px;
classDef class_error fill:#b51f1f,color:#fff,stroke:#4a4a49,stroke-width:2px;
classDef class_success fill:#a2c617,color:#fff,stroke:#4a4a49,stroke-width:2px;

A[[Receive Write request]]:::class_start
B(Check Item presence):::class_blue
C{Can Item <br>be accessed<br> with new <br>path?}:::class_blue
E[[Exit with error]]:::class_error
D(Perform write attempt<br>through new path):::class_blue
FF{Is successfull?}:::class_blue
FG[[Exit with success]]:::class_success

A --> B --> C
C ---> |no|E
C --> |yes|D --> FF
FF --> |yes|FG
FF --> |no|C

Access

You can access to a read or write operation by:

Asking for a single item operation: WriteSingle or ReadSingle
- In this case, the software will find the appropriate board to ask the operation
Asking for an operation on all the items on a board: WriteMultiple or ReadMultiple
- The content written in WriteMultiple operation will be the same for all items

These two paths are designed for convenience only. There is no performance benefits for using one or the other.

NDEF Format

This section is a reminder of NDEF format as defined by NFC Forum. The api-perso is fully based on this norm.

It supports the usage of Well Known Types as well as custom ones, with specific ids and so on…

Examples on how to create and use a Ndef data is present in the solution project example.

Below is a description of the data written in the tag. When asking for Ndef write, you can write a list of NDEF records in one operation. The Ndef Message allows describing every field of Record Header.

NDEFFormat

core/perso/perso.proto
- Services
  - Perso
- Enums
- Messages

Perso

Perso is the service used to personalize items (tags).

Method Name	Request Type	Response Type	Description
ReadSingle	ReadItemData	ItemContentResponse	ReadSingle returns the content of an item.
ReadMultiple	ReadItemsData	ItemsContentResponse	ReadMultiple returns the content of all items on a board.
WriteSingle	WriteItemData	RequestStatus	WriteSingle writes a content into an item.
WriteMultiple	WriteItemsData	ItemsResponse	WriteMultiple writes a content into all items on a board.

ItemContentFormat

ItemContentFormat represents each possible content format of an item.

Name	Number	Description
RAW	0	default value
NDEF	1

NdefTnf

Name	Number	Description
TNF_EMPTY	0	empty record
TNF_WKT	1	well Known Type : defined by the NFC forum
TNF_MIME	2	media type : An Internet media type as defined in RFC 2046
TNF_ABS_URI	3	absolute URI : A URI as defined in RFC 3986
TNF_EXTERN	4	external : A user-defined value, based on rules in the NFC Forum RTD specification
TNF_UNKNOWN	5	type is unknown, type length in header shall be 0
TNF_UNCHANGED	6	reserved for middle and terminating records of chunked payloads. Type length in header shall be 0
TNF_RESERVED	7	reserved by the NFC forum for future use

NdefUri

Name	Number	Description
URI_NONE	0	No prepending is done.
URI_HTTP_WWW	1	“http://www.”
URI_HTTPS_WWW	2	“https://www.”
URI_HTTP	3	“http:”
URI_HTTPS	4	“https:”
URI_TEL	5	“tel:”
URI_MAILTO	6	“mailto:”
URI_FTP_ANONYMOUS	7	“ftp://anonymous:anonymous@”
URI_FTP_FTP	8	“ftp://ftp.”
URI_FTPS	9	“ftps://”
URI_SFTP	10	“sftp://”
URI_SMB	11	“smb://”
URI_NFS	12	“nfs://”
URI_FTP	13	“ftp://”
URI_DAV	14	“dav://”
URI_NEWS	15	“news:”
URI_TELNET	16	“telnet://”
URI_IMAP	17	“imap:”
URI_RTSP	18	“rtsp://”
URI_URN	19	“urn:”
URI_POP	20	“pop:”
URI_SIP	21	“sip:”
URI_SIPS	22	“sips:”
URI_TFTP	23	“tftp:”
URI_BTSPP	24	“btspp://”
URI_BTL2CAP	25	“btl2cap://”
URI_BTGOEP	26	“btgoep://”
URI_TCPOBEX	27	“tcpobex://”
URI_IRDAOBEX	28	“irdaobex://”
URI_FILE	29	“file://”
URI_URN_EPC_ID	30	“urn:epc:id:”
URI_URN_EPC_TAG	31	“urn:epc:tag:”
URI_URN_EPC_PAT	32	“urn:epc:pat:”
URI_URN_EPC_RAW	33	“urn:epc:raw:”
URI_URN_EPC	34	“urn:epc:”
URI_URN_NFC	35	“urn:nfc:”
URI_RFU	255	No prepending is done. Reserved for future use.

Code

Name	Number	Description
OK	0	command succeed
TIMEOUT	1	timeout reached, board did not answer
KO	2	command failed
FAILED_BUT_RETRY	3	command failed with unknown error, retry
BOARD_NOT_AVAILABLE	4	board is suspicious or mute ⚠️ NOT IMPLEMENTED
BOARD_DISCONNECTED	5	board is disconnected, cannot send a request
BOARD_BUSY	6	board is busy, wait and retry

ItemContent

ItemContent represents either a raw payload or a NDEF content, linked to ITEMCONTENTFORMAT.

Field	Type	Label	Description
ndef	NdefMessage		ndef message
payload	bytes		bulk payload for raw data

ItemContentResponse

ItemContentResponse contains the content of an item and the request status.

Field	Type	Description
uid	string	item’s identifier
content	ItemContent	item’s content read
request_status	RequestStatus

ItemResponse

ItemResponse contains a request status associated to an item.

Field	Type	Label	Description
uid	string		item’s identifier
status	RequestStatus

ItemsContentResponse

ItemsContentResponse is a list of ItemContentResponse.

Field	Type	Label	Description
data	ItemContentResponse	repeated

ItemsResponse

ItemsResponse is a list of ItemResponse.

Field	Type	Label	Description
data	ItemResponse	repeated

NdefMessage

NdefMessage contains multiple records.

Field	Type	Label	Description
records	NdefRecord	repeated

NdefRecord

NdefRecord can contain a variety of content.

Field	Type	Description
type_format	NdefRecord.NdefTnf	type name format
type_len	uint32	length of the type field
id_len	uint32	length of the id field
type	bytes	payload of type, if type_len is 0, value shall be ignored
id	bytes	payload for id, if id_len is 0, value shall be ignored
uri	NdefRecord.WKTUri	Well Known Type URI payload
text	NdefRecord.WKTText	Well Known Type Text payload
sp	NdefRecord.WKTSmartPoster	Well Known Type Smart Poster
data	bytes	other payload

WKTSmartPoster

Field	Type	Label	Description
uri	NdefRecord.WKTUri		URI of the smart poster
text	NdefRecord.WKTText		Text descriptor for smart poster

WKTText

Field	Type	Description
is_utf_16	bool	encoding of the text. if 0 then utf-8 ; if 1 then utf-16
language	string	language for text, should follow ISO 639-1 standard language codes
data	string	text payload

WKTUri

Field	Type	Label	Description
id	NdefRecord.WKTUri.NdefUri		prefix of the uri
data	string		uri payload

ReadItemData

ReadItemData contains the item targeted, the format to read and which board to request.

Field	Type	Description
uid	string	item to read
address	uint32	address where reading (= block number), useless in case of NDEF format
length	uint32	number of bytes to read, useless in case of NDEF format
data_format	ItemContentFormat	data format to read

ReadItemsData

ReadItemsData contains the format to read and which board to request.

Field	Type	Description
address	uint32	address where reading (= block number), useless in case of NDEF format
length	uint32	number of bytes to read, useless in case of NDEF format
data_format	ItemContentFormat	data format to read
board_sn	string	board where the items targeted are

RequestStatus

RequestStatus represents the return of a board after a request.
The following messages can be returned :
OK

Command succeed
No content (for example, after a tag read command)

Request not implemented
Bad request
Tag not found
Request’s input too large
Internal server error
Unsupported format
Forbidden

FAILED_BUT_RETRY

Unknown error, retry

BOARD_BUSY

Tag is already busy, retry lately

Field	Type	Label	Description
code	RequestStatus.Code		code identifying the board state
message	string		description of the board state

WriteItemData

WriteItemData contains the item targeted, the writing information and which board to request.

Field	Type	Description
uid	string	item to write
address	uint32	address where reading (= block number), useless in case of NDEF content
content	ItemContent	content to write into the item ⚠️ if you give only 2 bytes of payload, the 2 bytes left (because 1 block = 4 bytes) will be set to zero

WriteItemsData

WriteItemsData contains the writing information and which board to request.

Field	Type	Description
address	uint32	address where reading (= block number), useless in case of NDEF format
content	ItemContent	content to write into the item ⚠️ if you give only 2 bytes of payload, the 2 bytes left (because 1 block = 4 bytes) will be set to zero
board_sn	string