ocpp2

Documentation

Overview

The package contains an implementation of the OCPP 2.0 communication protocol between a Charging Station and an Charging Station Management System in an EV charging infrastructure.

Index

• type CSMS
  • func NewCSMS(endpoint *ocppj.Server, server ws.WsServer) CSMS
• type ChargingStation
  • func NewChargingStation(id string, endpoint *ocppj.Client, client ws.WsClient) ChargingStation

Types

type CSMS

type CSMS interface {
	// Cancel a pending reservation, provided the reservationId, on a charging station.
	CancelReservation(clientId string, callback func(*reservation.CancelReservationResponse, error), reservationId int, props ...func(*reservation.CancelReservationRequest)) error
	// The CSMS installs a new certificate (chain), signed by the CA, on the charging station. This typically follows a SignCertificate message, initiated by the charging station.
	CertificateSigned(clientId string, callback func(*security.CertificateSignedResponse, error), certificate []string, props ...func(*security.CertificateSignedRequest)) error
	// Instructs a charging station to change its availability to the desired operational status.
	ChangeAvailability(clientId string, callback func(*availability.ChangeAvailabilityResponse, error), evseID int, operationalStatus availability.OperationalStatus, props ...func(*availability.ChangeAvailabilityRequest)) error
	// Instructs a charging station to clear its current authorization cache. All authorization saved locally will be invalidated.
	ClearCache(clientId string, callback func(*authorization.ClearCacheResponse, error), props ...func(*authorization.ClearCacheRequest)) error
	// Instructs a charging station to clear some or all charging profiles, previously sent to the charging station.
	ClearChargingProfile(clientId string, callback func(*smartcharging.ClearChargingProfileResponse, error), props ...func(request *smartcharging.ClearChargingProfileRequest)) error
	// Removes a specific display message, currently configured in a charging station.
	ClearDisplay(clientId string, callback func(*display.ClearDisplayResponse, error), id int, props ...func(*display.ClearDisplayRequest)) error
	// Removes one or more monitoring settings from a charging station for the given variable IDs.
	ClearVariableMonitoring(clientId string, callback func(*diagnostics.ClearVariableMonitoringResponse, error), id []int, props ...func(*diagnostics.ClearVariableMonitoringRequest)) error
	// Instructs a charging station to display the updated current total cost of an ongoing transaction.
	CostUpdated(clientId string, callback func(*tariffcost.CostUpdatedResponse, error), totalCost float64, transactionId string, props ...func(*tariffcost.CostUpdatedRequest)) error
	// Instructs a charging station to send one or more reports, containing raw customer information.
	CustomerInformation(clientId string, callback func(*diagnostics.CustomerInformationResponse, error), requestId int, report bool, clear bool, props ...func(*diagnostics.CustomerInformationRequest)) error
	// Performs a custom data transfer to a charging station. The message payload is not pre-defined and must be supported by the charging station. Every vendor may implement their own proprietary logic for this message.
	DataTransfer(clientId string, callback func(*data.DataTransferResponse, error), vendorId string, props ...func(*data.DataTransferRequest)) error
	// Deletes a previously installed certificate on a charging station.
	DeleteCertificate(clientId string, callback func(*iso15118.DeleteCertificateResponse, error), data types.CertificateHashData, props ...func(*iso15118.DeleteCertificateRequest)) error
	// Requests a report from a charging station. The charging station will asynchronously send the report in chunks using NotifyReportRequest messages.
	GetBaseReport(clientId string, callback func(*provisioning.GetBaseReportResponse, error), requestId int, reportBase provisioning.ReportBaseType, props ...func(*provisioning.GetBaseReportRequest)) error
	// Request a charging station to report some or all installed charging profiles. The charging station will report these asynchronously using ReportChargingProfiles messages.
	GetChargingProfiles(clientId string, callback func(*smartcharging.GetChargingProfilesResponse, error), chargingProfile smartcharging.ChargingProfileCriterion, props ...func(*smartcharging.GetChargingProfilesRequest)) error
	// Requests a charging station to report the composite charging schedule for the indicated duration and evseID.
	GetCompositeSchedule(clientId string, callback func(*smartcharging.GetCompositeScheduleResponse, error), duration int, evseId int, props ...func(*smartcharging.GetCompositeScheduleRequest)) error
	// Retrieves all messages currently configured on a charging station.
	GetDisplayMessages(clientId string, callback func(*display.GetDisplayMessagesResponse, error), requestId int, props ...func(*display.GetDisplayMessagesRequest)) error
	// Retrieves all installed certificates on a charging station.
	GetInstalledCertificateIds(clientId string, callback func(*iso15118.GetInstalledCertificateIdsResponse, error), typeOfCertificate types.CertificateUse, props ...func(*iso15118.GetInstalledCertificateIdsRequest)) error
	// Queries a charging station for version number of the Local Authorization List.
	GetLocalListVersion(clientId string, callback func(*localauth.GetLocalListVersionResponse, error), props ...func(*localauth.GetLocalListVersionRequest)) error
	// Instructs a charging station to upload a diagnostics or security logfile to the CSMS.
	GetLog(clientId string, callback func(*diagnostics.GetLogResponse, error), logType diagnostics.LogType, requestID int, logParameters diagnostics.LogParameters, props ...func(*diagnostics.GetLogRequest)) error
	// Requests a report about configured monitoring settings per component and variable from a charging station. The reports will be uploaded asynchronously using NotifyMonitoringReport messages.
	GetMonitoringReport(clientId string, callback func(*diagnostics.GetMonitoringReportResponse, error), props ...func(*diagnostics.GetMonitoringReportRequest)) error

	// Registers a handler for incoming security profile messages.
	SetSecurityHandler(handler security.CSMSHandler)
	// Registers a handler for incoming provisioning profile messages.
	SetProvisioningHandler(handler provisioning.CSMSHandler)
	// Registers a handler for incoming authorization profile messages.
	SetAuthorizationHandler(handler authorization.CSMSHandler)
	// Registers a handler for incoming local authorization list profile messages.
	SetLocalAuthListHandler(handler localauth.CSMSHandler)
	// Registers a handler for incoming transactions profile messages
	SetTransactionsHandler(handler transactions.CSMSHandler)
	// Registers a handler for incoming remote control profile messages
	SetRemoteControlHandler(handler remotecontrol.CSMSHandler)
	// Registers a handler for incoming availability profile messages
	SetAvailabilityHandler(handler availability.CSMSHandler)
	// Registers a handler for incoming reservation profile messages
	SetReservationHandler(handler reservation.CSMSHandler)
	// Registers a handler for incoming tariff and cost profile messages
	SetTariffCostHandler(handler tariffcost.CSMSHandler)
	// Registers a handler for incoming meter profile messages
	SetMeterHandler(handler meter.CSMSHandler)
	// Registers a handler for incoming smart charging messages
	SetSmartChargingHandler(handler smartcharging.CSMSHandler)
	// Registers a handler for incoming firmware management messages
	SetFirmwareHandler(handler firmware.CSMSHandler)
	// Registers a handler for incoming ISO15118 management messages
	SetISO15118Handler(handler iso15118.CSMSHandler)
	// Registers a handler for incoming diagnostics messages
	SetDiagnosticsHandler(handler diagnostics.CSMSHandler)
	// Registers a handler for incoming display messages
	SetDisplayHandler(handler display.CSMSHandler)
	// Registers a handler for incoming data transfer messages
	SetDataHandler(handler data.CSMSHandler)
	// Registers a handler for new incoming Charging station connections.
	SetNewChargingStationHandler(handler func(chargePointId string))
	// Registers a handler for Charging station disconnections.
	SetChargingStationDisconnectedHandler(handler func(chargePointId string))
	// Sends an asynchronous request to a Charging Station, identified by the clientId.
	// The charging station will respond with a confirmation message, or with an error if the request was invalid or could not be processed.
	// This result is propagated via a callback, called asynchronously.
	// In case of network issues (i.e. the remote host couldn't be reached), the function returns an error directly. In this case, the callback is never invoked.
	SendRequestAsync(clientId string, request ocpp.Request, callback func(ocpp.Response, error)) error

	// The function blocks forever, so it is suggested to wrap it in a goroutine, in case other functionality needs to be executed on the main program thread.
	Start(listenPort int, listenPath string)
}

A Charging Station Management System (CSMS) manages Charging Stations and has the information for authorizing Management Users for using its Charging Stations. You can instantiate a default CSMS struct by calling the NewCSMS function.

The logic for handling incoming messages needs to be implemented, and message handlers need to be registered with the CSMS:

	handler := &CSMSHandler{} 				// Custom struct
 csms.SetAuthorizationHandler(handler)
 csms.SetProvisioningHandler(handler)
 // set more handlers...

Refer to the CSMSHandler interface of each profile for the implementation requirements.

If a handler for a profile is not set, the OCPP library will reply to incoming messages for that profile with a NotImplemented error.

A CSMS can be started by using the Start function. To be notified of incoming (dis)connections from charging stations refer to the SetNewChargingStationHandler and SetChargingStationDisconnectedHandler functions.

While running, messages can be sent to a Charging Station by calling the CSMS's functions, e.g.:

callback := func(conf *ClearDisplayResponse, err error) {
	// handle the response...
}
clearDisplayConf, err := csms.ClearDisplay("cs0001", callback, 10)

All messages are sent asynchronously and do not block the caller.

func NewCSMS

func NewCSMS(endpoint *ocppj.Server, server ws.WsServer) CSMS

Creates a new OCPP 2.0 CSMS.

The endpoint and client parameters may be omitted, in order to use a default configuration:

csms := NewCSMS(nil, nil)

It is recommended to use the default configuration, unless a custom networking / ocppj layer is required. The default dispatcher supports all implemented OCPP 2.0 features out-of-the-box.

If you need a TLS server, you may use the following:

csms := NewCSMS(nil, ws.NewTLSServer("certificatePath", "privateKeyPath"))

type ChargingStation

type ChargingStation interface {
	// Sends a BootNotificationRequest to the CSMS, along with information about the charging station.
	BootNotification(reason provisioning.BootReason, model string, chargePointVendor string, props ...func(request *provisioning.BootNotificationRequest)) (*provisioning.BootNotificationResponse, error)
	// Requests explicit authorization to the CSMS, provided a valid IdToken (typically the customer's). The CSMS may either authorize or reject the token.
	Authorize(idToken string, tokenType types.IdTokenType, props ...func(request *authorization.AuthorizeRequest)) (*authorization.AuthorizeResponse, error)
	// Notifies the CSMS, that a previously set charging limit was cleared.
	ClearedChargingLimit(chargingLimitSource types.ChargingLimitSourceType, props ...func(request *smartcharging.ClearedChargingLimitRequest)) (*smartcharging.ClearedChargingLimitResponse, error)
	// Performs a custom data transfer to the CSMS. The message payload is not pre-defined and must be supported by the CSMS. Every vendor may implement their own proprietary logic for this message.
	DataTransfer(vendorId string, props ...func(request *data.DataTransferRequest)) (*data.DataTransferResponse, error)
	// Notifies the CSMS of a status change during a firmware update procedure (download, installation).
	FirmwareStatusNotification(status firmware.FirmwareStatus, requestID int, props ...func(request *firmware.FirmwareStatusNotificationRequest)) (*firmware.FirmwareStatusNotificationResponse, error)
	// Requests a new certificate, required for an ISO 15118 EV, from the CSMS.
	Get15118EVCertificate(schemaVersion string, exiRequest string, props ...func(request *iso15118.Get15118EVCertificateRequest)) (*iso15118.Get15118EVCertificateResponse, error)
	// Requests the CSMS to provide OCSP certificate status for the charging station's 15118 certificates.
	GetCertificateStatus(ocspRequestData types.OCSPRequestDataType, props ...func(request *iso15118.GetCertificateStatusRequest)) (*iso15118.GetCertificateStatusResponse, error)

	// Registers a handler for incoming security profile messages
	SetSecurityHandler(handler security.ChargingStationHandler)
	// Registers a handler for incoming provisioning profile messages
	SetProvisioningHandler(handler provisioning.ChargingStationHandler)
	// Registers a handler for incoming authorization profile messages
	SetAuthorizationHandler(handler authorization.ChargingStationHandler)
	// Registers a handler for incoming local authorization list profile messages
	SetLocalAuthListHandler(handler localauth.ChargingStationHandler)
	// Registers a handler for incoming transactions profile messages
	SetTransactionsHandler(handler transactions.ChargingStationHandler)
	// Registers a handler for incoming remote control profile messages
	SetRemoteControlHandler(handler remotecontrol.ChargingStationHandler)
	// Registers a handler for incoming availability profile messages
	SetAvailabilityHandler(handler availability.ChargingStationHandler)
	// Registers a handler for incoming reservation profile messages
	SetReservationHandler(handler reservation.ChargingStationHandler)
	// Registers a handler for incoming tariff and cost profile messages
	SetTariffCostHandler(handler tariffcost.ChargingStationHandler)
	// Registers a handler for incoming meter profile messages
	SetMeterHandler(handler meter.ChargingStationHandler)
	// Registers a handler for incoming smart charging messages
	SetSmartChargingHandler(handler smartcharging.ChargingStationHandler)
	// Registers a handler for incoming firmware management messages
	SetFirmwareHandler(handler firmware.ChargingStationHandler)
	// Registers a handler for incoming ISO15118 management messages
	SetISO15118Handler(handler iso15118.ChargingStationHandler)
	// Registers a handler for incoming diagnostics messages
	SetDiagnosticsHandler(handler diagnostics.ChargingStationHandler)
	// Registers a handler for incoming display messages
	SetDisplayHandler(handler display.ChargingStationHandler)
	// Registers a handler for incoming data transfer messages
	SetDataHandler(handler data.ChargingStationHandler)
	// Sends a request to the CSMS.
	// The CSMS will respond with a confirmation, or with an error if the request was invalid or could not be processed.
	// In case of network issues (i.e. the remote host couldn't be reached), the function also returns an error.
	//
	// The request is synchronous blocking.
	SendRequest(request ocpp.Request) (ocpp.Response, error)
	// Sends an asynchronous request to the CSMS.
	// The CSMS will respond with a confirmation message, or with an error if the request was invalid or could not be processed.
	// This result is propagated via a callback, called asynchronously.
	//
	// In case of network issues (i.e. the remote host couldn't be reached), the function returns an error directly. In this case, the callback is never invoked.
	SendRequestAsync(request ocpp.Request, callback func(confirmation ocpp.Response, protoError error)) error
	// Connects to the CSMS and starts the charging station routine.
	// The function doesn't block and returns right away, after having attempted to open a connection to the CSMS.
	// If the connection couldn't be opened, an error is returned.
	//
	// Optional client options must be set before calling this function. Refer to NewChargingStation.
	//
	// No auto-reconnect logic is implemented as of now, but is planned for the future.
	Start(csmsUrl string) error
	// Stops the charging station routine, disconnecting it from the CSMS.
	// Any pending requests are discarded.
	Stop()
}

A Charging Station represents the physical system where an EV can be charged. You can instantiate a default Charging Station struct by calling NewChargingStation.

The logic for incoming messages needs to be implemented, and message handlers need to be registered with the charging station:

	handler := &ChargingStationHandler{} 				// Custom struct
 chargingStation.SetAuthorizationHandler(handler)
 chargingStation.SetProvisioningHandler(handler)
 // set more handlers...

Refer to the ChargingStationHandler interface of each profile for the implementation requirements.

If a handler for a profile is not set, the OCPP library will reply to incoming messages for that profile with a NotImplemented error.

A charging station can be started and stopped using the Start and Stop functions. While running, messages can be sent to the CSMS by calling the Charging Station's functions, e.g.

bootConf, err := chargingStation.BootNotification(BootReasonPowerUp, "model1", "vendor1")

All messages are synchronous blocking, and return either the response from the CSMS or an error. To send asynchronous messages and avoid blocking the calling thread, refer to SendRequestAsync.

func NewChargingStation

func NewChargingStation(id string, endpoint *ocppj.Client, client ws.WsClient) ChargingStation

Creates a new OCPP 2.0 charging station client. The id parameter is required to uniquely identify the charge point.

The endpoint and client parameters may be omitted, in order to use a default configuration:

chargingStation := NewChargingStation("someUniqueId", nil, nil)

Additional networking parameters (e.g. TLS or proxy configuration) may be passed, by creating a custom client. Here is an example for a client using TLS configuration with a self-signed certificate:

certPool := x509.NewCertPool()
data, err := ioutil.ReadFile("serverSelfSignedCertFilename")
if err != nil {
	log.Fatal(err)
}
ok = certPool.AppendCertsFromPEM(data)
if !ok {
	log.Fatal("couldn't parse PEM certificate")
}
cs := NewChargingStation("someUniqueId", nil, ws.NewTLSClient(&tls.Config{
	RootCAs: certPool,
})

For more advanced options, or if a custom networking/occpj layer is required, please refer to ocppj.Client and ws.WsClient.