nanoFramework.M2Mqtt 5.1.138

文档语言: English | 简体中文

.NET nanoFramework M2Mqtt

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

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

从那时起，MQTT 客户端库经历了许多变化，并已适配到 .NET nanoFramework。

构建状态

组件	构建状态	NuGet 包
nanoFramework.M2Mqtt

项目描述

M2Mqtt 是一个用于物联网和 M2M 通信的 MQTT 客户端。

MQTT，全称为Message Queue Telemetry Transport，是一种轻量级消息协议，允许资源有限的嵌入式设备在某些受限的网络中对异步通信进行操作。

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

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

二进制文件作为NuGet包提供。

有关MQTT协议的所有信息，请访问MQTT官方网站。建议您详细了解MQTT协议的工作原理，以便正确使用它。服务质量机制的机理是理解的重要因素。

用法

无论使用哪个版本，用法都是全局相同的。在v3.1.1和v5.0之间存在一些特定性。v5.0版本带来了更多的控制和额外的属性。为了方便起见，它们在属性注释中都被注释为“仅v5.0”。如果您使用的是v3.1或v3.1.1协议的v5.0属性，它们将直接被忽略。

以下是一个基本示例，创建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 认证方法="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协议连接到Azure IoT Hub获得连接开启时的额外信息。以下示例显示了要使用启用了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库提供了一个主类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社区这里。

鸣谢

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

许可证

nanoFramework类库采用MIT许可证。

行为守则

本项目采用贡献者公约中定义的行为守则，以明确期望我们的社区中的行为。有关更多信息，请参阅.NET Foundation行为守则。

.NET Foundation

本项目由.NET Foundation支持。