MQTT协议中文版(2017.04.05).pdf
- 文档编号:14656846
- 上传时间:2023-06-25
- 格式:PDF
- 页数:96
- 大小:1,006.62KB
MQTT协议中文版(2017.04.05).pdf
《MQTT协议中文版(2017.04.05).pdf》由会员分享,可在线阅读,更多相关《MQTT协议中文版(2017.04.05).pdf(96页珍藏版)》请在冰点文库上搜索。
1.11.21.31.41.4.11.4.21.4.31.4.41.4.51.4.61.4.71.4.81.4.91.4.101.4.111.4.121.4.131.4.141.51.61.71.81.9目錄Introduction第一章-MQTT介绍第二章MQTT控制报文格式第三章MQTT控制报文3.1CONNECT连接服务端3.2CONNACK确认连接请求3.3PUBLISH发布消息3.4PUBACK发布确认3.5PUBREC发布收到(QoS2,第一步)3.6PUBREL发布释放(QoS2,第二步)3.7PUBCOMP发布完成(QoS2,第三步)3.8SUBSCRIBE-订阅主题3.9SUBACK订阅确认3.10UNSUBSCRIBE取消订阅3.11UNSUBACK取消订阅确认3.12PINGREQ心跳请求3.13PINGRESP心跳响应3.14DISCONNECT断开连接第四章操作行为第五章安全第六章使用WebSocket第七章一致性目标附录B-强制性规范声明1MQTT协议中文版bymcxiaoke最新版本:
v1.0.42017.04.05(感谢hentaicreep修复多处表格错位问题PRs)文档地址MQTT协议中文版PDF和ePub下载中文翻译项目概述MQTT是一个客户端服务端架构的发布/订阅模式的消息传输协议。
它的设计思想是轻巧、开放、简单、规范,易于实现。
这些特点使得它对很多场景来说都是很好的选择,特别是对于受限的环境如机器与机器的通信(M2M)以及物联网环境(IoT)。
说明MQTT英文原版协议提供了Word格式和HTML格式,我翻译的时候用的Word文档,之前一直提供的是Word文档转换的HTML和PDF供浏览和下载,最近花时间整理了Markdown版本,可以更方便的分章节在线浏览了,转换为Markdown后部分表格的格式不太对,会逐步用图片代替。
目录发现任何翻译问题或格式问题欢迎提PR帮忙完善。
说明前言目录第一章-MQTT介绍第二章MQTT控制报文格式第三章MQTT控制报文3.1CONNECT连接服务端Introduction23.2CONNACK确认连接请求3.3PUBLISH发布消息3.4PUBACK发布确认3.5PUBREC发布收到(QoS2,第一步)3.6PUBREL发布释放(QoS2,第二步)3.7PUBCOMP发布完成(QoS2,第三步)3.8SUBSCRIBE-订阅主题3.9SUBACK订阅确认3.10UNSUBSCRIBE取消订阅3.11UNSUBACK取消订阅确认3.12PINGREQ心跳请求3.13PINGRESP心跳响应3.14DISCONNECT断开连接第四章操作行为第五章安全第六章使用WebSocket第七章一致性目标附录B-强制性规范声明旧版文档已过期,建议使用GitBook版本最新版本:
v1.0.12015.10.22文档连接中文版HTMLMQTT3.1.1中文版中文版PDFMQTT3.1.1中文版英文版HTMLMQTTVersion3.1.1英文版PDFMQTTVersion3.1.1许可协议署名-非商业性使用-相同方式共享4.0国际联系方式Introduction3Blog:
http:
/Github:
https:
/是一个拉丁字母A后面跟着一个代码点U+2A6D4(它表示一个中日韩统一表意文字扩展B中的字符),这个字符串编码如下:
图例1.2UTF-8编码字符串非规范示例UTF-8encodedstringnonnormativeexample第一章-MQTT介绍7Bit76543210byte1字符串长度MSB(0x00)00000000byte2字符串长度LSB(0x05)00000101byte3A(0x41)01000001byte4(0xF0)11110000byte5(0xAA)10101010byte6(0x9B)10011011byte7(0x94)100101001.6编辑约定Editingconventions本规范用黄色高亮的文本标识一致性声明,每个一致性声明都分配了一个这种格式的引用:
MQTT-x.x.x-y。
项目主页MQTT协议中文版第一章-MQTT介绍8第二章MQTT控制报文格式MQTTControlPacketformat目录第一章-介绍第二章MQTT控制报文格式第三章MQTT控制报文第四章操作行为第五章安全第六章使用WebSocket第七章一致性目标附录B-强制性规范声明2.1MQTT控制报文的结构StructureofanMQTTControlPacketMQTT协议通过交换预定义的MQTT控制报文来通信。
这一节描述这些报文的格式。
MQTT控制报文由三部分组成,按照图例2.1MQTT控制报文的结构描述的顺序:
图例2.1MQTT控制报文的结构Fixedheader固定报头,所有控制报文都包含Variableheader可变报头,部分控制报文包含Payload有效载荷,部分控制报文包含2.2固定报头Fixedheader每个MQTT控制报文都包含一个固定报头。
图例2.2-固定报头的格式描述了固定报头的格式。
图例2.2-固定报头的格式第二章MQTT控制报文格式9Bit76543210byte1MQTT控制报文的类型用于指定控制报文类型的标志位byte2.剩余长度2.2.1MQTT控制报文的类型MQTTControlPackettype位置:
第1个字节,二进制位7-4。
表示为4位无符号值,这些值的定义见表格2.1-控制报文的类型表格2.1-控制报文的类型名字值报文流动方向描述Reserved0禁止保留CONNECT1客户端到服务端客户端请求连接服务端CONNACK2服务端到客户端连接报文确认PUBLISH3两个方向都允许发布消息PUBACK4两个方向都允许QoS1消息发布收到确认PUBREC5两个方向都允许发布收到(保证交付第一步)PUBREL6两个方向都允许发布释放(保证交付第二步)PUBCOMP7两个方向都允许QoS2消息发布完成(保证交互第三步)SUBSCRIBE8客户端到服务端客户端订阅请求SUBACK9服务端到客户端订阅请求报文确认UNSUBSCRIBE10客户端到服务端客户端取消订阅请求UNSUBACK11服务端到客户端取消订阅报文确认PINGREQ12客户端到服务端心跳请求PINGRESP13服务端到客户端心跳响应DISCONNECT14客户端到服务端客户端断开连接Reserved15禁止保留2.2.2标志Flags固定报头第1个字节的剩余的4位3-0包含每个MQTT控制报文类型特定的标志,见表格2.2-标志位。
表格2.2中任何标记为“保留”的标志位,都是保留给以后使用的,必须设置为表格中列出的值MQTT-2.2.2-1。
如果收到非法的标志,接收者必须关闭网络连接。
有关错误处理的详细信息见4.8节MQTT-2.2.2-2。
第二章MQTT控制报文格式10表格2.2-标志位FlagBits控制报文固定报头标志Bit3Bit2Bit1Bit0CONNECTReserved0000CONNACKReserved0000PUBLISHUsedinMQTT3.1.1DUPQoSQoSRETAINPUBACKReserved0000PUBRECReserved0000PUBRELReserved0010PUBCOMPReserved0000SUBSCRIBEReserved0010SUBACKReserved0000UNSUBSCRIBEReserved0010UNSUBACKReserved0000PINGREQReserved0000PINGRESPReserved0000DISCONNECTReserved0000DUP=控制报文的重复分发标志QoS=PUBLISH报文的服务质量等级RETAIN=PUBLISH报文的保留标志PUBLISH控制报文中的DUP,QoS和RETAIN标志的描述见3.3.1节。
2.2.3剩余长度RemainingLength位置:
从第2个字节开始。
剩余长度(RemainingLength)表示当前报文剩余部分的字节数,包括可变报头和负载的数据。
剩余长度不包括用于编码剩余长度字段本身的字节数。
剩余长度字段使用一个变长度编码方案,对小于128的值它使用单字节编码。
更大的值按下面的方式处理。
低7位有效位用于编码数据,最高有效位用于指示是否有更多的字节。
因此每个字节可以编码128个数值和一个延续位(continuationbit)。
剩余长度字段最大4个字节。
1223123第二章MQTT控制报文格式11非规范评注例如,十进制数64会被编码为一个字节,数值是64,十六进制表示为0x40,。
十进制数字321(=65+2*128)被编码为两个字节,最低有效位在前。
第一个字节是65+128=193。
注意最高位为1表示后面至少还有一个字节。
第二个字节是2。
非规范评注这允许应用发送最大256MB(268,435,455)大小的控制报文。
这个数值在报文中的表示是:
0xFF,0xFF,0xFF,0x7F。
表格2.4剩余长度字段的大小展示了剩余长度字段所表示的值随字节增长。
表格2.4剩余长度字段的大小SizeofRemainingLengthfield字节数最小值最大值10(0x00)127(0x7F)2128(0x80,0x01)16383(0xFF,0x7F)316384(0x80,0x80,0x01)2097151(0xFF,0xFF,0x7F)42097152(0x80,0x80,0x80,0x01)268435455(0xFF,0xFF,0xFF,0x7F)分别表示(每个字节的低7位用于编码数据,最高位是标志位):
1个字节时,从0(0x00)到127(0x7f)2个字节时,从128(0x80,0x01)到16383(0Xff,0x7f)3个字节时,从16384(0x80,0x80,0x01)到2097151(0xFF,0xFF,0x7F)4个字节时,从2097152(0x80,0x80,0x80,0x01)到268435455(0xFF,0xFF,0xFF,0x7F)第二章MQTT控制报文格式12非规范评注非负整数X使用变长编码方案的算法如下:
doencodedByte=XMOD128X=XDIV128/iftherearemoredatatoencode,setthetopbitofthisbyteif(X0)encodedByte=encodedByteOR128endifoutputencodedBytewhile(X0)MOD是模运算,DIV是整数除法,OR是位操作或(C语言中分别是%,/,|)非规范评注剩余长度字段的解码算法如下:
multiplier=1value=0doencodedByte=nextbytefromstreamvalue+=(encodedByteAND127)*multipliermultiplier*=128if(multiplier128*128*128)throwError(MalformedRemainingLength)while(encodedByteAND128)!
=0)AND是位操作与(C语言中的&)这个算法终止时,value包含的就是剩余长度的值。
2.3可变报头Variableheader某些MQTT控制报文包含一个可变报头部分。
它在固定报头和负载之间。
可变报头的内容根据报文类型的不同而不同。
可变报头的报文标识符(PacketIdentifier)字段存在于在多个类型的报文里。
2.3.1报文标识符PacketIdentifier图例2.3-报文标识符字节PacketIdentifierbytes第二章MQTT控制报文格式13Bit7-0byte1报文标识符MSBbyte2报文标识符LSB很多控制报文的可变报头部分包含一个两字节的报文标识符字段。
这些报文是PUBLISH(QoS0时),PUBACK,PUBREC,PUBREL,PUBCOMP,SUBSCRIBE,SUBACK,UNSUBSCIBE,UNSUBACK。
SUBSCRIBE,UNSUBSCRIBE和PUBLISH(QoS大于0)控制报文必须包含一个非零的16位报文标识符(PacketIdentifier)MQTT-2.3.1-1。
客户端每次发送一个新的这些类型的报文时都必须分配一个当前未使用的报文标识符MQTT-2.3.1-2。
如果一个客户端要重发这个特殊的控制报文,在随后重发那个报文时,它必须使用相同的标识符。
当客户端处理完这个报文对应的确认后,这个报文标识符就释放可重用。
QoS1的PUBLISH对应的是PUBACK,QoS2的PUBLISH对应的是PUBCOMP,与SUBSCRIBE或UNSUBSCRIBE对应的分别是SUBACK或UNSUBACKMQTT-2.3.1-3。
发送一个QoS0的PUBLISH报文时,相同的条件也适用于服务端MQTT-2.3.1-4。
QoS等于0的PUBLISH报文不能包含报文标识符MQTT-2.3.1-5。
PUBACK,PUBREC,PUBREL报文必须包含与最初发送的PUBLISH报文相同的报文标识符MQTT-2.3.1-6。
类似地,SUBACK和UNSUBACK必须包含在对应的SUBSCRIBE和UNSUBSCRIBE报文中使用的报文标识符MQTT-2.3.1-7。
需要报文标识符的控制报文在表格2.5-包含报文标识符的控制报文中列出。
表格2.5-包含报文标识符的控制报文ControlPacketsthatcontainaPacketIdentifier第二章MQTT控制报文格式14控制报文报文标识符字段CONNECT不需要CONNACK不需要PUBLISH需要(如果QoS0)PUBACK需要PUBREC需要PUBREL需要PUBCOMP需要SUBSCRIBE需要SUBACK需要UNSUBSCRIBE需要UNSUBACK需要PINGREQ不需要PINGRESP不需要DISCONNECT不需要客户端和服务端彼此独立地分配报文标识符。
因此,客户端服务端组合使用相同的报文标识符可以实现并发的消息交换。
非规范评注客户端发送标识符为0x1234的PUBLISH报文,它有可能会在收到那个报文的PUBACK之前,先收到服务端发送的另一个不同的但是报文标识符也为0x1234的PUBLISH报文。
ClientServerPUBLISHPacketIdentifier=0x1234-PUBLISHPacketIdentifier=0x1234PUBACKPacketIdentifier=0x1234-PUBACKPacketIdentifier=0x12342.4有效载荷Payload某些MQTT控制报文在报文的最后部分包含一个有效载荷,这将在第三章论述。
对于PUBLISH来说有效载荷就是应用消息。
表格2.6包含有效载荷的控制报文列出了需要有效载荷的控制报文。
第二章MQTT控制报文格式15表格2.6包含有效载荷的控制报文ControlPacketsthatcontainaPayload控制报文有效载荷CONNECT需要CONNACK不需要PUBLISH可选PUBACK不需要PUBREC不需要PUBREL不需要PUBCOMP不需要SUBSCRIBE需要SUBACK需要UNSUBSCRIBE需要UNSUBACK不需要PINGREQ不需要PINGRESP不需要DISCONNECT不需要项目主页MQTT协议中文版第二章MQTT控制报文格式16第三章MQTT控制报文MQTTControlPackets目录第一章-介绍第二章MQTT控制报文格式第三章MQTT控制报文第四章操作行为第五章安全第六章使用WebSocket第七章一致性目标附录B-强制性规范声明本章目录3.1CONNECT连接服务端3.2CONNACK确认连接请求3.3PUBLISH发布消息3.4PUBACK发布确认3.5PUBREC发布收到(QoS2,第一步)3.6PUBREL发布释放(QoS2,第二步)3.7PUBCOMP发布完成(QoS2,第三步)3.8SUBSCRIBE-订阅主题3.9SUBACK订阅确认3.10UNSUBSCRIBE取消订阅3.11UNSUBACK取消订阅确认3.12PINGREQ心跳请求3.13PINGRESP心跳响应3.14DISCONNECT断开连接项目主页MQTT协议中文版第三章MQTT控制报文17第三章MQTT控制报文183.1CONNECT连接服务端客户端到服务端的网络连接建立后,客户端发送给服务端的第一个报文必须是CONNECT报文MQTT-3.1.0-1。
在一个网络连接上,客户端只能发送一次CONNECT报文。
服务端必须将客户端发送的第二个CONNECT报文当作协议违规处理并断开客户端的连接MQTT-3.1.0-2。
有关错误处理的信息请查看4.8节。
有效载荷包含一个或多个编码的字段。
包括客户端的唯一标识符,Will主题,Will消息,用户名和密码。
除了客户端标识之外,其它的字段都是可选的,基于标志位来决定可变报头中是否需要包含这些字段。
3.1.1固定报头Fixedheader图例3.1CONNECT报文的固定报头Bit76543210byte1MQTT报文类型
(1)Reserved保留位00010000byte2.剩余长度剩余长度字段剩余长度等于可变报头的长度(10字节)加上有效载荷的长度。
编码方式见2.2.3节的说明。
3.1.2可变报头VariableheaderCONNECT报文的可变报头按下列次序包含四个字段:
协议名(ProtocolName),协议级别(ProtocolLevel),连接标志(ConnectFlags)和保持连接(KeepAlive)。
协议名ProtocolName图例3.2-协议名字节构成3.1CONNECT连接服务端19说明76543210协议名byte1长度MSB(0)00000000byte2长度LSB(4)00000100byte3M01001101byte4Q01010001byte5T01010100byte6T01010100协议名是表示协议名MQTT的UTF-8编码的字符串。
MQTT规范的后续版本不会改变这个字符串的偏移和长度。
如果协议名不正确服务端可以断开客户端的连接,也可以按照某些其它规范继续处理CONNECT报文。
对于后一种情况,按照本规范,服务端不能继续处理CONNECT报文MQTT-3.1.2-1。
非规范评注数据包检测工具,例如防火墙,可以使用协议名来识别MQTT流量。
协议级别ProtocolLevel图例3.3-ProtocolLevelbyte协议级别字节构成说明76543210协议级别byte7Level(4)00000100客户端用8位的无符号值表示协议的修订版本。
对于3.1.1版协议,协议级别字段的值是4(0x04)。
如果发现不支持的协议级别,服务端必须给发送一个返回码为0x01(不支持的协议级别)的CONNACK报文响应CONNECT报文,然后断开客户端的连接MQTT-3.1.2-2。
连接标志ConnectFlags连接标志字节包含一些用于指定MQTT连接行为的参数。
它还指出有效载荷中的字段是否存在。
图例3.4-连接标志位3.1CONNECT连接服务端20服务端必须验证CONNECT控制报文的保留标志位(第0位)是否为0,如果不为0必须断开客户端连接MQTT-3.1.2-3。
清理会话CleanSession位置:
连接标志字节的第1位这个二进制位指定了会话状态的处理方式。
客户端和服务端可以保存会话状态,以支持跨网络连接的可靠消息传输。
这个标志位用于控制会话状态的生存时间。
如果清理会话(CleanSession)标志被设置为0,服务端必须基于当前会话(使用客户端标识符识别)的状态恢复与客户端的通信。
如果没有与这个客户端标识符关联的会话,服务端必须创建一个新的会话。
在连接断开之后,当连接断开后,客户端和服务端必须保存会话信息MQTT-3.1.2-4。
当清理会话标志为0的会话连接断开之后,服务端必须将之后的QoS1和QoS2级别的消息保存为会话状态的一部分,如果这些消息匹配断开连接时客户端的任何订阅MQTT-3.1.2-5。
服务端也可以保存满足相同条件的QoS0级别的消息。
如果清理会话(CleanSession)标志被设置为1,客户端和服务端必须丢弃之前的任何会话并开始一个新的会话。
会话仅持续和网络连接同样长的时间。
与这个会话关联的状态数据不能被任何之后的会话重用MQTT-3.1.2-6。
客户端的会话状态包括:
已经发送给服务端,但是还没有完成确认的QoS1和QoS2级别的消息已从服务端接收,但是还没有完成确认的QoS2级别的消息。
服务端的会话状态包括:
会话是否存在,即使会话状态的其它部分都是空。
客户端的订阅信息。
已经发送给客户端,但是还没有完成确认的QoS1和QoS2级别的消息。
即将传输给客户端的QoS1和QoS2级别的消息。
已从客户端接收,但是还没有完成确认的QoS2级别的消息。
可选,准备发送给客户端的QoS0级别的消息。
保留消息不是服务端会话状态的一部分,会话终止时不能删除保留消息MQTT-3.1.2.7。
有关状态存储的限制和细节见第4.1节。
3.1CONNECT连接服务端21当清理会话标志被设置为1时,客户端和服务端的状态删除不需要是原子操作。
非规范评注为了确保在发生故障时状态的一致性,客户端应该使用会话状态标志1重复请求连接,直到连接成功。
非规范评注一般来说,客户端连接时总是将清理会话标志设置为0或1,并且不交替使用两种值。
这个选择取决于具体的应用。
清理会话标志设置为1的客户端不会收到旧的应用消息,而且在每次连接成功后都需要重新订阅任何相关的主题。
清理会话标志设置为0的客户端会收到所有在它连接断开期间发布的QoS1和QoS2级别的消息。
因此,要确保不丢失连接断开期间的消息,需要使用QoS1或QoS2级别,同时将清理会话标志设置为0。
非规范评注清理会话标志0的客户端连接时,它请求服务端在连接断开后保留它的MQTT会话状态。
如果打算在之后的某个时间点重连到这个服务端,客户端连接应该只使用清理会话标志0。
当客户端决定之后不再使用这个会话时,应该将清理会话标志设置为1最后再连接一次,然后断开连接。
遗嘱标志WillFlag位置:
连接标志的第2位。
遗嘱标志(WillFlag)被设置为1,表示如果连接请求被接受了,遗嘱(WillMessage)消息必须被存储在服务端并且与这个网络连接关联。
之后网络连接关闭时,服务端必须发布这个遗嘱消息,除非服务端收到DISCONNECT报文时删除了这个遗嘱消息MQTT-3.1.2-8。
遗嘱消息发布的条件,包括但不限于:
服务端检测到了一个I/O错误或者网络故障。
客户端在保持连接(KeepAlive)的时间内未能通讯。
客户端没有先发送DISCONNECT报文直接关闭了网络连接。
由于协议错误服务端关闭了网络连接。
如果遗嘱标志被设置为1,连接标志中的WillQoS和WillRetain字段会被服务端用到,同时有效载荷中必须包含WillTopic和WillMessage字段MQTT-3.1.2-9。
一旦被发布或者服务端收到了客户端发送的DISCONNECT报文,遗嘱消息就必须从存储的会话状态中移除MQTT-3.1.2-10。
如果遗嘱标志被设置为0,连接标志中的WillQoS和WillRetain字段必须设置为0,并且有效载荷中不能包含WillTopic和WillMessage字段MQTT-3.1.2-11。
如果遗嘱标志被设置为0,网络连接断开时,不能发送遗嘱消息MQTT-3.1.2-12。
3.1CONNECT连接服务端22服务端应该迅速发布遗嘱消息。
在关机或故障的情况下,服务端可以推迟遗嘱消息的发布直到之后的重启。
如果发生了这种情况,在服务器故障和遗嘱消息被发布之间可能会有一个延迟。
遗嘱QoSWillQoS位置:
连接标志的第4
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- MQTT 协议 中文版 2017.04 05