ntxcp10

Documentation

Overview

The package contains an implementation of the ntxcp 1.0 communication protocol between a Ding.X Gateway and a Ding.X Control Center in an EV charging infrastructure.

Index

• type DingXControlCenter
  • func NewDingXControlCenter(endpoint *ntxcpj.Server, server ws.WsServer) DingXControlCenter
• type DingXGateway
  • func NewDingXGateway(id string, endpoint *ntxcpj.Client, client ws.WsClient) DingXGateway
• type DingXGatewayConnection
• type DingXGatewayConnectionHandler

Types

type DingXControlCenter

type DingXControlCenter interface {
	// Changes the configuration of a Ding.X Gateway, by setting a specific key-value pair.
	// The configuration key must be supported by the target Ding.X Gateway, in order for the configuration to be accepted.
	ChangeConfiguration(clientId string, callback func(*core.ChangeConfigurationConfirmation, error), key string, value string, props ...func(*core.ChangeConfigurationRequest)) error
	// Instructs the Ding.X Gateway to clear its current authorization cache. All authorization saved locally will be invalidated.
	ClearCache(clientId string, callback func(*core.ClearCacheConfirmation, error), props ...func(*core.ClearCacheRequest)) error
	// Starts a custom data transfer request. Every vendor may implement their own proprietary logic for this message.
	DataTransfer(clientId string, callback func(*core.DataTransferConfirmation, error), vendorId string, props ...func(*core.DataTransferRequest)) error
	// Retrieves the configuration values for the provided configuration keys.
	GetConfiguration(clientId string, callback func(*core.GetConfigurationConfirmation, error), keys []string, props ...func(*core.GetConfigurationRequest)) error
	// Forces a Ding.X Gateway to perform an internal hard or soft reset. In both cases, all ongoing transactions are stopped.
	Reset(clientId string, callback func(*core.ResetConfirmation, error), resetType core.ResetType, props ...func(*core.ResetRequest)) error
	// Attempts to unlock a specific connector on a Ding.X Gateway. Used for remote support purposes.
	GetDiagnostics(clientId string, callback func(*firmware.GetDiagnosticsConfirmation, error), location string, props ...func(request *firmware.GetDiagnosticsRequest)) error
	// Instructs the Ding.X Gateway to download and install a new firmware version. The firmware binary will be downloaded out-of-band from the provided URL location.
	UpdateFirmware(clientId string, callback func(*firmware.UpdateFirmwareConfirmation, error), location string, retrieveDate *types.DateTime, props ...func(request *firmware.UpdateFirmwareRequest)) error
	// Instructs a Ding.X Gateway to send a specific message to the ding.x control center. This is used for forcefully triggering status updates, when the last known state is either too old or not clear to the ding.x control center.
	TriggerMessage(clientId string, callback func(*remotetrigger.TriggerMessageConfirmation, error), requestedMessage remotetrigger.MessageTrigger, props ...func(request *remotetrigger.TriggerMessageRequest)) error
	// capture a process on a gateway
	CaptureProcess(clientId string, callback func(*core.CaptureProcessConfirmation, error), serviceId string, datapointIds []string, props ...func(request *core.CaptureProcessRequest)) error
	// Registers a handler for incoming core profile messages.
	SetCoreHandler(handler core.DingxControlCenterHandler)
	// Registers a handler for incoming firmware management profile messages.
	SetFirmwareManagementHandler(handler firmware.DingxControlCenterHandler)
	// Registers a handler for incoming remote trigger profile messages.
	SetRemoteTriggerHandler(handler remotetrigger.DingxControlCenterHandler)
	// Registers a handler for new incoming Charging station connections.
	SetNewChargingStationValidationHandler(handler ws.CheckClientHandler)
	// Registers a handler for new incoming Ding.X Gateway connections.
	SetNewDingxGatewayHandler(handler DingXGatewayConnectionHandler)
	// Registers a handler for Ding.X Gateway disconnections.
	SetDingxGatewayDisconnectedHandler(handler DingXGatewayConnectionHandler)
	// Sends an asynchronous request to the Ding.X Gateway.
	// The Ding.X Gateway 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 called.
	SendRequestAsync(clientId string, request ntxcp.Request, callback func(ntxcp.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)
	// Stops the ding.x control center, clearing all pending requests.
	Stop()
	// Errors returns a channel for error messages. If it doesn't exist it es created.
	Errors() <-chan error
}

A Ding.X Control Center manages Ding.X Gateways and has the information for authorizing users for using its Ding.X Gateways. You can instantiate a default Ding.X Control Center struct by calling the NewServer function.

The logic for handling incoming messages needs to be implemented, and the message handlers need to be registered with the ding.x control center:

handler := &DingxControlCenterHandler{}
server.SetCoreHandler(handler)

Refer to the DingxControlCenterHandler interfaces in the respective core, firmware, localauth, remotetrigger, reservation and smartcharging profiles for the implementation requirements.

A Central system can be started by using the Start function. To be notified of incoming (dis)connections from Ding.X Gateways refer to the SetNewClientHandler and SetDingxGatewayDisconnectedHandler functions.

While running, messages can be sent to a Ding.X Gateway by calling the Central system's functions, e.g.:

callback := func(conf *ChangeAvailabilityConfirmation, err error) {
	// handle the response...
}
changeAvailabilityConf, err := server.ChangeAvailability("cs0001", callback, 1, AvailabilityTypeOperative)

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

func NewDingXControlCenter

func NewDingXControlCenter(endpoint *ntxcpj.Server, server ws.WsServer) DingXControlCenter

Creates a new ntxcp 1.0 ding.x control center.

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

client := NewServer(nil, nil)

It is recommended to use the default configuration, unless a custom networking / ntxcpj layer is required. The default ntxcpj endpoint supports all ntxcp 1.0 profiles out-of-the-box.

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

cs := NewServer(nil, ws.NewTLSServer("certificatePath", "privateKeyPath"))

type DingXGateway

type DingXGateway interface {
	// Sends a BootNotificationRequest to the ding.x control center, along with information about the Ding.X Gateway.
	BootNotification(dingxGatewayModel string, props ...func(request *core.BootNotificationRequest)) (*core.BootNotificationConfirmation, error)
	// Starts a custom data transfer request. Every vendor may implement their own proprietary logic for this message.
	DataTransfer(vendorId string, props ...func(request *core.DataTransferRequest)) (*core.DataTransferConfirmation, error)
	// Notifies the ding.x control center that the Ding.X Gateway is still online. The ding.x control center's response is used for time synchronization purposes. It is recommended to perform this operation once every 24 hours.
	Heartbeat(props ...func(request *core.HeartbeatRequest)) (*core.HeartbeatConfirmation, error)
	// Sends a batch of collected meter values to the ding.x control center, for billing and analysis. May be done periodically during ongoing transactions.
	MeterValues(serviceId int, meterValues []types.MeterValue, props ...func(request *core.MeterValuesRequest)) (*core.MeterValuesConfirmation, error)
	// Notifies the ding.x control center of a status update. This may apply to the entire Ding.X Gateway or to a single connector.
	StatusNotification(serviceId string, errorCode core.DingxGatewayErrorCode, status core.DingxGatewayStatus, props ...func(request *core.StatusNotificationRequest)) (*core.StatusNotificationConfirmation, error)
	// Notifies the ding.x control center of a status change in the upload of diagnostics data.
	DiagnosticsStatusNotification(status firmware.DiagnosticsStatus, props ...func(request *firmware.DiagnosticsStatusNotificationRequest)) (*firmware.DiagnosticsStatusNotificationConfirmation, error)
	// Notifies the ding.x control center of a status change during the download of a new firmware version.
	FirmwareStatusNotification(status firmware.FirmwareStatus, props ...func(request *firmware.FirmwareStatusNotificationRequest)) (*firmware.FirmwareStatusNotificationConfirmation, error)

	// Registers a handler for incoming core profile messages
	SetCoreHandler(listener core.DingxGatewayHandler)
	// Registers a handler for incoming firmware management profile messages
	SetFirmwareManagementHandler(listener firmware.DingxGatewayHandler)
	// Registers a handler for incoming remote trigger profile messages
	SetRemoteTriggerHandler(listener remotetrigger.DingxGatewayHandler)
	// Sends a request to the ding.x control center.
	// The ding.x control center 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 ntxcp.Request) (ntxcp.Response, error)
	// Sends an asynchronous request to the ding.x control center.
	// The ding.x control center will respond with a confirmation messages, 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 called.
	SendRequestAsync(request ntxcp.Request, callback func(confirmation ntxcp.Response, protoError error)) error
	// Connects to the ding.x control center and starts the Ding.X Gateway routine.
	// The function doesn't block and returns right away, after having attempted to open a connection to the ding.x control center.
	// If the connection couldn't be opened, an error is returned.
	//
	// Optional client options must be set before calling this function. Refer to NewClient.
	//
	// No auto-reconnect logic is implemented as of now, but is planned for the future.
	Start(centralSystemUrl string) error
	// Stops the Ding.X Gateway routine, disconnecting it from the ding.x control center.
	// Any pending requests are discarded.
	Stop()
	// Returns true if the Ding.X Gateway is currently connected to the ding.x control center, false otherwise.
	// While automatically reconnecting to the ding.x control center, the method returns false.
	IsConnected() bool
	// Errors returns a channel for error messages. If it doesn't exist it es created.
	// The channel is closed by the Ding.X Gateway when stopped.
	Errors() <-chan error
}

A Ding.X Gateway represents the physical system where an EV can be charged. You can instantiate a default Ding.X Gateway struct by calling NewClient.

The logic for incoming messages needs to be implemented, and the message handlers need to be registered with the Ding.X Gateway:

handler := &DingxGatewayHandler{}
client.SetCoreHandler(handler)

Refer to the DingxGatewayHandler interfaces in the respective core, firmware, localauth, remotetrigger, reservation and smartcharging profiles for the implementation requirements.

A Ding.X Gateway can be started and stopped using the Start and Stop functions. While running, messages can be sent to the Central system by calling the Charge point's functions, e.g.

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

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

func NewDingXGateway

func NewDingXGateway(id string, endpoint *ntxcpj.Client, client ws.WsClient) DingXGateway

Creates a new ntxcp 1.0 Ding.X Gateway client. The id parameter is required to uniquely identify the Ding.X Gateway.

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

client := NewClient("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 := os.ReadFile("serverSelfSignedCertFilename")
if err != nil {
	log.Fatal(err)
}
ok = certPool.AppendCertsFromPEM(data)
if !ok {
	log.Fatal("couldn't parse PEM certificate")
}
cp := NewClient("someUniqueId", nil, ws.NewTLSClient(&tls.Config{
	RootCAs: certPool,
})

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

type DingXGatewayConnection

type DingXGatewayConnection interface {
	ID() string
	RemoteAddr() net.Addr
	TLSConnectionState() *tls.ConnectionState
}

type DingXGatewayConnectionHandler

type DingXGatewayConnectionHandler func(dingxGateway DingXGatewayConnection)