ocpp

README

go-ocpp - Open Charge Point Protocol Client and Server Library for Go

A pure Go implementation of the Open Charge Point Protocol, for both roles: the Charging Station (OCPP 1.6: Charge Point) and the CSMS (OCPP 1.6: Central System). Both share one RPC engine, and either side can send requests once connected.

Status: Phase 7 of 8 (hardening). OCPP 1.6J (with the Security Whitepaper extensions), OCPP 2.0.1 and OCPP 2.1 are complete at the message level: every action is typed, validated against the OCA schemas, and dispatchable in both roles; 2.1 adds the SEND and CALLRESULTERROR message types. 1.6J and 2.0.1 pass against five independent implementations, 2.1 against three (two CSMSs, The Mobility House and CitrineOS, and the EVerest libocpp station), including TLS and compression (ocpp-interop v0.4.1). See IMPLEMENTATION_PLAN.md.

Docs: Architecture · Requirements · Specifications · Plan · API (client, server) · Errors · Observability · Security · Interoperability · Compatibility · Features and gaps · Releases

Table of contents

• Protocol versions
• Install
• Quick start
• Interoperability
• Assurance
• Development
• License

Protocol versions

Version	Priority	Status
OCPP 1.6J, with the Security Whitepaper (Edition 4) extensions	P0	39 actions, both roles (ocpp16)
OCPP 2.0.1 Edition 4, errata 2026-09	P0	64 actions, both roles (ocpp201)
OCPP 2.1 Edition 2, errata 2026-09	P1	91 actions, both roles, SEND and CALLRESULTERROR (ocpp21); interop pending
OCPP 1.6 SOAP, OCPP 1.5 and older	—	out of scope

Install

go get github.com/otfabric/go-ocpp

Requires Go 1.26 or later. The only dependency of the library is coder/websocket (ADR 0002); the tests also use a reference JSON Schema validator (ADR 0003).

Quick start

A CSMS and a charging station, OCPP 2.0.1 (the examples run complete, self-contained versions of this for 1.6 and 2.0.1):

// CSMS: answer the stations' CALLs.
type csms struct{ ocpp201.UnimplementedCSMSHandler }

func (csms) BootNotification(ctx context.Context, p ocpp.Peer, req *ocpp201.BootNotificationRequest) (*ocpp201.BootNotificationResponse, error) {
    return &ocpp201.BootNotificationResponse{Status: ocpp201.RegistrationStatusAccepted, CurrentTime: time.Now().UTC(), Interval: 300}, nil
}

srv, err := server.New(
    server.WithHandler(ocpp.V201, ocpp201.CSMS(csms{})),
    server.WithAuthenticator(server.BasicAuth(lookupPassword)),
)
http.Handle("/ocpp/", srv) // behind TLS

// Send a CALL to a connected station.
if s, ok := srv.Station("STATION001"); ok {
    resp, err := ocpp201.Reset(ctx, s, &ocpp201.ResetRequest{Type: ocpp201.ResetOnIdle})
}

// Charging station.
c, err := client.New("wss://csms.example.com/ocpp/STATION001",
    client.WithHandler(ocpp.V201, ocpp201.ChargingStation(station{})),
    client.WithBasicAuth("STATION001", password),
    client.WithReconnect(client.DefaultReconnect()),
    client.WithCompression(),
)
err = c.Connect(ctx)
boot, err := ocpp201.BootNotification(ctx, c, &ocpp201.BootNotificationRequest{
    Reason:          ocpp201.BootReasonPowerUp,
    ChargingStation: ocpp201.ChargingStationType{VendorName: "OTFabric", Model: "TestStation"},
})

Every request is validated against its schema before it is sent, every response when it arrives, and every incoming request before a handler sees it; an invalid one is answered with the CALLERROR its violation calls for.

go-ocpp is a protocol library. It transports, validates and dispatches messages. Charging behaviour, authorization policy, persistence and billing belong to the application's handlers.

Interoperability

go-ocpp is tested in both roles against The Mobility House ocpp 2.1.0 (1.6J, 2.0.1, 2.1), ChargeTimeEU Java-OCA-OCPP v2.0 and lorenzodonini/ocpp-go v0.19.0 (1.6J, 2.0.1), as a CSMS against EVerest libocpp (1.6J, 2.0.1, 2.1), and as a station against CitrineOS core v2.0.1 (1.6J, 2.0.1, 2.1), as packaged by otfabric/ocpp-interop v0.4.1: every action, security profiles 1 to 3 and compression. 1458 scenarios pass and none fails; the skipped ones are documented upstream defects and capabilities a reference does not have, and every payload the references send passes go-ocpp's schema validation. See INTEROPERABILITY.md and the per-version matrices in docs/compatibility.

make interop   # needs Docker

Assurance

go-ocpp distinguishes three levels of assurance and claims only the first two, once tests establish them:

Level	Meaning
Schema conformant	Messages validate against the OCA JSON schemas of their version
Interoperability tested	Communication succeeds against independent implementations from otfabric/ocpp-interop, in both roles
OCA certified	Formal certification of a specific product with the OCA. Not claimed

Development

make help     # list targets
make check    # format, lint, vet, vuln, test, coverage, cross-build

See CONTRIBUTING.md and AGENTS.md.

License

MIT; see LICENSE. OCPP specifications and schemas are © Open Charge Alliance, licensed under CC BY-ND 4.0, and are not part of this licence. See SPECIFICATIONS.md.

Documentation

Overview

Package ocpp holds what the OCPP versions and both roles of go-ocpp share: the protocol versions and their WebSocket subprotocols, the contracts between the layers (Peer, Caller, Dispatcher), CALLERRORs and their codes, the sentinel errors, and the observability hooks.

The roles are in package client (Charging Station) and package server (CSMS); the OCPP-J frame codec is in package ocppj. The typed messages of the version packages ocpp16, ocpp201 and ocpp21 are designed in ARCHITECTURE.md and are not implemented yet: until then, requests and responses are raw JSON.

Documentation:

• ARCHITECTURE.md: layers, packages, the engine, both roles
• REQUIREMENTS.md: what the library must do
• SPECIFICATIONS.md: the OCA editions and errata it follows
• IMPLEMENTATION_PLAN.md: phases and their gates
• ERRORS.md: error semantics

Index

• Variables
• func AfterResponse(ctx context.Context, f func()) bool
• func Ptr[T any](v T) *T
• type CallError
  • func NewCallError(code ErrorCode, description string) *CallError
  • func (e *CallError) Error() string
• type CallInfo
• type Caller
• type CloseError
  • func (e *CloseError) Error() string
  • func (e *CloseError) Normal() bool
• type ConnInfo
• type Direction
  • func (d Direction) String() string
• type Dispatcher
• type DispatcherFunc
  • func (f DispatcherFunc) Dispatch(ctx context.Context, p Peer, action string, payload json.RawMessage) (json.RawMessage, error)
• type ErrorCode
• type FrameObserver
• type Interceptor
• type Metrics
• type NopMetrics
  • func (NopMetrics) OnCallDone(ConnInfo, string, time.Duration, error)
  • func (NopMetrics) OnCallHandled(ConnInfo, string, time.Duration, error)
  • func (NopMetrics) OnConnect(ConnInfo)
  • func (NopMetrics) OnConnectFailed(ConnInfo, error)
  • func (NopMetrics) OnDisconnect(ConnInfo, error)
  • func (NopMetrics) OnProtocolError(ConnInfo, error)
  • func (NopMetrics) OnReconnectAttempt(ConnInfo, int)
• type Peer
• type Role
  • func (r Role) String() string
• type SendDispatcher
• type Sender
• type State
  • func (s State) String() string
• type ValidationError
  • func (e *ValidationError) CallError() *CallError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Unwrap() error
• type Version
  • func ParseSubprotocol(s string) (Version, bool)
  • func ParseVersion(s string) (Version, bool)
  • func Versions() []Version
  • func (v Version) String() string
  • func (v Version) Subprotocol() string
  • func (v Version) Valid() bool

Variables

var (
	// ErrClosed is returned by operations on a client, server or session
	// after Close.
	ErrClosed = errors.New("ocpp: closed")

	// ErrNotConnected is returned by a call on a client that has no open
	// connection, including while it reconnects. Nothing is queued.
	ErrNotConnected = errors.New("ocpp: not connected")

	// ErrConnectFailed is returned when a client cannot open a connection:
	// the dial, the TLS handshake, the WebSocket handshake or the
	// subprotocol negotiation failed.
	ErrConnectFailed = errors.New("ocpp: connect failed")

	// ErrConnectionLost is returned to calls that were pending or queued
	// when the connection broke.
	ErrConnectionLost = errors.New("ocpp: connection lost")

	// ErrTimeout is returned when no response to a CALL arrived in time.
	ErrTimeout = errors.New("ocpp: timeout")

	// ErrBusy is returned when the queue of calls waiting to be sent is
	// full. OCPP allows one outstanding CALL per direction.
	ErrBusy = errors.New("ocpp: busy")

	// ErrWrongDirection is returned when an action is sent by a role that
	// the specification does not let send it.
	ErrWrongDirection = errors.New("ocpp: action not sent in this direction")

	// ErrUnsupportedVersion is returned when no common OCPP version can be
	// negotiated, or when a version is used that was not configured.
	ErrUnsupportedVersion = errors.New("ocpp: unsupported version")

	// ErrProtocol is returned when the peer violates the OCPP-J framing.
	ErrProtocol = errors.New("ocpp: protocol error")

	// ErrInvalidOption is returned by constructors given an invalid option.
	ErrInvalidOption = errors.New("ocpp: invalid option")

	// ErrHandlerPanic is reported through Metrics.OnCallHandled when a
	// handler panicked. The panic is recovered, logged with its stack, and
	// the CALL answered with InternalError.
	ErrHandlerPanic = errors.New("ocpp: handler panic")
)

Sentinel errors shared by the client, the server and the version packages. They are usually wrapped with detail; test for them with errors.Is. ERRORS.md describes when each is returned.

var ErrInvalidMessage = errors.New("ocpp: invalid message")

ErrInvalidMessage is wrapped by every *ValidationError: a payload that does not conform to the JSON schema of its action.

var ErrUnexpectedResponse = errors.New("ocpp: unexpected response")

ErrUnexpectedResponse is reported through Metrics.OnProtocolError for a CALLRESULT or CALLERROR that matches no pending CALL: a late response after a timeout, a duplicate, or an unknown message ID.

Functions

func AfterResponse

func AfterResponse(ctx context.Context, f func()) bool

AfterResponse registers f to run once the response to the CALL being handled is on its way: for what a handler must do after answering, such as sending the NotifyReport messages after accepting GetBaseReport, the FirmwareStatusNotifications after accepting UpdateFirmware, or the triggered message after TriggerMessage. ctx must be the context the handler received; f runs on a goroutine of its own, after the response (CALLRESULT or CALLERROR) has been queued ahead of any CALL f sends. It reports false, and f does not run, when ctx is not a handler's context (a SEND handler's included: a SEND has no response).

func Ptr

func Ptr[T any](v T) *T

Ptr returns a pointer to v, for the optional fields of messages:

req := &ocpp16.BootNotificationRequest{
    ChargePointVendor:       "OTFabric",
    ChargePointModel:        "TestStation",
    ChargePointSerialNumber: ocpp.Ptr("OTF-0001"),
}

Types

type CallError

type CallError struct {
	Code        ErrorCode
	Description string
	// Details is a JSON object, or nil for {}.
	Details json.RawMessage
}

CallError is a CALLERROR: the peer's answer that it could not process a CALL. A call returns it as the error (test with errors.As), and a handler returns it to answer with a CALLERROR of its choosing.

A CALLERROR is not a business rejection. A BootNotification answered with status Rejected is a successful call.

func NewCallError

func NewCallError(code ErrorCode, description string) *CallError

NewCallError returns a CallError with the given code and description.

func (*CallError) Error

func (e *CallError) Error() string

Error implements error.

type CallInfo

type CallInfo struct {
	ConnInfo
	Action    string
	MessageID string
	Direction Direction // Outgoing: a call this end sends; Incoming: one it handles
}

CallInfo describes one CALL, for interceptors.

type Caller

type Caller interface {
	Call(ctx context.Context, action string, req, resp any) error
}

Caller sends a CALL and waits for its result.

req is marshalled with encoding/json; a json.RawMessage is sent as is. The result payload is unmarshalled into resp, which must be a pointer (a *json.RawMessage receives the payload unchanged) or nil to discard it. A CALLERROR is returned as a *CallError.

type CloseError

type CloseError struct {
	Code   int    // RFC 6455 §7.4 status code, e.g. 1000
	Reason string // the peer's reason text, often empty
}

CloseError says how the peer closed the connection, when it sent a WebSocket close frame. The error of a lost connection (Session.Err, the session handler, Metrics.OnDisconnect, the client's state handler) wraps it next to ErrConnectionLost:

var ce *ocpp.CloseError
if errors.As(err, &ce) && ce.Normal() { /* the peer closed on purpose */ }

func (*CloseError) Error

func (e *CloseError) Error() string

Error implements error.

func (*CloseError) Normal

func (e *CloseError) Normal() bool

Normal reports whether the peer closed on purpose: status 1000 (normal closure) or 1001 (going away, e.g. a reboot or a server shutting down).

type ConnInfo

type ConnInfo struct {
	StationID string
	Version   Version // zero before the handshake completes
	Role      Role    // the local role
	SessionID string  // random, unique per connection; for correlating logs
}

ConnInfo identifies a connection in callbacks.

type Direction

type Direction uint8

Direction says whether a frame or call was sent or received.

const (
	Outgoing Direction = iota + 1
	Incoming
)

The directions.

func (Direction) String

func (d Direction) String() string

String returns "outgoing" or "incoming".

type Dispatcher

type Dispatcher interface {
	Dispatch(ctx context.Context, p Peer, action string, payload json.RawMessage) (json.RawMessage, error)
}

Dispatcher handles the CALLs that arrive on a connection of one OCPP version. The version packages build dispatchers from typed handlers; DispatcherFunc handles raw payloads.

Dispatch returns the CALLRESULT payload, or an error: a *CallError is sent as is, any other error as an InternalError whose description does not reveal the error text.

type DispatcherFunc

type DispatcherFunc func(ctx context.Context, p Peer, action string, payload json.RawMessage) (json.RawMessage, error)

DispatcherFunc adapts a function to a Dispatcher.

func (DispatcherFunc) Dispatch

func (f DispatcherFunc) Dispatch(ctx context.Context, p Peer, action string, payload json.RawMessage) (json.RawMessage, error)

Dispatch calls f.

type ErrorCode

type ErrorCode string

ErrorCode is the error code of a CALLERROR (and, in OCPP 2.1, of a CALLRESULTERROR). Which codes a version allows is defined by package ocppj (ocppj.ValidErrorCode).

const (
	NotImplemented              ErrorCode = "NotImplemented"
	NotSupported                ErrorCode = "NotSupported"
	InternalError               ErrorCode = "InternalError"
	ProtocolError               ErrorCode = "ProtocolError"
	SecurityError               ErrorCode = "SecurityError"
	PropertyConstraintViolation ErrorCode = "PropertyConstraintViolation"
	TypeConstraintViolation     ErrorCode = "TypeConstraintViolation"
	GenericError                ErrorCode = "GenericError"

	// FormationViolation is the 1.6 name of the code 2.x calls FormatViolation.
	FormationViolation ErrorCode = "FormationViolation"
	// FormatViolation is OCPP 2.x only. See FormationViolation.
	FormatViolation ErrorCode = "FormatViolation"

	// OccurenceConstraintViolation is the OCPP 1.6 spelling, with one "r",
	// as the 1.6 specification writes it.
	OccurenceConstraintViolation ErrorCode = "OccurenceConstraintViolation"
	// OccurrenceConstraintViolation is the OCPP 2.x spelling.
	OccurrenceConstraintViolation ErrorCode = "OccurrenceConstraintViolation"

	// MessageTypeNotSupported is OCPP 2.x only.
	MessageTypeNotSupported ErrorCode = "MessageTypeNotSupported"
	// RpcFrameworkError is OCPP 2.x only.
	RpcFrameworkError ErrorCode = "RpcFrameworkError" //nolint:revive // the name the specification uses
)

The CALLERROR error codes of OCPP-J 1.6 §4.2.3 and OCPP 2.0.1/2.1 Part 4 §4.3. Most codes exist in every version. Where the versions differ, the constant's comment says so.

type FrameObserver

type FrameObserver func(info ConnInfo, dir Direction, frame []byte)

FrameObserver sees every OCPP-J frame sent or received, as raw JSON. It runs synchronously on the connection's reader or writer, so it must not block, and it must not retain or modify frame.

type Interceptor

type Interceptor func(ctx context.Context, info CallInfo, next func(context.Context) error) error

Interceptor wraps an outgoing call (client and server option WithCallInterceptor) or the handling of an incoming one (WithHandlerInterceptor). It must call next exactly once, with ctx or a context derived from it, and return its error or an error of its own. This is where tracing spans start and end.

type Metrics

type Metrics interface {
	// OnConnect is called when a connection opens.
	OnConnect(info ConnInfo)
	// OnConnectFailed is called when a client's dial or a server's
	// handshake fails. info.Version is zero.
	OnConnectFailed(info ConnInfo, err error)
	// OnDisconnect is called when an open connection ends; err is nil after
	// a local Close.
	OnDisconnect(info ConnInfo, err error)
	// OnReconnectAttempt is called before a client redials.
	OnReconnectAttempt(info ConnInfo, attempt int)
	// OnCallDone is called when an outgoing CALL ends, with its round trip
	// time and nil, a *CallError, ErrTimeout or another error.
	OnCallDone(info ConnInfo, action string, d time.Duration, err error)
	// OnCallHandled is called when an incoming CALL has been answered, with
	// the handler's duration and its error.
	OnCallHandled(info ConnInfo, action string, d time.Duration, err error)
	// OnProtocolError is called for a frame that violates OCPP-J, and for a
	// response that matches no pending CALL (late or unknown).
	OnProtocolError(info ConnInfo, err error)
}

Metrics receives events for metrics. Callbacks are synchronous and must be safe for concurrent use and must not block.

Every callback gets the station identity in ConnInfo. Whether it becomes a metric label is the implementation's choice; labelling by station gives one series per station.

Embed NopMetrics so that an implementation keeps compiling when callbacks are added.

type NopMetrics

type NopMetrics struct{}

NopMetrics implements Metrics and does nothing.

func (NopMetrics) OnCallDone

func (NopMetrics) OnCallDone(ConnInfo, string, time.Duration, error)

OnCallDone does nothing.

func (NopMetrics) OnCallHandled

func (NopMetrics) OnCallHandled(ConnInfo, string, time.Duration, error)

OnCallHandled does nothing.

func (NopMetrics) OnConnect

func (NopMetrics) OnConnect(ConnInfo)

OnConnect does nothing.

func (NopMetrics) OnConnectFailed

func (NopMetrics) OnConnectFailed(ConnInfo, error)

OnConnectFailed does nothing.

func (NopMetrics) OnDisconnect

func (NopMetrics) OnDisconnect(ConnInfo, error)

OnDisconnect does nothing.

func (NopMetrics) OnProtocolError

func (NopMetrics) OnProtocolError(ConnInfo, error)

OnProtocolError does nothing.

func (NopMetrics) OnReconnectAttempt

func (NopMetrics) OnReconnectAttempt(ConnInfo, int)

OnReconnectAttempt does nothing.

type Peer

type Peer interface {
	// ID returns the charging station identity of the connection, on both
	// ends: the client's own identity, or the identity of the station a
	// server session belongs to.
	ID() string
	// Version returns the OCPP version negotiated for the connection.
	Version() Version
	Caller
}

Peer is the other end of one connection, as a handler sees it: the station's identity, the negotiated version, and a way to send it CALLs.

type Role

type Role uint8

Role is one of the two OCPP roles.

const (
	ChargingStation Role = iota + 1
	CSMS
)

The roles. OCPP 1.6 calls them Charge Point and Central System.

func (Role) String

func (r Role) String() string

String returns "ChargingStation" or "CSMS".

type SendDispatcher

type SendDispatcher interface {
	DispatchSend(ctx context.Context, p Peer, action string, payload json.RawMessage) error
}

SendDispatcher is implemented by a Dispatcher that also handles incoming SEND messages (OCPP 2.1). They are never answered, so DispatchSend returns only an error, which is logged.

type Sender

type Sender interface {
	Send(ctx context.Context, action string, req any) error
}

Sender sends a SEND (OCPP 2.1): a message that is never answered and may be sent while a CALL is outstanding (2.1 Part 4 §4.1.1, §4.2.4). The client and server sessions implement it.

type State

type State uint8

State is the state of a client's connection.

const (
	Disconnected State = iota // not connected, and not trying to (yet)
	Connecting                // dialling or waiting to redial
	Connected                 // the WebSocket is open
	Closed                    // Close was called; final
)

The client states.

func (State) String

func (s State) String() string

String returns the state's name.

type ValidationError

type ValidationError struct {
	// Code is the CALLERROR code that fits the violation, spelt as the
	// connection's version spells it: FormationViolation/FormatViolation
	// for structure, OccurenceConstraintViolation/OccurrenceConstraintViolation
	// for a missing field or a wrong number of elements,
	// TypeConstraintViolation for a value of the wrong type, and
	// PropertyConstraintViolation for a value outside its constraints.
	Code ErrorCode
	// Field is the path of the offending field, e.g.
	// "meterValue[0].sampledValue[1].measurand"; empty for the payload.
	Field string
	// Reason says what is wrong.
	Reason string
}

ValidationError says why a payload does not conform to the schema of its action. The version packages return it for requests and responses they refuse, outgoing and incoming. An incoming CALL that fails validation is answered with a CALLERROR carrying Code.

func (*ValidationError) CallError

func (e *ValidationError) CallError() *CallError

CallError returns the CALLERROR that answers a CALL failing validation.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error implements error.

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error

Unwrap returns ErrInvalidMessage.

type Version

type Version uint8

Version is an OCPP protocol version that go-ocpp implements over JSON and WebSocket (OCPP-J). The zero value is not a valid version.

const (
	V16  Version = iota + 1 // OCPP 1.6J, with the Security Whitepaper extensions
	V201                    // OCPP 2.0.1
	V21                     // OCPP 2.1
)

The versions in scope. OCPP 1.6 SOAP and versions before 1.6 are not supported. SPECIFICATIONS.md lists the editions and errata followed.

func ParseSubprotocol

func ParseSubprotocol(s string) (Version, bool)

ParseSubprotocol returns the version a WebSocket subprotocol selects. The comparison is exact: RFC 6455 subprotocol tokens are case-sensitive.

func ParseVersion

func ParseVersion(s string) (Version, bool)

ParseVersion parses a version as String writes it.

func Versions

func Versions() []Version

Versions returns the supported versions, oldest first.

func (Version) String

func (v Version) String() string

String returns the version as the specifications write it: "1.6", "2.0.1" or "2.1". An invalid version is written as "Version(n)".

func (Version) Subprotocol

func (v Version) Subprotocol() string

Subprotocol returns the WebSocket subprotocol that selects v during the opening handshake ("ocpp1.6", "ocpp2.0.1" or "ocpp2.1"). It returns "" for an invalid version.

func (Version) Valid

func (v Version) Valid() bool

Valid reports whether v is one of the supported versions.