Protocol description
The following description gives an overview of the ams stream protocol and how the data of stream packets is forwarded to the commands() function. The protocol can be executed over USB or UART. Only the header bytes between USB and UART are different.
For a detailed description of the ams stream protocol have a look in ams_stream.h
Protocol for USB:
A simple USB stream packet (not splitted, only 1 protocol in packet) is shown in the following table, which maps the transmitted data to the function parameters of commands().
| Byte | 0 | 1 | 2 | 3 | 4..5 | 6..7 | 8..8+txprot-1 |
|---|---|---|---|---|---|---|---|
| Content | TID | payload | reserved | protocol | txprot | rxprot | data |
| Parameter | protocol | rxSize | txSize | rxData[0..rxSize-1] |
where
- TID : transaction ID.
- payload: amount of data in report.
- protocol: defines which action should be triggered. If commands() is is called it refers to a firmware application command (no generic stream command).
- txprot: amount of data which has been received and should be forwarded to command function.
- rxprot: This variable contains the expected size of data this command will return and will be set to the size of the actual data to be tx-ed back to host.
- data: input data for command
The response will look like this:
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6..7 | 8..8+txprot-1 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | payload | stream status | protocol | reserved | prot status | txprot | data |
| Parameter | protocol | status | txSize | txData[0..txSize-1] |
where
- TID : transaction ID.
- payload: amount of data in report.
- stream status : a non-zero value indicates that a previous command could not be processed
- protocol : defines to which action the transmitted data belongs
- prot status : a non-zero value indicates error condition of command (return value of function commands())
- txprot: size of data in response
- data: response data for command
Example for the antenna power command, handled by callAntennaPower():
Request from host (Reader Suite):
| Byte | 0 | 1 | 2 | 3 | 4..5 | 6..7 | 8 |
|---|---|---|---|---|---|---|---|
| Content | TID | payload | reserved | protocol | txprot | rxprot | data |
| Value | 0x0F | 0x07 | 0x00 | 0x01 | 0x0002 | 0x0001 | 0xFF |
where:
- 0x01: command ID for callAntennaPower(), is also used as index in call_fkt_() table.
- 0xFF: parameter for callAntennaPower(). 0xFF means turn antenna on.
The reader answer with this report:
| Byte | 0 | 1 | 2 | 3 | 4 | 5 | 6..7 | 8 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | payload | stream status | protocol | reserved | prot status | txprot | data |
| Value | 0xF0 | 0x06 | 0x00 | 0x01 | 0x00 | 0x00 | 0x0001 | 0x00 |
- 0x00 (txData[0]): the data this command produced.
- 0x00 (status): ERR_NONE
Protocol for UART:
A simple UART stream packet is shown in the following table, which maps the transmitted data to the function parameters of commands().
| Byte | 0 | 1 | 2..3 | 4 | 5..6 | 7..8 | 9..9+txprot-1 |
|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | txprot | rxprot | data |
| Parameter | protocol | rxSize | txSize | rxData[0..rxSize-1] |
where
- TID : transaction ID.
- Status : Uart Status
- payload: amount of data in report.
- protocol: defines which action should be triggered. If commands() is is called it refers to a firmware application command (no generic stream command).
- txprot: amount of data which has been received and should be forwarded to command function.
- rxprot: This variable contains the expected size of data this command will return and will be set to the size of the actual data to be tx-ed back to host.
- data: input data for command
The response will look like this:
| Byte | 0 | 1 | 2..3 | 4 | 5 | 6 | 7..8 | 9..9+txprot-1 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | reserved | prot status | txprot | data |
| Parameter | protocol | status | txSize | txData[0..txSize-1] |
where
- TID : transaction ID.
- Status : Uart Status
- payload: amount of data in report.
- protocol : defines to which action the transmitted data belongs
- prot status : a non-zero value indicates error condition of command (return value of function commands())
- txprot: size of data in response
- data: response data for command
UART Settings:
- BAUD RATE: 115200
- DATA BITS: 8
- PARITY: NONE
- STOP BITS: 1
- FLOW CONTROL: NONE
Example for the config TX RX command, handled by callConfigTxRx():
Request from host (Reader Suite):
| Byte | 0 | 1 | 2..3 | 4 | 5..6 | 7..8 | 9..12 |
|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | txprot | rxprot | data |
| Parameter | 0x20 | 0x00 | 0x00 09 | 0x04 | 0x00 04 | 0x00 04 | 0x00 00 01 01 |
where:
- 0x04: command ID for callConfigTxRx(), is also used as index in call_fkt_() table.
- 0x00 00 01 01 : parameter for callConfigTxRx() (set_sensitivity = false and sensitivity = 0; set_antenna = true and antenna id = 1)
The reader answer with this report:
| Byte | 0 | 1 | 2..3 | 4 | 5 | 6 | 7..8 | 9..12 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | reserved | prot status | txprot | data |
| Parameter | 0x01 | 0x00 | 0x00 09 | 0x04 | 0x00 | 0x00 | 0x00 04 | 0x00 0B 00 01 |
- 0x00 0B 00 01: reserved bytes are 0x00, sensitivity is 0x0B and antenna id is 0x01
Example for the Inventory Gen2 command, handled by callInventoryGen2():
Request from host (Reader Suite):
| Byte | 0 | 1 | 2..3 | 4 | 5..6 | 7..8 | 9..12 |
|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | txprot | rxprot | data |
| Parameter | 0x07 | 0x00 | 0x00 08 | 0x85 | 0x00 03 | 0x00 00 | 0x00 01 06 |
where:
- 0x85: command ID for callInventoryGen2(), is also used as index in call_fkt_() table.
- 0x00 01 06 : parameter for callInventoryGen2()
The reader answer with this report:
| Byte | 0 | 1 | 2..3 | 4 | 5 | 6 | 7..8 | 9..12 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | reserved | prot status | txprot | data |
| Parameter | 0x76 | 0x00 | 0x00 14 | 0x05 | 0x00 | 0x00 | 0x00 0F | 00 00 01 8f ff ac 3c 0d 06 10 00 ba ba 77 77 |
- 0xba ba 77 77: epc of tag
Example for the Read from Tag command, handled by callReadFromTag():
Request from host (Reader Suite):
| Byte | 0 | 1 | 2..3 | 4 | 5..6 | 7..8 | 9..17 |
|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | txprot | rxprot | data |
| Parameter | 0x3E | 0x00 | 0x00 0e | 0x08 | 0x00 09 | 0x00 09 | 0x00 00 00 00 00 00 00 00 00 |
where:
- 0x08: command ID for callReadFromTag(), is also used as index in call_fkt_() table.
- 0x00 00 00 00 00 00 00 00 00 : parameter for callReadFromTag()
The reader answer with this report:
| Byte | 0 | 1 | 2..3 | 4 | 5 | 6 | 7..8 | 9..16 |
|---|---|---|---|---|---|---|---|---|
| Content | TID | Status | payload | protocol | reserved | prot status | txprot | data |
| Parameter | 0xE7 | 0x00 | 0x00 0D | 0x08 | 0x00 | 0x00 | 0x00 08 | 00 00 00 00 55 55 55 55 |
- 00 00 00 00 55 55 55 55: reserved memory of the tag
Implemented commands
Functions which handle the commands from the host are located in appl_commands.c
- callAntennaPower()
- callAntennaTuner()
- callAutoTuner()
- callChangeFreq()
- callConfigGen2()
- callConfigTxRx()
- callInventoryGen2()
- callInventory6B()
- callReadFromTag6B()
- callKillTag()
- callLockUnlockTag()
- callReadFromTag()
- callReaderConfig()
- callSelectTag()
- callStartStop()
- callTunerTable()
- callWriteToTag()
- callWrongCommand()
The documentation of the various appl command functions will only discuss the data received/sent back to host and will not include the header information for every transmitted packet.
For more details on the ams stream protocol have a look into ams_stream.h
Definition at line 3324 of file appl_commands.c.