docs/1.0/api/command-and-control/index.html - gerrit/www.eclipse.org/hono - Git at Google

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


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

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

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

     <script src="/hono/docs/js/jquery-3.3.1.min.js?1626138735"></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="Command &amp; Control API Specification :: Eclipse Hono&amp;trade; Vers.: 1.0">
 <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="Command &amp; Control API Specification :: Eclipse Hono&amp;trade; Vers.: 1.0" />
 <meta property="og:type" content="website" />
 <meta property="og:url" content="https://www.eclipse.org/hono/docs/1.0/api/command-and-control//" />
 <meta property="og:image" content="https://www.eclipse.org/hono/docs/images/twitter_image.png" />

   </head>
   <body class="" data-url="/hono/docs/1.0/api/command-and-control/">
     <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?1626138735"></script>
 <script type="text/javascript" src="/hono/docs/js/auto-complete.js?1626138735"></script>
 <script type="text/javascript">

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

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


   </div>

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


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


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

         </a>
     </li>


         </ul>

     </li>


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


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

       </a>


         <ul>


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

         </a>
     </li>


       <li data-nav-id="/hono/docs/1.0/architecture/auth/" title="Authentication/Authorization" class="dd-item ">
         <a href="/hono/docs/1.0/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/command-and-control/">stable (1.8)</option>


                       <option id="1.8" value="https://www.eclipse.org/hono/docs/1.8/api/command-and-control/">1.8</option>


                       <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/api/command-and-control/">1.7</option>


                       <option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/api/command-and-control/">1.6</option>


                       <option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/api/command-and-control/">1.5</option>


                       <option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/api/command-and-control/">1.4</option>


                       <option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/api/command-and-control/">1.3</option>


                       <option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/api/command-and-control/">1.2</option>


                       <option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/api/command-and-control/">1.1</option>


                       <option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/api/command-and-control/" selected>1.0</option>


                       <option id="dev" value="https://www.eclipse.org/hono/docs/dev/api/command-and-control/">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.0</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/command-and-control/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.0/'>Documentation</a> > <a href='/hono/docs/1.0/api/'>API</a> > Command & Control API Specification


                   </span>
                 </div>

                     <div class="progress">
     <div class="wrapper">
 <nav id="TableOfContents">
   <ul>
     <li><a href="#send-a-one-way-command">Send a One-Way Command</a></li>
     <li><a href="#send-a-requestresponse-command">Send a (Request/Response) Command</a></li>
   </ul>
 </nav>
     </div>
 </div>


               </div>
             </div>

         <div id="head-tags">

         </div>

         <div id="body-inner">

             <h1>

               Command &amp; Control API Specification
             </h1>


 <p>The <em>Command &amp; Control</em> API of Eclipse Hono™ is used by <em>Business Applications</em> to send commands to connected devices.</p>
 <p>Commands can be used to trigger actions on devices. Examples include updating a configuration property, installing a software component or switching the state of an actuator.</p>
 <p>Hono distinguishes two types of commands. The first type is <em>one-way</em> only. In this case the sender of the command does not expect the device to send back a message in response to the command. This type of command is referred to as a <em>one-way command</em> in the remainder of this page. One-way commands may be used to e.g. <em>notify</em> a device about a change of state.</p>
 <p>The second type of commands expects a <em>response</em> to be sent back from the device as a result of processing the command. In this case the response contains a <em>status</em> code which indicates whether the command could be processed successfully. If so, the response may also include data representing the result of processing the command. This type of command is plainly referred to as a <em>command</em> because it represents the default case.</p>
 <p>The Command &amp; Control API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using AMQP 1.0 in order to invoke operations of the API as described in the following sections. Throughout the remainder of this page we will simply use AMQP when referring to AMQP 1.0.</p>
 <h2 id="send-a-one-way-command">Send a One-Way Command</h2>
 <p>Business Applications use this operation to send a command to a device for which they do not expect to receive a response from the device.</p>
 <p><strong>Preconditions</strong></p>
 <ol>
 <li>The <em>Business Application</em> has established an AMQP connection with the AMQP 1.0 Network.</li>
 <li>The <em>Business Application</em> has established an AMQP link in role <em>sender</em> with the target address <code>command/${tenant_id}</code>, where <code>${tenant_id}</code> is the ID of the tenant that the device belongs to. This link is used by the <em>Business Application</em> to send command messages.</li>
 </ol>
 <p>The following sequence diagram illustrates the establishment of the required link:</p>
 <figure>
     <img src="send_preconditions.svg"/> <figcaption>
             <h4>Application connecting to the AMQP 1.0 Messaging Network</h4>
         </figcaption>
 </figure>

 <div class="alert alert-notice">
     <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4>
     <div><p>Previous versions of Hono required applications to</p>
 <ul>
 <li>use a sender link with target address <code>control/${tenant_id}/${device_id}</code> for sending one-ways commands to a specific device.</li>
 </ul>
 <p>This link address can still be used but support for it will be removed in a future version of Hono!
 Newly built applications should <strong>only</strong> use the tenant scoped link as described above.
 Note that the deprecated link address also <strong>does not</strong> support sending commands to devices connected via a gateway.</p>
 </div>
 </div>
 <p><strong>Message Format</strong></p>
 <p>The following table provides an overview of the properties the <em>Business Application</em> needs to set on a one-way command message.</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">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>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 target address <code>command/${tenant_id}/${device_id}</code> of the message, where <code>${device_id}</code> is the ID of the device to send the message to.</td>
 </tr>
 <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">The name of the command to be executed by the device.</td>
 </tr>
 <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">If present, MUST contain a <em>Media Type</em> as defined by <a href="https://tools.ietf.org/html/rfc2046">RFC 2046</a> which describes the semantics and format of the command&rsquo;s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.</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">An identifier that uniquely identifies the message at the sender side.</td>
 </tr>
 </tbody>
 </table>
 <p>The command message MAY contain arbitrary payload to be sent to the device in a single AMQP <em>Data</em> section. The value of the message&rsquo;s <em>subject</em> property may provide a hint to the device regarding the format, encoding and semantics of the payload data.</p>
 <p>Hono indicates the outcome of the operation by means of the following AMQP delivery states:</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"><code>accepted</code></td>
 <td style="text-align:left">The command has been delivered to the device for processing.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>released</code></td>
 <td style="text-align:left">The command has not been delivered to the device because the device is (currently) not connected.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>rejected</code></td>
 <td style="text-align:left">The command has not been delivered to the device because it does not contain all required information.</td>
 </tr>
 </tbody>
 </table>
 <p><strong>Note</strong> that Hono relies on the particular protocol adapter to deliver commands to devices. Depending on the used transport protocol and the adapter&rsquo;s implementation, the <code>accepted</code> outcome may thus indicate any of the following:</p>
 <ul>
 <li>An <em>attempt</em> has been made to deliver the command to the device. However, it is unclear if the device has received (or processed) the command.</li>
 <li>The device has acknowledged the reception of the command but has not processed the command yet.</li>
 <li>The device has received and processed the command.</li>
 </ul>
 <p><strong>Examples</strong></p>
 <p>The following sequence diagram shows the successful delivery of a one-way command called <code>switchOn</code> to device <code>4711</code> of the <code>DEFAULT_TENANT</code>:</p>
 <figure>
     <img src="one_way_success.svg"/> <figcaption>
             <h4>Successfully send a One-Way Command</h4>
         </figcaption>
 </figure>

 <p>The following sequence diagram shows how the delivery of the same one-way command fails because the device is not connected:</p>
 <figure>
     <img src="device_not_connected.svg"/> <figcaption>
             <h4>Device not connected</h4>
         </figcaption>
 </figure>

 <p>The following sequence diagram illustrates how a malformed command sent by a <em>Business Application</em> gets rejected:</p>
 <figure>
     <img src="malformed_message.svg"/> <figcaption>
             <h4>Malformed Command message</h4>
         </figcaption>
 </figure>

 <h2 id="send-a-requestresponse-command">Send a (Request/Response) Command</h2>
 <p><em>Business Applications</em> use this operation to send a command to a device for which they expect the device to send back a response.</p>
 <p><a name="receiver-link-precondition"></a></p>
 <p><strong>Preconditions</strong></p>
 <ol>
 <li>The <em>Business Application</em> has established an AMQP connection with the AMQP 1.0 Network.</li>
 <li>The <em>Business Application</em> has established an AMQP link in role <em>sender</em> with the target address <code>command/${tenant_id}</code>, where <code>${tenant_id}</code> is the ID of the tenant that the device belongs to. This link is used by the <em>Business Application</em> to send command messages.</li>
 <li>The <em>Business Application</em> has established an AMQP link in role <em>receiver</em> with the source address <code>command_response/${tenant_id}/${reply_id}</code>.
 This link is used by the <em>Business Application</em> to receive the response to the command from the device. This link’s source address is also used as the <code>reply-to</code> address for the request messages. The <code>${reply_id}</code> may be any arbitrary string chosen by the application.</li>
 </ol>
 <p>The following sequence diagram illustrates the establishment of the required links:</p>
 <figure>
     <img src="receive_preconditions.svg"/> <figcaption>
             <h4>Application connecting to the AMQP 1.0 Messaging Network</h4>
         </figcaption>
 </figure>

 <div class="alert alert-notice">
     <h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4>
     <div><p>Previous versions of Hono required applications to</p>
 <ul>
 <li>use a sender link with target address <code>control/${tenant_id}/${device_id}</code> for sending commands to a specific device and</li>
 <li>use a receiver link with source address <code>control/${tenant_id}/${device_id}/{reply_id}</code> for receiving command responses from a device.</li>
 </ul>
 <p>These link addresses can still be used but support for them will be removed in a future version of Hono!
 Newly built applications should <strong>only</strong> use the tenant scoped links as described above.
 Note that the deprecated link addresses also <strong>do not</strong> support sending commands to devices connected via a gateway.</p>
 </div>
 </div>
 <p><strong>Command Message Format</strong></p>
 <p>The following table provides an overview of the properties the <em>Business Application</em> needs to set on a command message.</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">Type</th>
 <th style="text-align:left">Description</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td style="text-align:left"><em>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 target address <code>command/${tenant_id}/${device_id}</code> of the message, where <code>${device_id}</code> is the ID of the device to send the message to.</td>
 </tr>
 <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 contain the command name to be executed by a device.</td>
 </tr>
 <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">If present, MUST contain a <em>Media Type</em> as defined by <a href="https://tools.ietf.org/html/rfc2046">RFC 2046</a> which describes the semantics and format of the command&rsquo;s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.</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>string</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 application expects to receive the response from. This address MUST be the same as the source address used for establishing the client&rsquo;s receiver link (see <a href="./#receiver-link-precondition">Preconditions</a> above).</td>
 </tr>
 </tbody>
 </table>
 <p>The command message MAY contain arbitrary payload to be sent to the device in a single AMQP <em>Data</em> section. The value of the command message&rsquo;s <em>subject</em> value may provide a hint to the device regarding the format, encoding and semantics of the payload data.</p>
 <p>Hono uses following AMQP delivery states to indicate the outcome of sending the command to the device:</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"><code>accepted</code></td>
 <td style="text-align:left">The command has been delivered to the device for processing.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>released</code></td>
 <td style="text-align:left">The command has not been delivered to the device because the device is (currently) not connected.</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>rejected</code></td>
 <td style="text-align:left">The command has not been delivered to the device because it does not contain all required information.</td>
 </tr>
 </tbody>
 </table>
 <p><strong>Note</strong> that Hono relies on the particular protocol adapter to deliver commands to devices. Depending on the used transport protocol and the adapter&rsquo;s implementation, the <code>accepted</code> outcome may thus indicate any of the following:</p>
 <ul>
 <li>An <em>attempt</em> has been made to deliver the command to the device. However, it is unclear if the device has received (or processed) the command.</li>
 <li>The device has acknowledged the reception of the command but has not processed the command yet.</li>
 </ul>
 <p>An application can determine the overall outcome of the operation by means of the response to the command that is sent back by the device. An application should consider execution of a command to have failed, if it does not receive a response within a reasonable amount of time.</p>
 <p><strong>Response Message Format</strong></p>
 <p>The following table provides an overview of the properties set on a message sent in response to a command.</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">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">If present, MUST contain a <em>Media Type</em> as defined by <a href="https://tools.ietf.org/html/rfc2046">RFC 2046</a> which describes the semantics and format of the command&rsquo;s input data contained in the message payload. However, not all protocol adapters will support this property as not all transport protocols provide means to convey this information, e.g. MQTT 3.1.1 has no notion of message headers.</td>
 </tr>
 <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>string</em></td>
 <td style="text-align:left">MUST contain the correlation ID used to match the command message with the response message containing the result of execution on the device.</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">The identifier of the device that sent the response.</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>integer</em></td>
 <td style="text-align:left">MUST indicate the status of the execution. See table below for possible values.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>tenant_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 tenant that the device belongs to.</td>
 </tr>
 </tbody>
 </table>
 <p>The <em>status</em> property must contain an <a href="https://tools.ietf.org/html/rfc7231#section-6">HTTP 1.1 response status code</a>:</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>2xx</em></td>
 <td style="text-align:left">The command has been processed successfully.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>4xx</em></td>
 <td style="text-align:left">The command could not be processed due to a client error, e.g. malformed message payload.</td>
 </tr>
 <tr>
 <td style="text-align:left"><em>5xx</em></td>
 <td style="text-align:left">The command could not be processed due to an internal problem at the device side.</td>
 </tr>
 </tbody>
 </table>
 <p>The semantics of the individual codes are specific to the device and command. For status codes indicating an error (codes in the <code>400 - 599</code> range) the message body MAY contain a detailed description of the error that occurred.</p>
 <p>If a command message response contains a payload, the body of the message MUST consist of a single AMQP <em>Data</em> section containing the response message data.</p>
 <p><strong>Examples</strong></p>
 <p>The following sequence diagram illustrates how a <em>Business Application</em> sends a command called <code>getReading</code> to device <code>4711</code> of the <code>DEFAULT_TENANT</code> and receives a response from the device:</p>
 <figure>
     <img src="request_response_success.svg"/> <figcaption>
             <h4>Successfully send a Command</h4>
         </figcaption>
 </figure>

 <p>The sending of a command may fail for the same reasons as those illustrated for sending a one-way command. Additionally, the sending of a command may be considered unsuccessful by an application if it does not receive the response from the device in a reasonable amount of time:</p>
 <figure>
     <img src="response_time_out.svg"/> <figcaption>
             <h4>Command times out</h4>
         </figcaption>
 </figure>

 <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?1626138736"></script>
     <script src="/hono/docs/js/perfect-scrollbar.min.js?1626138736"></script>
     <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1626138736"></script>
     <script src="/hono/docs/js/jquery.sticky.js?1626138736"></script>
     <script src="/hono/docs/js/featherlight.min.js?1626138736"></script>
     <script src="/hono/docs/js/highlight.pack.js?1626138736"></script>
     <script>hljs.initHighlightingOnLoad();</script>
     <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1626138736"></script>
     <script src="/hono/docs/js/learn.js?1626138736"></script>
     <script src="/hono/docs/js/hugo-learn.js?1626138736"></script>

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