ocpp

README

ocpp-go

A Go library for building Open Charge Point Protocol (OCPP) clients and central systems.

ocpp-go provides typed OCPP message structs, JSON array serialization, a WebSocket client, a WebSocket server, callback-based message routing, and request/response helpers for sending calls and waiting for results.

The API is inspired by the Python mobilityhouse/ocpp project while staying idiomatic for Go.

Status

This project is still early. APIs may change while the library settles.

Current protocol support:

• OCPP 1.6 JSON: typed messages, client/server routing, callbacks, and request/response helpers.
• OCPP 2.1 JSON: typed messages, client/server routing, callbacks, and request/response helpers.

Installation

go get github.com/johnmaddison/ocpp-go

Import the packages you need:

import (
	"github.com/johnmaddison/ocpp-go"
	"github.com/johnmaddison/ocpp-go/client"
	"github.com/johnmaddison/ocpp-go/ocpp16"
	"github.com/johnmaddison/ocpp-go/ocpp21"
	"github.com/johnmaddison/ocpp-go/server"
)

Examples

The repository includes a runnable example central system and charge point.

In one terminal:

make run-server

In another terminal:

make run-client

The example server listens on 0.0.0.0:9001 and accepts charge points at:

ws://127.0.0.1:9001/ocpp/{chargePointId}

License

MIT License. See LICENSE.

Documentation

Overview

Package ocpp contains shared OCPP message envelope types and helpers.

Index

• Constants
• func Ptr[T any](v T) *T
• type Call
  • func NewCall(action string, payload any) *Call
  • func (c *Call) SerializeOCPP() ([]byte, error)
• type CallError
  • func (ce *CallError) SerializeOCPP() ([]byte, error)
  • func (c CallError) String() string
• type CallResult
  • func (cr *CallResult) SerializeOCPP() ([]byte, error)
• type ConnectRequest
• type ConnectRequestCallback
• type ConnectedCallback
• type ConnectionInfo
• type DisconnectCallback
• type MessageCallback
• type MessageDirection
• type MessageInfo
• type SocketCallbacks

Constants

const (
	MessageTypeCall       = 2
	MessageTypeCallResult = 3
	MessageTypeCallError  = 4
)

MessageType constants identify the OCPP JSON array envelope type.

Functions

func Ptr

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

Ptr returns a pointer to v.

Types

type Call

type Call struct {
	MessageType int    `json:"-"`
	MessageID   string `json:"-"`
	Action      string `json:"-"`
	Payload     any    `json:"-"`
}

Call represents a request from a client to a server.

func NewCall

func NewCall(action string, payload any) *Call

NewCall creates a CALL with a generated message ID.

func (*Call) SerializeOCPP

func (c *Call) SerializeOCPP() ([]byte, error)

SerializeOCPP converts a Call object to its JSON representation.

type CallError

type CallError struct {
	MessageType      int    `json:"-"`
	MessageID        string `json:"-"`
	ErrorCode        string `json:"errorCode"`
	ErrorDescription string `json:"errorDescription"`
	ErrorDetails     any    `json:"errorDetails,omitempty"`
}

CallError represents an error response to a Call.

func (*CallError) SerializeOCPP

func (ce *CallError) SerializeOCPP() ([]byte, error)

SerializeOCPP converts a CallError object to its JSON representation.

func (CallError) String

func (c CallError) String() string

String returns the JSON representation of the OCPP error fields.

type CallResult

type CallResult struct {
	MessageType int    `json:"-"`
	MessageID   string `json:"-"`
	Payload     any    `json:"-"`
}

CallResult represents a successful response to a Call.

func (*CallResult) SerializeOCPP

func (cr *CallResult) SerializeOCPP() ([]byte, error)

SerializeOCPP converts a CallResult object to its JSON representation.

type ConnectRequest

type ConnectRequest struct {
	R *http.Request
	W *http.ResponseWriter
}

ConnectRequest contains the HTTP upgrade request and response writer.

type ConnectRequestCallback

type ConnectRequestCallback func(ctx ConnectRequest) bool

ConnectRequestCallback decides whether an incoming websocket upgrade may continue.

type ConnectedCallback

type ConnectedCallback func(info ConnectionInfo)

ConnectedCallback is called after a websocket connection has been established.

type ConnectionInfo

type ConnectionInfo struct {
	ChargePointID string
	RemoteAddr    net.Addr
	LocalAddr     net.Addr
}

ConnectionInfo describes an established OCPP websocket connection.

type DisconnectCallback

type DisconnectCallback func(info ConnectionInfo)

DisconnectCallback is called after a websocket connection has closed.

type MessageCallback

type MessageCallback func(info MessageInfo)

MessageCallback observes an OCPP websocket text frame.

type MessageDirection

type MessageDirection string

MessageDirection identifies whether an OCPP websocket text frame was sent or received.

const (
	// MessageDirectionReceived identifies an inbound OCPP websocket text frame.
	MessageDirectionReceived MessageDirection = "received"
	// MessageDirectionSent identifies an outbound OCPP websocket text frame.
	MessageDirectionSent MessageDirection = "sent"
)

type MessageInfo

type MessageInfo struct {
	ConnectionInfo ConnectionInfo
	Protocol       string
	Direction      MessageDirection
	Message        []byte
}

MessageInfo describes an observed OCPP websocket text frame.

type SocketCallbacks

type SocketCallbacks struct {
	ConnectRequest  ConnectRequestCallback
	Connected       ConnectedCallback
	Disconnect      DisconnectCallback
	MessageReceived MessageCallback
	MessageSent     MessageCallback
}

SocketCallbacks groups websocket lifecycle callbacks.