EVerest API definition for powermeters 1.0.0

API for EVerest API clients implementing powermeter.

  • #EVerest
  • #powermeter

Servers

  • mqtt://localhost:1883/everest_api/1/powermeter/{module_id}mqttdefault

    default local MQTT

    object
    module_id
    required
    string

    The ID of the module as defined in the EVerest config file.

Operations

  • REPLY e2m/start_transaction

    Request to reply.

    This operation is used to handle the request to start a new transaction on the powermeter (for signed metering according to German Eichrecht).

    Operation IDreceive_request_start_transaction

    Available only on servers:

    Accepts the following message:

    Start transaction request messagereceive_request_start_transaction

    The start transaction request message contains the required input parameter for starting an OCMF transaction. These values will be included in the signed OCMF packet of the stop transaction reply.

    Message IDreceive_request_start_transaction
    object

    Examples

    REPLY INFORMATION

    REPLY CHANNEL INFORMATION

    Reply will be directed to the address specified at this location: $message.header#/replyTo

    REPLY address information

    REPLY will be sent to the address provided in:$message.header#/replyTo

  • SEND

    Dynamically defined channel. Used to reply to a start_transaction message.

    Request to reply.

    This operation is used to handle the request to start a new transaction on the powermeter (for signed metering according to German Eichrecht).

    Operation IDsend_reply_start_transaction

    Available only on servers:

    Accepts the following message:

    Start transaction reply messagesend_reply_start_transaction

    The start transaction reply message contains the request status. It indicates whether the transaction could be started successfully or not. Further values may be added to the message depending on the value of the status.

    Message IDsend_reply_start_transaction
    object

    Return value when a transaction is started.

    Examples

  • REPLY e2m/stop_transaction

    Request to reply.

    This operation is used to handle the request to stop the transaction on the powermeter and ask for the signed metering information in a reply.

    Operation IDreceive_request_stop_transaction

    Available only on servers:

    Accepts the following message:

    Stop transaction request messagereceive_request_stop_transaction

    The stop transaction request message contains the transaction id to stop the corresponding transaction.

    Message IDreceive_request_stop_transaction
    object

    Examples

    REPLY INFORMATION

    REPLY CHANNEL INFORMATION

    Reply will be directed to the address specified at this location: $message.header#/replyTo

    REPLY address information

    REPLY will be sent to the address provided in:$message.header#/replyTo

  • SEND

    Dynamically defined channel. Used to reply to a stop_transaction message.

    Request to reply.

    This operation is used to handle the request to stop the transaction on the powermeter and ask for the signed metering information in a reply.

    Operation IDsend_reply_stop_transaction

    Available only on servers:

    Accepts the following message:

    Stop transaction reply messagesend_reply_stop_transaction

    The stop transaction reply message contains the request status. It indicates whether the transaction could be stopped successfully or not. If successful the signed meter value report must be provided in this message too.

    Message IDsend_reply_stop_transaction
    object

    Report returned when a signed transaction is requested to stop. If successful, includes the signed meter value object. In case of an error, an additional error message can be provided.

    Examples

  • SEND m2e/powermeter_values

    Direction: Module to EVerest

    This operation is used to send a dataset of measured values. The timestamp and the imported energy (in Wh) are required. Other values are optional.

    Operation IDsend_powermeter_values

    Available only on servers:

    Accepts the following message:

    Send powermeter valuessend_powermeter_values

    The send powermeter values message contains the measured dataset. It requires a timestamp and the imported energy in Wh at least. Other values are optional.

    Message IDsend_powermeter_values
    object

    Measured dataset (AC or DC)

    Examples

  • SEND m2e/public_key_ocmf

    Operation IDsend_public_key_ocmf

    Available only on servers:

    Accepts the following message:

    Send the public keysend_public_key_ocmf

    Provide the public key used to sign the OCMF data

    Message IDsend_public_key_ocmf
    Payload
    string

    The public key as string used to sign the OCMF data

    Examples

  • RECEIVE e2m/heartbeat

    Operation IDreceive_heartbeat

    Available only on servers:

    Accepts the following message:

    Receive heartbeatreceive_heartbeat

    Heartbeat produced by EVerest as configured via cfg_heartbeat_interval_ms in the EVerest configuration

    Message IDreceive_heartbeat
    Payload
    integer

    64bit unsigned integer. The id of every heartbeat increases by 1 and overflows when the maximum representable value is reached

    Examples

  • SEND m2e/communication_check

    Operation IDsend_communication_check

    Available only on servers:

    Accepts the following message:

    Send communication checksend_communication_check

    Signal to EVerest that communication is good or check shall be stopped

    Message IDsend_communication_check
    Payload
    boolean

    Send 'true' at least every 'cfg_communication_check_to_s' seconds to signal module is alive. Send 'false' to stop communication check'

    Examples

Messages

  • #1Start transaction request messagereceive_request_start_transaction

    The start transaction request message contains the required input parameter for starting an OCMF transaction. These values will be included in the signed OCMF packet of the stop transaction reply.

    Message IDreceive_request_start_transaction
    object
  • #2Start transaction reply messagesend_reply_start_transaction

    The start transaction reply message contains the request status. It indicates whether the transaction could be started successfully or not. Further values may be added to the message depending on the value of the status.

    Message IDsend_reply_start_transaction
    object

    Return value when a transaction is started.

  • #3Stop transaction request messagereceive_request_stop_transaction

    The stop transaction request message contains the transaction id to stop the corresponding transaction.

    Message IDreceive_request_stop_transaction
    object
  • #4Stop transaction reply messagesend_reply_stop_transaction

    The stop transaction reply message contains the request status. It indicates whether the transaction could be stopped successfully or not. If successful the signed meter value report must be provided in this message too.

    Message IDsend_reply_stop_transaction
    object

    Report returned when a signed transaction is requested to stop. If successful, includes the signed meter value object. In case of an error, an additional error message can be provided.

  • #5Send powermeter valuessend_powermeter_values

    The send powermeter values message contains the measured dataset. It requires a timestamp and the imported energy in Wh at least. Other values are optional.

    Message IDsend_powermeter_values
    object

    Measured dataset (AC or DC)

  • #6Send the public keysend_public_key_ocmf

    Provide the public key used to sign the OCMF data

    Message IDsend_public_key_ocmf
    Payload
    string

    The public key as string used to sign the OCMF data

  • #7Receive heartbeatreceive_heartbeat

    Heartbeat produced by EVerest as configured via cfg_heartbeat_interval_ms in the EVerest configuration

    Message IDreceive_heartbeat
    Payload
    integer

    64bit unsigned integer. The id of every heartbeat increases by 1 and overflows when the maximum representable value is reached

  • #8Send communication checksend_communication_check

    Signal to EVerest that communication is good or check shall be stopped

    Message IDsend_communication_check
    Payload
    boolean

    Send 'true' at least every 'cfg_communication_check_to_s' seconds to signal module is alive. Send 'false' to stop communication check'

Schemas

  • OCMFIdentificationFlags
    string
    • RFID_NONE: No assignment via RFID
    • RFID_PLAIN: Assignment via external RFID card reader
    • RFID_RELATED: Assignment via protected RFID card reader
    • RFID_PSK: A previously known shared key (pre-shared key) was used, e.g. with a secured RFID card.
    • OCPP_NONE: No user assignment by OCPP
    • OCPP_RS: Assignment by OCPP RemoteStart method
    • OCPP_AUTH: Assignment by OCPP Authorize method
    • OCPP_RS_TLS: Assignment by OCPP RemoteStart method, obtained via a secured TLS connection.
    • OCPP_AUTH_TLS: Assignment by OCPP Authorize method, obtained via a secured TLS connection.
    • OCPP_CACHE: Assignment by authorization cache of OCPP
    • OCPP_WHITELIST: Assignment by whitelist from OCPP
    • OCPP_CERTIFIED: A certificate of the backend was used which certifies the user mapping.
    • ISO15118_NONE: no user assignment by ISO 15118
    • ISO15118_PNC: Plug & Charge was used
    • PLMN_NONE: no user assignment
    • PLMN_RING: call
    • PLMN_SMS: short message
      Allowed values:
    • "RFID_NONE"
    • "RFID_PLAIN"
    • "RFID_RELATED"
    • "RFID_PSK"
    • "OCPP_NONE"
    • "OCPP_RS"
    • "OCPP_AUTH"
    • "OCPP_RS_TLS"
    • "OCPP_AUTH_TLS"
    • "OCPP_CACHE"
    • "OCPP_WHITELIST"
    • "OCPP_CERTIFIED"
    • "ISO15118_NONE"
    • "ISO15118_PNC"
    • "PLMN_NONE"
    • "PLMN_RING"
    • "PLMN_SMS"
  • OCMFIdentificationLevel
    string
    • NONE: There is no user assignment. The other data for user assignment have no significance.
    • HEARSAY: The assignment is unsecured; e.g. by reading an RFID UID.
    • TRUSTED: The mapping can be trusted to some extent, but there is no absolute reliability. Example: Authorization by backend.
    • VERIFIED: The assignment has been verified by the signature component and special measures.
    • CERTIFIED: The assignment was verified by the signature component using a cryptographic signature that certifies the assignment.
    • SECURE: The mapping was established by a secure feature (e.g. secure RFID card, ISO 15118 with plug and charge, etc.).
    • MISMATCH: Error; UIDs do not match.
    • INVALID: Error; certificate not correct (check negative).
    • OUTDATED: Error; referenced trust certificate expired.
    • UNKNOWN: Certificate could not be successfully verified (no matching trust certificate found).
      Allowed values:
    • "NONE"
    • "HEARSAY"
    • "TRUSTED"
    • "VERIFIED"
    • "CERTIFIED"
    • "SECURE"
    • "MISMATCH"
    • "INVALID"
    • "OUTDATED"
    • "UNKNOWN"
  • OCMFIdentificationType
    string
    • NONE: No assignment available
    • DENIED: Assignment currently not available (due to two-factor authorization)
    • UNDEFINED: Type not specified
    • ISO14443: UID of an RFID card according to ISO 14443. Represented as 4 or 7 bytes in hexadecimal notation.
    • ISO15693: UID of an RFID card according to ISO 15693. Represented as 8 bytes in hexadecimal notation.
    • EMAID: Electro-Mobility-Account-ID according to ISO/IEC 15118 (string with length 14 or 15)
    • EVCCID: ID of an electric vehicle according to ISO/IEC 15118 (maximum length 6 characters)
    • EVCOID: EV Contract ID according to DIN 91286.
    • ISO7812: Identification card format according to ISO/IEC 7812 (credit and bank cards, etc.)
    • CARD_TXN_NR: Card transaction number (CardTxNbr) for a payment with credit or bank card used in a terminal at the charging point.
    • CENTRAL: Centrally generated ID. No exact format defined, can be e.g. a UUID. (OCPP 2.0)
    • CENTRAL_1: Centrally generated ID, e.g. by start via SMS. No exact format defined. (until OCPP 1.6)
    • CENTRAL_2: Centrally generated ID, e.g. by operator start. No exact format defined. (until OCPP 1.6)
    • LOCAL: Locally generated ID. No exact format defined, might be e.g. a UUID. (OCPP 2.0)
    • LOCAL_1: Locally generated ID, e.g. ID generated internally by the charge point. No exact format defined. (until OCPP 1.6)
    • LOCAL_2: Locally generated ID, for other cases. No exact format defined. (until OCPP 1.6)
    • PHONE_NUMBER: International phone number with leading "+".
    • KEY_CODE: User-related private key code. No exact format defined.
      Allowed values:
    • "NONE"
    • "DENIED"
    • "UNDEFINED"
    • "ISO14443"
    • "ISO15693"
    • "EMAID"
    • "EVCCID"
    • "EVCOID"
    • "ISO7812"
    • "CARD_TXN_NR"
    • "CENTRAL"
    • "CENTRAL_1"
    • "CENTRAL_2"
    • "LOCAL"
    • "LOCAL_1"
    • "LOCAL_2"
    • "PHONE_NUMBER"
    • "KEY_CODE"
  • OCMFUserIdentificationStatus
    string

    General status for user assignment

    • ASSIGNED: user successfully assigned
    • NOT_ASSIGNED: user not assigned
      Allowed values:
    • "ASSIGNED"
    • "NOT_ASSIGNED"
  • object

    Measured dataset (AC or DC)

  • SendPublicKeyOCMF
    string

    The public key as string used to sign the OCMF data

  • object

    Return value when a transaction is started.

  • object
  • object

    Report returned when a signed transaction is requested to stop. If successful, includes the signed meter value object. In case of an error, an additional error message can be provided.

  • object

    Temperature sensor expressed in C and a description (vendor specific) allowing to identify its purpose or meaning

  • TransactionStatus
    string

    Status of a start or stop transaction - used in start or stop transaction reply.

      Allowed values:
    • "OK"
    • "NOT_SUPPORTED"
    • "UNEXPECTED_ERROR"
  • units
    any

    Unit types

  • units_signed
    any

    Unit types signed

  • CommunicationCheck
    boolean

    Send 'true' at least every 'cfg_communication_check_to_s' seconds to signal module is alive. Send 'false' to stop communication check'

  • HeartBeatId
    integer

    64bit unsigned integer. The id of every heartbeat increases by 1 and overflows when the maximum representable value is reached