docs/1.1/api/device-connection/index.html - gerrit/www.eclipse.org/hono - Git at Google

 <!DOCTYPE html>
 <html lang="1.1" 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>Device Connection API Specification :: Eclipse Hono&trade; Vers.: 1.1</title>


     <link href="/hono/docs/css/nucleus.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/fontawesome-all.min.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/hybrid.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/featherlight.min.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/perfect-scrollbar.min.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/auto-complete.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/atom-one-dark-reasonable.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/theme.css?1626138733" rel="stylesheet">
     <link href="/hono/docs/css/hugo-theme.css?1626138733" rel="stylesheet">

     <link href="/hono/docs/css/theme-hono.css?1626138733" rel="stylesheet">

     <link href="/hono/docs/css/hono.css?1626138733" rel="stylesheet">

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138733"></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="Device Connection API Specification :: Eclipse Hono&amp;trade; Vers.: 1.1">
 <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="Device Connection API Specification :: Eclipse Hono&amp;trade; Vers.: 1.1" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.1/api/device-connection//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.1/api/device-connection/">
     <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?1626138733"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138733"></script>
 <script type="text/javascript">

         var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/1.1";

 </script>
 <script type="text/javascript" src="/hono/docs/js/search.js?1626138733"></script>


   </div>

     <div class="highlightable">
     <ul class="topics">


     <li data-nav-id="/hono/docs/1.1/concepts/" title="Concepts" class="dd-item


         ">
       <a href="/hono/docs/1.1/concepts/">
           <i class="far fa-lightbulb"></i> Concepts

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/concepts/device-identity/" title="Device Identity" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/device-identity/">
         Device Identity

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/tenancy/" title="Multi-Tenancy" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/tenancy/">
         Multi-Tenancy

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/device-provisioning/" title="Device Provisioning" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/device-provisioning/">
         Device Provisioning

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/connecting-devices/" title="Connecting Devices" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/connecting-devices/">
         Connecting Devices

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/device-notifications/" title="Device Notifications" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/device-notifications/">
         Device Notifications

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/command-and-control/" title="Command &amp; Control" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/command-and-control/">
         Command &amp; Control

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/resource-limits/" title="Resource limits" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/resource-limits/">
         Resource limits

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/concepts/connection-events/" title="Connection Events" class="dd-item ">
         <a href="/hono/docs/1.1/concepts/connection-events/">
         Connection Events

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/user-guide/" title="User Guide" class="dd-item


         ">
       <a href="/hono/docs/1.1/user-guide/">
           <i class="fas fa-book-reader"></i> User Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/user-guide/device-registry/" title="Device Registry" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/device-registry/">
         Device Registry

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/http-adapter/" title="HTTP Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/http-adapter/">
         HTTP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/mqtt-adapter/" title="MQTT Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/mqtt-adapter/">
         MQTT Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/amqp-adapter/" title="AMQP Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/amqp-adapter/">
         AMQP Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/kura-adapter/" title="Kura Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/kura-adapter/">
         Kura Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/sigfox-adapter/" title="Sigfox Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/sigfox-adapter/">
         Sigfox Adapter

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/user-guide/jmeter_load_tests/" title="Load Tests with JMeter" class="dd-item ">
         <a href="/hono/docs/1.1/user-guide/jmeter_load_tests/">
         Load Tests with JMeter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/admin-guide/" title="Admin Guide" class="dd-item


         ">
       <a href="/hono/docs/1.1/admin-guide/">
           <i class="fas fa-sliders-h"></i> Admin Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/admin-guide/common-config/" title="Common Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/common-config/">
         Common Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/auth-server-config/" title="Auth Server Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/auth-server-config/">
         Auth Server Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/device-registry-config/" title="Device Registry Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/device-registry-config/">
         Device Registry Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/device-connection-config/" title="Configuring the Device Connection Service" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/device-connection-config/">
         Device Connection Service Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/http-adapter-config/" title="HTTP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/http-adapter-config/">
         HTTP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/amqp-adapter-config/" title="AMQP Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/amqp-adapter-config/">
         AMQP Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/mqtt-adapter-config/" title="MQTT Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/mqtt-adapter-config/">
         MQTT Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/kura-adapter-config/" title="Kura Adapter Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/kura-adapter-config/">
         Kura Adapter Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/hono-client-configuration/" title="Hono Client Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/hono-client-configuration/">
         Hono Client Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/amqp-network-config/" title="AMQP 1.0 Messaging Network Configuration" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/amqp-network-config/">
         AMQP 1.0 Messaging Network Configuration

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/secure_communication/" title="Secure Communication" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/secure_communication/">
         Secure Communication

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/admin-guide/monitoring-tracing-config/" title="Monitoring &amp; Tracing" class="dd-item ">
         <a href="/hono/docs/1.1/admin-guide/monitoring-tracing-config/">
         Monitoring &amp; Tracing

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/dev-guide/" title="Developer Guide" class="dd-item


         ">
       <a href="/hono/docs/1.1/dev-guide/">
           <i class="fas fa-tools"></i> Developer Guide

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/dev-guide/building_hono/" title="Building from Source" class="dd-item ">
         <a href="/hono/docs/1.1/dev-guide/building_hono/">
         Building from Source

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/dev-guide/java_client_consumer/" title="Consuming Messages from Java" class="dd-item ">
         <a href="/hono/docs/1.1/dev-guide/java_client_consumer/">
         Consuming Messages from Java

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/dev-guide/custom_http_adapter/" title="Implement a Custom Hono HTTP Protocol Adapter" class="dd-item ">
         <a href="/hono/docs/1.1/dev-guide/custom_http_adapter/">
         Implement a Custom Hono HTTP Protocol Adapter

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/api/" title="API" class="dd-item
         parent


         ">
       <a href="/hono/docs/1.1/api/">
           &nbsp;<i class='fas fa-plug'></i>&nbsp;API

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/api/telemetry/" title="Telemetry API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/telemetry/">
         Telemetry API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/event/" title="Event API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/event/">
         Event API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/command-and-control/" title="Command &amp; Control API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/command-and-control/">
         Command &amp; Control API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/tenant/" title="Tenant API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/tenant/">
         Tenant API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/device-connection/" title="Device Connection API Specification" class="dd-item active">
         <a href="/hono/docs/1.1/api/device-connection/">
         Device Connection API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/device-registration/" title="Device Registration API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/device-registration/">
         Device Registration API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/credentials/" title="Credentials API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/credentials/">
         Credentials API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/authentication/" title="Authentication API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/authentication/">
         Authentication API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/management/" title="Device Registry Management API Specification" class="dd-item ">
         <a href="/hono/docs/1.1/api/management/">
         Device Registry Management API

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/api/metrics/" title="Metrics" class="dd-item ">
         <a href="/hono/docs/1.1/api/metrics/">
         Metrics

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/deployment/" title="Deployment" class="dd-item


         ">
       <a href="/hono/docs/1.1/deployment/">
           <i class="fas fa-shipping-fast"></i> Deployment

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/deployment/helm-based-deployment/" title="Helm based Deployment" class="dd-item ">
         <a href="/hono/docs/1.1/deployment/helm-based-deployment/">
         Helm based Deployment

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/deployment/openshift/" title="OpenShift / OKD" class="dd-item ">
         <a href="/hono/docs/1.1/deployment/openshift/">
         OpenShift / OKD

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/deployment/create-kubernetes-cluster/" title="Setting up a Kubernetes Cluster" class="dd-item ">
         <a href="/hono/docs/1.1/deployment/create-kubernetes-cluster/">
         Setting up a Kubernetes Cluster

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/deployment/resource-limitation/" title="Limiting Resource Usage" class="dd-item ">
         <a href="/hono/docs/1.1/deployment/resource-limitation/">
         Limiting Resource Usage

         </a>
     </li>


         </ul>

     </li>


     <li data-nav-id="/hono/docs/1.1/architecture/" title="Architecture" class="dd-item


         ">
       <a href="/hono/docs/1.1/architecture/">
           <i class="fas fa-landmark"></i> Architecture

       </a>


         <ul>


       <li data-nav-id="/hono/docs/1.1/architecture/component-view/" title="Component View" class="dd-item ">
         <a href="/hono/docs/1.1/architecture/component-view/">
         Component View

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.1/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.1/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&#39;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:&nbsp;
           <div class="select-style">
             <select id="select-language" onchange="location = this.value;">


                       <option id="stable" value="https://www.eclipse.org/hono/docs/api/device-connection/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/api/device-connection/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/api/device-connection/">1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/api/device-connection/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/api/device-connection/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/api/device-connection/">1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/api/device-connection/">1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/api/device-connection/">1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/api/device-connection/" selected>1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/api/device-connection/">1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/api/device-connection/">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>&copy; 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.1</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/api/device-connection/index.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.1/'>Documentation</a> > <a href='/hono/docs/1.1/api/'>API</a> > Device Connection API Specification


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#preconditions-for-invoking-the-device-connection-api">Preconditions for invoking the Device Connection API</a></li>
     <li><a href="#set-last-known-gateway-for-device">Set last known Gateway for Device</a></li>
     <li><a href="#get-last-known-gateway-for-device">Get last known Gateway for Device</a></li>
     <li><a href="#standard-message-properties">Standard Message Properties</a>
       <ul>
         <li><a href="#standard-request-properties">Standard Request Properties</a></li>
         <li><a href="#standard-response-properties">Standard Response Properties</a></li>
       </ul>
     </li>
     <li><a href="#delivery-states">Delivery States</a></li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Device Connection API Specification
             </h1>


 <p>The <em>Device Connection API</em> is used by <em>Protocol Adapters</em> to set and retrieve information about the connections from devices or gateways to the protocol adapters.</p>
 <p>The Device Connection API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.</p>
 <p><a name="preconditions"></a></p>
 <h2 id="preconditions-for-invoking-the-device-connection-api">Preconditions for invoking the Device Connection API</h2>
 <ol>
 <li>Client has established an AMQP connection with the Device Connection service.</li>
 <li>Client has established an AMQP link in role <em>sender</em> on the connection using target address <code>device_con/${tenant_id}</code>. This link is used by the client to send commands concerning device connections to Hono.</li>
 <li>Client has established an AMQP link in role <em>receiver</em> on the connection using source address <code>device_con/${tenant_id}/${reply-to}</code> where <em>reply-to</em> may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Device Connection service. This link&rsquo;s source address is also referred to as the <em>reply-to</em> address for the request messages.</li>
 </ol>
 <figure>
     <img src="preconditions.svg"
          alt="A client establishes an AMQP connection and the links required to invoke operations of the Device Connection service"/> <figcaption>
             <h4>Client connecting to Device Connection service</h4>
         </figcaption>
 </figure>

 <h2 id="set-last-known-gateway-for-device">Set last known Gateway for Device</h2>
 <p>Clients use this command to <em>set</em> the gateway that last acted on behalf of a given device.</p>
 <p>As this operation is invoked frequently by Hono&rsquo;s components, implementors may choose to keep this information in memory. This API doesn&rsquo;t mandate checks on the validity of the given device or gateway IDs in order not to introduce a dependency on the <em>Device Registration API</em>. However, implementations of this API may choose to perform such checks or impose a restriction on the overall amount of data that can be stored per tenant in order to protect against malicious requests.</p>
 <p><strong>Message Flow</strong></p>
 <figure>
     <img src="set_last_known_gateway_success.svg"
          alt="A client sends a request message for setting the last known gateway and receives a response containing a confirmation"/> <figcaption>
             <h4>Client sets the last known gateway for a device</h4>
         </figcaption>
 </figure>

 <p><strong>Request Message Format</strong></p>
 <p>The following table provides an overview of the properties a client needs to set on a message to set the last known gateway for a device in addition to the <a href="#standard-request-properties">Standard Request Properties</a>.</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>subject</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to <code>set-last-gw</code>.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>gateway_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The identifier of the gateway that last acted on behalf of the device identified by the <em>device_id</em> property. If a device connects directly instead of through a gateway, the device&rsquo;s identifier MUST be specified here.</td>
 </tr>
 </tbody>
 </table>
 <p>The body of the message SHOULD be empty and will be ignored if it is not.</p>
 <p><strong>Response Message Format</strong></p>
 <p>A response to a <em>set last known gateway for device</em> request contains the <a href="#standard-response-properties">Standard Response Properties</a>.</p>
 <p>The response message&rsquo;s <em>status</em> property may contain the following codes:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Code</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>204</em></td>
 <td style="text-align:left">OK, the last known gateway for the device has been updated.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>400</em></td>
 <td style="text-align:left">Bad Request, the last known gateway has not been updated due to invalid or missing data in the request.</td>
 </tr>
 </tbody>
 </table>
 <p>Implementors of this API may return a <em>404</em> status code in order to indicate that no device and/or gateway with the given identifier exists for the given tenant. However, performing such a check is optional.</p>
 <p>For status codes indicating an error (codes in the <code>400 - 499</code> range) the message body MAY contain a detailed description of the error that occurred.</p>
 <h2 id="get-last-known-gateway-for-device">Get last known Gateway for Device</h2>
 <p>Clients use this command to <em>retrieve</em> the gateway that last acted on behalf of a given device.</p>
 <p><strong>Message Flow</strong></p>
 <figure>
     <img src="get_last_known_gateway_success.svg"
          alt="A client sends a request message for retrieving the last known gateway and receives a response containing the information"/> <figcaption>
             <h4>Client retrieving the last known gateway for a device</h4>
         </figcaption>
 </figure>

 <p><strong>Request Message Format</strong></p>
 <p>The following table provides an overview of the properties a client needs to set on a message to retrieve the last known gateway for a device in addition to the <a href="#standard-request-properties">Standard Request Properties</a>.</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>subject</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to <code>get-last-gw</code>.</td>
 </tr>
 </tbody>
 </table>
 <p>The body of the message SHOULD be empty and will be ignored if it is not.</p>
 <p><strong>Response Message Format</strong></p>
 <p>A response to a <em>get last known gateway for device</em> request contains the <a href="#standard-response-properties">Standard Response Properties</a> as well as the properties shown in the following table:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>content-type</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to <code>application/json</code> if the invocation of the operation was successful and the body of the response message contains payload as described below.</td>
 </tr>
 </tbody>
 </table>
 <p>The result of a successful invocation is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.</p>
 <p>The response message JSON object has the following properties:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">JSON Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>gateway-id</em></td>
 <td style="text-align:center"><em>yes</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The ID of the last known gateway for the device.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>last-updated</em></td>
 <td style="text-align:center"><em>no</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">The date that the information about the last known gateway for the device was last updated. The value MUST be an <a href="https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations">ISO 8601 compliant <em>combined date and time representation in extended format</em></a>.</td>
 </tr>
 </tbody>
 </table>
 <p>The response message&rsquo;s <em>status</em> property may contain the following codes:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Code</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>200</em></td>
 <td style="text-align:left">OK, the payload contains the gateway ID.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>400</em></td>
 <td style="text-align:left">Bad Request, the request message does not contain all required information/properties.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>404</em></td>
 <td style="text-align:left">Not Found, there is no last known gateway assigned to the device.</td>
 </tr>
 </tbody>
 </table>
 <p>Implementors of this API may return a <em>404</em> status code in order to indicate that no device with the given identifier exists for the given tenant. However, performing such a check is optional.</p>
 <p>For status codes indicating an error (codes in the <code>400 - 499</code> range) the message body MAY contain a detailed description of the error that occurred.</p>
 <h2 id="standard-message-properties">Standard Message Properties</h2>
 <p>Due to the nature of the request/response message pattern of the operations of the Device Connection API, there are some standard properties shared by all of the request and response messages exchanged as part of the operations.</p>
 <h3 id="standard-request-properties">Standard Request Properties</h3>
 <p>The following table provides an overview of the properties shared by all request messages regardless of the particular operation being invoked.</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>subject</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST be set to the value defined by the particular operation being invoked.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>correlation-id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:left">MAY contain an ID used to correlate a response message to the original request. If set, it is used as the <em>correlation-id</em> property in the response, otherwise the value of the <em>message-id</em> property is used. Either this or the <em>message-id</em> property MUST be set.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MAY contain an identifier that uniquely identifies the message at the sender side. Either this or the <em>correlation-id</em> property MUST be set.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>reply-to</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST contain the source address that the client wants to received response messages from. This address MUST be the same as the source address used for establishing the client&rsquo;s receive link (see <a href="#preconditions-for-invoking-the-device-connection-api">Preconditions</a>).</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>device_id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">MUST contain the ID of the device that is subject to the operation.</td>
 </tr>
 </tbody>
 </table>
 <h3 id="standard-response-properties">Standard Response Properties</h3>
 <p>The following table provides an overview of the properties shared by all response messages regardless of the particular operation being invoked.</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Name</th>
 <th style="text-align:center">Mandatory</th>
 <th style="text-align:left">Location</th>
 <th style="text-align:left">AMQP Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>correlation-id</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>properties</em></td>
 <td style="text-align:left"><em>message-id</em></td>
 <td style="text-align:left">Contains the <em>message-id</em> (or the <em>correlation-id</em>, if specified) of the request message that this message is the response to.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>status</em></td>
 <td style="text-align:center">yes</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>int</em></td>
 <td style="text-align:left">Contains the status code indicating the outcome of the operation. Concrete values and their semantics are defined for each particular operation.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>cache_control</em></td>
 <td style="text-align:center">no</td>
 <td style="text-align:left"><em>application-properties</em></td>
 <td style="text-align:left"><em>string</em></td>
 <td style="text-align:left">Contains an <a href="https://tools.ietf.org/html/rfc2616#section-14.9">RFC 2616</a> compliant <em>cache directive</em>. The directive contained in the property MUST be obeyed by clients that are caching responses.</td>
 </tr>
 </tbody>
 </table>
 <h2 id="delivery-states">Delivery States</h2>
 <p>Hono uses the following AMQP message delivery states when receiving request messages from clients:</p>
 <table>
 <thead>
 <tr>
 <th style="text-align:left">Delivery State</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>ACCEPTED</em></td>
 <td style="text-align:left">Indicates that the request message has been received and accepted for processing.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>REJECTED</em></td>
 <td style="text-align:left">Indicates that Hono has received the request but was not able to process it. The <em>error</em> field contains information regarding the reason why. Clients should not try to re-send the request using the same message properties in this case.</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?1626138733"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138733"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138733"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138733"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138733"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138733"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138733"></script>
     <script src="/hono/docs/js/learn.js?1626138733"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138733"></script>

     <link href="/hono/docs/mermaid/mermaid.css?1626138733" rel="stylesheet" />
     <script src="/hono/docs/mermaid/mermaid.js?1626138733"></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>