README.rst
1Casimir
2=======
3
4Introduction
5------------
6
7Casimir aims to provide virtual tag discovery and emulation for NFC
8applications, in order to unlock NFC capability in various testing
9contexes.
10
11Casimir includes a virtual NFCC implementation, and internally emulates
12RF communications between multiple connected hosts. Cf the RF packets
13specification in ``src/rf_packets.pdl``.
14
15
16Usage
17-----
18
19Standalone
20^^^^^^^^^^
21
22Casimir may be built and run as a standalone server.
23
24.. sourcecode:: bash
25 Usage: casimir [--nci-port <nci-port>] [--rf-port <rf-port>]
26
27 Nfc emulator.
28
29 Options:
30 --nci-port configure the TCP port for the NCI server.
31 --rf-port configure the TCP port for the RF server.
32 --help display usage information
33
34Cuttlefish
35^^^^^^^^^^
36
37Cuttlefish runs casimir as a host service for emulating the NFC chipset inside
38the Android phone. The port numbers for a *local instance* can be obtained from
39the instance number:
40
41- ``nci_port`` is ``7100 + instance_num - 1``
42- ``rf_port`` is ``8100 + instance_num - 1``
43
44Tests
45^^^^^
46
47The script ``scripts/t4at.py`` may be used to emulate a Type 4-A Tag device on
48the RF port, in either listen or poll mode.
49
50.. sourcecode:: bash
51 usage: t4at.py [-h] [--address ADDRESS] [--rf-port RF_PORT] [--mode {poll,listen}
52
53 options:
54 -h, --help show this help message and exit
55 --address ADDRESS Select the casimir server address
56 --rf-port RF_PORT Select the casimir TCP RF port
57 --mode {poll,listen} Select the tag mode
58
59To run a basic tag detection test on Cuttlefish:
60
61.. sourcecode:: bash
62
63 # Start the cuttlefish instance (numbered 1)
64 # Wait for NFC start up.
65 launch_cvd
66
67 # Create a tag device connected to the casimir instance.
68 cd $ANDROID_TOP/system/nfc/tools/casimir
69 ./scripts/t4at.py --rf-port 8100 --mode listen
70
71
72Supported features
73------------------
74
75Casimir currently supports a subset of the NFC features described in the
76following technical specification documents:
77
78- ``[NCI]`` NFC Controller Interface Technical Specification Version 2.2
79- ``[DIGITAL]`` Digital Protocol Technical Specification Version 2.3
80- ``[ACTIVITY]`` Activity Technical Specification Version 2.2
81
82Supported technologies: ``NFC_A``
83Supported protocols: ``ISO_DEP``, ``NFC_DEP``
84Supported RF interfaces: ``ISO_DEP``, ``NFC_DEP``
85
86NCI Commands
87^^^^^^^^^^^^
88Core management
89"""""""""""""""
90+---------------------------------+--------------+-------------------------------------------------+
91| CORE_RESET_CMD | Completed | |
92| CORE_RESET_RSP | | |
93| CORE_RESET_NTF | | |
94+---------------------------------+--------------+-------------------------------------------------+
95| CORE_INIT_CMD | Completed | To be defined: number and type of RF |
96| CORE_INIT_RSP | | interfaces. It seems that the mandated default |
97| | | is 1 : frame RF interface. |
98| | | To be defined: default configuration for the |
99| | | NFCC, best is to get one from a real phone |
100| | | NCI trace. |
101+---------------------------------+--------------+-------------------------------------------------+
102| CORE_SET_CONFIG_CMD | Completed | The configuration is saved but currently |
103| CORE_SET_CONFIG_RSP | | unused. Basic validation is implemented. |
104+---------------------------------+--------------+-------------------------------------------------+
105| CORE_GET_CONFIG_CMD | Completed | |
106| CORE_GET_CONFIG_RSP | | |
107+---------------------------------+--------------+-------------------------------------------------+
108| CORE_CONN_CREATE_CMD | Completed | |
109| CORE_CONN_CREATE_RSP | | |
110+---------------------------------+--------------+-------------------------------------------------+
111| CORE_CONN_CLOSE_CMD | Completed | |
112| CORE_CONN_CLOSE_RSP | | |
113+---------------------------------+--------------+-------------------------------------------------+
114| CORE_CONN_CREDITS_NTF | Completed | |
115+---------------------------------+--------------+-------------------------------------------------+
116| CORE_GENERIC_ERROR_NTF | Not started | Unused in the implementation so far |
117| CORE_INTERFACE_ERROR_NTF | | |
118+---------------------------------+--------------+-------------------------------------------------+
119| CORE_SET_POWER_SUB_STATE_CMD | In progress | Implemented as stub |
120| CORE_SET_POWER_SUB_STATE_RSP | | |
121+---------------------------------+--------------+-------------------------------------------------+
122
123RF management
124"""""""""""""
125+---------------------------------+--------------+-------------------------------------------------+
126| RF_DISCOVER_MAP_CMD | Completed | |
127| RF_DISCOVER_MAP_RSP | | |
128+---------------------------------+--------------+-------------------------------------------------+
129| RF_SET_LISTEN_MODE_ROUTING_CMD | In progress | Implemented as stub |
130| RF_SET_LISTEN_MODE_ROUTING_RSP | | |
131+---------------------------------+--------------+-------------------------------------------------+
132| RF_GET_LISTEN_MODE_ROUTING_CMD | In progress | Implemented as stub |
133| RF_GET_LISTEN_MODE_ROUTING_RSP | | |
134| RF_GET_LISTEN_MODE_ROUTING_NTF | | |
135+---------------------------------+--------------+-------------------------------------------------+
136| RF_DISCOVER_CMD | Completed | |
137| RF_DISCOVER_RSP | | |
138| RF_DISCOVER_NTF | | |
139+---------------------------------+--------------+-------------------------------------------------+
140| RF_DISCOVER_SELECT_CMD | In progress | Missing protocol and interface combinations |
141| RF_DISCOVER_SELECT_RSP | | |
142+---------------------------------+--------------+-------------------------------------------------+
143| RF_INTF_ACTIVATED_NTF | Completed | |
144+---------------------------------+--------------+-------------------------------------------------+
145| RF_DEACTIVATE_CMD | In progress | |
146| RF_DEACTIVATE_RSP | | |
147| RF_DEACTIVATE_NTF | | |
148+---------------------------------+--------------+-------------------------------------------------+
149| RF_FIELD_INFO_NTF | Not started | |
150+---------------------------------+--------------+-------------------------------------------------+
151| RF_T3T_POLLING_CMD | Not started | |
152| RF_T3T_POLLING_RSP | | |
153| RF_T3T_POLLING_NTF | | |
154+---------------------------------+--------------+-------------------------------------------------+
155| RF_NFCEE_ACTION_NTF | Not started | |
156+---------------------------------+--------------+-------------------------------------------------+
157| RF_NFCEE_DISCOVERY_REQ_NTF | Completed | |
158+---------------------------------+--------------+-------------------------------------------------+
159| RF_PARAMETER_UPDATE_CMD | Not started | |
160| RF_PARAMETER_UPDATE_RSP | | |
161+---------------------------------+--------------+-------------------------------------------------+
162| RF_INTF_EXT_START_CMD | Not started | |
163| RF_INTF_EXT_START_RSP | | |
164+---------------------------------+--------------+-------------------------------------------------+
165| RF_INTF_EXT_STOP_CMD | Not started | |
166| RF_INTF_EXT_STOP_RSP | | |
167+---------------------------------+--------------+-------------------------------------------------+
168| RF_EXT_AGG_ABORT_CMD | Not started | |
169| RF_EXT_AGG_ABORT_RSP | | |
170+---------------------------------+--------------+-------------------------------------------------+
171| RF_NDEF_ABORT_CMD | Not started | |
172| RF_NDEF_ABORT_RSP | | |
173+---------------------------------+--------------+-------------------------------------------------+
174| RF_ISO_DEP_NAK_PRESENCE_CMD | Not started | |
175| RF_ISO_DEP_NAK_PRESENCE_RSP | | |
176| RF_ISO_DEP_NAK_PRESENCE_NTF | | |
177+---------------------------------+--------------+-------------------------------------------------+
178| RF_SET_FORCED_NFCEE_ROUTING_CMD | Not started | |
179| RF_SET_FORCED_NFCEE_ROUTING_RSP | | |
180+---------------------------------+--------------+-------------------------------------------------+
181
182NFCEE management
183""""""""""""""""
184+---------------------------------+--------------+-------------------------------------------------+
185| NFCEE_DISCOVER_CMD | In progress | Implemented discovery for one NFCEE (eSE (ST)) |
186| NFCEE_DISCOVER_RSP | | reproducing the configuration found on Pixel7 |
187| NFCEE_DISCOVER_NTF | | devices. |
188+---------------------------------+--------------+-------------------------------------------------+
189| NFCEE_MODE_SET_CMD | Completed | |
190| NFCEE_MODE_SET_RSP | | |
191| NFCEE_MODE_SET_NTF | | |
192+---------------------------------+--------------+-------------------------------------------------+
193| NFCEE_STATUS_NTF | Not started | |
194+---------------------------------+--------------+-------------------------------------------------+
195| NFCEE_POWER_AND_LINK_CNTRL_CMD | Not started | |
196| NFCEE_POWER_AND_LINK_CNTRL_RSP | | |
197+---------------------------------+--------------+-------------------------------------------------+
198