REST API through NFC

1. REST API over NFC

TODO: improve and use https://mybender-my.sharepoint.com/🅱️/g/personal/andreas_weber_ebee_de/EWFQQ0KXqphBjkJd6QCxTF4BOhbrc6fdno-UlXq5VpWLg

1.1. Configuring through NFC

The Charge Controller's REST API can be accessed via NFC to simplify preconfiguring a Charge Controller with your manufacturer settings.

2. Requirements

Make sure that you

• Have access to a smartphone with NFC support
• Have physical access to the HMI module of your Chargepoint

3. NFC mapping - protocol stack

To access the API from an NFC equipped smartphone, the following protocol stack is used:

Parameter	Value
Data Link Layer (MAC)	ISO 18092 NFCIP-1
Data Link Layer (Logical)	LLCP – Logical link control protocol
Application Layer	SNEP – Simple NFC exchange protocol
Application Data Container	NDEF – NFC Data Exchange Format - Text Record Type Messages

4. Enabling the NFC configuration mode

Charge Controllers support the ISO 14443 standard for regular use and ISO 18092 for manufacturer configuration purposes. Before you can configure the Charge Controller via NFC you first need to change the mode to support ISO 18092 interactions:

1. Emulate an RFID card with the UID = 0x08EBEE08
2. Read this RFID card with the HMI of your Charge Controller

After the Charge Controller reads an RFID card with that UID, it is ready to take in configuration data via NFC.

Ändert sich hierbei die LED am Charge Controller?

info

In this mode, the HMI will not read any regular RFID cards.

4.1. How to check that the NFC configuration mode is active

The user interface of the charger displays the blinking code for "Reading card" if it is in NFC configuration mode.

5. Disabling the NFC configuration mode

After 1 minute of inactivity the HMI switches back to the regular mode. You should see a change in the blinking pattern when this happens.

6. Request/response messaging

The NDEF Text messages provide a transport for text messages including transmitting their length. The protocol therefore does not need to transmit length information in the header like it is the case in HTTP.

However, some header information needs to be transmitted also for this transport which is otherwise not provided by the NDEF infrastructure. This includes the URL which defines the service type, the HTTP method as well as login information.

To provide a replacement for the HTTP header information in NDEF a separate JSON based header is transmitted for request messages. An example header looks like this:

{
"path": "/settings",
"method" : "POST",
"authorization" : "cdc630cd-5e5f-4587-8a1a-a2e83ae990b5",
"messageID" : "msg-id-increment"
}

The protocol allows for only one outstanding request message. Pipelining multiple messages is not allowed. It is therefore unambiguously clear which response message belongs to which request messages. The response header contains the message ID and status to replicate the functionality otherwise provided by the HTTP header.

{
"messageID": "msg-id-increment",
"statusCode": 401
}

In both request and response messages an optional content JSON document can follow the header. If a JSON document exists it is separated from the header by a comma (ASCII character 0x2C). In request messages which are fully defined by the request header (e.g. with method GET) no content document is needed. In response messages which do not provide any content as response (such as the equivalent of an HTTP error message) no content JSON object is transmitted.

The status code returned from the server is equivalent to the HTTP status code that would be used according to REST principles.

The message id which is defined by the client is recommended to be a number which is incremented in between consecutive messages and not randomized to ease the detection of bugs when analyzing logs.

7. Authentication

The NFC mapping of the interface is password protected in the same fashion as the HTTP interface. Only the endpoint /v1/login is available without login credentials. All other endpoints require the provision of a valid authorization header.