nanoFramework.M2Mqtt 5.1.138

文档语言：英语 | 简体中文

.NET nanoFramework M2Mqtt

欢迎使用 .NET nanoFramework 的 MQTT 客户端库。当前版本支持 v3.1、v3.1.1 和 v5.0。

这是 MQTT 客户端库 M2Mqtt 的初期移植。原始项目有一个官方网站 在这里。

自那时以来，MQTT 客户端经历了一些变化，并已适应 .NET nanoFramework。

构建状态

组件	构建状态	NuGet 包
nanoFramework.M2Mqtt

项目描述

M2Mqtt 是一种物联网和机器对机器 (M2M) 通信的 MQTT 客户端。

MQTT（消息队列遥测传输），是一种轻量级消息协议，允许资源有限的嵌入式设备在受限网络上执行异步通信。

MQTT 协议基于发布/订阅模式，因此客户端可以订阅一个或多个主题，并接收其他客户端发布到这些主题的消息。

此库包含一个示例 MQTT 客户端，您可以使用它连接到任何 MQTT 代理。

这些二进制文件可以作为 NuGet 包 获取。

有关 MQTT 协议的所有信息，请访问 MQTT 官方 网站。为了正确使用 MQTT 协议，建议您了解 MQTT 协议的工作方式。服务质量（QoS）机制是需要理解的一个重要方面。

使用方法

使用方法在所有版本中都是相同的。在 v3.1.1 和 v5.0 之间存在一些特定性。版本 5.0 带来了更多控制性和额外的属性。为了方便，所有属性的注释中都带有 仅 v5.0。如果使用 v5.0 属性与 v3.1 或 v3.1.1 协议，它们将被忽略。

以下是一个创建 v3.1.1 服务器并将其连接的简单示例

MqttClient mqtt = new MqttClient("test.mosquitto.org", 8883, true, new X509Certificate(CertMosquitto), null, MqttSslProtocols.TLSv1_2);
var ret = mqtt.Connect("nanoTestDevice", true);
if (ret != MqttReasonCode.Success)
{
    Debug.WriteLine($"ERROR connecting: {ret}");
    mqtt.Disconnect();
    return;
}

对于 v5.0，您只需在连接之前指定版本即可

MqttClient mqtt = new MqttClient("test.mosquitto.org", 8883, true, new X509Certificate(CertMosquitto), null, MqttSslProtocols.TLSv1_2);
mqtt.ProtocolVersion = MqttProtocolVersion.Version_5;
var ret = mqtt.Connect("nanoTestDevice", true);
if (ret != MqttReasonCode.Success)
{
    Debug.WriteLine($"ERROR connecting: {ret}");
    mqtt.Disconnect();
    return;
}

注意：在以下示例中，需要特定的证书才能连接到 Mosquitto 服务器。您可以在 示例 中找到它。

v5.0 扩展认证流程

MQTT 5.0 支持特定的认证流程。在 Connect 之后，可以使用认证机制作为挑战请求。在这种情况下，您需要

• 确保已将 v5 设置为协议
• 将属性 IsAuthenticationFlow 设置为 true
• 注册到 Authentication 事件
• 通过发送另一个认证消息或任何与您情况相关的其他内容来相应地管理答案。

注意：此协议使用 AuthenticationMethod 和 AuthenticationData 作为此类特定机制的属性。

以下是规范给出的示例

非规范性示例显示 SCRAM 挑战

• 客户端到服务器：CONNECT Authentication Method="SCRAM-SHA-1" Authentication Data=client-first-data
• 服务器到客户端：AUTH rc=0x18 Authentication Method="SCRAM-SHA-1" Authentication Data=server-first-data
• 客户端到服务器 AUTH rc=0x18 Authentication Method="SCRAM-SHA-1" Authentication Data=client-final-data
• 服务器到客户端 CONNACK rc=0 Authentication Method="SCRAM-SHA-1" Authentication Data=server-final-data

非规范性示例显示 Kerberos 挑战

• 客户端到服务器 CONNECT Authentication Method="GS2-KRB5"
• 服务器到客户端 AUTH rc=0x18 Authentication Method="GS2-KRB5"
• 客户端到服务器 AUTH rc=0x18 Authentication Method="GS2-KRB5" Authentication Data=initial context token
• 服务器到客户端 AUTH rc=0x18 Authentication Method="GS2-KRB5" Authentication Data=reply context token
• 客户端到服务器 AUTH rc=0x18 Authentication Method="GS2-KRB5"
• 服务器到客户端 CONNACK rc=0 Authentication Method="GS2-KRB5" Authentication Data=outcome of authentication

在这些机制中，只有在收到成功代码的 Connack 之后，IsConnected 属性才会被设置一次。由于这些认证机制是特定且用户配置的，这个特定的 MqttClient 提供了使用此机制的能力。

订阅事件

MqttClient 提供了事件。您可以订阅它们。例如，您可以使用 v5.0 协议获取连接打开时的额外信息。以下示例显示启用 MQTT v5.0 协议连接到 Azure IoT Hub 所需的内容

// Create the client
MqttClient mqtt = new MqttClient(IoTHub, 8883, true, new X509Certificate(CertAzure), null, MqttSslProtocols.TLSv1_2);
// Setup the version
mqtt.ProtocolVersion = MqttProtocolVersion.Version_5;
// Register to events
mqtt.ConnectionOpened += MqttConnectionOpened;
// You can add additional properties
var at = DateTime.UtcNow;
var atString = (at.ToUnixTimeSeconds() * 1000).ToString();
var expiry = at.AddMinutes(40);
var expiryString = (expiry.ToUnixTimeSeconds() * 1000).ToString();
string toSign = $"{IoTHub}\n{DeviceID}\n\n{atString}\n{expiryString}\n";
var hmac = new HMACSHA256(Convert.FromBase64String(Sas));
var sas = hmac.ComputeHash(Encoding.UTF8.GetBytes(toSign));
mqtt.AuthenticationMethod = "SAS";
mqtt.AuthenticationData = sas;
mqtt.UserProperties.Add(new UserProperty("sas-at", atString));
mqtt.UserProperties.Add(new UserProperty("sas-expiry", expiryString));
mqtt.UserProperties.Add(new UserProperty("api-version", "2020-10-01-preview"));
mqtt.UserProperties.Add(new UserProperty("host", IoTHub));
var ret = mqtt.Connect(DeviceID, null, null, false, MqttQoSLevel.AtLeastOnce, false, null, null, true, 60);
// You will have more code here

private static void MqttConnectionOpened(object sender, ConnectionOpenedEventArgs e)
{
    Debug.WriteLine($"Connection open");
    Debug.WriteLine($"  ClientID: {((MqttClient)sender).ClientId}");
    Debug.WriteLine($"  Assigned client id: {e.Message.AssignedClientIdentifier}");
    if (e.Message.AuthenticationData != null) Debug.WriteLine($"  Auth data length: {e.Message.AuthenticationData.Length}");
    Debug.WriteLine($"  Auth method: {e.Message.AuthenticationMethod}");
    Debug.WriteLine($"  Dup flag: {e.Message.DupFlag}");
    Debug.WriteLine($"  Max packet size: {e.Message.MaximumPacketSize}");
    Debug.WriteLine($"  Max QoS: {e.Message.MaximumQoS}");
    Debug.WriteLine($"  Msg ID: {e.Message.MessageId}");
    Debug.WriteLine($"  Qos level: {e.Message.QosLevel}");
    Debug.WriteLine($"  Reason: {e.Message.Reason}");
    Debug.WriteLine($"  Receive max: {e.Message.ReceiveMaximum}");
    Debug.WriteLine($"  Rep info: {e.Message.ResponseInformation}");
    Debug.WriteLine($"  Retain: {e.Message.Retain}");
    Debug.WriteLine($"  Retain available: {e.Message.RetainAvailable}");
    Debug.WriteLine($"  Return code: {e.Message.ReturnCode}");
    Debug.WriteLine($"  Server keep alive: {e.Message.ServerKeepAlive}");
    Debug.WriteLine($"  Server ref: {e.Message.ServerReference}");
    Debug.WriteLine($"  Session exp inter: {e.Message.SessionExpiryInterval}");
    Debug.WriteLine($"  Session present: {e.Message.SessionPresent}");
    Debug.WriteLine($"  Shared subs available: {e.Message.SharedSubscriptionAvailable}");
    Debug.WriteLine($"  Shared identifier available: {e.Message.SubscriptionIdentifiersAvailable}");
    Debug.WriteLine($"  Topic alias max: {e.Message.TopicAliasMaximum}");
    Debug.WriteLine($"  Num user props: {e.Message.UserProperties.Count}");
    foreach (UserProperty prop in e.Message.UserProperties)
    {
        Debug.WriteLine($"    Key  : {prop.Name}");
        Debug.WriteLine($"    Value: {prop.Value}");
    }

    Debug.WriteLine($"  Wildcard available: {e.Message.WildcardSubscriptionAvailable}");
}

示例

M2Mqtt 库提供了一个表示连接到代理的 MQTT 客户端的 MqttClient 主类。您可以通过提供代理的 IP 地址或主机名以及可选的与 MQTT 协议相关的参数来连接到代理。

连接到代理后，您可以使用 Publish() 方法向主题发布消息，使用 Subscribe() 方法订阅主题并接收其上发布的消息。MqttClient 类是基于事件驱动的，因此在您订阅的主题上发布消息时，您会收到一个事件。您可以在消息发布完成、订阅或退订主题时接收事件。

以下是一个客户端订阅主题的示例

string MQTT_BROKER_ADDRESS = "192.168.1.2";
// create client instance
MqttClient client = new MqttClient(IPAddress.Parse(MQTT_BROKER_ADDRESS));

// register to message received
client.MqttMsgPublishReceived += client_MqttMsgPublishReceived;

string clientId = Guid.NewGuid().ToString();
client.Connect(clientId);

// subscribe to the topic "/home/temperature" with QoS 2
client.Subscribe(new string[] { "/home/temperature" }, new MqttQoSLevel[] { MqttMsgBase.ExactlyOnce });

// You can add some code here

static void client_MqttMsgPublishReceived(object sender, MqttMsgPublishEventArgs e)
{
// handle message received
}

以下是一个客户端发布主题的示例

string MQTT_BROKER_ADDRESS = "192.168.1.2";
// create client instance
MqttClient client = new MqttClient(IPAddress.Parse(MQTT_BROKER_ADDRESS));

string clientId = Guid.NewGuid().ToString();
client.Connect(clientId);

string strValue = Convert.ToString(value);

// publish a message on "/home/temperature" topic with QoS 2
client.Publish("/home/temperature", Encoding.UTF8.GetBytes(strValue), MqttQoSLevel.ExactlyOnce, false);

// More code goes here

避免证书检查

在某些情况下，通过 TLS 连接时，避免证书检查可能会很方便。虽然这种场景不建议使用，但您可以像这样进行调整

// You can specify no certificate at all
MqttClient mqtt = new MqttClient(IoTHub, 8883, true, null, null, MqttSslProtocols.TLSv1_2);
// And you have to setup the ValidateServerCertificate to false
mqtt.Settings.ValidateServerCertificate = false;
string clientId = Guid.NewGuid().ToString();
client.Connect(clientId);

反馈和文档

有关文档、提供反馈、问题以及了解如何贡献的信息，请参阅首页仓库。

加入我们的 Discord 社区这里。

致谢

该项目贡献者的名单可在CONTRIBUTORS中找到。这个库是由Paolo Patierno 创建和维护的，它是Eclipse 项目的一部分。

许可协议

nanoFramework 类库根据 MIT 许可协议 许可。

行为准则

本项目采用了由贡献者承诺定义的行为准则，以阐明我们社群中预期的行为。有关更多信息，请参阅.NET 基金会行为准则。

.NET 基金会

本项目由.NET 基金会 支持。