OCPP16JSONSpecification 中文Word格式.docx
《OCPP16JSONSpecification 中文Word格式.docx》由会员分享,可在线阅读,更多相关《OCPP16JSONSpecification 中文Word格式.docx(17页珍藏版)》请在冰豆网上搜索。
除非清楚另有规定,旧版本假定为S,如ocpp1.5是和ocpp1.5s一样的
RPS
远程过程调用
WAMP
服务器是一个开放的WebSocket协议来提供消息传递模式来处理异步数据。
1.6.文献
[JSON]
http:
//www.json.org/
[OCPP_IMP_S]
OCPPSOAPimplementationspecification
[RFC2119]
“KeywordsforuseinRFCstoIndicate
RequirementLevels”.S.Bradner.March1997.
//www.ietf.org/RFC/RFC2119.txt
[RFC2616]
“HypertextTransferProtocol — HTTP/1.1”.
//tools.ietf.org/html/RFC2616
[RFC2617]
“HTTPAuthentication:
BasicandDigestAccess
Authentication”.http:
//tools.ietf.org/html/RFC2617
[RFC3629]
“UTF-8,atransformationformatofISO10646”.
//tools.ietf.org/html/RFC3629
[RFC3986]
“UniformResourceIdentifier(URI):
Generic
Syntax”.http:
//tools.ietf.org/html/RFC3986
[RFC5246]
“TheTransportLayerSecurity(TLS)Protocol;
Version1.2”.http:
//tools.ietf.org/html/RFC5246
[RFC6455]
“TheWebSocketProtocol”.
//tools.ietf.org/html/RFC6455
[WAMP]
//wamp.ws/
[WIKIWS]
//en.wikipedia.org/wiki/WebSocket
[WS]
//www.websocket.org/
2.效益与问题
WebSocket协议在【RFC6455】里有定义。
早期的草案工作实现Web-Socket规范的存在,但OCPP-J实现使用在[RFC6455]描述的协议。
注意,WebSocketTCP之上的定义自己的消息结构。
在TCP级别,通过WebSocket发送的数据,被包裹在一个WebSocket帧头。
使用框架时,这是完全透明的。
然而对于一个嵌入式系统工作时,WebSocket图书馆不可用并且她/他必须依据[RFC6455]正确地框架信息。
3.连接
用OCPP-J连接一个充电点和一个中央系统,中央系统扮演一个WebSocket服务器,充电点扮演WebSocket客户端。
3.1.客户端请求
建立一个连接,充电点启动一个WebSocket连接如在[RFC6455]第4节“所描述的:
开场握手”。
OCPP-J在URL和WebSocket子协议施加额外的约束,在下面的4.1.1和4.1.2这两个部分会详细介绍。
3.1.1.连接URL
为了启动一个WebSocket连接,充电点需要一个URL([RFC3986])连接。
这个URL从此被称为“连接URL”。
这个连接URL是特定于充电点的。
充电点的连接URL包含充电点身份使中枢系统知道充电点属于哪一个WebSocket连接。
支持OCPP-J的中央系统必须至少提供一个OCPP-J端点URL,从该点电荷应该得到它的URL连接。
这OCPP-J端点URL可以是任何以“ws”或“wss”方案URL。
充电点如何获得OCPP-J端点URL不是本文档的范围。
为了得到连接URL,充电点通过添加到路径“/”,然后识别唯一地充电点串来修改OCPP-J端点URL(U+002f固相线)。
这种独特的标识字符串必须成编码如在[RFC3986]描述中一样有必要。
例1:
身份为”CP001”的一个点电荷连接到一个中央系统OCPP-J端点URL”ws:
//
ws:
例2:
身份为“RDAM123”的一个点电荷连接到一个中央系统OCPP-J端点URLwss:
wss:
3.1.2.OCPP版本
精确的OCPP版必须在SEC-WebSocket协议字段指定。
这应该是下列值之一:
表1:
OCPP版本
版本
Websocket子协议名称
1.2
OCPP1.2
1.5
OCPP1.5
1.6
OCPP1.6
2.0
OCPP2.0
对于OCPP1.2,1.5和2.0是官方WebSocket子协议名称的值。
他们本身注册在因特网编号管理局。
注意:
OCPP1.2和1.5在列表中。
由于WebSocket解决方案中的JSON是独立的实际消息内容,所以也可用于旧版本OCP。
请记住,在这些情况下,实现还应该保持对基于SOAP的解决方案的支持,以便互操作。
将OCPP版包含在OCPP-J端点URL字符串的一部分是很好的实践。
如果你运行一个Web服务,可以在同一个OCPP-J端点URL处理多个OCPP版本,这是没有必要的课程。
3.1.3.一个开放的HTTP请求的例子
以下是一个OCPP-J连接握手的开放HTTP请求的例子:
GET/webServices/ocpp/CP3211HTTP/1.1
Host:
:
33033
Upgrade:
websocket
Connection:
Upgrade
Sec-WebSocket-Key:
x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol:
ocpp1.6,ocpp1.5
Sec-WebSocket-Version:
13
黑体部分是在每一个WebSocket握手请求时会出现,其他部分都是具体的例子。
在这个例子中,中央系统的OCPP-J端点URL是"
//:
33033/webServices/ocpp"
。
充电点的唯一标识符”CP3211”,因此请求路径为"
webServices/ocpp/CP3211"
根据sec-WebSocket协议报头,充电点在这里显示,它可以使用OCPP1.6J和OCPP1.5J,更偏向于前者。
在这个例子中,另一头是HTTP和WebSocket协议的一部分,与那些实施OCPP-J除第三方WebSocket库之外无关。
这些标题的作用在[RFC2616]和[RFC6455]中有解释。
3.2.服务器响应
在接收充电点的要求,中央系统与响应完成握手如在[RFC6455]描述。
以下为OCPP-J-specific申请条件:
●如果中央系统不能识别URL路径中的点电荷标识符,它应该发送状态404的HTTP响应和中断WebSocket连接如在[RFC6455]所描述。
●如果中央系统不同意使用一个由客户提供的子协议,它必须与一个反应不一秒WebSocket协议头,然后立即关闭WebSocket连接完整的WebSocket握手。
所以如果中央系统接受上述例子的要求并且同意使用充电点OCPP1.6J,中央系统的响应将如下所示:
HTTP/1.1101SwitchingProtocols
Sec-WebSocket-Accept:
s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
OCPP1.6
黑体部分是在每一个WebSocket握手响应中找到,其他部分都是具体的例子。
Sec-WebSocket-Accept的作用在[RFC6455]中有解释。
SEC-WebSocket协议头指示服务器将在此连接使用OCPP1.6J。
3.3.更多信息
对于那些做自己实现WebSocket握手的,[WS]和[WIKIWS]给更多关于WebSocket协议的信息。
4.RPC框架
4.1.介绍
一个WebSocket是一个全双工连接,简单来说就是数据可以从管道中的进出,进出之间没有明确的关系。
根据请求和响应,WebSocket协议本身没有提供任何方法与消息。
对这些请求/响应关系,我们需要在顶部的WebSocket有个小协议。
这个问题发生在WebSocket更多的案例,所以有现有的方案去解决它。
使用最广泛的是WAMP(见[WAMP])。
但随着现有的版本框架处理RPC不是WAMP兼容当前版本。
由于所需的框架很简单我们决定定义自己的框架,受到WAMP的启发,删除了我们不需要的并加上了我们发现所丢失的。
基本上,我们需要的是非常简单的:
我们需要发送一个消息(电话)和收到回复(callresult)或解释为什么信息不能妥善处理(callerror)。
对于未来可能的兼容性我们将对这些消息进行编号同步服务器。
我们实际的OCPP消息将被放入一个至少包含消息的类型的包装,一个独特的消息ID和有效载荷,该OCPP消息本身。
4.1.1.Synchronicity同步性
一个充电点或中央系统不应该向另一方发送呼叫信息,除非它之前发送的所有呼叫消息已被回复或超时。
一个电话的消息已经回应了,当callerror或callresult消息已收到了调用消息的消息ID。
当出现以下情况是会出现消息回复超时:
●已经回复过
●自发送消息以来,依赖于实现的超时间隔已经过去了。
实现可以自由选择此超时间隔。
建议他们考虑某种与另一方通信的网络。
移动网络通常比固定线路有更长的最坏情况往返时间。
上述规定不排除当充电点或中心系统在等待一个callerror或callresult时,会接收对方呼叫的信息。
这种情况很难预防,因为双方的通话信息总是相互交叉的。
4.1.2.字符编码
所有的信息包括包装和有效载荷的必须是有效的JSON与UTF-8编码(见[RFC3629])的字符编码。
请注意,所有有效的US-ASCII文本也是有效的UTF-8,所以如果一个系统只发送US-ASCII文本,它发送的所有信息符合UTF-8的要求。
一个充电点或中央系统应该只使用字符不是US-ASCII发送自然语言文本。
这样的自然语言文本的一个例子是在OCPP2.0中localizedtext型文本。
4.1.3.消息类型
为了标识消息的类型,必须使用以下消息类型号之一。
表2:
消息类型
编号
方向
CALL
2
CLIENT-TO-SERVER
CALLRESULT
3
SERVER-TO-CLIENT
CALLERROR
4
当服务器收到一个消息,该列表中没有消息类型号时,它将忽略消息有效负载。
每个消息类型可能有额外的必填字段。
4.1.4.ThemessageID消息ID
消息ID用于标识请求。
一个CALL消息ID必须不同于所有以前通过同一个websocket连接发送CALL消息的消息ID,消息ID为callresult或callerror消息必须等于响应该CALL消息的callresult或callerror消息。
表3:
特殊消息ID
名称
数据类型
限制
消息ID
串
最大为36字允许GUIDS
4.2.用于不同消息类型的消息结构
在下面的段落中,您可能会发现充电点标识丢失。
WebSocket连接握手过程中,标识被交换,也是一种连接的属性。
每个消息都是由这个标识发送或指向的。
因此,没有必要在每条消息中重复。
4.2.1.CALL
CALL总是包含4个要素:
标准的元素message和uniqueID,另一方需要的具体ACTION,payload,Action的论据。
调用的语法如下所示:
[<
MessageTypeId>
"
<
UniqueId>
"
Action>
{<
Payload>
}]
表4:
CALL领域
领域
意义
Uniqueid
这是一个惟一的标识符,用于匹配请求和结果
Action
远程过程或操作的名称。
这将是一个区分大小写的字符串,它包含与SOAP消息中的动作字段相同的值,没有前面的斜杠。
Payload
Payload是一个JSON对象,包含与Action相关的参数。
如果没有Payload,JSON允许两种不同的符号:
null或空对象\{}。
虽然看起来很琐碎,但我们认为只使用空对象语句是好习惯。
null通常表示未定义的事物,这与
空的不同,而且\{}比较短。
例如,一个Bootnotification请求可能看起来像这样:
[2,
19223201"
BootNotification"
{"
chargePointVendor"
:
"
VendorX"
chargePointModel"
SingleSocketCharger"
}
]
4.2.2.CallResult
如果CALL能正确处理,其结果将是一个普通callresult。
被OCPP响应所覆盖的错误情况在此文中是不被考虑在内的。
他们是正规的结果这样会被视为正常的callresult,即使结果是不可取的。
一个callresult总是包含3个要素:
标准的元素messagetypeidUniqueId和Payload,包含在原来的呼叫响应的Action。
表5:
CALLRESULT领域
UniqueID
这必须是调用请求中完全相同的ID,以便接收方能够匹配请求和结果。
Payload是一个JSON对象,包含Action动作的结果。
虽然看起来微不足道,但我们考虑只使用空对象语句是很好的实践。
null通常表示未定义的事物,这与空的不同,并且也是\{}比较短。
例如,一个bootnotification响应可能看起来像这样:
[3,
status"
Accepted"
currentTime"
2013-02-01T20:
53:
32.486Z"
heartbeatInterval"
300}
4.2.3.CallError
我们在两种情况下只使用callerror:
在传输消息期间发生错误。
这可能是一个网络问题,一个可用的服务问题,等等。
接收到该调用,但该调用的内容不符合适当消息的要求。
这可能缺少强制性字段,现有的具有相同唯一标识符的调用是已经处理,唯一标识符太长,等等。
一个callerror总是包含5个要素:
标准的元素messagetypeid和UniqueID,一个错误代码字符串(errorcodestring),一个错误描述字符串(errordescriptionstring)和一个errordetails对象。
errorCode>
errorDescription>
errorDetails>
表6:
CALLERROR领域
UniqueId
ErrorCode
该字段必须包含以下字符串错误代码表
ErrorDescription
如果可能,应填写,否则为空字符串“”。
ErrorDetails
这个JSON对象以未定义的方式描述错误细节。
如果没有错误详细信息,则必须填写一个空对象{}。
表7:
ValidErrorCodes有效的错误代码
ERRORCODE错误代码
描述description
NotImplemented
未实现
RequestedActionisnotknownbyreceiver
请求的操作没有被接收
NotSupported
RequestedActionisrecognizedbutnotsupportedbythereceiver
被请求的操作被认可,但接收方不支持。
InternalError
Aninternalerroroccurredandthereceiverwas
notabletoprocesstherequestedAction
successfully
发生内部错误,接收方无法成功处理请求的Action。
ProtocolError
PayloadforActionisincomplete
Action的Payload是不完整的
SecurityError
DuringtheprocessingofAction,asecurityissue
occurredpreventingreceiverfromcompletingtheActionsuccessfully
在处理Action过程中,发生了一个安全问题,成功地阻止接收方完成Action。
FormationViolation
PayloadforActionissyntacticallyincorrectornotconformthePDUstructureforAction
Action的Payload在语法上是不正确的或不合格的PDU结构
PropertyConstraintViolation
Payloadissyntacticallycorrectbutatleastone
fieldcontainsaninvalidvalue
Payload在语法上是正确的,但至少在一个领域中包含无效值
OccurenceConstraintViolation
PayloadforActionissyntacticallycorrectbutat
leastoneofthefieldsviolatesoccurence
constraints
Payload在语法上是正确的,但是至少一个领域违反发生限制
TypeConstraintViolation
leastoneofthefieldsviolatesdatatype
constraints(e.g.“somestring”:
12)
Action的Payload在语法上是正确的,但是至少一个领域违反数据类型的限制(如“somestring”:
12)
GenericError
Anyothererrornotcoveredbythepreviousones
前一种未涵盖的任何其他错误
5.连接
5.1.压缩
由于JSON非常紧凑,作为WebSocket[RFC6455]规范的一部分,我们不建议以其他任何形式使用压缩而是允许,否则可能危及互操作性。
5.2.数据的完整性
对于数据完整性,我们依赖于底层TCP/IP传输层机制。
5.3.WebSocketPing与OCPP的Heartbeat
WebsSocket规范定义了Ping和Pong帧,Ping和Pong是用来检查远程端点仍能响应。
在实践中,这种机制还可以防止网络操作员在某一段不活动之后悄悄关闭底层网络连接。
这WebSocket功能可以用于大多数的OCPPHeartbeat信息的替代品,但不能代替其所有功能。
Heartbeat响应的一个重要方面是时间同步。
ping和Pong帧不能用于此,因此建议每天至少有一条原始Heartbeat,以确保在充电点上设置正确的时钟设置。
5.4.重新连接
当重新连接一个充电点时,不应该发送一个Bootnotification,除非Bootnotificat