| <!DOCTYPE html> |
| <html lang="dev" 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.54.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>CoAP Adapter :: Eclipse Hono™ Vers.: dev</title> |
| |
| |
| <link href="/hono/docs/css/nucleus.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/fontawesome-all.min.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/hybrid.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/featherlight.min.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/perfect-scrollbar.min.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/auto-complete.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/theme.css?1585103013" rel="stylesheet"> |
| <link href="/hono/docs/css/hugo-theme.css?1585103013" rel="stylesheet"> |
| |
| <link href="/hono/docs/css/theme-hono.css?1585103013" rel="stylesheet"> |
| |
| |
| <script src="/hono/docs/js/jquery-2.x.min.js?1585103013"></script> |
| |
| <style type="text/css"> |
| :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"> |
| <link rel="stylesheet" href='/hono/docs/css/hono.css'> |
| |
| |
| <meta name="twitter:card" content="summary_large_image"> |
| <meta name="twitter:site" content="@EclipseHono"> |
| <meta name="twitter:title" content="CoAP Adapter :: Eclipse Hono&trade; Vers.: dev"> |
| <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="CoAP Adapter :: Eclipse Hono&trade; Vers.: dev" /> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="https://www.eclipse.org/hono/docs/dev/user-guide/coap-adapter//" /> |
| <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" /> |
| |
| </head> |
| <body class="" data-url="/hono/docs/dev/user-guide/coap-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?1585103013"></script> |
| <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1585103013"></script> |
| <script type="text/javascript"> |
| |
| var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev"; |
| |
| </script> |
| <script type="text/javascript" src="/hono/docs/js/search.js?1585103013"></script> |
| |
| |
| </div> |
| |
| <div class="highlightable"> |
| <ul class="topics"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/" title="Concepts" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/concepts/"> |
| <i class="far fa-lightbulb"></i> Concepts |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/device-identity/" title="Device Identity" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/device-identity/"> |
| Device Identity |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/tenancy/" title="Multi-Tenancy" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/tenancy/"> |
| Multi-Tenancy |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/device-provisioning/" title="Device Provisioning" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/device-provisioning/"> |
| Device Provisioning |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/connecting-devices/" title="Connecting Devices" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/connecting-devices/"> |
| Connecting Devices |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/device-notifications/" title="Device Notifications" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/device-notifications/"> |
| Device Notifications |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/command-and-control/" title="Command & Control" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/command-and-control/"> |
| Command & Control |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/resource-limits/" title="Resource limits" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/resource-limits/"> |
| Resource limits |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/concepts/connection-events/" title="Connection Events" class="dd-item "> |
| <a href="/hono/docs/dev/concepts/connection-events/"> |
| Connection Events |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/" title="User Guide" class="dd-item |
| parent |
| |
| |
| "> |
| <a href="/hono/docs/dev/user-guide/"> |
| <i class="fas fa-book-reader"></i> User Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/device-registry/" title="Device Registry" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/device-registry/"> |
| Device Registry |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/http-adapter/"> |
| HTTP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/mqtt-adapter/"> |
| MQTT Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/amqp-adapter/"> |
| AMQP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/coap-adapter/" title="CoAP Adapter" class="dd-item active"> |
| <a href="/hono/docs/dev/user-guide/coap-adapter/"> |
| CoAP Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/kura-adapter/"> |
| Kura Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/sigfox-adapter/"> |
| Sigfox Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item "> |
| <a href="/hono/docs/dev/user-guide/jmeter_load_tests/"> |
| Load Tests with JMeter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/" title="Admin Guide" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/admin-guide/"> |
| <i class="fas fa-sliders-h"></i> Admin Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/common-config/" title="Common Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/common-config/"> |
| Common Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/auth-server-config/"> |
| Auth Server Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/device-registry-config/" title="Device Registry Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/device-registry-config/"> |
| Device Registry Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/device-connection-config/"> |
| Device Connection Service Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/http-adapter-config/"> |
| HTTP Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/amqp-adapter-config/"> |
| AMQP Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/mqtt-adapter-config/"> |
| MQTT Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/kura-adapter-config/"> |
| Kura Adapter Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/hono-client-configuration/"> |
| Hono Client Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/amqp-network-config/"> |
| AMQP 1.0 Messaging Network Configuration |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/secure_communication/" title="Secure Communication" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/secure_communication/"> |
| Secure Communication |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/admin-guide/monitoring-tracing-config/" title="Monitoring & Tracing" class="dd-item "> |
| <a href="/hono/docs/dev/admin-guide/monitoring-tracing-config/"> |
| Monitoring & Tracing |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/dev-guide/" title="Developer Guide" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/dev-guide/"> |
| <i class="fas fa-tools"></i> Developer Guide |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/dev-guide/building_hono/" title="Building from Source" class="dd-item "> |
| <a href="/hono/docs/dev/dev-guide/building_hono/"> |
| Building from Source |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/dev-guide/amqp_adapter_client/" title="AMQP Adapter Client for Java" class="dd-item "> |
| <a href="/hono/docs/dev/dev-guide/amqp_adapter_client/"> |
| AMQP Adapter Client for Java |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item "> |
| <a href="/hono/docs/dev/dev-guide/java_client_consumer/"> |
| Consuming Messages from Java |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item "> |
| <a href="/hono/docs/dev/dev-guide/custom_http_adapter/"> |
| Implement a Custom Hono HTTP Protocol Adapter |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/" title="API" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/api/"> |
| <i class='fas fa-plug'></i> API |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/telemetry/" title="Telemetry API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/telemetry/"> |
| Telemetry API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/event/" title="Event API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/event/"> |
| Event API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/command-and-control/" title="Command & Control API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/command-and-control/"> |
| Command & Control API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/tenant/" title="Tenant API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/tenant/"> |
| Tenant API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/device-connection/" title="Device Connection API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/device-connection/"> |
| Device Connection API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/device-registration/" title="Device Registration API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/device-registration/"> |
| Device Registration API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/credentials/" title="Credentials API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/credentials/"> |
| Credentials API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/authentication/" title="Authentication API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/authentication/"> |
| Authentication API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/management/" title="Device Registry Management API Specification" class="dd-item "> |
| <a href="/hono/docs/dev/api/management/"> |
| Device Registry Management API |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/api/metrics/" title="Metrics" class="dd-item "> |
| <a href="/hono/docs/dev/api/metrics/"> |
| Metrics |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/deployment/" title="Deployment" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/deployment/"> |
| <i class="fas fa-shipping-fast"></i> Deployment |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item "> |
| <a href="/hono/docs/dev/deployment/helm-based-deployment/"> |
| Helm based Deployment |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/deployment/openshift/" title="OpenShift / OKD" class="dd-item "> |
| <a href="/hono/docs/dev/deployment/openshift/"> |
| OpenShift / OKD |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item "> |
| <a href="/hono/docs/dev/deployment/create-kubernetes-cluster/"> |
| Setting up a Kubernetes Cluster |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item "> |
| <a href="/hono/docs/dev/deployment/resource-limitation/"> |
| Limiting Resource Usage |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/architecture/" title="Architecture" class="dd-item |
| |
| |
| |
| "> |
| <a href="/hono/docs/dev/architecture/"> |
| <i class="fas fa-landmark"></i> Architecture |
| |
| </a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/architecture/component-view/" title="Component View" class="dd-item "> |
| <a href="/hono/docs/dev/architecture/component-view/"> |
| Component View |
| |
| </a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li data-nav-id="/hono/docs/dev/architecture/auth/" title="Authentication/Authorization" class="dd-item "> |
| <a href="/hono/docs/dev/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="/hono/docs/user-guide/coap-adapter/">stable (1.2)</option> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <option id="dev" value="/hono/docs/dev/user-guide/coap-adapter/" selected>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>© 2020 <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>dev</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/coap-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/dev/'>Documentation</a> > <a href='/hono/docs/dev/user-guide/'>User Guide</a> > CoAP Adapter |
| |
| |
| |
| |
| |
| |
| |
| </span> |
| </div> |
| |
| <div class="progress"> |
| <div class="wrapper"> |
| <nav id="TableOfContents"> |
| <ul> |
| <li> |
| <ul> |
| <li><a href="#device-authentication">Device Authentication</a> |
| <ul> |
| <li><a href="#psk">PSK</a></li> |
| </ul></li> |
| <li><a href="#message-limits">Message Limits</a></li> |
| <li><a href="#coap-content-format-codes">CoAP Content Format Codes</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="#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="#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> |
| <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></li> |
| </ul> |
| </nav> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| |
| |
| <div id="body-inner"> |
| |
| <h1>CoAP Adapter</h1> |
| |
| |
| |
| |
| |
| <p>The CoAP protocol adapter exposes <a href="https://tools.ietf.org/html/rfc7252">CoAP</a> based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.</p> |
| |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Experimental</h4> |
| <div>The CoAP adapter has not yet reached the level of maturity of the other standard adapters. In particular, the resources implemented by the adapter might |
| still be subject to change.</div> |
| </div> |
| |
| |
| <h2 id="device-authentication">Device Authentication</h2> |
| |
| <p>The CoAP adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. |
| The adapter (currently) only supports <a href="https://tools.ietf.org/html/rfc4279">PSK</a> as part of a DTLS handshake for that purpose. |
| Additional variants mentioned in <a href="https://tools.ietf.org/html/rfc7252#section-9">Securing CoAP</a> might be added in the future.</p> |
| |
| <p>The adapter tries to authenticate the device using these mechanisms in the following order</p> |
| |
| <h3 id="psk">PSK</h3> |
| |
| <p>The <em>identity</em> provided in the ClientKeyExchange must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>. |
| The adapter performs the handshake using the credentials the <a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">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 |
| with the <em>tenant</em> and <em>auth-id</em> provided by the device in the <em>identity</em> and <code>psk</code> as the <em>type</em> of secret as query parameters.</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 secrets. The example deployment as described in the <a href="/hono/docs/dev/deployment/">Deployment Guides</a> comes pre-configured |
| with the corresponding entities in its device registry component. |
| Please refer to the <a href="/hono/docs/dev/api/credentials/#standard-credential-types">Credentials API</a> for details regarding the different |
| types of secrets.</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/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p> |
| |
| <h2 id="message-limits">Message Limits</h2> |
| |
| <p>Before accepting any telemetry or event or command messages, the CoAP adapter verifies that the configured <a href="/hono/docs/dev/concepts/resource-limits/#messages-limit">message limit</a> is not exceeded. |
| For CoAP currently only the messages limit is verified, the connections limit is not available. If the limit is exceeded then the incoming message is discarded with the status code <code>429 Too Many Requests</code>.</p> |
| |
| <h2 id="coap-content-format-codes">CoAP Content Format Codes</h2> |
| |
| <p>CoAP doesn’t use a textual identifier for content types. Instead numbers are used, which are maintained by the <a href="https://www.iana.org/">IANA</a>. |
| The <a href="https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats">IANA - CoAP Content Formats</a> page lists all |
| (currently) registered codes and the corresponding media types.</p> |
| |
| <h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2> |
| |
| <p>The device is authenticated using PSK.</p> |
| |
| <ul> |
| <li>URI: <code>/telemetry</code></li> |
| <li>Method: <code>POST</code></li> |
| <li>Type: |
| |
| <ul> |
| <li><code>CON</code>: <em>at least once</em> delivery semantics</li> |
| <li><code>NON</code>: <em>at most once</em> delivery semantics</li> |
| </ul></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command</code> for one-way-commands and |
| <code>command_response/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device.</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</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).</p> |
| |
| <p>If the <code>hono-ttd</code> <em>URI-query</em> option is set in order to receive a command and if the authenticated device is actually a gateway, |
| the returned command will be the first command that the north bound application has sent to either the gateway itself or to <em>any</em> |
| device that has last sent a telemetry or event message via this gateway.</p> |
| |
| <p><strong>Examples</strong></p> |
| |
| <p>The examples provided below make use of the <em>coap-client</em> command line tool which is part of the <a href="https://libcoap.net/">libcoap project</a>. |
| Precompiled packages should be available for different Linux variants.</p> |
| |
| <p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4> |
| <div><em>coap-client</em> only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.</div> |
| </div> |
| |
| |
| <p>Publish some JSON data for device <code>4711</code> using message type <code>NON</code> (<em>at most once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -N -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4> |
| <div>In the example above the response actually contains payload that should be used as input to a command to be executed by the device. |
| This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could |
| send any commands to the device.</div> |
| </div> |
| |
| |
| <h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2> |
| |
| <ul> |
| <li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type: |
| |
| <ul> |
| <li><code>CON</code>: <em>at least once</em> delivery semantics</li> |
| <li><code>NON</code>: <em>at most once</em> delivery semantics</li> |
| </ul></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command</code> for one-way-commands and |
| <code>command_response/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| <li>The given device does not belong to the given tenant.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the |
| <code>HONO_COAP_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> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4711</code> using message type <code>NON</code> (<em>at most once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -N -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2> |
| |
| <ul> |
| <li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type: |
| |
| <ul> |
| <li><code>CON</code>: <em>at least once</em> delivery semantics</li> |
| <li><code>NON</code>: <em>at most once</em> delivery semantics</li> |
| </ul></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command/${tenantId}/${deviceId}</code> for one-way-commands and |
| <code>command_response/${tenantId}/${deviceId}/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. Note that in both cases the <code>${tenantId}/${deviceId}</code> path segments indicate the device that |
| the command is targeted at. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li> |
| <li>The device belongs to another tenant than the gateway.</li> |
| <li>The gateway is not authorized to act <em>on behalf of</em> the device.</li> |
| <li>The gateway associated with the device is not registered or disabled.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource 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 URI 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/dev/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> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4712</code> using message type <code>NON</code> (<em>at most once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -N -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code> |
| which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p> |
| |
| <h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2> |
| |
| <p>The device is authenticated using PSK.</p> |
| |
| <ul> |
| <li>URI: <code>/event</code></li> |
| <li>Method: <code>POST</code></li> |
| <li>Type:<code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command</code> for one-way-commands and |
| <code>command_response/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</li> |
| </ul></li> |
| </ul> |
| |
| <p>This is the preferred way for devices to publish events. It is available only if the protocol adapter is configured to require |
| devices to authenticate (which is the default).</p> |
| |
| <p>If the <code>hono-ttd</code> <em>URI-query</em> option is set in order to receive a command and if the authenticated device is actually a gateway, |
| the returned command will be the first command that the north bound application has sent to either the gateway itself or to <em>any</em> |
| device that has last sent a telemetry or event message via this gateway.</p> |
| |
| <p><strong>Examples</strong></p> |
| |
| <p>The examples provided below make use of the <em>coap-client</em> command line tool which is part of the <a href="https://libcoap.net/">libcoap project</a>. |
| Precompiled packages should be available for different Linux variants.</p> |
| |
| <p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4> |
| <div><em>coap-client</em> only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.</div> |
| </div> |
| |
| |
| <p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <div class="alert alert-notice"> |
| <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4> |
| <div>In the example above the response actually contains payload that should be used as input to a command to be executed by the device. |
| This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could |
| send any commands to the device.</div> |
| </div> |
| |
| |
| <h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2> |
| |
| <ul> |
| <li>URI: <code>/event/${tenantId}/${deviceId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type:<code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command</code> for one-way-commands and |
| <code>command_response/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| <li>The given device does not belong to the given tenant.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the |
| <code>HONO_COAP_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> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2> |
| |
| <ul> |
| <li>URI: <code>/event/${tenantId}/${deviceId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type:<code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li> |
| <li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li> |
| </ul></li> |
| <li>Response Options: |
| |
| <ul> |
| <li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body. |
| This option will only be present if the response contains a command to be executed by the device which requires input data. |
| Note that this option will be empty if the media type contained in the command (AMQP) message’s <em>content-type</em> property cannot |
| be mapped to one of the registered CoAP <em>content-format</em> codes.</li> |
| <li>(optional) <code>location-query</code>: The <code>hono-command</code> query parameter contains the name of the command to execute. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| <li>(optional) <code>location-path</code>: The location path is <code>command/${tenantId}/${deviceId}</code> for one-way-commands and |
| <code>command_response/${tenantId}/${deviceId}/<command-request-id></code> for commands expecting a response. |
| In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its |
| response to the command. Note that in both cases the <code>${tenantId}/${deviceId}</code> path segments indicate the device that |
| the command is targeted at. |
| This option will only be present if the response contains a command to be executed by the device.</li> |
| </ul></li> |
| <li>Response Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li> |
| <li>(optional) Error details, if status code is >= 4.00.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute. |
| Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been |
| delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits |
| for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li> |
| <li>4.00 (Bad Request): The request cannot be processed. Possible reasons include: |
| |
| <ul> |
| <li>the request body is empty and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter</li> |
| </ul></li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li> |
| <li>The device belongs to another tenant than the gateway.</li> |
| <li>The gateway is not authorized to act <em>on behalf of</em> the device.</li> |
| <li>The gateway associated with the device is not registered or disabled.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of telemetry data for the given tenant |
| connected to Hono.</li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource 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 URI 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/dev/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> using default message type <code>CON</code> (<em>at least once</em>):</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}' |
| </code></pre> |
| |
| <p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712?hono-ttd=10 -t application/json -e '{"temp": 5}' |
| |
| { |
| "brightness": 87 |
| } |
| </code></pre> |
| |
| <p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code> |
| which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p> |
| |
| <h2 id="sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</h2> |
| |
| <p>The device is authenticated using PSK.</p> |
| |
| <ul> |
| <li>URI: <code>/command_response/${commandRequestId}</code></li> |
| <li>Method: <code>POST</code></li> |
| <li>Type: <code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body. |
| This option must be set if the result of processing the command on the device is non-empty. In this case the result data is |
| contained in the request body.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data representing the result of processing the command on the device.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li> |
| <li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: |
| |
| <ul> |
| <li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li> |
| <li>The application has already given up on waiting for a response.</li> |
| </ul></li> |
| </ul></li> |
| </ul> |
| |
| <p>This is the preferred way for devices to respond to commands. It is available only if the protocol adapter is configured to require devices to |
| authenticate (which is the default).</p> |
| |
| <p><strong>Example</strong></p> |
| |
| <p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4711</code>:</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/req-id-uuid?hono-cmd-status=200 |
| </code></pre> |
| |
| <h2 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h2> |
| |
| <ul> |
| <li>URI: <code>/command_response/${tenantId}/${deviceId}/${commandRequestId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type: <code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body. |
| This option must be set if the result of processing the command on the device is non-empty. In this case the result data is |
| contained in the request body.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data representing the result of processing the command on the device.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li> |
| <li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| <li>The given device does not belong to the given tenant.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: |
| |
| <ul> |
| <li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li> |
| <li>The application has already given up on waiting for a response.</li> |
| </ul></li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the |
| <code>HONO_HTTP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p> |
| |
| <p><strong>Examples</strong></p> |
| |
| <p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for the unauthenticated device <code>4711</code>:</p> |
| |
| <pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status=200 -e '{"brightness-changed": true}' |
| </code></pre> |
| |
| <h2 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h2> |
| |
| <ul> |
| <li>URI: <code>/command_response/${tenantId}/${deviceId}/${commandRequestId}</code></li> |
| <li>Method: <code>PUT</code></li> |
| <li>Type: <code>CON</code></li> |
| <li>Request Options: |
| |
| <ul> |
| <li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body. |
| This option must be set if the result of processing the command on the device is non-empty. In this case the result data is |
| contained in the request body.</li> |
| </ul></li> |
| <li>Query Parameters: |
| |
| <ul> |
| <li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li> |
| </ul></li> |
| <li>Request Body: |
| |
| <ul> |
| <li>(optional) Arbitrary data representing the result of processing the command on the device.</li> |
| </ul></li> |
| <li>Response Codes: |
| |
| <ul> |
| <li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li> |
| <li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li> |
| <li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. |
| Possible reasons for this include: |
| |
| <ul> |
| <li>The given tenant is not allowed to use this protocol adapter.</li> |
| <li>The given device does not belong to the given tenant.</li> |
| <li>The gateway is not authorized to act <em>on behalf of</em> the device.</li> |
| <li>The gateway associated with the device is not registered or disabled.</li> |
| </ul></li> |
| <li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li> |
| <li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li> |
| <li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include: |
| |
| <ul> |
| <li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li> |
| <li>The application has already given up on waiting for a response.</li> |
| </ul></li> |
| </ul></li> |
| </ul> |
| |
| <p>This resource can be used by <em>gateway</em> components to send the response to a command <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 URI are used |
| to identify the device that the gateway publishes data for.</p> |
| |
| <p>The protocol adapter checks the gateway’s authority to send responses to a command on behalf of the device implicitly by means of |
| retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p> |
| |
| <p><strong>Examples</strong></p> |
| |
| <p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4712</code>:</p> |
| |
| <pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4712/req-id-uuid?hono-cmd-status=200 -e '{"brightness-changed": true}' |
| </code></pre> |
| |
| <p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code> which is |
| authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p> |
| |
| <h2 id="downstream-meta-data">Downstream Meta Data</h2> |
| |
| <p>The adapter includes the following meta data in the application properties of messages being sent downstream:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th align="left">Name</th> |
| <th align="left">Type</th> |
| <th align="left">Description</th> |
| </tr> |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td align="left"><em>device_id</em></td> |
| <td align="left"><em>string</em></td> |
| <td align="left">The identifier of the device that the message originates from.</td> |
| </tr> |
| |
| <tr> |
| <td align="left"><em>orig_adapter</em></td> |
| <td align="left"><em>string</em></td> |
| <td 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 CoAP adapter’s type name is <code>hono-coap</code>.</td> |
| </tr> |
| |
| <tr> |
| <td align="left"><em>orig_address</em></td> |
| <td align="left"><em>string</em></td> |
| <td align="left">Contains the (relative) URI that the device has originally posted the data to.</td> |
| </tr> |
| |
| <tr> |
| <td align="left"><em>ttd</em></td> |
| <td align="left"><em>integer</em></td> |
| <td align="left">Contains the effective number of seconds that the device will wait for a response. This property is only set if the HTTP request contains the <code>hono-ttd</code> header or request parameter.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a> or the <a href="/hono/docs/dev/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 protocol adapter supports setting a |
| downstream event message’s <em>ttl</em> property based on the <em>hono-ttl</em> property set as a query parameter in the event requests by the devices. |
| Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the <a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p> |
| |
| <h2 id="tenant-specific-configuration">Tenant specific Configuration</h2> |
| |
| <p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-coap</code>. |
| The following properties are (currently) supported:</p> |
| |
| <table> |
| <thead> |
| <tr> |
| <th align="left">Name</th> |
| <th align="left">Type</th> |
| <th align="left">Default Value</th> |
| <th align="left">Description</th> |
| </tr> |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td align="left"><em>enabled</em></td> |
| <td align="left"><em>boolean</em></td> |
| <td align="left"><code>true</code></td> |
| <td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td> |
| </tr> |
| |
| <tr> |
| <td align="left"><em>max-ttd</em></td> |
| <td align="left"><em>integer</em></td> |
| <td align="left"><code>60</code></td> |
| <td align="left">Defines a tenant specific upper limit for the <em>time until disconnect</em> property that devices may include in requests for uploading telemetry data or events. Please refer to the <a href="/hono/docs/dev/concepts/command-and-control/">Command & Control concept page</a> for a discussion of this parameter’s purpose and usage.<br>This property can be set for the <code>hono-coap</code> adapter type as an <em>extension</em> property in the adapter section of the tenant configuration.<br>If it is not set, then the default value of <code>60</code> seconds is used.</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?1585103013"></script> |
| <script src="/hono/docs/js/perfect-scrollbar.min.js?1585103013"></script> |
| <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1585103013"></script> |
| <script src="/hono/docs/js/jquery.sticky.js?1585103013"></script> |
| <script src="/hono/docs/js/featherlight.min.js?1585103013"></script> |
| <script src="/hono/docs/js/html5shiv-printshiv.min.js?1585103013"></script> |
| <script src="/hono/docs/js/highlight.pack.js?1585103013"></script> |
| <script>hljs.initHighlightingOnLoad();</script> |
| <script src="/hono/docs/js/modernizr.custom.71422.js?1585103013"></script> |
| <script src="/hono/docs/js/learn.js?1585103013"></script> |
| <script src="/hono/docs/js/hugo-learn.js?1585103013"></script> |
| |
| <link href="/hono/docs/mermaid/mermaid.css?1585103013" type="text/css" rel="stylesheet" /> |
| <script src="/hono/docs/mermaid/mermaid.js?1585103013"></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> |
| |
