Bridge Tools

Tools to aid bridge development for the Share & Charge core client, including session management and charge detail record calculation.

Install

npm install @motionwerk/sharecharge-bridge-tools

Usage

API Abstraction

The session manager requires an API abstraction in order to track the consumption and duration of a driver's session and stop charges on their behalf.

import { AbstractAPI, SessionDetails } from '@motionwerk/sharecharge-bridge-tools';

export default class API implements AbstractAPI {
    
    startRemoteTransaction(sessionDetails: SessionDetails): Promise<any>{
        // start session
    };

    stopRemoteTransaction(sessionDetails: SessionDetails): Promise<any> {
        // end session
    };
    
    checkSession(sessionDetails: SessionDetails): Promise<{
        consumption: number;
        duration: number;
        terminated: boolean;
    }> {
        // get session information from CPO backend or otherwise here
    };
}

Session Management

The session manager can be used as follows:

import { SessionManagement } from '@motionwerk/sharecharge-bridge-tools';
import API from './api';

// request session management to start tracking session
class Bridge implements IBridge {

    sm: SessionManagement;

    constructor() {

        // initialize api abstraction
        const api = new API();

        // initialize session management
        this.sm = new SessionManagement(api, {
            // optional database name found in $HOME/.sharecharge/sessions/, default named 'sessions.db'
            dbName: 'my.bridge.db',
            // optional timeout for every new session (e.g. wait 5 minutes to start tracking each session), default 0
            timeout: 0,
            // optional interval for polling API for latest session information, default 10000 (10 seconds)
            interval: 10000
        });

        // subscribe to session management stop events
        this.sm.on('stop', (session: SessionDetails) => {
            // handle session automatic stop here
        });
    }

    public async start(session: ISession): Promise<IResult> {
        // initialize a sessionDetails object with any charge point/session identifiers necessary to track and stop sessions
        const details = SessionDetails.create({
            locationId: 'LOC-1',
            evseId: 'DE-EVSE-1',
            connectorId: '1',
            sessionId: session.id
        }, parameters);
        const success = await this.api.startRemoteTransaction(details);
        if (success) {
            this.sm.manage(details);
        }
    }

}

Charge Detail Records

For bridges which need to calculate the final prices themselves, this can be done as follows:

import { ChargeDetailRecord } from '@motionwerk/sharecharge-bridge-tools';

// session details object containing the final consumption and duration of the charging session
const sessionDetails = <SessionDetails>{};
// tariff object relating to the connector being charged at
const tariff = <Tariff>{};

const cdr = ChargeDetailRecord.create(sessionDetails, tariff);
/*
    {
        scId: '0x2d33312e3933373331382c3131352e373535373938',
        evseId: 'DE-EVSE-1',
        chargedUnits: 1000,
        price: 29
    }
*/

Result

A result object can also be generated for the core client as follows:

import { Result } from '@motionwerk/sharecharge-bridge-tools';

const success = true;

const result = Result.create(success, sessionDetails, cdr);
/*
    {
        success: true,
        data: {
            sessionId: '1234',
            session: {
                scId: '0x2d33312e3933373331382c3131352e373535373938',
                evseId: 'DE-EVSE-3',
                controller: '0x3D3e776F83cCf6Aa443B8Bd5B6F245dD429F9JD9',
                tariffId: '0',
                tariffValue: '3000',
                sessionId: '1234'
            },
            cdr: {
                scId: '0x2d33312e3933373331382c3131352e373535373938',
                evseId: 'DE-EVSE-3',
                chargedUnits: 2500,
                price: 51
            }
        }
    }
*/

Examples

See sharecharge-example-bridge for a full implementation.