Skip to content

Commit

Permalink
Move 2.0.1 use case documentation into a dedicated guide
Browse files Browse the repository at this point in the history 
Signed-off-by: Daniel Moore <[email protected]>
  • Loading branch information
@drmrd
drmrd committed Oct 15, 2024
1 parent 27b8fab commit 84d98b9
Show file tree
Hide file tree
Showing 2 changed files with 216 additions and 213 deletions.
215 changes: 2 additions & 213 deletions doc/ocpp_201_README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -135,220 +135,9 @@ The complete set of event handlers defined on an OCPP 2.0.1 `ChargePoint` can be

To initialize the database where a `ChargePoint` will persist state, please use the provided [SQLite database](/doc/database_migrations.md) or implement your own storage drive.

## OCPP 2.0.1 Use Cases in `libocpp`

The OCPP 2.0.1 specification is broken down into concrete functional requirements using a three-tier system. At the top, there are sixteen **functional blocks** lettered A through P that describe the high-level desired capabilities of actors adhering to the standard. These functional blocks are then broken into **use cases** that describe different scenarios in which one or more charging stations, local controllers, and charging station management systems might find themselves. The required and optional behaviors of these systems in these scenarios are then declared as **functional requirements** within each use case.

This section includes an overview of how a subset of the OCPP 2.0.1 use cases that supported by `libocpp` are implemented in conjunction with callbacks provided by the charging station. We hope it serves as a useful guide to portions of the `libocpp` API and illustrates patterns of interaction between `libocpp` and other systems within a charging station.

> [!NOTE]
> Our goal is not to reproduce the entire OCPP 2.0.1 specification in this document. Rather we intend to illustrate how various use cases are realized using `ChargePoint` methods in `libocpp` in conjunction with callback implementations and event handlers.
>
> Please refer to the [OCPP 2.0.1 standard](https://openchargealliance.org/protocols/open-charge-point-protocol/#OCPP2.0.1) for more details. Functional blocks, use cases, and functional requirements are addressed in Part 2 of Edition 2.
| Functional Block | Subject |
| :--------------- | :------------------------------------------ |
| A | Security |
| B | Provisioning |
| C | Authorization |
| D | Local Authorization List Management |
| E | Transactions |
| F | Remote Control |
| G | Availability |
| H | Reservation |
| I | Tariff and Cost |
| J | Meter Values |
| K | [Smart Charging](#smart-charging-use-cases) |
| L | Firmware Management |
| M | ISO 15118 Certificate Management |
| N | Diagnostics |
| O | Display Message |
| P | Data Transfer |

### Smart Charging Use Cases

The use cases within the Smart Charging functional block are subdivided into the following three categories of use cases:

1. General Smart Charging (Use Cases K01–K10)
2. External Charging Limit-based Smart Charging (K11–K14)
3. ISO 15118-based Smart Charging (K15–K17)

Support for General and External Charging Limit-based Smart Charging is largely complete, with ISO 15118-based Smart Charging under active development. For an up-to-date overview of exactly which features are currently supported as well as design decisions that have been made to address optional or ambiguous functional requirements, please refer to the [OCPP 2.0.1 Status document](ocpp_201_status.md).

#### K01 SetChargingProfile

Allows the CSMS to influence the charging power or current drawn from a specific EVSE or the
entire Charging Station over a period of time.

```mermaid
sequenceDiagram
CSMS->>+ChargePoint : SetChargingProfileRequest(call)
ChargePoint->>+DeviceModel : SmartChargingCtrlrAvailable?
DeviceModel-->>-ChargePoint : Component
rect Red
break SmartChargingCtrlrAvailable = false
ChargePoint-->>CSMS : Smart Charging NotSupported CallError
end
end
ChargePoint->>+SmartCharging : validate_and_add_profile(call.msg.Profile, call.msg.EVSE ID)
SmartCharging->>SmartCharging : validate_profile(Profile, EVSE ID)
rect Red
break Invalid Profile
SmartCharging-->>ChargePoint : SetChargingProfileResponse: Rejected
ChargePoint-->>CSMS : SetChargingProfileResponse: Rejected
end
end
SmartCharging->>+SmartCharging : add_profile(Profile, EVSE ID)
SmartCharging->>-EVerest : signal_set_charging_profiles_callback
SmartCharging-->>-ChargePoint : SetChargingProfileResponse: Accepted
ChargePoint-->>-CSMS : SetChargingProfileResponse: Accepted
```

Profile validation returns the following errors to the caller when a Profile
is `Rejected`:

| Errors | Description |
| :------------------------------------------------------------ | :-------------------------------------------------------------- |
| `ChargingProfileFirstStartScheduleIsNotZero` | The `startPeriod` of the first `chargingSchedulePeriod` needs to be 0.<br>[K01.FR.31] |
| `ChargingProfileNoChargingSchedulePeriods` | Happens when the `ChargingProfile` doesn't have any Charging Schedule Periods. |
| `ChargingScheduleChargingRateUnitUnsupported` | Happens when a chargingRateUnit is passed in that is not configured in the `ChargingScheduleChargingRateUnit`. [K01.FR.26] |
| `ChargingSchedulePeriodInvalidPhaseToUse` | Happens when an invalid `phaseToUse` is passed in. [K01.FR.19] [K01.FR.48] |
| `ChargingSchedulePeriodPhaseToUseACPhaseSwitchingUnsupported` | Happens when phaseToUse is passed in and the EVSE does not have `ACPhaseSwitchingSupported` defined and set to true. [K01.FR.20] [K01.FR.48] |
| `ChargingSchedulePeriodsOutOfOrder` | `ChargingSchedulePeriod.startPeriod` elements need to be in increasing values. [K01.FR.35] |
| `ChargingStationMaxProfileCannotBeRelative` | Happens when a `ChargingStationMaxProfile.chargingProfileKind` is set to `Relative`. [K01.FR.38] |
| `ChargingStationMaxProfileEvseIdGreaterThanZero` | Happens when a `ChargingStationMaxProfile` is attempted to be set with an EvseID isn't `0`. [K01.FR.03] |
| `ChargingProfileMissingRequiredStartSchedule` | Happens when an `Absolute` or `Recurring` `ChargingProfile` doesn't have a `startSchedule`. [K01.FR.40] |
| `ChargingProfileExtraneousStartSchedule` | Happens when a Relative `ChargingProfile` has a `startSchedule`. [K01.FR.41] |
| `EvseDoesNotExist` | Happens when the `evseId`of a `SetChargingProfileRequest` does not exist. [K01.FR.28] |
| `ExistingChargingStationExternalConstraints` | Happens when a `SetChargingProfileRequest` Profile has a purpose of `ChargingStationExternalConstraints` and one already exists with the same `ChargingProfile.id` exists. [K01.FR.05] |
| `InvalidProfileType` | Happens when a `ChargingStationMaxProfile` is attempted to be set with a `ChargingProfile` that isn't a `ChargingStationMaxProfile`. |
| `TxProfileEvseHasNoActiveTransaction` | Happens when a `SetChargingProfileRequest` with a `TxProfile` is submitted and there is no transaction active on the specified EVSE. [K01.FR.09] |
| `TxProfileEvseIdNotGreaterThanZero` | `TxProfile` needs to have an `evseId` greater than 0. [K01.FR.16] |
| `TxProfileMissingTransactionId` | A `transactionId` is required for`SetChargingProfileRequest`s with a `TxProfile` in order to match the profile to a specific transation. [K01.FR.03] |
| `TxProfileTransactionNotOnEvse` | Happens when the provided `transactionId` is not known. [K01.FR.33] |
| `TxProfileConflictingStackLevel` | Happens when a TxProfile has a stackLevel and transactionId combination already exists in a TxProfile with a different id in order to ensure that no two charging profiles with same stack level and purpose can be valid at the same time. [K01.FR.39] |


#### K08 Get Composite Schedule

The CSMS requests the Charging Station to report the Composite Charging
Schedule, as calculated by the Charging Station for a specific point of
time, and may change over time due to external causes such as local
balancing based on grid connection capacity and EVSE availablity.

The Composite Schedule is the result of result of merging the time periods
set in the `ChargingStationMaxProfile`, `ChargingStationExternalConstraints`,
`TxDefaultProfile` and `TxProfile` type profiles.

```mermaid
sequenceDiagram
CSMS->>+ChargePoint: GetCompositeSchedule(call)
ChargePoint->>+DeviceModel : ChargingScheduleChargingRateUnit?
DeviceModel-->>-ChargePoint : Component
rect Red
break call.msg.chargingRateUnit is not supported
ChargePoint-->>CSMS : ChargingScheduleChargingRateUnitUnsupported CallError
end
end
ChargePoint->>+EvseManager : does_evse_exist(call.msg.evseId)
EvseManager-->>-ChargePoint : bool
rect Red
break EVSE does not exist
ChargePoint-->>CSMS : EvseDoesNotExist CallError
end
end
ChargePoint->>+SmartChargingHandler : get_valid_profiles(call.msg.evseId)
SmartChargingHandler-->>-ChargePoint : vector<ChargingProfile>
ChargePoint->>+SmartChargingHandler : calculate_composite_schedule<br/>(vector<ChargingProfile, now, msg.duration, evseId, call.msg.chargingRateUnit)
loop ExternalConstraints, Max, TxDefault, and Tx Profiles
SmartChargingHandler->>+Profile: calculate_composite_schedule(profiles)
Profile-->>-SmartChargingHandler: composite_schedule
end
note right of SmartChargingHandler: Create consolidated CompositeSchedule<br />from all 4 Profile types
SmartChargingHandler->>+Profile: calculate_composite_schedule(ExternalConstraints, Max, TxDefault, Tx)
Profile-->>-SmartChargingHandler: CompositeSchedule

SmartChargingHandler-->>-ChargePoint: CompositeSchedule
ChargePoint-->>-CSMS : GetCompositeScheduleResponse(CompositeSchedule)
```


#### K09 Get Charging Profiles

Returns to the CSMS the Charging Schedules/limits installed on a Charging Station based on the
passed in criteria.

```mermaid
sequenceDiagram
CSMS->>+ChargePoint: GetChargingProfiles(criteria)
ChargePoint->>+SmartChargingHandler : get_reported_profiles(criteria)
loop filter ChargingProfiles
SmartChargingHandler->>SmartChargingHandler: filter on ChargingProfile criteria
end
SmartChargingHandler-->>-ChargePoint : Vector<Profiles>
ChargePoint-->>CSMS : GetChargingProfilesResponse(profiles)
alt no Profiles
rect Red
ChargePoint-->>CSMS : GetChargingProfilesResponse(NoProfiles)
ChargePoint->>CSMS : return
end
else Profiles
ChargePoint-->>CSMS : GetChargingProfilesResponse(Accepted)
end
ChargePoint->>ChargePoint : determine profiles_to_report
ChargePoint-->>-CSMS : ReportChargingProfilesRequest(profiles_to_report)
```


#### K10 Clear Charging Profile

Clears Charging Profiles installed on a Charging Station based on the
passed in criteria.

```mermaid
sequenceDiagram
CSMS->>+ChargePoint: ClearChargingProfileRequest(criteria)
alt no Profiles matching criteria
rect Red
ChargePoint-->>CSMS : ClearChargingProfileResponse(Unknown)
end
else found matching Profiles
ChargePoint-->>-CSMS : ClearChargingProfileResponse(Accepted)
end
```
## OCPP 2.0.1 Use Cases in `libocpp`
For an in-depth guide to use cases from the OCPP 2.0.1 standard and how these use cases are implemented in `libocpp`, please see [this guide](/doc/ocpp_201_use_cases_in_depth.md).


## Quickstart for OCPP 2.0.1
Expand Down
Loading

0 comments on commit 84d98b9

Please sign in to comment.