MQTT-V3.1协议规范(中文版)

作者：InternationalBusinessMachinesCorporation(IBM)Eurotech翻译：明歌协议原文：摘要MQ遥测传输（MQTelemetryTransport，MQTT）是一个轻量级的基于代理的发布/订阅式消息传输协议，它的设计目标是开放、简单、轻量和易于实现。这些特征使它适用于各种受限环境，比如，但不限于：网络代价昂贵，低带宽或不可靠。在嵌入设备中运行，处理器和内存资源有限。该协议的特性包括：使用发布/订阅消息模式，提供一对多的消息分发，解除应用程序耦合。消息传输对有效载荷内容不可知。使用TCP/IP提供基础网络连接。有3个消息发布服务质量级别：“至多一次”，消息发布完全依赖于底层TCP/IP网络。消息有可能丢失或重复。这一级别可应用于如下情景，如环境传感器数据，丢失一次读记录无所谓，因为很快下一次读记录就会产生。“至少一次”，确保消息到达，但消息重复有可能发生。“只有一次”，确保消息到达且只到达一次。这一级别可用于如计费系统等场景，在计费系统中，消息丢失或重复可能会导致生成错误的费用。轻量传输，开销很小（固定头部的长度只有2字节），协议交换最小化，以降低网络流量。提供一种机制，当客户端异常中断时，利用LastWill和Testament特性来通知有关各方。版权声明©1999-2010Eurotech,InternationalBusinessMachinesCorporation(IBM).Allrightsreserved.PermissiontocopyanddisplaytheMQTelemetryTransportspecification(theSpecification),inanymediumwithoutfeeorroyaltyisherebygrantedbyEurotechandInternationalBusinessMachinesCorporation(IBM)(collectively,theAuthors),providedthatyouincludethefollowingonALLcopiesoftheSpecification,orportionsthereof,thatyoumake:AlinkorURLtotheSpecificationatoneoftheAuthors'websites.ThecopyrightnoticeasshownintheSpecification.TheAuthorseachagreetograntyouaroyalty-freelicense,underreasonable,non-discriminatorytermsandconditionstotheirrespectivepatentsthattheydeemnecessarytoimplementtheSpecification.THESPECIFICATIONISPROVIDEDASIS,ANDTHEAUTHORSMAKENOREPRESENTATIONSORWARRANTIES,EXPRESSORIMPLIED,INCLUDING,BUTNOTLIMITEDTO,WARRANTIESOFMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSE,NON-INFRINGEMENT,ORTITLE;THATTHECONTENTSOFTHESPECIFICATIONARESUITABLEFORANYPURPOSE;NORTHATTHEIMPLEMENTATIONOFSUCHCONTENTSWILLNOTINFRINGEANYTHIRDPARTYPATENTS,COPYRIGHTS,TRADEMARKSOROTHERRIGHTS.THEAUTHORSWILLNOTBELIABLEFORANYDIRECT,INDIRECT,SPECIAL,INCIDENTALORCONSEQUENTIALDAMAGESARISINGOUTOFORRELATINGTOANYUSEORDISTRIBUTIONOFTHESPECIFICATION.ThenameandtrademarksoftheAuthorsmayNOTbeusedinanymanner,includingadvertisingorpublicitypertainingtotheSpecificationoritscontentswithoutspecific,writtenpriorpermission.TitletocopyrightintheSpecificationwillatalltimesremainwiththeAuthors.Nootherrightsaregrantedbyimplication,estoppelorotherwise.目录1.简介1.1V3.1与V3之间的变化2.消息格式2.1固定头部2.2可变头部2.3有效载荷2.4消息标识符2.5MQTT和UTF-82.6未使用的位3.命令消息3.1CONNECT3.2CONNACK3.3PUBLISH3.4PUBACK3.5PUBREC3.6PUBREL3.7PUBCOMP3.8SUBSCRIBE3.9SUBACK3.10UNSUBSCRIBE3.11UNSUBACK3.12PINGREQ3.13PINGRESP3.14DISCONNECT4.消息流4.1交付质量级别和消息流4.2消息重传4.3消息排序5.附录A主题通配符1.简介该协议规范主要分为3个主要部分：对所有类型的数据包都通用的消息格式每种特定数据包的具体细节数据包如何在服务器和客户端之间传输在附录中将介绍如何主题通配符（topicwildcards）的使用方法。1.1V3.1与V3之间的变化MQTTV3.1中与MQTTV3之间的不同点如下所示：添加用户验证，用户名和密码现在可以在CONNECT数据包中一并发送。为解决一些安全问题，在CONNACK数据包中添加了新的返回码。当客户端发送未授权的PUBLISH或SUBSCRIBE命令时，客户端不会收到相应的通知，即客户端不知道命令不会被执行。而且即使命令未被执行，该MQTT流也应该正常完成。MQTT中的字符串现在支持完整的UTF-8字符集，而不仅仅是US-ASCII子集。V3.1中，通过CONNECT包传送的协议版本号仍然是“3”，与V3相比没有变化。现存的基于MQTTV3的服务器实现须通过正确考虑“剩余长度（RemainingLength）字段”，以及相应地忽略多余的安全信息来接受来自V3.1协议的客户端的连接。2.消息格式每个MQTT命令消息的消息头部都包含了一个固定头部。其中一些类型的消息可能还需要一个可变头部和一个有效载荷（可理解为消息体）。消息头部的具体格式将在后面章节中进行详细介绍。2.1固定头部（Fixedheader）每个MQTT命令消息的消息头部都包含一个固定头部。固定头部的格式如下表如示。Byte1包含消息类型和标志（包括DUP，QoSlevel和RETAIN）字段。Byte2包含剩余长度字段（至少1个字节，最多4个字节）。以下章节将详细介绍这些字段。所有数据的值都是以big-endian（大端）模式存储：数据的高位字节存放在内存的低地址中，数据的低位字节存放在内存高地址中。一个16位字在内存中的存放顺序是先最高有效位（MSB），然后再最低有效位（LSB）。消息类型（MessageType）位置：byte1,bits7-4该字段为4-bit无符号值。当前协议版本中该字段的具体枚举值如下表所示。0：保留1：客户端请求连接服务器2：连接确认3：发布消息4：发布确认5：发布接收（有保证的交付第1部分）6：发布释放（有保证的交付第2部分）7：发布完成（有保证的交付第3部分）8：客户端订阅请求9：订阅确认10：客户端取消订阅请求11：取消订阅确认12：PING请求13：PING回复14：客户端断开连接15：保留标志位（Flags）固定头部第1个字节中剩余的部分包含DUP，QoS和RETAIN标志字段。相应bit位置如下表所示。DUP位置：byte1，bit3当客户端或服务器试图重发PUBLISH、PUBREL、SUBSRIBE、UNSUBSCRIBE消息时，该标志位要被置位（即设为1）。这适用于消息的QoS标志值大于0的情况，此时消息确认是必需的。当DUP位被置位时，可变头部将包含一个消息ID。消息的接收者应当将该标志视为该消息之前可能已收到的提示消息，而不该依赖于它进行消息重复检测。QoS位置：byte1，bits2-1该标志位标明PUBLISH消息的交付质量级别。具体的QoS级别如下表所示。RETAIN位置：byte1，bit0该标志位只用于PUBLISH消息。当一个客户端发送一条PUBLISH消息给服务器，假设该消息所属的主题（topic）为topicA，如果该标志位被置位（1），服务器在将该条消息发布给当前的所有topicA的订阅者之后，还应当保持这条消息。当topicA出现了一个新的订阅者，则topicA的最后一条保持消息应当发给该订阅者。当然，如果不存在保持消息，则什么也不用发。当消息发布者以基于“reportbyexception”的方式发送消息时，这个功能就特别有用，因为这种情况下，消息发送间隔往往较长。这个功能使得新的订阅者可以立刻收到之前保持的或上一个确定有效的消息。当服务器收到某个主题的PUBLISH消息时，对于之前已经订阅该主题的客户端，服务器将给这些客户端发送这一PUBLISH消息，发送前，服务器会将该消息的RETAIN标志置为0（即不置位），不管服务器之前收到该PUBLISH消息时其RETAIN标志是否被置位。这样做可以使得区分它接收到的PUBLISH消息是服务器之前保持的（RETAIN标志置位）还是即时收到的（RETAIN标志不置位）。保持消息应当在重启服务器后仍能保留。如果服务器收到有效载荷长度为0或重复主题的保持消息，服务器可以删除该保持消息。剩余长度（RemainingLength）位置：byte2（从byte2，最大可至byte5）该字段表示当前消息的剩余内容的字节数，包括可变头部和有效载荷的数据。该字段本身的字节数是根据可变头部和有效载荷的长度不同而变化的。该可变长度编码方案如下：每个字节的低7位（7-0位）编码剩余长度的数据，第8位表示后面是否还有编码剩余长度的字节。即每个字节编码128个值和一个“延续位”。所以只用一个字节时，最大只可表示127字节的长度。举例如下，十进制数字64只需用1个字节来编码，即0x40。十进制数字321（=65+2x128）则需要用2个字节来编码，其中第1个字节为11000001，该字节的低7位表示65，第8位表示后面还有字节；第2个字节为00000010，表示2x128。协议限制该字段最大为4个字节，这允许应用程序发送的最大消息长度为268435455（256MB），即0xFF，0xFF，0xFF，0x7F。下表给出了增加该字段的字节数时相应可表示的剩余长度值。该编码方案的算法如下所示，输入为一个十进制数（X），输出为编码后的结果。dodigit=XMOD128X=XDIV128//iftherearemoredigitstoencode,setthetopbitofthisdigitif(X0)digit=digitOR0x80endif'output'digitwhile(X0)其中，MOD是模运算符（在C语言中相当于%），DIV表示整数除法（在C语言中相当于/），OR是位或运算符（在C语言中相当于|）。相应地，剩余长度字段的解码算法如下所示：multiplier=1value