Google Git
Sign in
eclipse / gerrit / www.eclipse.org / hono / 5205c03aef0248437f32ed671b25d996f60bdaf7 / . / getting-started / index.html
blob: 715340f4f8792b3cfd13ee37bf85cbb9ad1c4d40 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="utf-8">
<meta name="robots" content="all,follow">
<meta name="googlebot" content="index,follow,snippet,archive">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Getting started with Eclipse Hono :: Eclipse Hono&trade;</title>
<meta name="author" content="" />
<meta name="description" content="A set of micro-services for connecting millions of devices.">
<meta name="generator" content="Hugo 0.54.0" />
<link href='//fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,500,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" integrity="sha384-oS3vJWv+0UjzBfQzYUhtDYW+Pj2yciDJxpsK1OYPAYjqT085Qq/1cq5FLXAZQ7Ay" crossorigin="anonymous">
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<link href="/hono/css/animate.css" rel="stylesheet">
<link href="/hono/css/style.hono.css" rel="stylesheet" id="theme-stylesheet">
<link href="/hono/css/custom.css" rel="stylesheet">
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<link rel="apple-touch-icon" sizes="180x180" href="/hono/favicon/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="48x48" href="/hono/favicon/favicon-48x48.png">
<link rel="icon" type="image/png" sizes="32x32" href="/hono/favicon/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/hono/favicon/favicon-16x16.png">
<link rel="manifest" href="/hono/favicon/site.webmanifest">
<link rel="mask-icon" href="/hono/favicon/safari-pinned-tab.svg" color="#5bbad5">
<link rel="shortcut icon" href="/hono/favicon/favicon.ico">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/hono/favicon/browserconfig.xml">
<meta name="theme-color" content="#ffffff">
<link href="/hono/css/owl.carousel.css" rel="stylesheet">
<link href="/hono/css/owl.theme.css" rel="stylesheet">
<link rel="alternate" href="https://www.eclipse.org/hono//index.xml" type="application/rss+xml" title="Eclipse Hono&amp;trade;">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@EclipseHono">
<meta name="twitter:title" content="Getting started with Eclipse Hono :: Eclipse Hono&amp;trade;">
<meta name="twitter:image" content="https://www.eclipse.org/hono/img/twitter_image.png">
<meta name="twitter:description" content="A set of micro-services for connecting millions of devices.">
<meta property="og:title" content="Getting started with Eclipse Hono :: Eclipse Hono&amp;trade;" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://www.eclipse.org/hono/getting-started//" />
<meta property="og:image" content="https://www.eclipse.org/hono/img/twitter_image.png" />
<link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css">
</head>
<body>
<div id="all">
<header>
<div class="navbar-affixed-top" data-spy="affix" data-offset-top="70">
<div class="navbar navbar-default yamm" role="navigation" id="navbar">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand home" href="https://www.eclipse.org/hono/">
<img src="https://www.eclipse.org/hono/img/HONO-Logo_Bild-Wort_quer-s-310x120px.svg" alt="Getting started with Eclipse Hono logo" class="logo">
<span class="sr-only">Getting started with Eclipse Hono - go to homepage</span>
</a>
<div class="navbar-buttons">
<button type="button" class="navbar-toggle btn-template-main" data-toggle="collapse" data-target="#navigation">
<span class="sr-only">Toggle Navigation</span>
<i class="fa fa-align-justify"></i>
</button>
</div>
</div>
<div class="navbar-collapse collapse" id="navigation">
<ul class="nav navbar-nav navbar-right">
<li class="dropdown active">
<a href="/hono/getting-started/">Getting started</a>
</li>
<li class="dropdown">
<a href="/hono/docs">Documentation</a>
</li>
<li class="dropdown">
<a href="/hono/downloads/">Download</a>
</li>
<li class="dropdown">
<a href="/hono/sandbox/">Sandbox</a>
</li>
<li class="dropdown">
<a href="/hono/faq/">FAQ</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Community <span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="/hono/community/contributing/">Contributing</a></li>
<li><a href="/hono/community/presentations/">Resources</a></li>
<li><a href="/hono/community/get-in-touch/">Get in Touch</a></li>
<li><a href="/hono/community/road-map/">Road Map</a></li>
</ul>
</li>
</ul>
</div>
<div class="collapse clearfix" id="search">
<form class="navbar-form" role="search">
<div class="input-group">
<input type="text" class="form-control" placeholder="Search">
<span class="input-group-btn">
<button type="submit" class="btn btn-template-main"><i class="fa fa-search"></i></button>
</span>
</div>
</form>
</div>
</div>
</div>
</div>
</header>
<div id="heading-breadcrumbs">
<div class="container">
<div class="row">
<div class="col-md-12">
<h1>Getting started with Eclipse Hono</h1>
</div>
</div>
</div>
</div>
<div id="content">
<div class="container">
<div class="row">
<div class="col-md-12">
<div>
<p>This guide will walk you through an interactive example usage scenario of Eclipse Hono. You will learn how devices can use Hono&rsquo;s protocol adapters to publish telemetry data and events using both HTTP and/or MQTT. You will also see how a downstream application can consume this data using Hono&rsquo;s north bound API without requiring the application to know anything about the specifics of the communication protocols used by the devices.</p>
<h2 id="prerequisites-for-the-getting-started-guide">Prerequisites for the Getting started Guide</h2>
<p>This guide requires several tools to be installed on your computer.
During the course of this guide, the devices publishing data will be represented by means of running some command line tools for posting HTTP requests and for publishing MQTT packets.</p>
<h4 id="curl-http-command-line-client">Curl HTTP Command Line Client</h4>
<p>The <code>curl</code> command is used in this guide for registering devices with Hono and for simulating a device publishing data using HTTP.
On most *nix like systems <code>curl</code> will probably already be installed. Otherwise, please refer to the
<a href="https://curl.haxx.se/">Curl project page</a> for installation instructions.</p>
<h4 id="mosquitto-mqtt-command-line-client">Mosquitto MQTT Command Line Client</h4>
<p>The <code>mosquitto_pub</code> command is used in this guide for simulating a device publishing data using the MQTT protocol.
Please refer to the <a href="https://mosquitto.org/">Mosquitto project page</a> for installation instructions, if you do not
have it installed already.</p>
<p><strong>NB</strong> The installation of the Mosquitto command line client is optional. If you do not install it then you will not be able to simulate
an MQTT based device but otherwise will be able to get the same results described in this guide.</p>
<h4 id="hono-command-line-client">Hono Command Line Client</h4>
<p>The Hono command line client is used in this guide for simulating an application that consumes telemetry data and events published by devices.
The client is available from <a href="/hono/downloads/">Hono&rsquo;s download page</a>.
Note that running the command line client requires a Java 11 runtime environment being installed locally.</p>
<h4 id="hono-sandbox">Hono Sandbox</h4>
<p>The most important prerequisite is, of course, a Hono instance that you can work with.</p>
<p>The most straightforward option to use for this guide is the <a href="/hono/sandbox/">Hono Sandbox</a> which is running on
infrastructure provided by the Eclipse Foundation and which is publicly accessible from the internet.</p>
<p>Using the Sandbox, there is no need to set up your own Hono instance locally. However, it requires several non-standard ports
being accessible from your computer which may not be the case, e.g. if you are behind a firewall restricting internet access to
a few standard ports only.</p>
<p>You can verify if you can access the relevant ports of the Sandbox by running the following command and comparing the output:</p>
<pre><code class="language-sh">curl -sIX GET http://hono.eclipse.org:28080/v1/tenants/DEFAULT_TENANT
</code></pre>
<p>If you get output like this</p>
<pre><code class="language-sh">HTTP/1.1 200 OK
etag: 89d40d26-5956-4cc6-b978-b15fda5d1823
content-type: application/json; charset=utf-8
content-length: 260
</code></pre>
<p>you can use the Sandbox. Run the following commands to set some environment variables which will be used during the guide</p>
<pre><code class="language-sh">export REGISTRY_IP=hono.eclipse.org
export HTTP_ADAPTER_IP=hono.eclipse.org
export MQTT_ADAPTER_IP=hono.eclipse.org
</code></pre>
<p>and then proceed to the <a href="#overview">Overview of Hono Components</a>.</p>
<p>However, if the <code>curl</code> command yielded different output, you will need to set up Hono locally as described in the next section.</p>
<h4 id="setting-up-a-local-hono-instance">Setting up a local Hono Instance</h4>
<p>In case you cannot access the Hono Sandbox as described above, you will need to set up an instance of Hono running on your local computer.
For evaluation purposes a single node <em>Minikube</em> cluster is sufficient to deploy Hono to.</p>
<ol>
<li>Please refer to the <a href="https://www.eclipse.org/hono/docs/deployment/create-kubernetes-cluster/#local-development
">installation instructions</a> for setting up a local Minikube cluster, then</li>
<li>follow the <a href="https://www.eclipse.org/hono/docs/deployment/helm-based-deployment/
">Deployment Guide</a> in order to install Hono to your local Minikube cluster.</li>
</ol>
<p>Once Hono has been deployed to your local cluster, run the following commands to set some environment variables which will be used during the guide</p>
<pre><code class="language-sh">export REGISTRY_IP=$(kubectl get service hono-service-device-registry-ext --output='jsonpath={.status.loadBalancer.ingress[0].ip}' -n hono)
export HTTP_ADAPTER_IP=$(kubectl get service hono-adapter-http-vertx --output='jsonpath={.status.loadBalancer.ingress[0].ip}' -n hono)
export MQTT_ADAPTER_IP=$(kubectl get service hono-adapter-mqtt-vertx --output='jsonpath={.status.loadBalancer.ingress[0].ip}' -n hono)
</code></pre>
<p><a name="overview"></a></p>
<h2 id="overview-of-hono-components">Overview of Hono Components</h2>
<p>Hono consists of a set of microservices which are deployed as Docker containers. The diagram below provides an overview of the containers that are part of the example deployment of Hono on the Sandbox or a local Minikube cluster.</p>
<figure>
<img src="Hono_instance.svg"
alt="The Docker containers representing the services of the example Hono deployment"/> <figcaption>
<h4>Components of the example Hono deployment</h4>
</figcaption>
</figure>
<ul>
<li>Hono Instance
<ul>
<li>An <em>HTTP Adapter</em> instance that exposes Hono&rsquo;s Telemetry and Event APIs as URI resources.</li>
<li>A <em>Kura Adapter</em> instance that exposes Hono&rsquo;s Telemetry and Event APIs as an <a href="https://www.eclipse.org/kura">Eclipse Kura&trade;</a> compatible MQTT topic hierarchy.</li>
<li>An <em>MQTT Adapter</em> instance that exposes Hono&rsquo;s Telemetry and Event APIs as a generic MQTT topic hierarchy.</li>
<li>An <em>AMQP Adapter</em> instance that exposes Hono&rsquo;s Telemetry and Event APIs as a set of AMQP 1.0 addresses.</li>
<li>A <em>Device Registry</em> instance that manages registration information and issues device registration assertions to protocol adapters.</li>
<li>An <em>Auth Server</em> instance that authenticates Hono components and issues tokens asserting identity and authorities.</li>
</ul></li>
<li>AMQP Network
<ul>
<li>An <em>Apache Qpid Dispatch Router</em> instance that downstream applications connect to in order to consume telemetry data and events from devices.</li>
<li>An <em>Apache ActiveMQ Artemis</em> instance serving as the persistence store for events.</li>
</ul></li>
<li>Monitoring Infrastructure
<ul>
<li>A <em>Prometheus</em> instance for storing metrics data from services and protocol adapters.</li>
<li>A <em>Grafana</em> instance providing a dash board visualizing the collected metrics data.</li>
</ul></li>
</ul>
<p>In the example scenario used in the remainder of this guide, the devices will connect to the HTTP and MQTT adapters in order to publish telemetry data and events.
The devices will be authenticated using information stored in the Device Registry. The data is then forwarded downstream to the example application via the AMQP Messaging Network.</p>
<h2 id="registering-devices">Registering Devices</h2>
<p>When a device tries to connect to one of Hono&rsquo;s protocol adapters, the protocol adapter first tries to authenticate the device using information kept in the Device Registry.
The information maintained in the registry includes the <em>tenant</em> (a logical scope) that the device belongs to, the device&rsquo;s unique <em>identity</em> within the tenant and the <em>credentials</em> used by the device for authentication.</p>
<p>Before a device can connect to Hono and publish any data, the corresponding information needs to be added to the Device Registry.</p>
<h3 id="creating-a-new-tenant">Creating a new Tenant</h3>
<p>Register a tenant using Hono&rsquo;s Device Registry&rsquo;s management HTTP API (a random tenant identifier will be generated):</p>
<pre><code class="language-sh">curl -i -X POST http://$REGISTRY_IP:28080/v1/tenants
HTTP/1.1 201 Created
etag: becc93d7-ab0f-48ec-ad26-debdf339cbf4
location: /v1/tenants/85f63e23-1b78-4156-8500-debcbd1a8d35
content-type: application/json; charset=utf-8
content-length: 45
{&quot;id&quot;:&quot;85f63e23-1b78-4156-8500-debcbd1a8d35&quot;}
</code></pre>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Random tenant ID value</h4>
<div><p>You will receive a randomly generated tenantId value. It will probably be different than the value given in this example.
Make sure to export it to an environment variable to make the following steps easier:</p>
<pre><code class="language-sh">export MY_TENANT=85f63e23-1b78-4156-8500-debcbd1a8d35
</code></pre>
</div>
</div>
<h3 id="adding-a-device-to-the-tenant">Adding a Device to the Tenant</h3>
<p>Register a device using Hono&rsquo;s Device Registry&rsquo;s management HTTP API (a random device identifier will be assigned):</p>
<pre><code class="language-sh">curl -i -X POST http://$REGISTRY_IP:28080/v1/devices/$MY_TENANT
HTTP/1.1 201 Created
etag: 68eab243-3df9-457d-a0ab-b702e57c0c17
location: /v1/devices/85f63e23-1b78-4156-8500-debcbd1a8d35/4412abe2-f219-4099-ae14-b446604ae9c6
content-type: application/json; charset=utf-8
content-length: 45
{&quot;id&quot;:&quot;4412abe2-f219-4099-ae14-b446604ae9c6&quot;}
</code></pre>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Random device ID value</h4>
<div><p>You will receive a randomly generated deviceId value. It will probably be different than the value given in this example.
Make sure to export it to an environment variable to make the following steps easier:</p>
<pre><code class="language-sh">export MY_DEVICE=4412abe2-f219-4099-ae14-b446604ae9c6
</code></pre>
</div>
</div>
<h3 id="setting-a-password-for-the-device">Setting a Password for the Device</h3>
<p>Choose a (random) password and register it using Hono&rsquo;s Device Registry&rsquo;s management HTTP API (replace <code>my-pwd</code> with your password):</p>
<pre><code class="language-sh">export MY_PWD=my-pwd
curl -i -X PUT -H &quot;content-type: application/json&quot; --data-binary '[{
&quot;type&quot;: &quot;hashed-password&quot;,
&quot;auth-id&quot;: &quot;'$MY_DEVICE'&quot;,
&quot;secrets&quot;: [{
&quot;pwd-plain&quot;: &quot;'$MY_PWD'&quot;
}]
}]' http://$REGISTRY_IP:28080/v1/credentials/$MY_TENANT/$MY_DEVICE
HTTP/1.1 204 Updated
etag: cf91fd4d-7111-4e8a-af68-c703993a8be1
Content-Length: 0
</code></pre>
<p><a name="starting-a-consumer"></a></p>
<h2 id="starting-the-example-application">Starting the example Application</h2>
<p>The telemetry data produced by devices is usually consumed by downstream applications that use it to implement their corresponding business functionality.
In this guide we will use the Hono command line client to simulate such an application.
The client will connect to Hono&rsquo;s north bound <a href="https://www.eclipse.org/hono/docs/api/telemetry-api/
">Telemetry</a> and <a href="https://www.eclipse.org/hono/docs/api/event-api/
">Event API</a>s using the AMQP 1.0 transport protocol, subscribe to all telemetry and event messages and log the messages to the console.</p>
<p>Open a new terminal window and set the <code>AMQP_NETWORK_IP</code> environment variable.
If you are using the Sandbox server:</p>
<pre><code class="language-sh">export AMQP_NETWORK_IP=hono.eclipse.org
</code></pre>
<p>Otherwise, if you are using a local Minikube cluster:</p>
<pre><code class="language-sh">export AMQP_NETWORK_IP=$(kubectl get service hono-dispatch-router-ext --output='jsonpath={.status.loadBalancer.ingress[0].ip}' -n hono)
</code></pre>
<p>The client can then be started from the command line as follows (make sure to replace <code>my-tenant</code> with your tenant identifier):</p>
<pre><code class="language-sh"># in directory where the hono-cli-*-exec.jar file has been downloaded to
export MY_TENANT=my-tenant
java -jar hono-cli-*-exec.jar --hono.client.host=$AMQP_NETWORK_IP --hono.client.port=15672 --hono.client.username=consumer@HONO --hono.client.password=verysecret --spring.profiles.active=receiver --tenant.id=$MY_TENANT
</code></pre>
<h2 id="publishing-telemetry-data-to-the-http-adapter">Publishing Telemetry Data to the HTTP Adapter</h2>
<p>Now that the downstream application is running, devices can start publishing telemetry data and events using Hono&rsquo;s protocol adapters.
First, you will simulate a device publishing data to Hono using the HTTP protocol.
Go back to the original terminal and run:</p>
<pre><code class="language-sh">curl -i -u $MY_DEVICE@$MY_TENANT:$MY_PWD -H 'Content-Type: application/json' --data-binary '{&quot;temp&quot;: 5}' http://$HTTP_ADAPTER_IP:8080/telemetry
HTTP/1.1 202 Accepted
Content-Length: 0
</code></pre>
<p>If you have started the downstream application as described above, you should now see the telemetry message being logged to the application&rsquo;s console
in the other terminal. The output should look something like this:</p>
<pre><code class="language-sh">13:36:49.169 [vert.x-eventloop-thread-0] INFO org.eclipse.hono.cli.Receiver - received telemetry message [device: my-device, content-type: application/json]: {&quot;temp&quot;: 5}
13:36:49.170 [vert.x-eventloop-thread-0] INFO org.eclipse.hono.cli.Receiver - ... with application properties: {orig_adapter=hono-http, device_id=my-device, orig_address=/telemetry, JMS_AMQP_CONTENT_TYPE=application/json}
</code></pre>
<p>You can publish more data simply by re-running the <code>curl</code> command above with arbitrary payload.</p>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Service Unavailable</h4>
<div><p>When you invoke the command above for the first time, you may get the following response:</p>
<pre><code>HTTP/1.1 503 Service Unavailable
Content-Length: 23
Content-Type: text/plain; charset=utf-8
Retry-After: 2
temporarily unavailable
</code></pre>
<p>This is because the first request to publish data for a given tenant is used as the trigger to establish a tenant specific sender link with
the AMQP 1.0 Messaging Network to forward the data over. However, the HTTP adapter may not receive credits quickly enough for the
request to be served immediately. You can simply ignore this response and re-submit the command.</p>
</div>
</div>
<p>If you haven&rsquo;t started the application you will always get <code>503 Resource Unavailable</code> responses because Hono does not
accept any telemetry data from devices if there aren&rsquo;t any consumers connected that are interested in the data. The reason for this is
that Hono <em>never</em> persists Telemetry data and thus it doesn&rsquo;t make any sense to accept and process telemetry data if there is no
consumer to deliver it to.</p>
<p>The HTTP Adapter also supports publishing telemetry messages using <em>at least once</em> delivery semantics. For information on how that works
and additional examples for interacting with Hono via HTTP, please refer to the
<a href="https://www.eclipse.org/hono/docs/user-guide/http-adapter/
">HTTP Adapter&rsquo;s User Guide</a>.</p>
<h2 id="publishing-events-to-the-http-adapter">Publishing Events to the HTTP Adapter</h2>
<p>In a similar way you can upload events:</p>
<pre><code class="language-sh">curl -i -u $MY_DEVICE@$MY_TENANT:$MY_PWD -H 'Content-Type: application/json' --data-binary '{&quot;alarm&quot;: &quot;fire&quot;}' http://$HTTP_ADAPTER_IP:8080/event
HTTP/1.1 202 Accepted
Content-Length: 0
</code></pre>
<p>Again, you should see the event being logged to the console of the downstream application.</p>
<h2 id="publishing-telemetry-data-to-the-mqtt-adapter">Publishing Telemetry Data to the MQTT Adapter</h2>
<p>Devices can also publish data to Hono using the MQTT protocol. If you have installed the <code>mosquitto_pub</code> command line client, you
can run the following command to publish arbitrary telemetry data to Hono&rsquo;s MQTT adapter using QoS 0:</p>
<pre><code class="language-sh">mosquitto_pub -h $MQTT_ADAPTER_IP -u $MY_DEVICE@$MY_TENANT -P $MY_PWD -t telemetry -m '{&quot;temp&quot;: 5}'
</code></pre>
<p>Again, you should now see the telemetry message being logged to console of the downstream application.</p>
<p>The MQTT Adapter also supports publishing telemetry messages using QoS 1. For information on how that works
and additional examples for interacting with Hono via MQTT, please refer to the
<a href="https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/
">MQTT Adapter&rsquo;s User Guide</a>.</p>
<h2 id="publishing-events-to-the-mqtt-adapter">Publishing Events to the MQTT Adapter</h2>
<p>In a similar way you can upload events:</p>
<pre><code class="language-sh">mosquitto_pub -h $MQTT_ADAPTER_IP -u $MY_DEVICE@$MY_TENANT -P $MY_PWD -t event -q 1 -m '{&quot;temp&quot;: 5}'
</code></pre>
<p>Again, you should now see the telemetry message being logged to console of the downstream application.</p>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Congratulations</h4>
<div><p>You have successfully connected a device to Hono and published sensor data for consumption by an application connected to Hono&rsquo;s north bound API.
The application used the AMQP 1.0 protocol to receive messages regardless of the transport protocol used by the device to publish the data.</p>
<p><strong>What to try next?</strong></p>
<ul>
<li>Continue with the next sections to learn how applications can send commands to devices by means of the <a href="https://www.eclipse.org/hono/docs/api/command-and-control-api/">Command &amp; Control API</a>.</li>
<li>Take a look at some of the metrics collected by Hono&rsquo;s components by opening the Hono dashboard. On the Sandbox server the dashboard is available at <a href="https://hono.eclipse.org:3000">https://hono.eclipse.org:3000</a>. When running a local Minikube cluster, please refer to <a href="https://www.eclipse.org/hono/docs/deployment/helm-based-deployment/#dashboard">Opening the Dashboard</a> for instructions.</li>
<li>Check out the <a href="https://www.eclipse.org/hono/docs/user-guide/">User Guides</a> to explore more options for devices to connect to Hono using different transport protocols.</li>
<li>Learn more about the managing tenants, devices and credentials using the <a href="https://www.eclipse.org/hono/docs/user-guide/device-registry/">Device Registry&rsquo;s HTTP API</a>.</li>
</ul>
</div>
</div>
<h2 id="sending-commands-to-a-device">Sending Commands to a Device</h2>
<p>The following walk-through example will guide you through some of the more advanced functionality of Hono.
In particular you will see how an application can send a command to a device and receive a response containing the outcome of the command.</p>
<h3 id="starting-the-example-application-1">Starting the example application</h3>
<p>Hono comes with an example application (located in the <code>example</code> module) that is as small as possible but still covers the main message communication patterns.
This application also supports Command &amp; Control.</p>
<p>Please start (and potentially configure) the application as described <a href="https://www.eclipse.org/hono/docs/dev-guide/java_client_consumer/
">here</a>.
The application writes the payload of incoming messages to standard output and will serve to view how messages are received
and sent by Hono.</p>
<p>After the application has been successfully connected to the AMQP 1.0 network, it is time to send an appropriate downstream message to the HTTP protocol adapter to trigger the sending of a command.</p>
<p>Note that it is the responsibility of the application to send a command - to illustrate how this is done, the example application sends a command <code>setBrightness</code> when it receives a downstream message that has a valid <em>time until disconnect</em> parameter set. Refer to the usage of the helper class <code>MessageTap</code> in the example code as a blueprint for writing your own application.</p>
<h3 id="uploading-data-and-receiving-a-command">Uploading Data and receiving a Command</h3>
<p>To simulate an HTTP device, we use the standard tool <code>curl</code> to publish some JSON data for the device <code>4711</code>.
To signal that the device is willing to receive and process a command, the device uploads a telemetry or event message and includes the <code>hono-ttd</code> request parameter to indicate the number of seconds it will wait for the response:</p>
<pre><code>curl -i -X POST -u sensor1@DEFAULT_TENANT:hono-secret -H 'Content-Type: application/json' \
--data-binary '{&quot;temp&quot;: 5}' http://127.0.0.1:8080/telemetry?hono-ttd=30
</code></pre>
<p>Watch the example application that receives the message - on the console you will find a line looking similar to the following:</p>
<pre><code>Device is ready to receive a command : &lt;TimeUntilDisconnectNotification{tenantId='DEFAULT_TENANT', deviceId='4711', readyUntil=2018-05-22T12:11:35.055Z}&gt;
</code></pre>
<p>and some lines below</p>
<pre><code>[vert.x-eventloop-thread-0] DEBUG o.e.hono.client.impl.HonoClientImpl - Command client created successfully for [tenantId: DEFAULT_TENANT, deviceId: 4711]
</code></pre>
<p>The response to the <code>curl</code> command contains the command from the example application and looks like the following:</p>
<pre><code>HTTP/1.1 200 OK
hono-command: setBrightness
hono-cmd-req-id: 10117f669c12-09ef-416d-88c1-1787f894856d
Content-Length: 23
{
&quot;brightness&quot; : 87
}
</code></pre>
<p>The example application sets the <code>brightness</code> to a random value between 0 and 100 on each invocation. It also generates a unique correlation identifier for each new command to be sent to the device. The device will need to include this identifier in its response to the command so that the application can properly correlate the response with the request.</p>
<p><strong>NB:</strong> If the application would send a <em>one-way command</em> instead (see <a href="https://www.eclipse.org/hono/docs/concepts/command-and-control/
">Command and Control Concepts</a>), the <code>hono-cmd-req-id</code> response header would be missing.</p>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div><p>If you are running Hono on another node than the application, e.g. using <em>Minikube</em> or <em>Minishift</em>, and the clock of that node is not in sync with the node that your (example) application is running on, then the application might consider the <em>time til disconnect</em> indicated by the device in its <em>hono-ttd</em> parameter to already have expired. This will happen if the application node&rsquo;s clock is ahead of the clock on the HTTP protocol adapter node. Consequently, this will result in the application <strong>not</strong> sending any command to the device.</p>
<p>Thus, you need to make sure that the clocks of the node running the application and the node running the HTTP protocol adapter are synchronized (you may want to search the internet for several solutions to this problem).</p>
</div>
</div>
<h3 id="uploading-the-response-to-the-command">Uploading the Response to the Command</h3>
<p>If the received command was <em>not</em> a <em>one-way command</em>, and the device has received the command and has processed it, it needs to inform the application about the outcome. For this purpose the device uploads the result to the HTTP adapter using a new HTTP request. The following command simulates the device uploading some JSON payload indicating a successful result:</p>
<pre><code>curl -i -X POST -u sensor1@DEFAULT_TENANT:hono-secret -H 'Content-Type: application/json' \
-H 'hono-cmd-status: 200' --data-binary '{&quot;success&quot;: true}' \
http://127.0.0.1:8080/command/res/10117f669c12-09ef-416d-88c1-1787f894856d
HTTP/1.1 202 Accepted
Content-Length: 0
</code></pre>
<p><strong>NB</strong> Make sure to issue the command above before the application gives up on waiting for the response. By default, the example application will wait for as long as indicated in the <code>hono-ttd</code> parameter of the uploaded telemetry message. Also make sure to use the actual value of the <code>hono-cmd-req-id</code> header from the HTTP response that contained the command.</p>
<h3 id="using-cli-command-line-interface-to-send-commands-and-receive-command-responses">Using CLI (command line interface) to send Commands and receive Command responses</h3>
<p>The command line client from the <code>cli</code> module supports the interactive sending of commands to connected devices.
In order to do so, the client needs to be run with the <code>command</code> profile as follows:</p>
<pre><code class="language-sh"># in directory: hono/cli/
mvn spring-boot:run -Dspring-boot.run.arguments=--hono.client.host=localhost,--hono.client.username=consumer@HONO,--hono.client.password=verysecret -Dspring-boot.run.profiles=command,ssl
</code></pre>
<p>The client will prompt the user to enter the command&rsquo;s name, the payload to send and the payload&rsquo;s content type. For more information about command and payload refer to <a href="https://www.eclipse.org/hono/docs/concepts/command-and-control/
">Command and Control Concepts</a>.</p>
<p>The example below illustrates how a command to set the volume with a JSON payload is sent to device <code>4711</code>.</p>
<pre><code class="language-sh">&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt; Enter name of command for device [&lt;TenantId&gt;:&lt;DeviceId&gt;] (prefix with 'ow:' to send one-way command):
setVolume
&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt; Enter command payload:
{&quot;level&quot;: 50}
&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt; Enter content type:
application/json
INFO org.eclipse.hono.cli.Commander - Command sent to device... [Command request will timeout in 60 seconds]
</code></pre>
<p>In the above example, the client waits up to 60 seconds for the response from the device before giving up.
For more information on how to connect devices, receive commands and send responses refer to <a href="https://www.eclipse.org/hono/docs/user-guide/http-adapter/#specifying-the-time-a-device-will-wait-for-a-response
">Commands using HTTP</a> and <a href="https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/#command-control
">Commands using MQTT</a>.</p>
<p>The received command response <code>{&quot;result&quot;:&quot;success&quot;}</code> is displayed as shown in the below example.</p>
<pre><code>INFO org.eclipse.hono.cli.Commander - Received Command response : {&quot;result&quot;:&quot;success&quot;}
</code></pre>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>The command line client also supports sending of <em>one-way</em> commands to a device, i.e. commands for which no response is expected from the device.
In order to send a one-way command, the command name needs to be prefixed with <code>ow:</code>, e.g. <code>ow:setVolume</code>. The client will then not wait for
a response from the device but will consider the sending of the command successful as soon as the command message has been accepted by Hono.</div>
</div>
<p>The command line argument <code>command.timeoutInSeconds</code> can be used to set the timeout period (default is 60 seconds). The command line arguments <code>device.id</code> and <code>tenant.id</code> provide the device and tenant ID of the device that you want to send commands to.</p>
<pre><code class="language-sh"># in directory: hono/cli/
mvn spring-boot:run -Dspring-boot.run.arguments=--hono.client.host=localhost,--hono.client.username=consumer@HONO,--hono.client.password=verysecret,--command.timeoutInSeconds=10,--device.id=4711,--tenant.id=DEFAULT_TENANT -Dspring-boot.run.profiles=command,ssl
</code></pre>
<h3 id="summary">Summary</h3>
<p>The following parts of Hono are involved in the upper scenario:</p>
<ul>
<li>HTTP protocol adapter: detects the <code>hono-ttd</code> parameter in the request and opens an AMQP 1.0 receiver link with the AMQP 1.0
Messaging Network in order to receive commands for the device</li>
<li>example application: receives a telemetry message with <code>hono-ttd</code> which invokes an application internal callback that sends a
command to the HTTP adapter via the opened receiver link. Additionally it opens a receiver link for any responses.</li>
<li>HTTP protocol adapter: receives the command and forwards it to the device in the HTTP response body</li>
<li>Device sends result of processing the command to HTTP adapter which then forwards it to the application</li>
</ul>
<p>The <a href="https://www.eclipse.org/hono/docs/concepts/command-and-control/
">Command and Control Concepts</a> page contains sequence diagrams that
explain this in more detail.</p>
</div>
</div>
</div>
</div>
</div>
<footer id="footer">
<div class="container">
<div class="col-md-4 col-sm-6">
<h4>More</h4>
<ul>
<li><a href="https://github.com/eclipse/hono" title="View Source Code on GitHub"><i class='fab fa-github'></i> GitHub Repository</a></li>
<li><a href="https://twitter.com/EclipseHono" title="Follow us on Twitter"><i class='fab fa-twitter'></i> Twitter</a></li>
<li><a href="/hono/thankyou">Thank you</a></li>
</ul>
<hr class="hidden-md hidden-lg hidden-sm">
</div>
<div class="col-md-4 col-sm-6">
<h4>Eclipse Legal</h4>
<ul>
<li><a href="http://www.eclipse.org/legal/privacy.php" target="_blank">Privacy Policy</a></li>
<li><a href="http://www.eclipse.org/legal/termsofuse.php" target="_blank">Terms of Use</a></li>
<li><a href="http://www.eclipse.org/legal/copyright.php" target="_blank">Copyright Agent</a></li>
<li><a href="http://www.eclipse.org/legal" target="_blank">Legal</a></li>
<li><a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">License</a></li>
<li><a href="https://eclipse.org/security" target="_blank">Report a Vulnerability</a></li>
</ul>
<hr class="hidden-md hidden-lg">
</div>
<div class="col-md-4 col-sm-6">
<div>
<div class="incubation">
<a href="https://www.eclipse.org/projects/what-is-incubation.php" target="_blank">
<img src="https://www.eclipse.org/hono/img/eclipse_incubation_vertical_png-02.png" width="100%" />
</a>
</div>
<div class="eclipse-logo">
<a href="https://www.eclipse.org" target="_blank">
<img src="https://www.eclipse.org/hono/img/eclipse_foundation_logo_wo.svg"/>
</a>
</div>
</div>
</div>
</div>
</footer>
<div id="copyright">
<div class="container">
<div class="col-md-12">
<p class="pull-left">&copy; 2019 The Eclipse Hono Project</p>
<p class="pull-right">
Template by <a href="http://bootstrapious.com/free-templates">Bootstrapious</a>.
Ported to Hugo by <a href="https://github.com/devcows/hugo-universal-theme">DevCows</a>
</p>
</div>
</div>
</div>
</div>
<script src="//code.jquery.com/jquery-3.1.1.min.js" integrity="sha256-hVVnYaiADRTO2PzUGmuLJr8BLUSjGIZsDYGmIJLv2b8=" crossorigin="anonymous"></script>
<script src="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/waypoints/4.0.1/jquery.waypoints.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/Counter-Up/1.0/jquery.counterup.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery-parallax/1.1.3/jquery-parallax.js"></script>
<script src="https://www.eclipse.org/hono/js/front.js"></script>
<script src="https://www.eclipse.org/hono/js/owl.carousel.min.js"></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>