Eichrecht - Transmission of data
--------------------------------

In order to allow be.ENERGISED to show the user
the validity of signed meter values, station need
to send different type of information to the backend
with in OCPP. Namely those are on the one hand
the signed values itself and on the other hand the
public keys, which are needed by the Transparenzsoftware
to verify the transferred information. This information
can be provided in different ways.

All embedded in the signed values
=================================
In `OCPP 2.0.1` the protocol got much clearer on how to
transfer public keys and signed values, as it introduced
an extra datastructure for this. This is also the preferred
way how signed values should be transferred in ocpp 1.6
with a small adaptions, where the `value` just contains
the full object as in `OCPP 2.0.1` suggested.

JSON Example

.. code-block:: json

    [
       2,
       "1234",
       "StopTransaction",
       {
          "reason":"Local",
          "transactionId":123,
          "meterStop":500,
          "timestamp":"2022-08-27T12:34:56.000Z",
          "transactionData":[
             {
                "sampledValue":[
                   {
                      "unit":"Wh",
                      "context":"Transaction.End",
                      "format":"SignedData",
                      "location":"Outlet",
                      "measurand":"Energy.Active.Import.Register",
                      "value":"{\"signedMeterValue\":\"<base64 encoded OCMF string>\", \"encodingMethod\":\"OCMF\", \"publicKey\":\"<public key>\"}"
                   }
                ],
                "timestamp":"2022-08-27T12:34:56.000Z"
             }
          ]
       }
    ]

SOAP Example

.. code-block:: xml

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="urn://Ocpp/Cs/2015/10/">
       <soap:Header>
          <ns:chargeBoxIdentity>ABCDEF12345</ns:chargeBoxIdentity>
       </soap:Header>
       <soap:Body>
          <ns:meterValuesRequest>
             <ns:connectorId>1</ns:connectorId>
             <ns:transactionId>1234567</ns:transactionId>
             <ns:meterValue>
                <ns:timestamp>2018-08-02T08:58:21Z</ns:timestamp>
                <ns:sampledValue>
                   <ns:value>{"signedMeterValue":"<base64 encoded OCMF string>", "encodingMethod":"OCMF", "publicKey":"<public key>"}</ns:value>
                   <ns:context>Transaction.Begin</ns:context>
                   <ns:format>SignedData</ns:format>
                   <ns:measurand>Energy.Active.Import.Register</ns:measurand>
                </ns:sampledValue>
             </ns:meterValue>
          </ns:meterValuesRequest>
       </soap:Body>
    </soap:Envelope>


We further suggest, that all relevant values which should be
checked by the Transparenzsoftware are sent as part of
the `StopTransactionRequest`.

Currently all type of signed values which are supported in the
Transparencysoftware (Versions: 1.0, 1.1, 1.2), are also supported
by the backend.

.. code-block:: json

    [
       2,
       "1234",
       "StopTransaction",
       {
          "reason":"Local",
          "transactionId":123,
          "meterStop":500,
          "timestamp":"2022-08-27T12:34:56.000Z",
          "transactionData":[
             {
                "sampledValue":[
                    {
                      "unit":"Wh",
                      "context":"Transaction.Start",
                      "format":"SignedData",
                      "location":"Outlet",
                      "measurand":"Energy.Active.Import.Register",
                      "value":"{\"signedMeterValue\":\"<base64 encoded OCMF string>\", \"encodingMethod\":\"OCMF\", \"publicKey\":\"<public key>\"}"
                   },
                   {
                      "unit":"Wh",
                      "context":"Transaction.End",
                      "format":"SignedData",
                      "location":"Outlet",
                      "measurand":"Energy.Active.Import.Register",
                      "value":"{\"signedMeterValue\":\"<base64 encoded OCMF string>\", \"encodingMethod\":\"OCMF\", \"publicKey\":\"<public key>\"}"
                   }
                ],
                "timestamp":"2022-08-27T12:34:56.000Z"
             }
          ]
       }
    ]

If the station is not following this suggestion, the backend will still try
to parse on the transferred data and will treat the string defined
in `value` of the `MeterValue` object as a signed value. With this setup
though the station needs to send the public key via different way.

Additional options to send a public key
=======================================
In addition to the suggestion above, the backend will also understand
the submission of public keys with a custom `DataTransfer` message.

.. list-table:: setMeterConfiguration (Public key transfer)
   :widths: 25 25 50
   :header-rows: 1

   * - Key
     - Type
     - Description
   * - connectorId
     - int (required)
     - connectorId according to the OCPP specification
   * - meterSerial
     - string (optional)
     - Serialnumber of the meter connected to this public key
   * - type
     - string (required)
     - Defined the type of conformity (see list below)
   * - publicKey
     - string (optional)
     - Actual public key hex encoded (necessary if type is set
       to `SIGNATURE`)

The different types derive from different possibilities on how the
conformity is reached. Following types are currently allowed

.. list-table:: Type passed in meter configuration
   :widths: 25 75
   :header-rows: 1

   * - Type
     - Description
   * - SIGNATURE
     - Station will transmit signed values to the backend
   * - LOCAL
     - Only local (local on the station) via visibility on the station itself
       (Note that this cannot be automatically ensured by the backend then)

SOAP Example

.. code-block:: xml

    <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ns="urn://Ocpp/Cs/2015/10/">
       <soap:Header>
          <ns:chargeBoxIdentity>ABCDEF12345</ns:chargeBoxIdentity>
       </soap:Header>
       <soap:Body>
          <ns:DataTransferRequest>
             <ns:vendorId>generalConfiguration</ns:vendorId>
             <ns:messageId>setMeterConfiguration</ns:messageId>
             <ns:data>{"meters":[{"connectorId":1,"meterSerial":"123456789","type":"SIGNATURE","publicKey":"887FABF407AC82782EEFFF2220C2F856AEB0BC22364BBCC6B55761911ED651D1A922BADA88818C9671AFEE7094D7F536"}]}</ns:data>
          </ns:DataTransferRequest>
       </soap:Body>
    </soap:Envelope>

JSON Example

.. code-block:: json

    {
      "vendorId": "generalConfiguration",
      "messageId": "setMeterConfiguration",
      "data": "{\"meters\":[{\"connectorId\":1,\"meterSerial\":\"123456789\",\"type\":\"SIGNATURE\",\"publicKey\":\"887FABF407AC82782EEFFF2220C2F856AEB0BC22364BBCC6B55761911ED651D1A922BADA88818C9671AFEE7094D7F536\"}]}"
    }