Integrate Tariff and Cost

This guide explains how to subscribe to tariff and session cost updates published by EVerest, and how the data flow differs between OCPP 1.6 and OCPP 2.x.

Prerequisites

  • An EVerest deployment with an OCPP module (OCPP for 1.6 or OCPP201 for 2.x) and the Auth module and the relevant API modules (see next section).

  • An API client that connects via MQTT and subscribes to the relevant consumer API topics.

Relevant Consumer APIs

Two consumer APIs carry tariff and cost information:

  • Session cost consumer API — provides the tariff_message and session_cost variables on the session_cost interface.

  • Auth consumer API — provides token_validation_status, which may include tariff messages received at authorization time.

At least the session cost consumer API must be subscribed to receive tariff and cost updates.

See the AsyncAPI reference for the auth_consumer_API and the session_cost_consumer_API for message schemas.

Note

The OCPP implementations follow the requirements of the OCA California Pricing Whitepaper. Note that this whitepaper contains requirements for displaying pricing information to the user, so in order to comply with it, the tariff and session cost messages must be used to show the required information on a charger display. The APIs only provide the necessary data.

OCPP configuration

If you plan to use session cost information from OCPP (e.g. according to the California Pricing requirements), you need to configure the OCPP modules to receive tariff and cost information from the CSMS.

OCPP 1.6

Enable the CostAndPrice profile in the OCPP 1.6 module configuration. Once enabled, the OCPP module registers the tariff message and session cost callbacks. Configure the configuration keys of the CostAndPrice profile as needed.

OCPP 2.x

Enable the TariffCostCtrlr in the OCPP 2.x device model. The component variables TariffEnabled and CostEnabled control which features are active:

  • TariffEnabled — publishes tariff / pricing messages via the tariff_message variable.

  • CostEnabled — publishes running and final session cost via the session_cost variable.

Both can be enabled independently. Also configure other variables of the TariffCostCtrlr as needed.

Note

Additional requirements of the OCPP 2.1 specification with respect to tariff and costs have not yet been implemented. The implemented features can still be used with OCPP 2.1.

Tariff message flow

Tariff messages contain human-readable pricing text in one or more languages. They are published on the tariff_message variable of the session cost consumer API.

OCPP 1.6

Tariff messages originate from a SetUserPrice DataTransfer message sent by the CSMS. The CSMS typically sends this message shortly after the Authorize.conf, so the tariff message is available close to authorization time.

If the SetUserPrice DataTransfer is not received within the configured timeout, a default tariff message (if configured) is published instead.

OCPP 2.x

Tariff messages are published at two points:

  1. Authorization time — from the personalMessage field in the AuthorizeResponse. The tariff message is also included in the messages field of the token_validation_status on the auth consumer API. At this point the identifier_type is IdToken and the identifier_id is the token value, since no transaction exists yet.

  2. During the session — from the updatedPersonalMessage field in TransactionEventResponse messages. At this point the identifier_type is TransactionId and the identifier_id is the OCPP transaction ID.

Note

To correlate auth-time tariff messages (keyed by IdToken) with in-session updates (keyed by TransactionId), use the token_validation_status message on the auth consumer API to capture the token, then match it against the session information from the EVSE manager consumer API.

Session cost flow

Session cost messages contain the accumulated cost of a charging session, broken down into cost chunks (energy, time, flat fees), with current and next-period pricing. They are published on the session_cost variable of the session cost consumer API.

OCPP 1.6

Session cost updates are triggered by RunningCost and FinalCost DataTransfer messages from the CSMS.

OCPP 2.x

Session cost updates are triggered by:

  • totalCost in a TransactionEventResponse — publishes a running cost update with status Running or Idle.

  • CostUpdated message — publishes a final cost update with status Finished.

When both totalCost and updatedPersonalMessage are present in the same TransactionEventResponse, the personal message appears in both the tariff_message variable and the message field of the session_cost record.

Relationship between the APIs

Event

Auth consumer API

Session cost consumer API

Token authorized with tariff

token_validation_status includes messages

tariff_message published

In-session tariff update

—

tariff_message published

Running / final cost

—

session_cost published (may include message)