| <!DOCTYPE html> |
| <html lang="1.4" class="js csstransforms3d"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Hugo 0.81.0" /> |
| <meta name="description" content="A set of micro-services for connecting millions of devices."> |
| <meta name="author" content="The Eclipse Hono Project"> |
| |
| <link rel="apple-touch-icon" sizes="180x180" href="/hono/docs/favicon/apple-touch-icon.png"> |
| <link rel="icon" type="image/png" sizes="48x48" href="/hono/docs/favicon/favicon-48x48.png"> |
| <link rel="icon" type="image/png" sizes="32x32" href="/hono/docs/favicon/favicon-32x32.png"> |
| <link rel="icon" type="image/png" sizes="16x16" href="/hono/docs/favicon/favicon-16x16.png"> |
| <link rel="manifest" href="/hono/docs/favicon/site.webmanifest"> |
| <link rel="mask-icon" href="/hono/docs/favicon/safari-pinned-tab.svg" color="#5bbad5"> |
| <link rel="shortcut icon" href="/hono/docs/favicon/favicon.ico"> |
| <meta name="msapplication-TileColor" content="#da532c"> |
| <meta name="msapplication-config" content="/hono/docs/favicon/browserconfig.xml"> |
| <meta name="theme-color" content="#ffffff"> |
| |
| <title>MQTT Adapter :: Eclipse Hono™ Vers.: 1.4</title> |
| |
| |
| <link href="/hono/docs/css/nucleus.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/fontawesome-all.min.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/hybrid.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/featherlight.min.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/auto-complete.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/theme.css?1626138727" rel="stylesheet"> |
| <link href="/hono/docs/css/hugo-theme.css?1626138727" rel="stylesheet"> |
| |
| <link href="/hono/docs/css/theme-hono.css?1626138727" rel="stylesheet"> |
| |
| <link href="/hono/docs/css/hono.css?1626138727" rel="stylesheet"> |
| |
| <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138727"></script> |
| |
| <style> |
| :root #header + #content > #left > #rlblock_left{ |
| display:none !important; |
| } |
| |
| :not(pre) > code + span.copy-to-clipboard { |
| display: none; |
| } |
| |
| </style> |
| |
| <link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css"> |
| |
| |
| <meta name="twitter:card" content="summary_large_image"> |
| <meta name="twitter:site" content="@EclipseHono"> |
| <meta name="twitter:title" content="MQTT Adapter :: Eclipse Hono&trade; Vers.: 1.4"> |
| <meta name="twitter:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png"> |
| <meta name="twitter:description" content="A set of micro-services for connecting millions of devices."> |
| |
| |
| <meta property="og:title" content="MQTT Adapter :: Eclipse Hono&trade; Vers.: 1.4" /> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.4/user-guide/mqtt-adapter//" /> |
| <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" /> |
| |
| </head> |
| <body class="" data-url="/hono/docs/1.4/user-guide/mqtt-adapter/"> |
| <nav id="sidebar" class=""> |
| |
| |
| |
| <div id="header-wrapper"> |
| <div id="header"> |
| <a href="https://www.eclipse.org/hono/"> |
| <img src="/hono/docs/images/HONO-Logo_Bild-Wort_quer-w-310x120px.svg" alt="Hono logo" class="logo-img"> |
| </a> |
| |
| </div> |
| |
| <div class="searchbox"> |
| <label for="search-by"><i class="fas fa-search"></i></label> |
| <input data-search-input id="search-by" type="search" placeholder="Search..."> |
| <span data-search-clear=""><i class="fas fa-times"></i></span> |
| </div> |
| |
| <script type="text/javascript" src="/hono/docs/js/lunr.min.js?1626138727"></script> |
| <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138727"></script> |
| <script type="text/javascript"> |
| |
| var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.4"; |
| |
| </script> |
| <script type="text/javascript" src="/hono/docs/js/search.js?1626138727"></script> |
| |
| |
| </div> |
| |
| <div class="highlightable"> |
| <ul class="topics"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/" title="Concepts" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/concepts/"> |
| <i class="far fa-lightbulb"></i> Concepts |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/device-identity/" title="Device Identity" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/device-identity/"> |
| Device Identity |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/tenancy/" title="Multi-Tenancy" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/tenancy/"> |
| Multi-Tenancy |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/device-provisioning/" title="Device Provisioning" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/device-provisioning/"> |
| Device Provisioning |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/connecting-devices/" title="Connecting Devices" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/connecting-devices/"> |
| Connecting Devices |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/device-notifications/" title="Device Notifications" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/device-notifications/"> |
| Device Notifications |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/command-and-control/" title="Command & Control" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/command-and-control/"> |
| Command & Control |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/resource-limits/" title="Resource limits" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/resource-limits/"> |
| Resource limits |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/concepts/connection-events/" title="Connection Events" class="dd-item "> |
| <a href="/hono/docs/1.4/concepts/connection-events/"> |
| Connection Events |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/" title="User Guide" class="dd-item |
| parent |
| |
| |
| "> |
| <a href="/hono/docs/1.4/user-guide/"> |
| <i class="fas fa-book-reader"></i> User Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/mongodb-based-device-registry/" title="MongoDB Based Device Registry" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/mongodb-based-device-registry/"> |
| MongoDB Based Device Registry |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/file-based-device-registry/" title="File Based Device Registry" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/file-based-device-registry/"> |
| File Based Device Registry |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/http-adapter/"> |
| HTTP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item active"> |
| <a href="/hono/docs/1.4/user-guide/mqtt-adapter/"> |
| MQTT Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/amqp-adapter/"> |
| AMQP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/coap-adapter/"> |
| CoAP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/kura-adapter/"> |
| Kura Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/sigfox-adapter/"> |
| Sigfox Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item "> |
| <a href="/hono/docs/1.4/user-guide/jmeter_load_tests/"> |
| Load Tests with JMeter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/" title="Admin Guide" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/admin-guide/"> |
| <i class="fas fa-sliders-h"></i> Admin Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/common-config/" title="Common Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/common-config/"> |
| Common Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/auth-server-config/"> |
| Auth Server Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/mongodb-device-registry-config/" title="MongoDB Based Device Registry Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/mongodb-device-registry-config/"> |
| MongoDB Based Device Registry Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/file-based-device-registry-config/" title="File Based Device Registry Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/file-based-device-registry-config/"> |
| File Based Device Registry Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/device-connection-config/"> |
| Device Connection Service Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/http-adapter-config/"> |
| HTTP Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/mqtt-adapter-config/"> |
| MQTT Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/amqp-adapter-config/"> |
| AMQP Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/coap-adapter-config/" title="CoAP Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/coap-adapter-config/"> |
| CoAP Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/kura-adapter-config/"> |
| Kura Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/hono-client-configuration/"> |
| Hono Client Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/amqp-network-config/"> |
| AMQP 1.0 Messaging Network Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/secure_communication/" title="Secure Communication" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/secure_communication/"> |
| Secure Communication |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/admin-guide/monitoring-tracing-config/" title="Monitoring & Tracing" class="dd-item "> |
| <a href="/hono/docs/1.4/admin-guide/monitoring-tracing-config/"> |
| Monitoring & Tracing |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/dev-guide/" title="Developer Guide" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/dev-guide/"> |
| <i class="fas fa-tools"></i> Developer Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/dev-guide/building_hono/" title="Building from Source" class="dd-item "> |
| <a href="/hono/docs/1.4/dev-guide/building_hono/"> |
| Building from Source |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item "> |
| <a href="/hono/docs/1.4/dev-guide/amqp_adapter_client/"> |
| AMQP Adapter Client for Java |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item "> |
| <a href="/hono/docs/1.4/dev-guide/java_client_consumer/"> |
| Consuming Messages from Java |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item "> |
| <a href="/hono/docs/1.4/dev-guide/custom_http_adapter/"> |
| Implement a Custom Hono HTTP Protocol Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/" title="API" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/api/"> |
| <i class='fas fa-plug'></i> API |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/telemetry/" title="Telemetry API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/telemetry/"> |
| Telemetry API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/event/" title="Event API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/event/"> |
| Event API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/command-and-control/" title="Command & Control API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/command-and-control/"> |
| Command & Control API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/tenant/" title="Tenant API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/tenant/"> |
| Tenant API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/device-connection/" title="Device Connection API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/device-connection/"> |
| Device Connection API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/device-registration/" title="Device Registration API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/device-registration/"> |
| Device Registration API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/credentials/" title="Credentials API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/credentials/"> |
| Credentials API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/authentication/" title="Authentication API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/authentication/"> |
| Authentication API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/management/" title="Device Registry Management API Specification" class="dd-item "> |
| <a href="/hono/docs/1.4/api/management/"> |
| Device Registry Management API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/api/metrics/" title="Metrics" class="dd-item "> |
| <a href="/hono/docs/1.4/api/metrics/"> |
| Metrics |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/deployment/" title="Deployment" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/deployment/"> |
| <i class="fas fa-shipping-fast"></i> Deployment |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item "> |
| <a href="/hono/docs/1.4/deployment/helm-based-deployment/"> |
| Helm based Deployment |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/deployment/openshift/" title="OpenShift / OKD" class="dd-item "> |
| <a href="/hono/docs/1.4/deployment/openshift/"> |
| OpenShift / OKD |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item "> |
| <a href="/hono/docs/1.4/deployment/create-kubernetes-cluster/"> |
| Setting up a Kubernetes Cluster |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item "> |
| <a href="/hono/docs/1.4/deployment/resource-limitation/"> |
| Limiting Resource Usage |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/architecture/" title="Architecture" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/1.4/architecture/"> |
| <i class="fas fa-landmark"></i> Architecture |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/architecture/component-view/" title="Component View" class="dd-item "> |
| <a href="/hono/docs/1.4/architecture/component-view/"> |
| Component View |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/1.4/architecture/auth/" title="Authentication/Authorization" class="dd-item "> |
| <a href="/hono/docs/1.4/architecture/auth/"> |
| Authentication/Authorization |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| </ul> |
| |
| |
| |
| <section id="shortcuts"> |
| <h3></h3> |
| <ul> |
| |
| <li> |
| <a class="padding" href="https://www.eclipse.org/hono/" title="Hono's Homepage"><i class='fas fa-home'></i> Hono Home</a> |
| </li> |
| |
| <li> |
| <a class="padding" href="https://www.eclipse.org/hono/getting-started/" title="Getting started with Eclipse Hono"><i class='fas fa-plane-departure'></i> Getting Started</a> |
| </li> |
| |
| </ul> |
| </section> |
| |
| |
| |
| <section id="prefooter"> |
| <hr/> |
| <ul> |
| |
| <li> |
| <div id="select-box-wrapper"> |
| <div id="select-box"> |
| <a class="padding"> |
| Version: |
| <div class="select-style"> |
| <select id="select-language" onchange="location = this.value;"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/">stable (1.8)</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/user-guide/mqtt-adapter/">1.8</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/mqtt-adapter/">1.7</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/mqtt-adapter/">1.6</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/mqtt-adapter/">1.5</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/mqtt-adapter/" selected>1.4</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/mqtt-adapter/">1.3</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/mqtt-adapter/">1.2</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/mqtt-adapter/">1.1</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/mqtt-adapter/">1.0</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/mqtt-adapter/">dev</option> |
| |
| |
| |
| |
| </select> |
| <svg version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" |
| width="255px" height="255px" viewBox="0 0 255 255" style="enable-background:new 0 0 255 255;" xml:space="preserve"> |
| <g> |
| <g id="arrow-drop-down"> |
| <polygon points="0,63.75 127.5,191.25 255,63.75 " /> |
| </g> |
| </g> |
| </svg> |
| </div> |
| </a> |
| </div> |
| </div> |
| </li> |
| |
| |
| |
| </ul> |
| </section> |
| |
| <section id="footer"> |
| |
| |
| <p>© 2021 <a href="https://www.eclipse.org/hono/">The Eclipse Hono Project</a></p> |
| |
| <p> |
| Documentation built with |
| <a href="https://gohugo.io/" target="_blank">Hugo</a> |
| using the |
| <a href="https://github.com/matcornic/hugo-theme-learn" target="_blank">Learn</a> theme. |
| </p> |
| |
| <div class="eclipse-logo"> |
| <a href="https://www.eclipse.org" target="_blank"> |
| <img src="https://www.eclipse.org/hono/docs/images/eclipse_foundation_logo.svg"/> |
| </a> |
| </div> |
| |
| </section> |
| </div> |
| </nav> |
| |
| |
| |
| |
| <section id="body"> |
| <div id="overlay"></div> |
| |
| |
| <div class="old-version-hint"> |
| <p>This page refers to version <em>1.4</em>. |
| You might want to use the <a href="https://www.eclipse.org/hono/docs/">current stable</a> version. |
| </p> |
| </div> |
| |
| |
| |
| <div class="padding highlightable"> |
| |
| <div> |
| <div id="top-bar"> |
| |
| |
| |
| |
| <div id="top-github-link"> |
| <a class="github-link" title='Edit this page' href="https://github.com/eclipse/hono/edit/master/site/documentation/content/user-guide/mqtt-adapter.md" target="blank"> |
| <i class="fas fa-code-branch"></i> |
| <span id="top-github-link-text">Edit this page</span> |
| </a> |
| </div> |
| |
| |
| |
| <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb"> |
| <span id="sidebar-toggle-span"> |
| <a href="#" id="sidebar-toggle" data-sidebar-toggle=""> |
| <i class="fas fa-bars"></i> |
| </a> |
| </span> |
| |
| <span id="toc-menu"><i class="fas fa-list-alt"></i></span> |
| |
| <span class="links"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href='/hono/docs/1.4/'>Documentation</a> > <a href='/hono/docs/1.4/user-guide/'>User Guide</a> > MQTT Adapter |
| |
| |
| |
| |
| |
| |
| |
| </span> |
| </div> |
| |
| <div class="progress"> |
| <div class="wrapper"> |
| <nav id="TableOfContents"> |
| <ul> |
| <li><a href="#authentication">Authentication</a> |
| <ul> |
| <li><a href="#client-certificate">Client Certificate</a></li> |
| <li><a href="#usernamepassword">Username/Password</a></li> |
| </ul> |
| </li> |
| <li><a href="#resource-limit-checks">Resource Limit Checks</a> |
| <ul> |
| <li><a href="#connection-limits">Connection Limits</a></li> |
| <li><a href="#connection-duration-limits">Connection Duration Limits</a></li> |
| <li><a href="#message-limits">Message Limits</a></li> |
| </ul> |
| </li> |
| <li><a href="#connection-events">Connection Events</a></li> |
| <li><a href="#publishing-telemetry-data">Publishing Telemetry Data</a></li> |
| <li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li> |
| <li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li> |
| <li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li> |
| <li><a href="#publishing-events">Publishing Events</a></li> |
| <li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li> |
| <li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li> |
| <li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li> |
| <li><a href="#command--control">Command & Control</a> |
| <ul> |
| <li><a href="#receiving-commands-authenticated-device">Receiving Commands (authenticated Device)</a></li> |
| <li><a href="#receiving-commands-unauthenticated-device">Receiving Commands (unauthenticated Device)</a></li> |
| <li><a href="#receiving-commands-authenticated-gateway">Receiving Commands (authenticated Gateway)</a></li> |
| <li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li> |
| <li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li> |
| <li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li> |
| </ul> |
| </li> |
| <li><a href="#custom-message-mapping">Custom Message Mapping</a></li> |
| <li><a href="#downstream-meta-data">Downstream Meta Data</a> |
| <ul> |
| <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li> |
| </ul> |
| </li> |
| <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li> |
| </ul> |
| </nav> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| <div id="head-tags"> |
| |
| </div> |
| |
| <div id="body-inner"> |
| |
| <h1> |
| |
| MQTT Adapter |
| </h1> |
| |
| |
| |
| |
| |
| <p>The MQTT protocol adapter exposes an MQTT topic hierarchy for publishing telemetry data and events to downstream consumers and for receiving commands from applications and sending back responses.</p> |
| <p>The MQTT adapter is <strong>not</strong> a general purpose MQTT broker. In particular the adapter</p> |
| <ul> |
| <li>supports MQTT 3.1.1 only.</li> |
| <li>does not maintain session state for clients and thus always sets the <em>session present</em> flag in its CONNACK packet to <code>0</code>, regardless of the value of the <em>clean session</em> flag provided in a client’s CONNECT packet.</li> |
| <li>ignores any <em>Will</em> included in a client’s CONNECT packet.</li> |
| <li>only supports topic names/filters for devices to publish and subscribe to that are specific to Hono’s functionality as described in the following sections.</li> |
| <li>does not support <em>retaining</em> messages. However, if an event or telemetry message’s <em>retain</em> flag is set to <code>1</code> then the corresponding AMQP 1.0 message being sent downstream by the adapter will contain an <em>x-opt-retain</em> message annotation containing the boolean value <code>true</code>. A downstream consumer may then react according to the presence of this annotation.</li> |
| </ul> |
| <h2 id="authentication">Authentication</h2> |
| <p>The MQTT adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. |
| The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT packet as well as client |
| certificate based authentication as part of a TLS handshake for that purpose.</p> |
| <p>The adapter tries to authenticate the device using these mechanisms in the following order</p> |
| <h3 id="client-certificate">Client Certificate</h3> |
| <p>When a device uses a client certificate for authentication during the TLS handshake, the adapter tries to determine the tenant |
| that the device belongs to based on the <em>issuer DN</em> contained in the certificate. |
| In order for the lookup to succeed, the tenant’s trust anchor needs to be configured by means of registering the |
| <a href="/hono/docs/1.4/api/tenant/#tenant-information-format">trusted certificate authority</a>. The device’s client certificate will then be |
| validated using the registered trust anchor, thus implicitly establishing the tenant that the device belongs to. |
| In a second step, the adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the client |
| certificate’s <em>subject DN</em> as the <em>auth-id</em>, <code>x509-cert</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the |
| request payload.</p> |
| <p><strong>NB</strong> The adapter needs to be <a href="/hono/docs/1.4/admin-guide/secure_communication/">configured for TLS</a> in order to support this mechanism.</p> |
| <h3 id="usernamepassword">Username/Password</h3> |
| <p>When a device wants to authenticate using this mechanism, it needs to provide a <em>username</em> and a <em>password</em> in the MQTT <em>CONNECT</em> packet |
| it sends in order to initiate the connection. The <em>username</em> must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>. |
| The adapter verifies the credentials provided by the client against the credentials that the |
| <a href="/hono/docs/1.4/admin-guide/common-config/">configured Credentials service</a> has on record for the client. |
| The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the <em>tenant</em> and <em>auth-id</em> provided |
| by the client in the <em>username</em>, <code>hashed-password</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the request payload.</p> |
| <p>The examples below refer to devices <code>4711</code> and <code>gw-1</code> of tenant <code>DEFAULT_TENANT</code> using <em>auth-ids</em> <code>sensor1</code> and <code>gw1</code> and corresponding passwords. |
| The example deployment as described in the <a href="/hono/docs/1.4/deployment/">Deployment Guides</a> comes pre-configured with the corresponding entities in its device registry component.</p> |
| <p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication. |
| See <a href="/hono/docs/1.4/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p> |
| <h2 id="resource-limit-checks">Resource Limit Checks</h2> |
| <p>The adapter performs additional checks regarding <a href="/hono/docs/1.4/concepts/resource-limits/">resource limits</a> when a client tries to connect and/or |
| send a message to the adapter.</p> |
| <h3 id="connection-limits">Connection Limits</h3> |
| <p>The adapter rejects a client’s connection attempt with return code</p> |
| <ul> |
| <li><code>0x03</code> (<em>Connection Refused: server unavailable</em>), if the maximum number of connections per protocol adapter instance is reached</li> |
| <li><code>0x05</code> (<em>Connection Refused: not authorized</em>), if the maximum number of simultaneously connected devices for the tenant is reached.</li> |
| </ul> |
| <h3 id="connection-duration-limits">Connection Duration Limits</h3> |
| <p>The adapter rejects a client’s connection attempt with return code <code>0x05</code> (<em>Connection Refused: not authorized</em>), if the |
| <a href="/hono/docs/1.4/concepts/resource-limits/">connection duration limit</a> that has been configured for the client’s tenant is exceeded.</p> |
| <h3 id="message-limits">Message Limits</h3> |
| <p>The adapter</p> |
| <ul> |
| <li>rejects a client’s connection attempt with return code <code>0x05</code> (<em>Connection Refused: not authorized</em>),</li> |
| <li>discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and</li> |
| <li>rejects any AMQP 1.0 message containing a command sent by a north bound application</li> |
| </ul> |
| <p>if the <a href="/hono/docs/1.4/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p> |
| <h2 id="connection-events">Connection Events</h2> |
| <p>The adapter can emit <a href="/hono/docs/1.4/api/event/#connection-event">Connection Events</a> for client connections being established and/or terminated. |
| Please refer to the <a href="/hono/docs/1.4/admin-guide/common-config/">common configuration options</a> |
| for details regarding how to enable this behavior.</p> |
| <p>The adapter includes the <em>client identifier</em> from the client’s MQTT CONNECT packet as the Connection Event’s <em>remote-id</em>.</p> |
| <h2 id="publishing-telemetry-data">Publishing Telemetry Data</h2> |
| <p>The MQTT adapter supports the publishing of telemetry data by means of MQTT <em>PUBLISH</em> packets using either QoS 0 or QoS 1. |
| Using QoS 1 will result in the adapter sending an MQTT <em>PUBACK</em> packet to the client once the message has been settled with the <em>accepted</em> outcome by the AMQP 1.0 Messaging Network.</p> |
| <p>This requires that</p> |
| <ul> |
| <li>the AMQP 1.0 Messaging Network has capacity to process telemetry messages for the client’s tenant and</li> |
| <li>the messages published by the client comply with the format defined by the Telemetry API.</li> |
| </ul> |
| <p>The protocol adapter checks the configured [message limit] (/hono/docs/1.4/concepts/resource-limits/) before accepting any telemetry messages. If the message limit is exceeded or the incoming telemetry message cannot be processed, the connection to the client is closed.</p> |
| <h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2> |
| <ul> |
| <li>Topic: <code>telemetry</code> or <code>t</code></li> |
| <li>Authentication: required</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default). When using this topic, the MQTT adapter determines the device’s tenant and device identity as part of the authentication process.</p> |
| <p><strong>Example</strong></p> |
| <p>Publish some JSON data for device <code>4711</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t telemetry -m <span style="color:#e6db74">'{"temp": 5}'</span> |
| </code></pre></div><p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in base directory of Hono repository:</span> |
| mosquitto_pub -p <span style="color:#ae81ff">8883</span> -t telemetry -m <span style="color:#e6db74">'{"temp": 5}'</span> --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cafile demo-certs/certs/trusted-certs.pem |
| </code></pre></div><p><strong>NB</strong> The example above assumes that the MQTT adapter is <a href="/hono/docs/1.4/admin-guide/secure_communication/">configured for TLS</a> and the secure port is used.</p> |
| <h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2> |
| <ul> |
| <li>Topic: <code>telemetry/${tenant-id}/${device-id}</code> or <code>t/${tenant-id}/${device-id}</code></li> |
| <li>Authentication: none</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the |
| <code>HONO_MQTT_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p> |
| <p><strong>Examples</strong></p> |
| <p>Publish some JSON data for device <code>4711</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t telemetry/DEFAULT_TENANT/4711 -m <span style="color:#e6db74">'{"temp": 5}'</span> |
| </code></pre></div><h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2> |
| <ul> |
| <li>Topic: <code>telemetry/${tenant-id}/${device-id}</code> or <code>t/${tenant-id}/${device-id}</code></li> |
| <li>Authentication: required</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This topic can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.</p> |
| <p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/1.4/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p> |
| <p><strong>Examples</strong></p> |
| <p>Publish some JSON data for device <code>4712</code> via gateway <code>gw-1</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t telemetry/DEFAULT_TENANT/4712 -m <span style="color:#e6db74">'{"temp": 5}'</span> |
| </code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p> |
| <h2 id="publishing-events">Publishing Events</h2> |
| <p>The MQTT adapter supports the publishing of events by means of MQTT <em>PUBLISH</em> packets using QoS 1 only. |
| The adapter will send an MQTT <em>PUBACK</em> packet to the client once the event has been settled with the <em>accepted</em> outcome by the AMQP 1.0 Messaging Network.</p> |
| <p>This requires that</p> |
| <ul> |
| <li>the AMQP 1.0 Messaging Network has capacity to process events for the client’s tenant and</li> |
| <li>the events published by the client comply with the format defined by the Event API.</li> |
| </ul> |
| <p>The protocol adapter checks the configured [message limit] (/hono/docs/1.4/concepts/resource-limits/) before accepting any event messages. If the message limit is exceeded or the incoming event message cannot be processed, the connection to the client is closed.</p> |
| <p>The devices can optionally indicate a <em>time-to-live</em> duration for event messages by setting the <em>hono-ttl</em> property explicitly in the <code>property-bag</code>. The <code>property-bag</code> is an optional collection of properties intended for the receiver of the message. A property bag is only allowed at the very end of a topic. It always starts with a <code>/?</code> character, followed by pairs of URL encoded property names and values that are separated by <code>&</code>. For example, a property bag containing two properties <em>seqNo</em> and <em>importance</em> looks like this: <code>/topic/name/?seqNo=10034&importance=high</code>.</p> |
| <p>The MQTT adapter currently does not use any properties except <em>hono-ttl</em>.</p> |
| <h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2> |
| <ul> |
| <li>Topic: <code>event</code> or <code>e</code></li> |
| <li>Authentication: required</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This is the preferred way for devices to publish events. It is available only if the protocol adapter has been configured to require devices to authenticate (which is the default).</p> |
| <p><strong>Example</strong></p> |
| <p>Upload a JSON string for device <code>4711</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t event -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span> |
| </code></pre></div><p>Upload a JSON string for device <code>4711</code> with <code>time-to-live</code> as 10 seconds:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t event/?hono-ttl<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span> |
| </code></pre></div><h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2> |
| <ul> |
| <li>Topic: <code>event/${tenant-id}/${device-id}</code> or <code>e/${tenant-id}/${device-id}</code></li> |
| <li>Authentication: none</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the |
| <code>HONO_MQTT_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p> |
| <p><strong>Examples</strong></p> |
| <p>Publish some JSON data for device <code>4711</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t event/DEFAULT_TENANT/4711 -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span> |
| </code></pre></div><p>Publish some JSON data for device <code>4711</code> with <code>time-to-live</code> as 15 seconds:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t event/DEFAULT_TENANT/4711/?hono-ttl<span style="color:#f92672">=</span><span style="color:#ae81ff">15</span> -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span> |
| </code></pre></div><h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2> |
| <ul> |
| <li>Topic: <code>event/${tenant-id}/${device-id}</code> or <code>e/${tenant-id}/${device-id}</code></li> |
| <li>Authentication: required</li> |
| <li>Payload: |
| <ul> |
| <li>(required) Arbitrary payload</li> |
| </ul> |
| </li> |
| </ul> |
| <p>This topic can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.</p> |
| <p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/1.4/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p> |
| <p><strong>Examples</strong></p> |
| <p>Publish some JSON data for device <code>4712</code> via gateway <code>gw-1</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t event/DEFAULT_TENANT/4712 -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"temp": 5}'</span> |
| </code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p> |
| <h2 id="command--control">Command & Control</h2> |
| <p>The MQTT adapter enables devices to receive commands that have been sent by business applications by means of sending an MQTT <em>SUBSCRIBE</em> packet containing a device specific <em>topic filter</em> as described below. Devices can subscribe with QoS 1 or QoS 0. The adapter indicates the outcome of the subscription request by sending back a corresponding <em>SUBACK</em> packet. The SUBACK packet will contain <em>Success - QoS 0</em> (<code>0x00</code>) or <em>Success - QoS 1</em> (<code>0x01</code>) for a command topic filter indicating QoS 0 or 1 and will contain the <em>Failure</em> (<code>0x80</code>) value for all other filters. When a device no longer wants to receive commands anymore, it can send an MQTT <em>UNSUBSCRIBE</em> packet to the adapter, including the same topic filter that has been used to subscribe.</p> |
| <p>When a device has successfully subscribed, the adapter sends an <a href="/hono/docs/1.4/api/event/#empty-notification">empty notification</a> on behalf of the device to the downstream AMQP 1.0 Messaging Network with the <em>ttd</em> header set to <code>-1</code>, indicating that the device will be ready to receive commands until further notice. Analogously, the adapter sends an empty notification with the <em>ttd</em> header set to <code>0</code> when a device unsubscribes from commands.</p> |
| <p>Commands can be sent following a <em>request/response</em> pattern or being <em>one-way</em>.</p> |
| <p>For <em>Request/Response</em> commands, devices send their responses to commands by means of sending an MQTT <em>PUBLISH</em> message to a topic that is specific to the command that has been executed. The MQTT adapter accepts responses being published using either QoS 0 or QoS 1.</p> |
| <p>The MQTT adapter checks the configured [message limit] (/hono/docs/1.4/concepts/resource-limits/) before accepting any command requests and responses. In case of incoming command requests from business applications, if the message limit is exceeded, the Adapter rejects the message with the reason <code>amqp:resource-limit-exceeded</code>. And for the incoming command responses from devices, the Adapter rejects the message and closes the connection to the client.</p> |
| <p>The following sections define the topic filters/names to use for subscribing to and responding to commands. The following <em>shorthand</em> versions of topic path segments are supported:</p> |
| <ul> |
| <li><code>c</code> instead of <code>command</code></li> |
| <li><code>q</code> instead of <code>req</code></li> |
| <li><code>s</code> instead of <code>res</code></li> |
| </ul> |
| <p>The following variables are used:</p> |
| <ul> |
| <li><code>${command}</code> : An arbitrary string that indicates the command to execute, e.g. <code>setBrightness</code>. The command is provided by the application that sends the command.</li> |
| <li><code>${req-id}</code> (only for <em>Request/Response</em> commands) : The unique identifier of the command execution request. The identifier is passed to the device as part of the name of the topic that the command is published to. The device needs to publish its response to the command to a topic which includes this identifier, thus allowing the adapter to correlate the response with the request.</li> |
| <li><code>${status}</code> : The HTTP status code indicating the outcome of executing the command. This status code is passed on to the application in the AMQP message’s <em>status</em> application property.</li> |
| </ul> |
| <h3 id="receiving-commands-authenticated-device">Receiving Commands (authenticated Device)</h3> |
| <p>An authenticated device MUST use the topic filter <code>command///req/#</code> to subscribe to commands.</p> |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4> |
| <div>Previous versions of Hono required authenticated devices to use <code>command/+/+/req/#</code> for subscribing to commands. |
| This old topic filter is deprecated. Devices MAY still use it until support for it will be removed in a future Hono version.</div> |
| </div> |
| <p><strong>Example</strong></p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t command///req/# |
| </code></pre></div><p>The adapter will then publish <em>Request/Response</em> commands for the device to topic <code>command///req/${req-id}/${command}</code> and <em>one-way</em> commands to topic <code>command///req//${command}</code>.</p> |
| <p>For example, a request/response command with name <code>setBrightness</code> from an application might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command///q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command///q//setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>Note that the topic in the latter case doesn’t contain a request identifier.</p> |
| <h3 id="receiving-commands-unauthenticated-device">Receiving Commands (unauthenticated Device)</h3> |
| <p>An unauthenticated device MUST use the topic filter <code>command/${tenant-id}/${device-id}/req/#</code> to subscribe to commands.</p> |
| <p><strong>Example</strong></p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -t command/DEFAULT_TENANT/4711/req/# |
| </code></pre></div><p>The adapter will then publish <em>Request/Response</em> commands for the device to topic <code>command/${tenant-id}/${device-id}/req/${req-id}/${command}</code> and <em>one-way</em> commands to topic <code>command/${tenant-id}/${device-id}/req//${command}</code>.</p> |
| <p>For example, a request/response command with name <code>setBrightness</code> from an application might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command/DEFAULT_TENANT/4711/q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command/DEFAULT_TENANT/4711/q//setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>Note that the topic in the latter case doesn’t contain a request identifier.</p> |
| <h3 id="receiving-commands-authenticated-gateway">Receiving Commands (authenticated Gateway)</h3> |
| <p><em>Gateway</em> components can receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/1.4/admin-guide/file-based-device-registry-config/">Configuring Gateway Devices</a> for details.</p> |
| <p>An authenticated gateway MUST use the topic filter <code>command//+/req/#</code> to subscribe to commands for all devices in whose behalf it acts.</p> |
| <p>To subscribe only to commands for a specific device, an authenticated gateway MUST use the topic filter <code>command//${device-id}/req/#</code>.</p> |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4> |
| <div>Previous versions of Hono required authenticated gateways to use <code>command/+/+/req/#</code> for subscribing to commands. |
| This old topic filter is deprecated. Gateways MAY still use it until support for it will be removed in a future Hono version.</div> |
| </div> |
| <p>When processing an incoming command message, the protocol adapter will give precedence to a device-specific command subscription matching the command target device, whether the subscription comes from a gateway or the device itself. If there are multiple such subscriptions from multiple gateways and/or from the device itself, the subscription initiated last will get the command messages.</p> |
| <p>If no device-specific command subscription exists for a command target device, but <em>one</em> gateway, that may act on behalf of the device, has subscribed to commands for all its devices, then the command message is sent to that gateway.</p> |
| <p>If <em>multiple</em> gateways have initiated such generic subscriptions, the protocol adapter may have to decide to which gateway a particular command message will be sent to. |
| In case the command target device has already sent a telemetry, event or command response message via a gateway and if that gateway has created such a command subscription, that gateway will be chosen. Otherwise one gateway that may act on behalf of the command target device and that has an open subscription will be chosen randomly to receive the command message.</p> |
| <p><strong>Example</strong></p> |
| <p>A subscription to commands for all devices that a gateway acts on behalf of looks like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t command//+/req/# |
| </code></pre></div><p>A subscription to commands for a specific device can be done like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t command//4711/req/# |
| </code></pre></div><p>The adapter will then publish <em>Request/Response</em> commands for devices, that the gateway has acted on behalf of, to topic <code>command//${device-id}/req/${req-id}/${command}</code> and <em>one-way</em> commands to topic <code>command//${device-id}/req//${command}</code>.</p> |
| <p>For example, a request/response command for device <code>4711</code> with name <code>setBrightness</code> from an application might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command//4711/q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command//4711/q//setBrightness |
| { |
| "brightness": 79 |
| } |
| </code></pre></div><p>Note that the topic in the latter case doesn’t contain a request identifier.</p> |
| <h3 id="sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</h3> |
| <p>An authenticated device MUST send the response to a previously received command to the topic <code>command///res/${req-id}/${status}</code>.</p> |
| <p><strong>Example</strong></p> |
| <p>After a command has arrived as in the above example, you send a response using the arrived <code>${req-id}</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t command///res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span> |
| </code></pre></div><h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3> |
| <p>An unauthenticated device MUST send the response to a previously received command to the topic <code>command/${tenant-id}/${device-id}/res/${req-id}/${status}</code>.</p> |
| <p><strong>Example</strong></p> |
| <p>After a command has arrived as in the above example, you send a response using the arrived <code>${req-id}</code>:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t command/DEFAULT_TENANT/4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span> |
| </code></pre></div><h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3> |
| <p>An authenticated gateway MUST send a device’s response to a command it has received on behalf of the device to the topic <code>command//${device-id}/res/${req-id}/${status}</code>.</p> |
| <p><strong>Example</strong></p> |
| <p>After a command has arrived as in the above example, the response is sent using the <code>${req-id}</code> from the topic that the command had been published to:</p> |
| <div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t command//4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span> |
| </code></pre></div><h2 id="custom-message-mapping">Custom Message Mapping</h2> |
| <p>This protocol adapter supports transformation of messages that have been uploaded by devices before they get forwarded to downstream consumers.</p> |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Experimental</h4> |
| <div>This is an experimental feature. The names of the configuration properties, potential values and the overall functionality are therefore |
| subject to change without prior notice.</div> |
| </div> |
| <p>This feature is useful in scenarios where devices are connected to the adapter via a gateway but the gateway is not able to include |
| the device ID in the topic that the gateway publishes data to. The gateway will use the plain <code>telemetry</code> or <code>event</code> topics in this case. |
| The message payload will usually contain the identifier of the device that the data originates from.</p> |
| <p>The same functionality can also be used to transform the payload of messages uploaded by a device. This can be used for example to |
| transform binary encoded data into a JSON document which can be consumed more easily by downstream consumers.</p> |
| <p>The mechanism works as follows:</p> |
| <ol> |
| <li>A client uploads a message to the MQTT adapter.</li> |
| <li>The adapter invokes the Device Registration service’s <em>assert Registration</em> operation using either |
| the authenticated device’s identifier, if the topic does not contain a device ID, or the device ID from the |
| topic.</li> |
| <li>If the assertion succeeds, the adapter creates the downstream message using the original message’s payload and |
| the asserted device ID as the origin device.</li> |
| <li>If the response payload contains a value for the <em>mapper</em> property, the adapter tries to find a <em>mapper endpoint</em> configuration |
| for the given value. If a mapper endpoint with a matching name has been configured for the adapter, |
| <ol> |
| <li>the adapter sends an HTTP request to the endpoint which contains the original message’s payload in the request body.</li> |
| <li>If the response body is not empty, it is used as the downstream message’s payload.</li> |
| <li>If the response contains a <em>device_id</em> header and its value is different from the original device ID, then the adapter |
| invokes the <em>assert Registration</em> operation again, this time using the mapped device ID instead of the original device ID. |
| If the assertion succeeds, the adapter uses the asserted (mapped) device ID for the downstream message.</li> |
| </ol> |
| </li> |
| <li>The adapter forwards the downstream message.</li> |
| </ol> |
| <p>Please refer to the <a href="/hono/docs/1.4/api/management/#/devices/createDeviceRegistration">Device Registry Management API</a> |
| for how to register a <em>mapper</em> for a device. |
| Please refer to the <a href="/hono/docs/1.4/admin-guide/mqtt-adapter-config/#custom-message-mapping">MQTT Adapter Admin Guide</a> |
| for how to configure custom mapper endpoints.</p> |
| <h2 id="downstream-meta-data">Downstream Meta Data</h2> |
| <p>The adapter includes the following meta data in messages being sent downstream:</p> |
| <table> |
| <thead> |
| <tr> |
| <th style="text-align:left">Name</th> |
| <th style="text-align:left">Location</th> |
| <th style="text-align:left">Type</th> |
| <th style="text-align:left">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td style="text-align:left"><em>device_id</em></td> |
| <td style="text-align:left"><em>application</em></td> |
| <td style="text-align:left"><em>string</em></td> |
| <td style="text-align:left">The identifier of the device that the message originates from.</td> |
| </tr> |
| <tr> |
| <td style="text-align:left"><em>orig_adapter</em></td> |
| <td style="text-align:left"><em>application</em></td> |
| <td style="text-align:left"><em>string</em></td> |
| <td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The MQTT adapter’s type name is <code>hono-mqtt</code>.</td> |
| </tr> |
| <tr> |
| <td style="text-align:left"><em>orig_address</em></td> |
| <td style="text-align:left"><em>application</em></td> |
| <td style="text-align:left"><em>string</em></td> |
| <td style="text-align:left">Contains the name of the MQTT topic that the device has originally published the data to.</td> |
| </tr> |
| <tr> |
| <td style="text-align:left"><em>x-opt-retain</em></td> |
| <td style="text-align:left"><em>message-annotations</em></td> |
| <td style="text-align:left"><em>boolean</em></td> |
| <td style="text-align:left">Contains <code>true</code> if the device has published an event or telemetry message with its <em>retain</em> flag set to <code>1</code></td> |
| </tr> |
| </tbody> |
| </table> |
| <p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/1.4/api/tenant/#tenant-information-format">tenant</a> |
| or the <a href="/hono/docs/1.4/api/device-registration/#assert-device-registration">device level</a>. |
| The values of the default properties are determined as follows:</p> |
| <ol> |
| <li>If the message already contains a non-empty property of the same name, the value if unchanged.</li> |
| <li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li> |
| <li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li> |
| </ol> |
| <p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p> |
| <h3 id="event-message-time-to-live">Event Message Time-to-live</h3> |
| <p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers. |
| In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed |
| from the persistent store if no consumer has attached to receive the event before the message expires.</p> |
| <p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the MQTT protocol adapter supports setting a |
| downstream event message’s <em>ttl</em> property based on the <em>hono-ttl</em> property set as <em>property-bag</em> at the end of the event topic. |
| Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the [Tenant API] |
| (/hono/docs/1.4/api/tenant/#resource-limits-configuration-format).</p> |
| <h2 id="tenant-specific-configuration">Tenant specific Configuration</h2> |
| <p>The adapter uses the <a href="/hono/docs/1.4/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-mqtt</code>. |
| The following properties are (currently) supported:</p> |
| <table> |
| <thead> |
| <tr> |
| <th style="text-align:left">Name</th> |
| <th style="text-align:left">Type</th> |
| <th style="text-align:left">Default Value</th> |
| <th style="text-align:left">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td style="text-align:left"><em>enabled</em></td> |
| <td style="text-align:left"><em>boolean</em></td> |
| <td style="text-align:left"><code>true</code></td> |
| <td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <footer class="footline"> |
| |
| </footer> |
| |
| |
| </div> |
| |
| |
| </div> |
| |
| <div id="navigation"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| |
| </section> |
| |
| <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"> |
| <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div> |
| </div> |
| <script src="/hono/docs/js/clipboard.min.js?1626138728"></script> |
| <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138728"></script> |
| <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138728"></script> |
| <script src="/hono/docs/js/jquery.sticky.js?1626138728"></script> |
| <script src="/hono/docs/js/featherlight.min.js?1626138728"></script> |
| <script src="/hono/docs/js/highlight.pack.js?1626138728"></script> |
| <script>hljs.initHighlightingOnLoad();</script> |
| <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138728"></script> |
| <script src="/hono/docs/js/learn.js?1626138728"></script> |
| <script src="/hono/docs/js/hugo-learn.js?1626138728"></script> |
| |
| <link href="/hono/docs/mermaid/mermaid.css?1626138728" rel="stylesheet" /> |
| <script src="/hono/docs/mermaid/mermaid.js?1626138728"></script> |
| <script> |
| mermaid.initialize({ startOnLoad: true }); |
| </script> |
| |
| |
| |
| |
| <script> |
| (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': |
| new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], |
| j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= |
| 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); |
| })(window,document,'script','dataLayer','GTM-5WLCZXC'); |
| </script> |
| |
| |
| <script src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script> |
| |
| </body> |
| </html> |
| |
