Managing Sessions

This tutorial demonstrates how to manage charging sessions in an OCPI application.

Overview

Sessions represent active charging events. They track: - When charging started/stopped - Energy consumed (kWh) - Cost information - Location and connector details - Status (ACTIVE, COMPLETED, etc.)

Setup

Include the sessions module in your application:

from ocpi import get_application
from ocpi.core.enums import ModuleID, RoleEnum
from ocpi.modules.versions.enums import VersionNumber

app = get_application(
    version_numbers=[VersionNumber.v_2_3_0],
    roles=[RoleEnum.cpo, RoleEnum.emsp],
    modules=[ModuleID.sessions],
    authenticator=YourAuthenticator,
    crud=YourCrud,
)

Session Lifecycle

1. Start Session (EMSP)

An EMSP starts a session when a user begins charging:

session_data = {
    "country_code": "ES",
    "party_id": "ABC",
    "id": "SESS001",
    "start_date_time": "2024-01-01T10:00:00Z",
    "location_id": "LOC001",
    "evse_uid": "EVSE001",
    "connector_id": "CONN001",
    "kwh": 0.0,
    "currency": "EUR",
    "status": "ACTIVE",
    "last_updated": "2024-01-01T10:00:00Z"
}

2. Update Session (CPO)

The CPO updates the session as charging progresses:

# Update energy consumed
updated_session = {
    "kwh": 15.5,
    "status": "ACTIVE",
    "last_updated": "2024-01-01T10:30:00Z"
}

3. End Session (CPO)

When charging completes:

ended_session = {
    "end_date_time": "2024-01-01T11:00:00Z",
    "kwh": 30.0,
    "status": "COMPLETED",
    "last_updated": "2024-01-01T11:00:00Z"
}

CRUD Operations

Create Session

class YourCrud(Crud):
    @classmethod
    async def create(
        cls, module: ModuleID, role: RoleEnum, data: dict, *args, **kwargs
    ) -> dict:
        """Create a new session."""
        session_id = data.get("id")
        # Store in your database
        # ...
        return data

Update Session

@classmethod
async def update(
    cls, module: ModuleID, role: RoleEnum, data: dict, id: str, *args, **kwargs
) -> dict:
    """Update an existing session."""
    # Update energy, status, etc.
    # ...
    return updated_data

Get Session

@classmethod
async def get(
    cls, module: ModuleID, role: RoleEnum, id: str, *args, **kwargs
) -> dict | None:
    """Get a session by ID."""
    # Retrieve from database
    # ...
    return session_data

List Sessions

@classmethod
async def list(
    cls, module: ModuleID, role: RoleEnum, filters: dict, *args, **kwargs
) -> tuple[list[dict], int, bool]:
    """Get paginated list of sessions."""
    # Filter by date_from, date_to, etc.
    # ...
    return sessions, total_count, is_last_page

Session Status

Common session statuses:

• ACTIVE - Charging is in progress
• COMPLETED - Charging finished normally
• INVALID - Session data is invalid
• PENDING - Session is pending start

API Usage

Create/Update Session (PUT)

curl -X PUT 'http://127.0.0.1:8000/ocpi/emsp/2.3.0/sessions/ES/ABC/SESS001' \
  -H 'Authorization: Token your-token' \
  -H 'Content-Type: application/json' \
  -d @session.json

Get Session (GET)

curl 'http://127.0.0.1:8000/ocpi/cpo/2.3.0/sessions/ES/ABC/SESS001' \
  -H 'Authorization: Token your-token'

List Sessions (GET)

curl 'http://127.0.0.1:8000/ocpi/cpo/2.3.0/sessions/?date_from=2024-01-01T00:00:00Z' \
  -H 'Authorization: Token your-token'

Partial Update (PATCH)

curl -X PATCH 'http://127.0.0.1:8000/ocpi/cpo/2.3.0/sessions/ES/ABC/SESS001' \
  -H 'Authorization: Token your-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "kwh": 25.5,
    "status": "ACTIVE"
  }'

Advanced Features

Charging Preferences (OCPI 2.2.1+)

session_data["charging_preferences"] = {
    "profile_type": "FAST",
    "departure_time": "2024-01-01T12:00:00Z",
    "energy_need": 50.0
}

Meter Values

session_data["meter_value"] = [
    {
        "timestamp": "2024-01-01T10:00:00Z",
        "sampled_value": [
            {
                "value": "0.0",
                "context": "Sample.Periodic",
                "measurand": "Energy.Active.Import.Register",
                "unit": "kWh"
            }
        ]
    }
]

Best Practices

1. Update frequently - Update session energy consumption regularly
2. Set timestamps - Always include start_date_time and end_date_time
3. Track status - Keep session status accurate
4. Link to location - Always reference the correct location and EVSE
5. Calculate costs - Include cost information when available

Complete Example

See the EMSP Sessions Example for a complete working implementation.