nanoFramework.M2Mqtt.Core 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协议的工作原理有一个很好的理解，以便正确使用它。服务质量机制是理解中的一个重要方面。

使用方法

使用方法全局上相同，无论使用哪个版本。在3.1.1和5.0之间有一些具体区别。版本5.0带来了更多的控制性和额外的属性。为了方便，它们都在属性注释中注释为`v5.0 only`。如果您使用的是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服务器需要一个特定的证书。您可以在示例中找到它。

5.0特定身份验证流程

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

• 确保已设置v5为协议
• 将属性IsAuthenticationFlow设置为true
• 注册到Authentication事件
• 根据需要通过发送另一个身份验证消息或其他任何事情来相应地管理答案。

注意：该协议使用AuthenticationMethod和AuthenticationData作为属性来支持此特定机制。

以下是规范给出的示例

非规范性示例，展示SCRAM挑战

• 客户端到服务器：CONNECT 身份验证方法="SCRAM-SHA-1" 身份验证数据=client-first-data
• 服务器到客户端：AUTH rc=0x18 身份验证方法="SCRAM-SHA-1" 身份验证数据=server-first-data
• 客户端到服务器 AUTH rc=0x18 身份验证方法="SCRAM-SHA-1" 身份验证数据=client-final-data
• 服务器到客户端 CONNACK rc=0 身份验证方法="SCRAM-SHA-1" 身份验证数据=server-final-data

非规范性示例，展示Kerberos挑战

• 客户端到服务器 CONNECT 身份验证方法="GS2-KRB5"
• 服务器到客户端 AUTH rc=0x18 身份验证方法="GS2-KRB5"
• 客户端到服务器 AUTH rc=0x18 身份验证方法="GS2-KRB5" 身份验证数据=initial context token
• 服务器到客户端 AUTH rc=0x18 身份验证方法="GS2-KRB5" 身份验证数据=reply context token
• 客户端到服务器 AUTH rc=0x18 身份验证方法="GS2-KRB5"
• 服务器到客户端 CONNACK rc=0 身份验证方法="GS2-KRB5" 身份验证数据=身份验证结果

在这些机制中，只有当收到一个成功代码的Connack并设置IsConnected属性时才会这样做。由于这些身份验证机制是特定的且由用户设置，因此此特定MqttClient提供使用此机制的能力。

订阅事件

MqttClient提供事件。您可以订阅它们。例如，您可以使用v5.0协议获取连接打开时的附加信息。以下示例显示了需要启用MQTT 5.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库提供了一个主类MqttClient，代表连接到代理的MQTT客户端。您可以通过提供一个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 Foundation 行为准则。

.NET Foundation

本项目由.NET Foundation 支持。