CAENRFID protocol

From CAEN RFID support

Jump to: navigation, search

CAEN UHF RFID Readers Communication Protocol Revision date: 28/06/2010 Revision: 11-rc

Contents

Introduction

This document describes the message format of the communication protocol used by the host and the reader in order to issuing commands and reply with responses.

The protocol is based on the Attribute Value Pair (AVP) schema and foresees a message header in order to identify the message scope.

The command set and the firmware architecture draw inspiration from the Reader Protocol 1.0 specification draft from EPCGlobal but, at now, this protocol is not fully compatible with the same last specifications.

Message fields are described left to right, with the most significant byte on the left and the least on the right.

Note: This is a version 11-rc (Release Candidate), it is fully compatible with previous version 10 (revision date of 09/03/2009) and extends it.

Protocol specification

CAEN UHF RFID Reader protocol uses two logical communication channels: one for synchronous commands and one for asynchronous notifications. Command channel is mandatory and it is currently implemented on top of a TCP/IP socket (port 1000) and on RS232 while notification channels are implemented only with sockets.

All the messages (commands, responses and notifications) are composed by a header and a body. In all cases the body of the message is a list of attribute-value pairs.

Responses always echo the Command AVP sent by the host.

The header

All the packets for the control and notification channel share a common header format:

                     1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-------------------------------+------------------------------+
|              ver              |              id              |
+-------------------------------+------------------------------+
|                             vendor                           |
+-------------------------------+------------------------------+
|              len              |
+-------------------------------+
  • ver: Must be 0x8001 for commands and 0x0001 for responses.
  • id: ID of the message. It is a sequence number used to map requests to its responses: a request and its corresponding response have the same message ID (the id is local to the channel).
  • vendor: Must be 21336: the IANA “SMI Network Management Private Enterprise Code” assigned to CAEN SpA.
  • len: Encodes the length of the message (in bytes) including the header.

The C struct definition is:

struct proto_header {
        uint16_t ver;
        uint16_t id;
        uint32_t vendor;
        uint16_t len;
        uint8_t data[0];
} __packed;

The AVP

The header is followed by a list of AVPs the number of which depends on the command.

Each AVP have the following format:

                     1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-------------------------------+------------------------------+
|            reserved           |             len              |
+-------------------------------+------------------------------+
|              type             |            value...          |
+-------------------------------+------------------------------+
|              ...[ until length is reached ]...               |
+--------------------------------------------------------------+
  • reserved: The first 16 bits are reserved for future extensions. All reserved bits must be set to 0 on outgoing messages and ignored on incoming messages.
  • len: Encodes the length of the AVP packet including the length and the reserved fields.
  • type: A 2 byte code identifying the attribute type.
  • value: The actual attribute value according to the type. It follows immediately after the Attribute Type field and runs for the remaining bytes indicated in the Length (i.e. Length minus 6 bytes of header).

The C struct definition is:

struct avp_generic {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint8_t data[0];
} __packed;

If not specified all numeric values are in the big-endian format.

AVP's attribute types

Code 0x01 (1) - Command

Call a command.

The C struct definition is:

struct avp_command {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t cmd;
} __packed;

Possible commands value are listed into section CAENRFID_protocol#Commands.

Code 0x02 (2) - ResultCode

Return the result code of a command.

The C struct definition is:

struct avp_result_code {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t code;
} __packed;

Possible code value are:

Code Name Description
0x00 (0) AVP_ERR_SUCCESS No error. Command success
0x66 (102) AVP_ERR_UNKNOW Unknow errror
0x7f (127) AVP_ERR_INVALIDCMD Supplied command is not invalid
0xc8 (200) AVP_ERR_INVALIDPAR One of the input parameters is invalid
0xca (202) AVP_ERR_TAGNOTPRESENT No tags detected
0xcb (203) AVP_ERR_TAGWRITE Tag write error. Usually an RF related error.
0xcc (204) AVP_ERR_TAGREAD Tag read error. Usually an RF related error.
0xd1 (209) AVP_ERR_TAGLOCK Tag lock error. Usually an RF related error.

Code 0x0f (15) - TagIDLength

Set a tag ID length.

The C struct definition is:

struct avp_tag_id_len {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t id_len;
} __packed;

Code 0x10 (16) - TimeStamp

Set a time stamp referred to the POSIX time.

The C struct definition is:

struct avp_timestamp {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint32_t secs;
        uint32_t u_secs;
} __packed;

Code 0x11 (17) - TagID

Set a tag ID.

The C struct definition is:

struct avp_tag_id {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint8_t id[0];
} __packed;

Code 0x12 (18) - TagType

Set a tag type.

The C struct definition is:

struct avp_tag_type {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t tag_t;
} __packed;

Allowed values for tag_t are:

Name Value
ISO18000 6B 0
EPC C1G1 1
ISO18000 6A 2
EPC C1G2 3
MULTIPROTOCOL 4
EPC119 5
Unspecified 255

The C struct definition is:

struct avp_tag_type {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t tag_t;
} __packed;

Code 0x22 (34) - ReadpointName

Set a readpoint name.

The C struct definition is:

struct avp_readpoint_name {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        char *name[0];
} __packed;

Code 0x4d (77) - TagValue

Specify tag data.

The C struct definition is:

struct avp_tag_value {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint8_t data[0];
} __packed;

Code 0x4e (78) - TagAddress

Set an address inside a tag memory.

The C struct definition is:

struct avp_tag_address {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t addr;
} __packed;

Code 0x50 (80) - Length

Set a length.

The C struct definition is:

struct avp_length {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t length;
} __packed;

Code 0x51 (81) - BitRate

Set a bit rate.

In the caenrfidd daemon this AVP has been named as Modulation for historical reasons.

The C struct definition is:

struct avp_modulation {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t mod;
} __packed;

Allowed values for mod are:

Name Value
AIR_MODULATION_DSB_ASK_FM0_TX10RX10 0
AIR_MODULATION_DSB_ASK_FM0_TX10RX40 1
AIR_MODULATION_DSB_ASK_FM0_TX40RX40 2
AIR_MODULATION_DSB_ASK_FM0_TX40RX160 3
AIR_MODULATION_DSB_ASK_FM0_TX160RX400 4
AIR_MODULATION_DSB_ASK_M2_TX40RX160 5
AIR_MODULATION_PR_ASK_M4_TX40RX250 6
AIR_MODULATION_PR_ASK_M4_TX40RX300 7
AIR_MODULATION_PR_ASK_M2_TX40RX250 8
AIR_MODULATION_PR_ASK_FM0_TX40RX40 9

Code 0x52 (82) - Power

Set a power level in mW.

The C struct definition is:

struct avp_power_value {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint32_t power;
} __packed;

Note: for backward compatibility this AVP, in setting commands, may have the code 0x96 (150).

Code 0x54 (84) - Protocol

Set a protocol type.

The C struct definition is:

struct avp_protocol {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint32_t proto;
} __packed;

Allowed values for proto are:

Name Value
ISO18000 6B 0
EPC C1G1 1
ISO18000 6A 2
EPC C1G2 3
MULTIPROTOCOL 4
EPC119 5
Unspecified 255

Code 0x67 (103) - Bitmask

Set a bitmask.

The C struct definition is:

struct avp_bitmask {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t value;
} __packed;

Code 0x71 (113) - MemoryBank

Set a memory bank.

The C struct definition is:

struct avp_membank {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t bank;
} __packed;

Valid bank values are:

Name Value
Reserved 0
EPC 1
TID 2
USER 3

Code 0x72 (114) - G2Payload

Specify a payload.

The C struct definition is:

struct avp_g2_payload {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint32_t payload;
} __packed;

Code 0x73 (115) - G2Password

Specify a G2 password.

The C struct definition is:

struct avp_g2_password {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint32_t pwd;
} __packed;

Code 0x74 (116) - G2NSI

Specify a G2 NSI numbering system.

The C struct definition is:

struct avp_g2_nsi {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t nsi;
} __packed;

Code 0x78 (120) - RFChannel

Specify a RF channel number.

The C struct definition is:

struct avp_rfchannel {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t ch;
} __packed;

Code 0x7a (122) - RSSI

Set a RSSI value which is the power in dBm of the backscattered signal from a tag.

The C struct definition is:

struct avp_rssi {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        uint16_t rssi;
} __packed;

Code 0xfb (251) - SourceName

Address a source name.

The C struct definition is:

struct avp_source_name {
        uint16_t reserved;
        uint16_t len;
        uint16_t type;
        char *name[0];
} __packed;

All source names are in the form Source_X, where X is a non negative integer number.

Commands

A command is called by using a Command AVP followed by others AVP whose represent the Input parameters.

For each command the server will answer by sending a message staring with the same Command AVP (echoing AVP) followed by others AVP whose represent the Output parameters.

Code 0x13 (19) - NewRawReadIDs

Permits to get all the tag’s IDs that are under the RF field of the selected source.

Input parameters

  • SourceName [optional, default to "Source_0"]: the name of the source to use
  • mask parameters [optional]:
    • Length [default 0]: the length of the filter mask in bits
    • TagID [undefined if Length=0]: the filter mask
    • TagAddress [undefined if Length=0]: the start address in byte where to apply the filter mask
  • Bitmask [optional, default 0]: inventory flags

Bitmask's bits are (striked entries will be supported in the future):

  • bit 0 - CAEN_RSSI_FLG: ask for RSSI value
  • bit 1 - CAEN_FRAMED_FLG: enable framed mode
  • bit 2 - CAEN_CONTINUOUS_FLG: enable continuous mode
  • bit 3 - CAEN_COMPACT_FLG: enable compact mode


Output parameters

  • tag data [if ResultCode=0]:
  • ResultCode: the result code

Note

The client gets one output parameters message for each tag detected, under all available readpoints of the selected source.

An inventory may be driven by 3 variables:

  • CAEN_CONTINUOUS_FLG flag
  • CAEN_FRAMED_FLG flag
  • read_cycle setting

and the following table defines how the server should operate according to these variables combinations:

CONTINUOS FRAMED read_cycle
0 0 not care exec 1 simple inventory
return standard packet
1 0 N > 0 exec N simple inventories
return standard packet
1 0 N = 0 Error
invalid values
0 1 not care Error
invalid values
1 1 N = 0 exec continuos inventories till AB
return non standard packet
1 1 N > 0 exec N continuos inventories or AB
return non standard packet

Non standard packets are sent at different times:

  • the header is sent as soon as the inventiry starts (length fields are ignored by the client)
  • the tag AVPs are sent as soon as they arrives from the underlying radios
  • as soon as the AB arrives or all rounds have been executed we return the error code AVP

Error conditions

  • If (Length > 0) AND (Length/8 > length(TagID)) the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If no tags are found the command returns ResultCode=AVP_ERR_TAGNOTPRESENT.

Code 0x5f (95) - AddReadPoint

Permits to add a readpoint to a source.

Input parameters

Output parameters

Note

Error conditions

Code 0x60 (96) - RemoveReadPoint

Permits to remove a readpoint from a source.

Input parameters

Output parameters

Note

Error conditions

Code 0x64 (100) - SetPower

Permits to set the protocol to use.

Input parameters

  • Power: the power level to set

Output parameters

Note

On systems with two or more antennae this function is deprecated and should not be used!

Error conditions

For backward compatibility, on multiple-antennae systems, it tries to set the same power level for all antennae in the system. If one or more antennae fail to do the setting the command returns the AVP_ERR_UNKNOWN error and antennae power setting is undefined.

Code 0x72 (114) - SetBitRate

Permits to set the bit rate to use.

Input parameters

Output parameters

Note

On systems with two or more antennae this function is deprecated and should not be used!

In the caenrfidd daemon the command has been named SetModulation for historical reasons.

Error conditions

For backward compatibility, on multiple-antennae systems, it tries to set the same bit rate for all antennae in the system. If one or more antennae fail to do the setting the command returns the AVP_ERR_UNKNOWN error and antennae bit rate setting is undefined.

Code 0x73 (115) - GetPower

Permits to get the current RF power level.

Input parameters

Output parameters

  • power data [if ResultCode=0]:
    • Power: the current power level
  • ResultCode: the result code

Note

On systems with two or more antennae this function is deprecated and should not be used!

For backward compatibility, on multiple-antennae systems, it just returns the first antenna settings.

Error conditions

Code 0x74 (116) - SetProtocol

Permits to set the protocol to use.

Input parameters

Output parameters

Note

On systems with two or more antennae this function is deprecated and should not be used!

Error conditions

For backward compatibility, on multiple-antennae systems, it tries to set the same protocol for all antennae in the system. If one or more antennae fail to do the setting the command returns the AVP_ERR_UNKNOWN error and antennae protocol setting is undefined.

Code 0x79 (121) - GetProtocol

Permits to get the protocol in use.

Input parameters

Output parameters

  • protocol data [if ResultCode=0]:
  • ResultCode: the result code

Note

On systems with two or more antennae this function is deprecated and should not be used!

For backward compatibility, on multiple-antennae systems, it just returns the first antenna settings.

Error conditions

Code 0x81 (129) - GetBitRate

Permits to get the current bit rate.

Input parameters

Output parameters

  • bit rate data [if ResultCode=0]:
  • ResultCode: the result code

Note

On systems with two or more antennae this function is deprecated and should not be used!

For backward compatibility, on multiple-antennae systems, it just returns the first antenna settings.

In the caenrfidd daemon the command has been named GetModulation for historical reasons.

Error conditions

Code 0x95 (149) - G2ProgramID

Permits to write the EPC on a tag under the RF field of the selected source. There must be only one tag under the source's RF field.

Input parameters

  • SourceName [optional, default to "Source_0"]: the name of the source to use
  • TagIDLength: the length of the tag ID in byte
  • TagID: the tag ID
  • G2NSI: the EPC numbering system
  • G2Password: [optional] the EPC access password

Output parameters

Note

Error conditions

  • if Length % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If TagIDLength > length(TagID) the command returns ResultCode=AVP_ERR_INVALIDPAR.

Code 0x96 (150) - G2Read

Permits to read data from any of the Gen2 memory banks of a tag under the RF field of the selected source. The tag must be identified unequivocally by passing its ID to this command.

Input parameters

Output parameters

  • read data [if ResultCode=0]:
    • TagValue: the data to write into the tag memory bank
  • ResultCode: the result code

Note

Error conditions

  • if TagAddress % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • if Length % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If TagIDLength > length(TagID) the command returns ResultCode=AVP_ERR_INVALIDPAR.

Code 0x97 (151) - G2Write

Permits to write data into any of the Gen2 memory banks of a tag under the RF field of the selected source. The tag must be identified unequivocally by passing its ID to this command.

Input parameters

Output parameters

Note

Error conditions

  • if TagAddress % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • if Length % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If TagIDLength > length(TagID) the command returns ResultCode=AVP_ERR_INVALIDPAR.


Code 0x98 (152) - G2Lock

Permits to execute the tag lock command defined by the EPC on a tag under the RF field of the selected source. The tag must be identified unequivocally by passing its ID to this command.

Input parameters

  • SourceName [optional, default to "Source_0"]: the name of the source to use
  • TagIDLength: the length of the tag ID in byte
  • TagID: the tag ID
  • G2Payload: the lock payload (see below)
  • G2Password: [optional] the EPC access password

Output parameters

Note

Error conditions

  • if Length % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If TagIDLength > length(TagID) the command returns ResultCode=AVP_ERR_INVALIDPAR.

Lock payload specification

The meaning of the bit in the payload parameter required by the lock command is as follow:

Lock Command payload
bit # 19 18 17 16 15 14 13 12 11 10
label Kill mask Access mask EPC mask TID mask User mask
mask skip/write skip/write skip/write skip/write skip/write skip/write skip/write skip/write skip/write skip/write
bit # 9 8 7 6 5 4 3 2 1 0
label Kill action Access action EPC action TID action User action
action pwd read/write perma lock pwd read/write perma lock pwd write perma lock pwd write perma lock pwd write perma lock

Each bit set to 1 in the MASK field allows you to write the bit of the corresponding ACTION FIELD (for example if you set to 1 the bit 19 of the KILL MASK you will be able to write to 0 or 1 the bit 9 of the KILL ACTION field); each bit set to 0 in the MASK field masks the write operation in the corresponding ACTION FIELD.

The two bits of the EPC, TID and USER ACTION field mean the following:

Lock action-field functionality
pwd write perma lock description
0 0 Associated memory bank is writeable from either the open or secured states
0 1 Associated memory bank is permanently writeable from either the open or secured states and may never be locked
1 0 Associated memory bank is writeable from the secured state but not from the open state
1 1 Associated memory bank is not writeable from any state
pwd read/write perma lock description
0 0 Associated password location is readable and writeable from either the open or secured states
0 1 Associated password location is permanently readable and writeable from either the open or secured states and may never be locked
1 0 Associated password location is readable and writeable from the secured state but not from the open state
1 1 Associated password location is not readable nor writeable from any state

For example if you are using a payload value of 0x0C030, this should permanently prevent of writing the EPC code. In the case of tags that implement the USER memory, the value 0x00C02 should make the USER memory writeable only from the secured state but not from the open state.

Another example: the payload value 0xC0200 makes the KILL memory word not readable or writeable from the open state, while you can read or write it from the SECURE state. A tag that has the ACCESS word memory set to 0x00000000 (default condition) is always in the secured state and cannot be killed.

Code 0x99 (153) - G2Kill

Permits to execute the tag kill command defined by the EPC on a tag under the RF field of the selected source. The tag must be identified unequivocally by passing its ID to this command.

Input parameters

  • SourceName [optional, default to "Source_0"]: the name of the source to use
  • TagIDLength: the length of the tag ID in byte
  • TagID: the tag ID
  • G2Password: [optional] the EPC access password

Output parameters

Note

Error conditions

  • if Length % 2 = 1 the command returns ResultCode=AVP_ERR_INVALIDPAR.
  • If TagIDLength > length(TagID) the command returns ResultCode=AVP_ERR_INVALIDPAR.

Code 0xa3 (163) - SetRFChannel

Permits to set the RF channel where the reader emits the RF field.

Input parameters

Output parameters

Note

On systems with two or more antennae this function is deprecated and should not be used!

In the caenrfidd daemon the command has been named SetModulation for historical reasons.

Error conditions

For backward compatibility, on multiple-antennae systems, it tries to set the same channel for all antennae in the system. If one or more antennae fail to do the setting the command returns the AVP_ERR_UNKNOWN error and antennae channel setting is undefined.

Code 0xa4 (164) - GetRFChannel

Permits to read the RF channel currently in use.

Input parameters

Output parameters

  • channel data [if ResultCode=0]:
  • ResultCode: the result code

Note

On systems with two or more antennae this function is deprecated and should not be used!

For backward compatibility, on multiple-antennae systems, it just returns the first antenna settings.

Error conditions

Asynchronous Notification: Protocol specification

TODO.

Default configuration

Serial settings

TODO.

Ethernet settings

The following settings are not mandatory.

IP Address IP Netmask IP Gateway
192.168.0.125 255.255.255.0 192.168.0.1

Composition of sources

Source Readpoints
Source_0 Ant0
Source_1 Ant1
Source_2 Ant2
Source_3 Ant3
Personal tools