Skip to content

Powerfill Documentation

Welcome aboard! This document is intended to provide an overview of the Powerfill, the platform, and its APIs and how to get started with it.

Table of Contents

Terminology

  • Charge Point (per Ocpp):
    The Charge Point is the physical system where an electric vehicle can be charged. A Charge Point has one or more connectors.

  • Charge Box (or: Charging station):
    Used synonymously with Charge Point.

  • Charge Box ID:
    A unique Ocpp identifier for a Charge Point.

  • Connector (per Ocpp):
    The term "Connector" refers to an independently operated and managed electrical outlet on a Charge Point. This usually corresponds to a single physical connector, but in some cases a single outlet may have multiple physical socket types and/or tethered cable/connector arrangements to facilitate different vehicle types (e.g. four-wheeled EVs and electric scooters).

  • Transaction (per Ocpp):
    The part of the charging process that starts when all relevant preconditions (e.g. authorization, plug inserted) are met, and ends at the moment when the Charge Point irrevocably leaves this state.

  • Charging session:
    A less technical and more business-friendly synonym for transaction.

  • Ocpp Tag (or: ID Tag, Ocpp ID Tag):
    An Ocpp Tag is the identifier of the actor that interacts with the charge box. It can be used for authorization, but also to start and stop charging sessions. An RFID card is an example of an Ocpp Tag.

  • User:
    A person that possesses an Ocpp Tag. Even though Ocpp Tag is enough for all technical purposes, the term "User" can be used to associate more information with the Ocpp Tag. For example, a user can have a name, email address, and phone number which makes it easier to identify the human behind the Ocpp Tag which is an alphanumerical value usually.

  • Site:
    A site is a physical location where charge boxes are installed. The site is modeled as a tree structure with nodes representing different parts of the site. Each node can have children nodes, which allows for a flexible representation of the site. Charge boxes can be associated with nodes in the tree. For example, a site can be a building where the floors are nodes and the charge boxes are associated with the floors. Please refer to the dedicated section for more information.

Getting started

We first need to introduce the charge points and Ocpp Tags to the platform.

  • Adding a Charge Point:
    In order for Powerfill to accept messages from a charge point, the charge point must first be registered (i.e. its data record needs to be added/introduced to the platform). To add a charge point, go to Web UI and select Data Management >> Charge Points >> Add. Enter the ChargeBox ID configured in the charge point and confirm.

  • Adding an Ocpp Tag:
    Ocpp Tags interacting with a charge point need to be acknowledged by the platform. Otherwise, these interaction attempts will be rejected. To add an Ocpp Tag, go to Web UI and select Data Management >> Ocpp Tags >> Add. Enter the Ocpp Tag ID and confirm.

You may repeat these steps for all charge points and Ocpp Tags that you want to manage with the platform. Afterwards, the charge points and Ocpp Tags will exist in the platform, but they will lack any structure or relationship between them. They are not quite ready to be used yet. We first need to introduce a structure to group (and separate at the same time) charge points and Ocpp Tags, such that the access control can be managed in a more granular way.

Site management

The site topology is a flexible model to represent various types of real-world setups where charging stations are installed. In general, it is helpful to imagine it as a tree:

Definition

A tree structure is a hierarchical data model that consists of nodes. Nodes are connected in a parent-child relationship. The top node is called the root, and each node can have zero or more child nodes.

The site topology is important to understand, because 2 other concepts are built on top of it:

  1. The charging stations are associated with the particular nodes.
  2. The Ocpp Tag permissions are associated with the nodes.

Basically, the charging stations and Ocpp Tags are attributes (or: labels) of a node. And therefore, as a consequence of these two points, all Ocpp Tags associated with a node have access to all charging stations associated with that node. We will come back to this later.

So, let's consider some site examples:

  1. The site can represent a whole building. Each node (at depth 1) can represent, for example, the floors in your building. And then, these nodes can have child nodes as well: Let's say the 3rd floor has a left and right wing. This is doable as follows:
    Site topology for example 1
  2. Let's generalize on example 1: Our site should represent a building complex (i.e. a collection of 4 buildings). The root node can represent the whole complex, and then the immediate child nodes can represent the buildings in the complex. We, basically, added a higher level to the existing tree example:
    Site topology for example 2
  3. We can generalize even further. A site could represent the whole city. The root node can represent the city, and then the immediate child nodes can represent the districts in the city. And then, the districts can have child nodes that represent the buildings (or building complexes) in the district, and so on. We omit an image for this example for brevity :).
  4. Consider a more specific version of example 1: The first floor has 3 parking lots where each parking lot has 1 charging station. Each parking lot is dedicated to a resident (i.e. others cannot use it). Therefore, the charging station must be used only by that resident. This can be modeled as follows:
    Site topology for example 4

We will revisit this example later when talking about assigning stations and Ocpp Tags to nodes.

Note

The following endpoints allow CRUD operations on sites:

  • GET /api/v1/sites
  • POST /api/v1/sites
  • GET /api/v1/sites/{id}
  • DELETE /api/v1/sites/{id}

Important

Site management exists solely as API endpoints. There is no Web UI for it.

Assigning charging stations to a node

When the general real-world model exists as a site topology, the next step is to assign charging stations to the nodes. This would refine the site topology with the actual charging stations. Conceptually, every node of the site can have 0 or multiple charging stations associated with it. It can be the root node, it can be intermediate notes (e.g. node 3 of example 1), or it can be leaf nodes (e.g. parking lots of example 4). Since the notion of "node" is an abstract concept, it is not tied to any architectural constraints. Nodes can be anything one desires in order to create boundaries between groups of stations. This flexibility allows the site manager/owner to model the site as close to the real-world setup as possible.

However, most likely, the charging stations will be associated with the leaf nodes only. And, probably, it does not make sense to associate charging stations with the root node or intermediate nodes.

The following image shows the site topology that is a combination of aforementioned examples 1 and 4 after assigning charging stations: Site topology for example 5

Notice that nodes X, Y and Z have one charging station each because each station is dedicated to a parking lot. Also notice that nodes 4 and 5 have multiple charging stations. This allows to create a station group per wing within the floor. On the other hand, node 2 does not event need the distinction per wings: All stations belong to the same logical group. A more granular configuration was not needed in these cases.

This is a good example for the flexibility in order to cover a wide variety of business cases.

Note

The endpoint PUT /api/v1/sites/{id} can be used to assign charging stations to a node.

Important

This functionality exists solely as API endpoint. There is no Web UI for it.

Ocpp Tag Group management

An Ocpp Tag Group is a logical grouping of Ocpp Tags. This allows for flexible management of permissions1 in bulk: Instead of assigning permissions to each Ocpp Tag individually, permissions can be assigned to the group. Therefore, all Ocpp Tags in the group inherit the permissions of the group.

For example, let's assume the following business case: All residents of a floor can use all stations assigned to that floor.

This can be modeled in two ways:

  1. Assigning each resident's Ocpp Tag to the node representing the floor.
  2. Creating an Ocpp Tag Group for the residents of the floor and assigning the group to the node representing the floor.

Obviously, 1st approach is simpler and more straightforward, but 2nd approach is more scalable and maintainable. Our platform supports both approaches.

Note

The following endpoints allow CRUD operations on Ocpp Tag Groups:

  • POST /api/v1/ocppTagGroups
  • GET /api/v1/ocppTagGroups/{ocppTagGroupPk}/ocppTags
  • PUT /api/v1/ocppTagGroups/{ocppTagGroupPk}/ocppTags/add
  • PUT /api/v1/ocppTagGroups/{ocppTagGroupPk}/ocppTags/delete

Important

Ocpp Tag Group management exists solely as API endpoints. There is no Web UI for it.

Permission management

This section brings all the concepts introduced so far together: Site topology; assigning charging stations, Ocpp Tags and Ocpp Tag Groups.

A permission is granting of access of an Ocpp Tag to a Charge Box. This allows the owner of the Ocpp Tag, e.g., to start and stop charging sessions at that Charge Box. Permission management uses the tree model of the site topology to implement granular access management. Let's introduce the general concept first:

Permissions on a node

On our platform, Ocpp Tags and Ocpp Tag Groups can be associated with a node. We say "an Ocpp Tag X has permission to a station Y", when one of the following is true (in this order!):

  1. The charging station Y is assigned to a node N, and the Ocpp Tag X is associated with the same node N.
  2. The charging station Y is assigned to a node N, and the Ocpp Tag X belongs to a Ocpp Tag Group that is associated with the same node N.

When checking a permission of an Ocpp Tag at a station, we try the more specific case first (i.e. Ocpp Tag). If the Ocpp Tag does not have the permission, we try the more general case (i.e. Ocpp Tag Group). For this, we first resolve the Ocpp Tag Groups of the Ocpp Tag and then check the permissions of these Ocpp Tag Groups at that station.

Note

The following endpoints allow CRUD operations on associations of Ocpp Tag Groups to nodes:

  • POST /api/v1/permissions/ocppTagGroups
  • GET /api/v1/permissions/ocppTagGroups/{ocppTagGroupPk}
  • DELETE /api/v1/permissions/ocppTagGroups/{ocppTagGroupPk}

The following endpoints allow CRUD operations on associations of Ocpp Tags to nodes:

  • POST /api/v1/permissions/ocppTags
  • GET /api/v1/permissions/ocppTags/{ocppTagPk}
  • DELETE /api/v1/permissions/ocppTags/{ocppTagPk}

Notes on appliesToAllChildren boolean flag

Use case: Imagine a scenario where an admin role should be able to access all stations in a site, or a manager role to all stations within a specific subtree of the site topology. This can be achieved in three ways

  1. Assigning the Ocpp Tag to each node in the subtree.
  2. Assigning the Ocpp Tag to a group that is assigned to each node in the subtree.
  3. Assigning the Ocpp Tag to the root node of the subtree and setting the appliesToAllChildren flag to true.

The third approach is the most efficient and maintainable way to achieve this. The two POST methods to create Ocpp Tag and Ocpp Tag Group permissions have an optional boolean field appliesToAllChildren. When this flag is set to true, the permission is inherited by all child nodes of that node.

Let's revisit the example 1 from the site management section, and exercise the usage of appliesToAllChildren:

Permissions on a node

In this example, the role has access to all stations of nodes 3, 4 and 5. If, however, the role would be associated with the root node, it would have access to all stations of the site.

Important

Permission management exists solely as API endpoints. There is no Web UI for it.

Technical Notes

Secure Communication

All communications with the platform must use secure protocols: Requests sent over unsecured HTTP are automatically redirected with a 301 HTTP status code to the corresponding HTTPS endpoint. This applies to all HTTP traffic (not just the APIs) and to WebSocket connections.

In that regard, we do not support unsecure WebSocket (ws://) and therefore OCPP security profile 0. Each connection attempt to ws://... will be redirected to wss://...

Rate Limiting

API requests are limited to 600 requests per minute per account. Exceeding this limit results in an HTTP 429 (Too Many Requests) response. The rate-limited requests include the X-Rate-Limit-Retry-After-Seconds header, which indicates how long to wait before retrying.

  1. A permission is granting of access of an Ocpp Tag to a Charge Box. ↩