# OCPI Tariffs

[![crates-io]](https://crates.io/crates/ocpi-tariffs "Crates.io version")
[![docs-rs]](https://docs.rs/ocpi-tariffs "Documentation")

[crates-io]: https://img.shields.io/crates/v/ocpi-tariffs.svg?logo=rust
[docs-rs]: https://img.shields.io/docsrs/ocpi-tariffs/latest?logo=docs.rs
[ocpi]: https://evroaming.org/ocpi-background/
[tariffs]: https://github.com/ocpi/ocpi/blob/2.2.1/mod_tariffs.asciidoc#1-tariffs-module

This project provides software for doing calculations with
[OCPI](https://evroaming.org/ocpi-background/)
[tariffs](https://github.com/ocpi/ocpi/blob/2.2.1/mod_tariffs.asciidoc#1-tariffs-module).
Specifically for the
[`OCPI 2.2.1`](https://evroaming.org/app/uploads/2021/11/OCPI-2.2.1.pdf) and some
support for the
[`OCPI 2.1.1`](https://github.com/ocpi/ocpi/releases/download/2.1.1-d2/OCPI_2.1.1-d2.pdf)
version.

You can test the tariff tool [online](https://tools.tandemdrive.com/).

OCPI is a protocol owned and maintained by the [EV Roaming
foundation](https://evroaming.org/).

## Goals

- Provide a reference OCPI tariff implementation

  Given a certain
  [CDR](https://github.com/ocpi/ocpi/blob/2.2.1/mod_cdrs.asciidoc) and
  a certain tariff it's able to calculate the different (sub)totals.

  The software provides as output a breakdown of how these (sub)totals were
  calculated.

- Provide an extensive set of test-cases to ensure correctness.

- Collect feedback from the community

  We aim to have as many parties as possible agree that this reference
  implementation is a correct interpretation of the OCPI specification and
  intentions. We aim for close cooperation with the [EV Roaming
  Foundation](https://evroaming.org/).

  We welcome community contributions to this project. We aim to make it easy for
  people, familiar with OCPI, to provide new test cases.

- Provide the software as open source software so others can freely use and
  test it.

  Both a command line tool and a Rust library are provided.

- Expose the software functionality [online](https://tools.tandemdrive.com/)
  to make it even easier for people to do calculations with the tariff
  software.

- Support OCPI 3 tariffs soon after OCPI 3 is finalized.

## Non-Goals

- Provide software which communicates tariffs using the OCPI protocol between
  EV roaming parties.

- Produce human consumable receipts which specify the different cost components
  that led to the calculated total price.

- Provide OCPI specification compliant types for use in third-party projects.

## Limitations

The current implementation is restricted to applying a single tariff per CDR.
Consequently, it does not yet leverage the OCPI capability of assigning multiple
tariffs to a connector, which allows for planned switching of tariffs in time
and preference-based smart charging.

Reservation pricing is not supported. A CDR alone does not carry enough
information to determine reservation costs, so `total_reservation_cost` is not
computed and is not present in `price::Report`.

## Tariff Structure Overview

```mermaid
classDiagram
    class Tariff {
        TariffElement elements
    }
    class TariffElement {
        PriceComponent price_components
        TariffRestriction restrictions
    }
    class PriceComponent {
        TarifDimensionType type
        Number price
        Number vat
        int step_size
    }
    class TariffRestriction {
        DayOfWeek day_of_week
        ...
    }
    Tariff "1" --o "1.." TariffElement
    TariffElement "1" --o "1.." PriceComponent
    TariffElement "1" --o "0..1" TariffRestriction
```

## Interpretation

This implementation aims to follow the OCPI specification as closely as
possible. However, as with any specification, details might be left open to
interpretation. The following is a list of assumptions that have been made in
this implementation:

- We assume that a `FLAT` price component can only be active once in a session.
  The first time a `FLAT` price component becomes active it will be used and
  subsequent active `FLAT` components will be ignored. Although this is not
  explicitly mentioned in the OCPI 2.*.* specs, we feel it is the correct
  interpretation.

- We assume that the charging periods provided as input are well-formed.
  Meaning, each period in the session that has a different price must be
  provided as a separate charging period in the CDR. No attempt will be made
  to subdivide or interpolate data inside a single provided period.

## Naming Deviations/Improvements

We use clearer field names to avoid semantic confusion.

Any use of `parking` is changed to `idle` such as `total_parking_time` is
renamed to `total_idle_time`. The definition of 'parking' in the OCPI spec
is open to confusion as some people read the word parking to mean the total
amount of time the vehicle spent in the parking spot. But confusingly, the
OCPI spec means the total time not spent charging. In this crate the term
'idle' time means the time spent not charging.

We also rename `total_time_cost` to `total_charging_time_cost` as the
definition of `total_time_cost` in the OCPI spec is:

> Total sum of all the cost related to duration of charging during this transaction, in the
> specified currency

But confusingly, the definition of `total_time` is:

> Total duration of the charging session (including the duration of charging and not charging), in
> hours.

These field renames can be seen in the `ocpi_tariffs::price::Report`.

## Minimum Supported Rust Version (MSRV)

The minimum supported Rust version is declared in the `rust-version` field of
`Cargo.toml`. Both crates in the workspace build on this version and newer.

Raising the MSRV is treated as a notable change. It's recorded in the
changelog. The declared version is verified against the actual toolchain at
release time (via `cargo msrv verify` in `scripts/release_prepare.sh`), so a
published release is guaranteed to build on against the stated MSRV.

## Contributing

We welcome community contributions to this project.

Please read our [Contributor Terms](CONTRIBUTING.md#contributor-terms) before
you make any contributions.

Any contribution intentionally submitted for inclusion, shall comply with the
Rust standard licensing model (MIT OR Apache 2.0) and therefore be dual licensed
as described below, without any additional terms or conditions:

### License

This contribution is dual licensed under EITHER OF

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
  <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

For clarity, "your" refers to TandemDrive or any other licensee/user of the contribution.
