Website build Hono-Website-Declarative-Pipeline-196
Signed-off-by: Hono Bot <hono-bot@eclipse.org>
diff --git a/docs/dev/user-guide/amqp-adapter/index.html b/docs/dev/user-guide/amqp-adapter/index.html
index 6d1aaa5..fd2dcff 100644
--- a/docs/dev/user-guide/amqp-adapter/index.html
+++ b/docs/dev/user-guide/amqp-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>AMQP Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/amqp-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/amqp-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/amqp-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/amqp-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/amqp-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/amqp-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/amqp-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/amqp-adapter/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/amqp-adapter/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/amqp-adapter/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/amqp-adapter/" selected>dev</option>
@@ -1964,45 +2010,46 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#device-authentication">Device Authentication</a>
-<ul>
-<li><a href="#sasl-plain-authentication">SASL PLAIN Authentication</a></li>
-<li><a href="#sasl-external-authentication">SASL EXTERNAL Authentication</a></li>
-</ul></li>
-<li><a href="#resource-limit-checks">Resource Limit Checks</a>
-<ul>
-<li><a href="#connection-limits">Connection Limits</a></li>
-<li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
-<li><a href="#message-limits">Message Limits</a></li>
-</ul></li>
-<li><a href="#connection-events">Connection Events</a></li>
-<li><a href="#link-establishment">Link Establishment</a></li>
-<li><a href="#error-handling">Error Handling</a></li>
-<li><a href="#amqp-command-line-client">AMQP Command-line Client</a></li>
-<li><a href="#publishing-telemetry-data">Publishing Telemetry Data</a></li>
-<li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
-<li><a href="#publishing-events">Publishing Events</a></li>
-<li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
-<li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
-<li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
-<li><a href="#command-control">Command & Control</a>
-<ul>
-<li><a href="#receiving-commands">Receiving Commands</a></li>
-<li><a href="#sending-a-response-to-a-command">Sending a Response to a Command</a></li>
-<li><a href="#examples">Examples</a></li>
-</ul></li>
-<li><a href="#downstream-meta-data">Downstream Meta Data</a>
-<ul>
-<li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
-</ul></li>
-<li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#device-authentication">Device Authentication</a>
+ <ul>
+ <li><a href="#sasl-plain-authentication">SASL PLAIN Authentication</a></li>
+ <li><a href="#sasl-external-authentication">SASL EXTERNAL Authentication</a></li>
+ </ul>
+ </li>
+ <li><a href="#resource-limit-checks">Resource Limit Checks</a>
+ <ul>
+ <li><a href="#connection-limits">Connection Limits</a></li>
+ <li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
+ <li><a href="#message-limits">Message Limits</a></li>
+ </ul>
+ </li>
+ <li><a href="#connection-events">Connection Events</a></li>
+ <li><a href="#link-establishment">Link Establishment</a></li>
+ <li><a href="#error-handling">Error Handling</a></li>
+ <li><a href="#amqp-command-line-client">AMQP Command-line Client</a></li>
+ <li><a href="#publishing-telemetry-data">Publishing Telemetry Data</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
+ <li><a href="#publishing-events">Publishing Events</a></li>
+ <li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
+ <li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
+ <li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
+ <li><a href="#command--control">Command & Control</a>
+ <ul>
+ <li><a href="#receiving-commands">Receiving Commands</a></li>
+ <li><a href="#sending-a-response-to-a-command">Sending a Response to a Command</a></li>
+ <li><a href="#examples">Examples</a></li>
+ </ul>
+ </li>
+ <li><a href="#downstream-meta-data">Downstream Meta Data</a>
+ <ul>
+ <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
+ </ul>
+ </li>
+ <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -2027,43 +2074,31 @@
<p>The AMQP protocol adapter allows clients (devices or gateway components) supporting the AMQP 1.0 protocol to publish
-messages to Eclipse Hono™’s Telemetry, Event and Command & Control endpoints.</p>
-
+messages to Eclipse Hono™’s Telemetry, Event and Command & Control endpoints.</p>
<h2 id="device-authentication">Device Authentication</h2>
-
<p>By default, all Hono protocol adapters require clients (devices or gateway components) to authenticate during connection establishment.
This is the preferred way for devices to publish data via protocol adapters. The AMQP adapter supports both the
<a href="https://tools.ietf.org/html/rfc4616">SASL PLAIN</a> and <a href="https://tools.ietf.org/html/rfc4422">SASL EXTERNAL</a> authentication mechanisms.
The former uses a <em>username</em> and <em>password</em> to authenticate to the adapter while the latter uses an X.509 client certificate.</p>
-
<p>This guide provides examples for publishing telemetry and events for <em>authenticated</em> (using SASL PLAIN) and <em>unauthenticated</em> clients.</p>
-
<p><strong>NB</strong> The AMQP adapter can be configured to <em>allow</em> unauthenticated devices to connect by setting configuration variable
<code>HONO_AMQP_AUTHENTICATION_REQUIRED</code> to <code>false</code>.</p>
-
<h3 id="sasl-plain-authentication">SASL PLAIN Authentication</h3>
-
<p>The AMQP adapter supports authenticating clients using a <em>username</em> and <em>password</em>. This means that clients need to provide a <em>username</em> and a <em>password</em>
when connecting to the AMQP adapter. The <em>username</em> must match the pattern [<em>auth-id@tenant</em>], e.g. <code>sensor1@DEFAULT_TENANT</code>.</p>
-
<p>The adapter verifies the credentials provided by the client against the credentials that the
<a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">configured Credentials service</a> has on record for the client.
If the credentials match, the client device can proceed to publish messages to Hono.</p>
-
<p>The examples below refer to devices <code>4711</code> and <code>gw-1</code> of tenant <code>DEFAULT_TENANT</code> using <em>auth-ids</em> <code>sensor1</code> and <code>gw1</code> and corresponding passwords.
The example deployment as described in the <a href="/hono/docs/dev/deployment/">Deployment Guide</a> comes pre-configured with the corresponding entities in its
device registry component.</p>
-
<p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication.
See <a href="/hono/docs/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p>
-
<h3 id="sasl-external-authentication">SASL EXTERNAL Authentication</h3>
-
<p>When a device uses a client certificate for authentication, the TLS handshake is initiated during TCP connection establishment.
If no trust anchor is configured for the AMQP adapter, the TLS handshake will succeed only if the certificate has not yet expired.
Once the TLS handshake completes and a secure connection is established, the certificate’s signature is checked during the SASL handshake.
To complete the SASL handshake and authenticate the client, the adapter performs the following steps:</p>
-
<ol>
<li>The adapter extracts the client certificate’s <em>Issuer DN</em> from the client certificate</li>
<li>The adapter invokes the Tenant service to look up the tenant matching the DN.
@@ -2075,88 +2110,58 @@
uses the client certificate’s <em>Subject DN</em> (as authentication identifier) and <code>x509-cert</code> (for the credentials type)
in order to determine the device ID.</li>
</ol>
-
<p><strong>NB</strong> The AMQP adapter needs to be configured for TLS in order to support this mechanism.</p>
-
<h2 id="resource-limit-checks">Resource Limit Checks</h2>
-
<p>The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.</p>
-
<h3 id="connection-limits">Connection Limits</h3>
-
<p>The adapter immediately closes a newly established connection with an <code>amqp:unauthorized-access</code> error if</p>
-
<ul>
<li>the maximum number of connections per protocol adapter instance is reached, or</li>
<li>if the maximum number of simultaneously connected devices for the client’s tenant is reached.</li>
</ul>
-
<p>Please refer to <a href="/hono/docs/dev/concepts/resource-limits/">resource-limits</a> for details.</p>
-
<h3 id="connection-duration-limits">Connection Duration Limits</h3>
-
<p>The adapter immediately closes a newly established connection with an <code>amqp:unauthorized-access</code> error if the
-<a href="/hono/docs/dev/concepts/resource-limits/#connection-duration-limit">connection duration limit</a> that has been configured for
+<a href="/hono/docs/dev/concepts/resource-limits/">connection duration limit</a> that has been configured for
the client’s tenant is exceeded.</p>
-
<h3 id="message-limits">Message Limits</h3>
-
<p>The adapter</p>
-
<ul>
<li>immediately closes a newly established connection with an <code>amqp:unauthorized-access</code> error and</li>
<li>rejects any AMQP 1.0 message containing
-
<ul>
<li>telemetry data or an event uploaded by a client</li>
<li>a command sent by a north bound application</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>if the <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p>
-
<h2 id="connection-events">Connection Events</h2>
-
<p>The adapter can emit <a href="/hono/docs/dev/api/event/#connection-event">Connection Events</a> for client connections being established and/or terminated.
-Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/#connection-event-producer-configuration">common configuration options</a>
+Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/">common configuration options</a>
for details regarding how to enable this behavior.</p>
-
<p>The adapter includes the client’s AMQP <em>container-id</em> as the Connection Event’s <em>remote-id</em>.</p>
-
<h2 id="link-establishment">Link Establishment</h2>
-
<p>The AMQP adapter supports the <a href="http://docs.oasis-open.org/amqp/anonterm/v1.0/anonterm-v1.0.html">Anonymous Terminus for Message Routing</a> specification
and requires clients to create a single sender link using the <code>null</code> target address for publishing all types of messages to the AMQP adapter.</p>
-
<p>Using <em>AT MOST ONCE</em> delivery semantics, the client will not wait for the message to be accepted and settled by the downstream consumer. However, with <em>AT LEAST ONCE</em>, the client sends the message and waits for the message to be delivered to and accepted by the downstream consumer. If the message cannot be delivered due to a failure, the client will be notified.</p>
-
<p>The client indicates its preferred message delivery mode by means of the <em>snd-settle-mode</em> and <em>rcv-settle-mode</em> fields of its <em>attach</em> frame during link establishment. Clients should use <code>mixed</code> as the <em>snd-settle-mode</em> and <code>first</code> as the <em>rcv-settle-mode</em> in order to be able to use the same link for sending all types of messages using different delivery semantics as described in the following sections.</p>
-
<h2 id="error-handling">Error Handling</h2>
-
<p>The AMQP adapter distinguishes between two types of errors when a message is published using <em>AT LEAST ONCE</em> delivery semantics:</p>
-
<ul>
<li>An error caused by the client side, e.g invalid message address, content-type, adapter disabled for tenant etc.</li>
<li>An error caused by the server side, e.g no downstream consumers registered, downstream connection loss etc.</li>
</ul>
-
<p>For a client side error, the adapter settles the message transfer with the <em>rejected</em> outcome and provides an error description in the corresponding disposition frame. In the case of a server-side error, the adapter settles the message with the <em>released</em> outcome, indicating to the client that the message itself was OK but it cannot be delivered due to a failure beyond the control of the client. In the latter case, a client may attempt to re-send the message unaltered.</p>
-
<p>In case of terminal errors the AMQP connection to the device is closed. The errors that are classified as terminal are listed below.</p>
-
<ul>
<li>The adapter is disabled for the tenant that the client belongs to.</li>
<li>The authenticated device or gateway is disabled or not registered.</li>
<li>The tenant is disabled or does not exist.</li>
</ul>
-
<h2 id="amqp-command-line-client">AMQP Command-line Client</h2>
-
<p>For purposes of demonstrating the usage of the AMQP adapter, the <strong>Hono CLI Module</strong> contains an AMQP command-line client for interacting with the AMQP adapter. The client can be used to send telemetry or events and to receive/respond to command request messages.</p>
-
<p>The command-line client supports the following parameters (with default values):</p>
-
<ul>
<li><code>--spring.profiles.active=amqp-send</code>: Profile for sending telemetry data or events to Hono.</li>
<li><code>--spring.profiles.active=amqp-command</code>: Profile for receiving and responding to command request messages.</li>
@@ -2165,73 +2170,59 @@
<li><code>--hono.client.host</code>: The host name that the AMQP adapter is running on (default: <code>localhost</code>)</li>
<li><code>--hono.client.port</code>: The port that the adapter is listening for incoming connections (default: <code>5672</code>)</li>
</ul>
-
<p>To run the client to send a telemetry message to Hono, open a terminal and execute the following:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.username<span style="color:#f92672">=</span>sensor1@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>hono-secret
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.username=sensor1@DEFAULT_TENANT --hono.client.password=hono-secret
-
-Accepted{}
-</code></pre>
-
-<p>The client prints the outcome of the operation to standard out. The outcome above (<code>Accepted</code>) indicates that the request to upload the data has succeeded.</p>
-
+Accepted<span style="color:#f92672">{}</span>
+</code></pre></div><p>The client prints the outcome of the operation to standard out. The outcome above (<code>Accepted</code>) indicates that the request to upload the data has succeeded.</p>
<p><strong>NB</strong>
There are two JAR files in the hono/cli/target directory. The JAR to use for the client is the <code>hono-cli-$VERSION-exec.jar</code> and not the <code>hono-cli-$VERSION.jar</code> file. Running the latter will not work and will output the message: <code>no main manifest attribute, in hono-cli-$VERSION.jar</code></p>
-
<h2 id="publishing-telemetry-data">Publishing Telemetry Data</h2>
-
<p>The client indicates the delivery mode to use when uploading telemetry messages by means of the <em>settled</em> and
<em>rcv-settle-mode</em> properties of the AMQP <em>transfer</em> frame(s) it uses for uploading the message.
The AMQP adapter will accept messages using a delivery mode according to the following table:</p>
-
<table>
<thead>
<tr>
-<th align="left">settled</th>
-<th align="left">rcv-settle-mode</th>
-<th align="left">Delivery semantics</th>
+<th style="text-align:left">settled</th>
+<th style="text-align:left">rcv-settle-mode</th>
+<th style="text-align:left">Delivery semantics</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><code>false</code></td>
-<td align="left"><code>first</code></td>
-<td align="left">The adapter will forward the message to the downstream AMQP 1.0 Messaging Network and will forward any AMQP <em>disposition</em> frame received from the AMQP 1.0 Messaging Network to the client <em>as is</em>. It is up to the client’s discretion if and how it processes the disposition frame. The adapter will accept any re-delivered message. Sending <em>unsettled</em> messages allows for clients to implement either <em>AT LEAST ONCE</em> or <em>AT MOST ONCE</em> delivery semantics, depending on whether a client actually waits for and considers the disposition frames it receives from the adapter or not. This is the recommended mode for uploading telemetry data.</td>
+<td style="text-align:left"><code>false</code></td>
+<td style="text-align:left"><code>first</code></td>
+<td style="text-align:left">The adapter will forward the message to the downstream AMQP 1.0 Messaging Network and will forward any AMQP <em>disposition</em> frame received from the AMQP 1.0 Messaging Network to the client <em>as is</em>. It is up to the client’s discretion if and how it processes the disposition frame. The adapter will accept any re-delivered message. Sending <em>unsettled</em> messages allows for clients to implement either <em>AT LEAST ONCE</em> or <em>AT MOST ONCE</em> delivery semantics, depending on whether a client actually waits for and considers the disposition frames it receives from the adapter or not. This is the recommended mode for uploading telemetry data.</td>
</tr>
-
<tr>
-<td align="left"><code>true</code></td>
-<td align="left"><code>first</code></td>
-<td align="left">The adapter will acknowledge and settle any received message spontaneously before forwarding it to the downstream AMQP 1.0 Messaging Network. The adapter will ignore any AMQP <em>disposition</em> frames it receives from the AMQP 1.0 Messaging Network. Sending <em>pre-settled</em> messages allows for clients to implement <em>AT MOST ONCE</em> delivery semantics only. This is the fastest mode of delivery but has the drawback of less reliable end-to-end flow control and potential loss of messages without notice.</td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left"><code>first</code></td>
+<td style="text-align:left">The adapter will acknowledge and settle any received message spontaneously before forwarding it to the downstream AMQP 1.0 Messaging Network. The adapter will ignore any AMQP <em>disposition</em> frames it receives from the AMQP 1.0 Messaging Network. Sending <em>pre-settled</em> messages allows for clients to implement <em>AT MOST ONCE</em> delivery semantics only. This is the fastest mode of delivery but has the drawback of less reliable end-to-end flow control and potential loss of messages without notice.</td>
</tr>
</tbody>
</table>
-
<p>All other combinations are not supported by the adapter and will result in the message being ignored (pre-settled) or rejected (unsettled).</p>
-
<h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2>
-
<ul>
<li>Authentication: SASL PLAIN or SASL EXTERNAL</li>
<li>Message <em>properties</em>:
-
<ul>
<li>(required) <code>to</code>: either <code>telemetry</code> or <code>t</code></li>
<li>(optional) <code>content-type</code>: The type of payload contained in the message body. The given content type will be used
in the AMQP message being forwarded downstream if not empty. Otherwise, the content type of the downstream
message will be set to <code>application/octet-stream</code> if the payload is not empty and no default content type has been
defined for the origin device or its tenant (see <a href="#downstream-meta-data">Downstream Meta Data</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Message Body:
-
<ul>
<li>(optional) Arbitrary payload contained in either a single AMQP <em>Data</em> or <em>AmqpValue</em> section. Note that the adapter
-only supports values of type <em>string</em> or <em>array</em> of *byte*s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
-</ul></li>
+only supports values of type <em>string</em> or <em>array</em> of <em>byte</em>s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
+</ul>
+</li>
<li>Outcomes:
-
<ul>
<li><code>accepted</code>: The message has been successfully forwarded downstream.</li>
<li><code>released</code>: The message could not be processed by the adapter due to a (temporary) problem that has not been caused
@@ -2239,55 +2230,45 @@
<li><code>rejected</code>: The message could not be processed by the adapter because the client and/or the message did not fulfill
some requirements. The <em>rejected</em> outcome’s <em>error</em> field will indicate the reason why the message could not
be processed. Possible error conditions include:
-
<ul>
<li><code>hono:bad-request</code>: The message does not meet all formal requirements, e.g. a required property is missing.</li>
<li><code>amqp:unauthorized-access</code>: The adapter is not enabled for the tenant that the client belongs to.</li>
<li><code>amqp:resource-limit-exceeded</code>: One of the <a href="#resource-limit-checks">Resource Limit Checks</a> has failed for the
tenant that the client belongs to.</li>
<li><code>amqp:precondition-failed</code>: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc.</li>
-</ul></li>
-</ul></li>
</ul>
-
+</li>
+</ul>
+</li>
+</ul>
<p>When a device publishes data to the <code>telemetry</code> address, the AMQP adapter automatically determines the device’s identity
and tenant during the authentication process.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.username=sensor1@DEFAULT_TENANT --hono.client.password=hono-secret
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.port=5671 --hono.client.certPath=config/hono-demo-certs-jar/device-4711-cert.pem --hono.client.keyPath=config/hono-demo-certs-jar/device-4711-key.pem --hono.client.trustStorePath=config/hono-demo-certs-jar/trusted-certs.pem --hono.client.hostnameVerificationRequired=false
-</code></pre>
-
-<h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.username<span style="color:#f92672">=</span>sensor1@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>hono-secret
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.port<span style="color:#f92672">=</span><span style="color:#ae81ff">5671</span> --hono.client.certPath<span style="color:#f92672">=</span>config/hono-demo-certs-jar/device-4711-cert.pem --hono.client.keyPath<span style="color:#f92672">=</span>config/hono-demo-certs-jar/device-4711-key.pem --hono.client.trustStorePath<span style="color:#f92672">=</span>config/hono-demo-certs-jar/trusted-certs.pem --hono.client.hostnameVerificationRequired<span style="color:#f92672">=</span>false
+</code></pre></div><h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2>
<ul>
<li>Authentication: SASL PLAIN or SASL EXTERNAL</li>
<li>Message <em>properties</em>:
-
<ul>
<li>(required) <code>to</code>: either <code>telemetry/${tenant-id}/${device-id}</code> or <code>t/${tenant-id}/${device-id}</code></li>
<li>(optional) <code>content-type</code>: The type of payload contained in the message body. The given content type will be used
in the AMQP message being forwarded downstream if not empty. Otherwise, the content type of the downstream
message will be set to <code>application/octet-stream</code> if the payload is not empty and no default content type has been
defined for the origin device or its tenant (see <a href="#downstream-meta-data">Downstream Meta Data</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Message Body:
-
<ul>
<li>(optional) Arbitrary payload contained in either a single AMQP <em>Data</em> or <em>AmqpValue</em> section. Note that the adapter
-only supports values of type <em>string</em> or <em>array</em> of *byte*s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
-</ul></li>
+only supports values of type <em>string</em> or <em>array</em> of <em>byte</em>s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
+</ul>
+</li>
<li>Outcomes:
-
<ul>
<li><code>accepted</code>: The message has been successfully forwarded downstream.</li>
<li><code>released</code>: The message could not be processed by the adapter due to a (temporary) problem that has not been caused
@@ -2295,69 +2276,53 @@
<li><code>rejected</code>: The message could not be processed by the adapter because the client and/or the message did not fulfill
some requirements. The <em>rejected</em> outcome’s <em>error</em> field will indicate the reason why the message could not
be processed. Possible error conditions include:
-
<ul>
<li><code>hono:bad-request</code>: The message does not meet all formal requirements, e.g. a required property is missing.</li>
<li><code>amqp:unauthorized-access</code>: The adapter is not enabled for the tenant that the client belongs to.</li>
<li><code>amqp:resource-limit-exceeded</code>: One of the <a href="#resource-limit-checks">Resource Limit Checks</a> has failed for the
tenant that the client belongs to.</li>
<li><code>amqp:precondition-failed</code>: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc.</li>
-</ul></li>
-</ul></li>
</ul>
-
+</li>
+</ul>
+</li>
+</ul>
<p>This address format is used by devices that have not authenticated to the protocol adapter. Note that this requires the
adapter’s <code>HONO_AMQP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --message.address=t/DEFAULT_TENANT/4711
-</code></pre>
-
-<h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --message.address<span style="color:#f92672">=</span>t/DEFAULT_TENANT/4711
+</code></pre></div><h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
<p>A device that publishes data on behalf of another device is called a gateway device. The message address is used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the message address is used to identify the device that the gateway publishes data for.</p>
-
<p><strong>Examples</strong></p>
-
<p>A gateway connecting to the adapter using <code>gw@DEFAULT_TENANT</code> as username and <code>gw-secret</code> as password and then publishing some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.username=gw@DEFAULT_TENANT --hono.client.password=gw-secret --message.address=t/DEFAULT_TENANT/4711
-</code></pre>
-
-<p>In this example, we are using message address <code>t/DEFAULT_TENANT/4711</code> which contains the device that the gateway is publishing the message for.</p>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.username<span style="color:#f92672">=</span>gw@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>gw-secret --message.address<span style="color:#f92672">=</span>t/DEFAULT_TENANT/4711
+</code></pre></div><p>In this example, we are using message address <code>t/DEFAULT_TENANT/4711</code> which contains the device that the gateway is publishing the message for.</p>
<h2 id="publishing-events">Publishing Events</h2>
-
<p>The adapter supports <em>AT LEAST ONCE</em> delivery of <em>Event</em> messages only. A client therefore MUST set the <em>settled</em>
property to <code>false</code> and the <em>rcv-settle-mode</em> property to <code>first</code> in all <em>transfer</em> frame(s) it uses for uploading events.
All other combinations are not supported by the adapter and result in the message being rejected.</p>
-
<h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2>
-
<ul>
<li>Authentication: SASL PLAIN or SASL EXTERNAL</li>
<li>Message <em>properties</em>:
-
<ul>
<li>(required) <code>to</code>: either <code>event</code> or <code>e</code></li>
<li>(optional) <code>content-type</code>: The type of payload contained in the message body. The given content type will be used
in the AMQP message being forwarded downstream if not empty. Otherwise, the content type of the downstream
message will be set to <code>application/octet-stream</code> if the payload is not empty and no default content type has been
defined for the origin device or its tenant (see <a href="#downstream-meta-data">Downstream Meta Data</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Message Body:
-
<ul>
<li>(optional) Arbitrary payload contained in either a single AMQP <em>Data</em> or <em>AmqpValue</em> section. Note that the adapter
-only supports values of type <em>string</em> or <em>array</em> of *byte*s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
-</ul></li>
+only supports values of type <em>string</em> or <em>array</em> of <em>byte</em>s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
+</ul>
+</li>
<li>Outcomes:
-
<ul>
<li><code>accepted</code>: The message has been successfully forwarded downstream.</li>
<li><code>released</code>: The message could not be processed by the adapter due to a (temporary) problem that has not been caused
@@ -2365,49 +2330,42 @@
<li><code>rejected</code>: The message could not be processed by the adapter because the client and/or the message did not fulfill
some requirements. The <em>rejected</em> outcome’s <em>error</em> field will indicate the reason why the message could not
be processed. Possible error conditions include:
-
<ul>
<li><code>hono:bad-request</code>: The message does not meet all formal requirements, e.g. a required property is missing.</li>
<li><code>amqp:unauthorized-access</code>: The adapter is not enabled for the tenant that the client belongs to.</li>
<li><code>amqp:resource-limit-exceeded</code>: One of the <a href="#resource-limit-checks">Resource Limit Checks</a> has failed for the
tenant that the client belongs to.</li>
<li><code>amqp:precondition-failed</code>: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc.</li>
-</ul></li>
-</ul></li>
</ul>
-
+</li>
+</ul>
+</li>
+</ul>
<p>This is the preferred way for devices to publish events. It is available only if the protocol adapter has been
configured to require devices to authenticate (which is the default).</p>
-
<p><strong>Example</strong></p>
-
<p>Upload a JSON string for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.username=sensor1@DEFAULT_TENANT --hono.client.password=hono-secret --message.address=event --message.payload='{"alarm": 1}'
-</code></pre>
-
-<h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.username<span style="color:#f92672">=</span>sensor1@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>hono-secret --message.address<span style="color:#f92672">=</span>event --message.payload<span style="color:#f92672">=</span><span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
<ul>
<li>Authentication: SASL PLAIN or SASL EXTERNAL</li>
<li>Message <em>properties</em>:
-
<ul>
<li>(required) <code>to</code>: either <code>event/${tenant-id}/${device-id}</code> or <code>e/${tenant-id}/${device-id}</code></li>
<li>(optional) <code>content-type</code>: The type of payload contained in the message body. The given content type will be used
in the AMQP message being forwarded downstream if not empty. Otherwise, the content type of the downstream
message will be set to <code>application/octet-stream</code> if the payload is not empty and no default content type has been
defined for the origin device or its tenant (see <a href="#downstream-meta-data">Downstream Meta Data</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Message Body:
-
<ul>
<li>(optional) Arbitrary payload contained in either a single AMQP <em>Data</em> or <em>AmqpValue</em> section. Note that the adapter
-only supports values of type <em>string</em> or <em>array</em> of *byte*s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
-</ul></li>
+only supports values of type <em>string</em> or <em>array</em> of <em>byte</em>s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
+</ul>
+</li>
<li>Outcomes:
-
<ul>
<li><code>accepted</code>: The message has been successfully forwarded downstream.</li>
<li><code>released</code>: The message could not be processed by the adapter due to a (temporary) problem that has not been caused
@@ -2415,126 +2373,94 @@
<li><code>rejected</code>: The message could not be processed by the adapter because the client and/or the message did not fulfill
some requirements. The <em>rejected</em> outcome’s <em>error</em> field will indicate the reason why the message could not
be processed. Possible error conditions include:
-
<ul>
<li><code>hono:bad-request</code>: The message does not meet all formal requirements, e.g. a required property is missing.</li>
<li><code>amqp:unauthorized-access</code>: The adapter is not enabled for the tenant that the client belongs to.</li>
<li><code>amqp:resource-limit-exceeded</code>: One of the <a href="#resource-limit-checks">Resource Limit Checks</a> has failed for the
tenant that the client belongs to.</li>
<li><code>amqp:precondition-failed</code>: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc.</li>
-</ul></li>
-</ul></li>
</ul>
-
+</li>
+</ul>
+</li>
+</ul>
<p>This address format is used by devices that have not authenticated to the protocol adapter. Note that this requires the
adapter’s <code>HONO_AMQP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Example</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --message.address=e/DEFAULT_TENANT/4711 --message.payload='{"alarm": 1}'
-</code></pre>
-
-<h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --message.address<span style="color:#f92672">=</span>e/DEFAULT_TENANT/4711 --message.payload<span style="color:#f92672">=</span><span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
<p><strong>Example</strong></p>
-
<p>A gateway connecting to the adapter using <code>gw@DEFAULT_TENANT</code> as username and <code>gw-secret</code> as password and then publishing some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-send --hono.client.username=gw@DEFAULT_TENANT --hono.client.password=gw-secret --message.address=e/DEFAULT_TENANT/4711
-</code></pre>
-
-<p>In this example, we are using message address <code>e/DEFAULT_TENANT/4711</code> which contains the device that the gateway is publishing the message for.</p>
-
-<h2 id="command-control">Command & Control</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-send --hono.client.username<span style="color:#f92672">=</span>gw@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>gw-secret --message.address<span style="color:#f92672">=</span>e/DEFAULT_TENANT/4711
+</code></pre></div><p>In this example, we are using message address <code>e/DEFAULT_TENANT/4711</code> which contains the device that the gateway is publishing the message for.</p>
+<h2 id="command--control">Command & Control</h2>
<p>The AMQP adapter enables devices to receive commands that have been sent by business applications by means of opening a receiver link using a device specific <em>source address</em> as described below. When a device no longer wants to receive commands anymore, it can simply close the link.</p>
-
<p>When a device has successfully opened a receiver link for commands, the adapter sends an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a> on behalf of the device to the downstream AMQP 1.0 Messaging Network with the <em>ttd</em> header set to <code>-1</code>, indicating that the device will be ready to receive commands until further notice. Analogously, the adapter sends an empty notification with the <em>ttd</em> header set to <code>0</code> when a device closes the link or disconnects.</p>
-
<p>Devices send their responses to commands by means of sending an AMQP message with properties specific to the command that has been executed. The AMQP adapter accepts responses being published using either <em>at most once</em> (QoS 0) or <em>at least once</em> (QoS 1) delivery semantics. The device must send the command response messages using the same (sender) link that it uses for sending telemetry data and events.</p>
-
-<p>The AMQP adapter checks the configured <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> before accepting any command requests and responses. In case of incoming command requests from business applications or the command responses from devices, if the message limit is exceeded, the Adapter rejects the message with the reason <code>amqp:resource-limit-exceeded</code>.</p>
-
+<p>The AMQP adapter checks the configured [message limit] (/hono/docs/dev/concepts/resource-limits/) before accepting any command requests and responses. In case of incoming command requests from business applications or the command responses from devices, if the message limit is exceeded, the Adapter rejects the message with the reason <code>amqp:resource-limit-exceeded</code>.</p>
<h3 id="receiving-commands">Receiving Commands</h3>
-
<p>A device MUST use the following source address in its <em>attach</em> frame to open a link for receiving commands:</p>
-
<ul>
<li><code>command</code> (authenticated device)</li>
<li><code>command</code> (authenticated gateway receiving commands for all devices it acts on behalf of)</li>
<li><code>command/${tenant}/${device-id}</code> (unauthenticated device)</li>
<li><code>command/${tenant}/${device-id}</code> (authenticated gateway receiving commands for a specific device it acts on behalf of)</li>
</ul>
-
<p>The adapter supports <em>AT LEAST ONCE</em> delivery of command messages only. A client therefore MUST use <code>unsettled</code> for
the <em>snd-settle-mode</em> and <code>first</code> for the <em>rcv-settle-mode</em> fields of its <em>attach</em> frame during link establishment.
All other combinations are not supported and result in the termination of the link.</p>
-
<p>Once the link has been established, the adapter will send command messages having the following properties:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="center">Mandatory</th>
-<th align="left">Location</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<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 align="left"><em>subject</em></td>
-<td align="center">yes</td>
-<td align="left"><em>properties</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the name of the command to be executed.</td>
+<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">Contains the name of the command to be executed.</td>
</tr>
-
<tr>
-<td align="left"><em>reply-to</em></td>
-<td align="center">no</td>
-<td align="left"><em>properties</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the address to which the command response should be sent. This property will be empty for <em>one-way</em> commands.</td>
+<td style="text-align:left"><em>reply-to</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">Contains the address to which the command response should be sent. This property will be empty for <em>one-way</em> commands.</td>
</tr>
-
<tr>
-<td align="left"><em>correlation-id</em></td>
-<td align="center">no</td>
-<td align="left"><em>properties</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">This property will be empty for <em>one-way</em> commands, otherwise it will contain the identifier used to correlate the response with the command request.</td>
+<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">This property will be empty for <em>one-way</em> commands, otherwise it will contain the identifier used to correlate the response with the command request.</td>
</tr>
-
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="center">no</td>
-<td align="left"><em>application-properties</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">This property will only be set if an authenticated gateway has connected to the adapter. It will contain the id of the device (connected to the gateway) that the command is targeted at.</td>
+<td style="text-align:left"><em>device_id</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">This property will only be set if an authenticated gateway has connected to the adapter. It will contain the id of the device (connected to the gateway) that the command is targeted at.</td>
</tr>
</tbody>
</table>
-
-<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/#configuring-gateway-devices">Configuring Gateway Devices</a> for details.</p>
-
+<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/">Configuring Gateway Devices</a> for details.</p>
<p>A gateway can open a link to receive commands for <em>all</em> devices it acts on behalf of. An authenticated gateway can also open a receiver link for commands targeted at a <em>specific</em> device.</p>
-
<p>When processing an incoming command message, the protocol adapter will give precedence to a device-specific command consumer matching the command target device, whether it was created by a gateway or by the device itself. If multiple such consumer links have been created, by multiple gateways and/or from the device itself, the gateway or device that last created the consumer link will get the command messages.</p>
-
<p>If no device-specific command consumer exists for a command target device, but <em>one</em> gateway, that may act on behalf of the device, has opened a generic, device-unspecific command consumer link, then the command message is sent to that gateway.</p>
-
<p>If <em>multiple</em> gateways have opened a generic command consumer link, the protocol adapter may have to decide to which gateway a particular command message will be sent to.
In case the command target device has already sent a telemetry, event or command response message via a gateway and if that gateway has opened a command consumer link, that gateway will be chosen. Otherwise one gateway that may act on behalf of the command target device and that has opened a command consumer link will be chosen randomly to receive the command message.</p>
-
<p>Clients MUST settle command messages using one of the following outcomes:</p>
-
<ul>
<li><code>accepted</code>: The command message has been accepted for processing.</li>
<li><code>released</code>: The command message can not be processed by the client due to a (temporary) problem at the client side.</li>
@@ -2542,40 +2468,35 @@
some requirements. The <em>rejected</em> outcome’s <em>error</em> field SHOULD indicate the reason why the message can not
be processed.</li>
</ul>
-
<h3 id="sending-a-response-to-a-command">Sending a Response to a Command</h3>
-
<p>A device only needs to respond to commands that contain a <em>reply-to</em> address and a <em>correlation-id</em>.
However, if the application expects a response, then devices must publish a response back to the application.
Devices may use the same anonymous sender link for this purpose that they also use for sending telemetry data and events.</p>
-
<p>The adapter supports <em>AT LEAST ONCE</em> delivery of command response messages only. A client therefore MUST set the
<em>settled</em> property to <code>false</code> and the <em>rcv-settle-mode</em> property to <code>first</code> in all <em>transfer</em> frame(s) it uses
for uploading command responses. All other combinations are not supported by the adapter and result in the message being rejected.</p>
-
<ul>
<li>Authentication: SASL PLAIN or SASL EXTERNAL</li>
<li>Message <em>properties</em>:
-
<ul>
<li>(required) <code>to</code>: MUST contain the value of the <em>reply-to</em> property of the command request message.</li>
<li>(required) <code>correlation-id</code>: MUST contain the value of the <em>correlation-id</em> property of the command request message.</li>
<li>(optional) <code>content-type</code>: The type of payload contained in the message body.</li>
-</ul></li>
+</ul>
+</li>
<li>Message <em>application-properties</em>:
-
<ul>
<li>(required) <code>status</code>: MUST contain an integer status code indicating the outcome of processing the command at the
device (see <a href="/hono/docs/dev/api/command-and-control/">Command & Control API</a> for details).</li>
-</ul></li>
+</ul>
+</li>
<li>Message Body:
-
<ul>
<li>(optional) Arbitrary payload contained in either a single AMQP <em>Data</em> or <em>AmqpValue</em> section. Note that the adapter
-only supports values of type <em>string</em> or <em>array</em> of *byte*s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
-</ul></li>
+only supports values of type <em>string</em> or <em>array</em> of <em>byte</em>s in the <em>AmqpValue</em> section. Values of other types will be ignored.</li>
+</ul>
+</li>
<li>Outcomes:
-
<ul>
<li><code>accepted</code>: The message has been successfully forwarded downstream.</li>
<li><code>released</code>: The message could not be processed by the adapter due to a (temporary) problem that has not been caused
@@ -2583,133 +2504,102 @@
<li><code>rejected</code>: The message could not be processed by the adapter because the client and/or the message did not fulfill
some requirements. The <em>rejected</em> outcome’s <em>error</em> field will indicate the reason why the message could not
be processed. Possible error conditions include:
-
<ul>
<li><code>hono:bad-request</code>: The message does not meet all formal requirements, e.g. a required property is missing.</li>
<li><code>amqp:unauthorized-access</code>: The adapter is not enabled for the tenant that the client belongs to.</li>
<li><code>amqp:resource-limit-exceeded</code>: One of the <a href="#resource-limit-checks">Resource Limit Checks</a> has failed for the
tenant that the client belongs to.</li>
<li><code>amqp:precondition-failed</code>: The message does not fulfill certain requirements, e.g adapter cannot assert device registration etc.</li>
-</ul></li>
-</ul></li>
</ul>
-
+</li>
+</ul>
+</li>
+</ul>
<h3 id="examples">Examples</h3>
-
<p>The AMQP adapter client can be used to simulate a device which receives commands and sends responses back to the application. The command line client is used to simulate an application sending commands to devices and receiving command responses from devices.</p>
-
<p>Start the AMQP adapter client, as follows:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/target/
-java -jar hono-cli-*-exec.jar --spring.profiles.active=amqp-command --hono.client.username=sensor1@DEFAULT_TENANT --hono.client.password=hono-secret
-</code></pre>
-
-<p>After successfully starting the client, a message indicating that the device is ready to receive commands will be printed to standard output. The device is now waiting to receive commands from applications.</p>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/target/</span>
+java -jar hono-cli-*-exec.jar --spring.profiles.active<span style="color:#f92672">=</span>amqp-command --hono.client.username<span style="color:#f92672">=</span>sensor1@DEFAULT_TENANT --hono.client.password<span style="color:#f92672">=</span>hono-secret
+</code></pre></div><p>After successfully starting the client, a message indicating that the device is ready to receive commands will be printed to standard output. The device is now waiting to receive commands from applications.</p>
<p>To send a command to the device, open a new terminal shell and start the command application, as shown below:</p>
-
-<pre><code class="language-sh"># in directory: hono/cli/
-java -jar target/hono-cli-*-exec.jar --hono.client.host=localhost --hono.client.username=consumer@HONO --hono.client.password=verysecret --spring.profiles.active=command,ssl
-</code></pre>
-
-<div class="alert alert-notice">
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in directory: hono/cli/</span>
+java -jar target/hono-cli-*-exec.jar --hono.client.host<span style="color:#f92672">=</span>localhost --hono.client.username<span style="color:#f92672">=</span>consumer@HONO --hono.client.password<span style="color:#f92672">=</span>verysecret --spring.profiles.active<span style="color:#f92672">=</span>command,ssl
+</code></pre></div><div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>Change into the <code>cli</code> directory before running the command above to start the command application. If you change into the target directory (i.e <code>cli/target</code>), then the client will not be able to locate to certificate needed to connect to the messaging network.</div>
</div>
-
<p>Once the command application starts successfully, enter a command name, payload and content-type of the command to send to the device.</p>
-
-<pre><code class="language-plaintext">>>>>>>>>> Enter name of command for device [DEFAULT_TENANT:4711] (prefix with 'ow:' to send one-way command):
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">>>>>>>>>> Enter name of command for device [DEFAULT_TENANT:4711] (prefix with 'ow:' to send one-way command):
setBrightness
>>>>>>>>> Enter command payload:
some-payload
>>>>>>>>> Enter content type:
text/plain
-</code></pre>
-
-<p>After sending the command, the device (i.e. AMQP command client) will print out the command name and payload that it receives and automatically sends a command response to the application.</p>
-
-<pre><code class="language-plaintext">Received Command Message : [Command name: setBrightness, Command payload: some-payload]
+</code></pre></div><p>After sending the command, the device (i.e. AMQP command client) will print out the command name and payload that it receives and automatically sends a command response to the application.</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">Received Command Message : [Command name: setBrightness, Command payload: some-payload]
Command response sent [outcome: Accepted{}]
-</code></pre>
-
-<h2 id="downstream-meta-data">Downstream Meta Data</h2>
-
+</code></pre></div><h2 id="downstream-meta-data">Downstream Meta Data</h2>
<p>The adapter includes the following meta data in the application properties of messages being sent downstream:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier of the device that the message originates from.</td>
+<td style="text-align:left"><em>device_id</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">The identifier of the device that the message originates from.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_adapter</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The AMQP adapter’s type name is <code>hono-amqp</code>.</td>
+<td style="text-align:left"><em>orig_adapter</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The AMQP adapter’s type name is <code>hono-amqp</code>.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_address</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the AMQP <em>target address</em> that the device has used to send the data.</td>
+<td style="text-align:left"><em>orig_address</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the AMQP <em>target address</em> that the device has used to send the data.</td>
</tr>
</tbody>
</table>
-
<p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a>
or the <a href="/hono/docs/dev/api/device-registration/#assert-device-registration">device level</a>.
The values of the default properties are determined as follows:</p>
-
<ol>
<li>If the message already contains a non-empty property of the same name, the value if unchanged.</li>
<li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li>
<li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li>
</ol>
-
<p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p>
-
<h3 id="event-message-time-to-live">Event Message Time-to-live</h3>
-
<p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers.
In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed
from the persistent store if no consumer has attached to receive the event before the message expires.</p>
-
<p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the protocol adapter supports setting a
downstream event message’s <em>ttl</em> property based on the default <em>ttl</em> and <em>max-ttl</em> values configured for a tenant/device as described in the
<a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p>
-
<h2 id="tenant-specific-configuration">Tenant specific Configuration</h2>
-
<p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-amqp</code>.
The following properties are (currently) supported:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Default Value</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Default Value</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>enabled</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left"><code>true</code></td>
-<td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant and respond with a <code>amqp:unauthorized-access</code> as the error condition value for rejecting the message.</td>
+<td style="text-align:left"><em>enabled</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant and respond with a <code>amqp:unauthorized-access</code> as the error condition value for rejecting the message.</td>
</tr>
</tbody>
</table>
@@ -3836,19 +3726,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/coap-adapter/index.html b/docs/dev/user-guide/coap-adapter/index.html
index beacded..4cbef71 100644
--- a/docs/dev/user-guide/coap-adapter/index.html
+++ b/docs/dev/user-guide/coap-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>CoAP Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/coap-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/coap-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/coap-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/coap-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/coap-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/coap-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/coap-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/coap-adapter/">1.2</option>
@@ -1794,6 +1834,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/coap-adapter/" selected>dev</option>
@@ -1912,35 +1954,35 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#device-authentication">Device Authentication</a>
-<ul>
-<li><a href="#psk">PSK</a></li>
-</ul></li>
-<li><a href="#message-limits">Message Limits</a></li>
-<li><a href="#coap-content-format-codes">CoAP Content Format Codes</a></li>
-<li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
-<li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
-<li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
-<li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
-<li><a href="#command-control">Command & Control</a>
-<ul>
-<li><a href="#commands-handled-by-gateways">Commands handled by gateways</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
-</ul></li>
-<li><a href="#downstream-meta-data">Downstream Meta Data</a>
-<ul>
-<li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
-</ul></li>
-<li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#device-authentication">Device Authentication</a>
+ <ul>
+ <li><a href="#psk">PSK</a></li>
+ </ul>
+ </li>
+ <li><a href="#message-limits">Message Limits</a></li>
+ <li><a href="#coap-content-format-codes">CoAP Content Format Codes</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
+ <li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
+ <li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
+ <li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
+ <li><a href="#command--control">Command & Control</a>
+ <ul>
+ <li><a href="#commands-handled-by-gateways">Commands handled by gateways</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
+ </ul>
+ </li>
+ <li><a href="#downstream-meta-data">Downstream Meta Data</a>
+ <ul>
+ <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
+ </ul>
+ </li>
+ <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -1964,79 +2006,62 @@
-<p>The CoAP protocol adapter exposes <a href="https://tools.ietf.org/html/rfc7252">CoAP</a> based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.</p>
-
+<p>The CoAP protocol adapter exposes <a href="https://tools.ietf.org/html/rfc7252">CoAP</a> based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.</p>
<h2 id="device-authentication">Device Authentication</h2>
-
<p>The CoAP adapter by default requires clients (devices or gateway components) to authenticate during connection establishment.
The adapter (currently) only supports <a href="https://tools.ietf.org/html/rfc4279">PSK</a> as part of a DTLS handshake for that purpose.
Additional variants mentioned in <a href="https://tools.ietf.org/html/rfc7252#section-9">Securing CoAP</a> might be added in the future.</p>
-
<p>The adapter tries to authenticate the device using these mechanisms in the following order</p>
-
<h3 id="psk">PSK</h3>
-
<p>The <em>identity</em> provided in the ClientKeyExchange must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>.
The adapter performs the handshake using the credentials the <a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">configured Credentials service</a>
has on record for the client. The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record
with the <em>tenant</em> and <em>auth-id</em> provided by the device in the <em>identity</em> and <code>psk</code> as the <em>type</em> of secret as query parameters.</p>
-
<p>The examples below refer to devices <code>4711</code> and <code>gw-1</code> of tenant <code>DEFAULT_TENANT</code> using <em>auth-ids</em> <code>sensor1</code> and <code>gw1</code> and
corresponding secrets. The example deployment as described in the <a href="/hono/docs/dev/deployment/">Deployment Guides</a> comes pre-configured
with the corresponding entities in its device registry component.
Please refer to the <a href="/hono/docs/dev/api/credentials/#standard-credential-types">Credentials API</a> for details regarding the different
types of secrets.</p>
-
<p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication. See <a href="/hono/docs/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p>
-
<h2 id="message-limits">Message Limits</h2>
-
<p>The adapter rejects</p>
-
<ul>
<li>a client’s request to upload data with status code <code>429 Too Many Requests</code> and</li>
<li>any AMQP 1.0 message containing a command sent by a north bound application</li>
</ul>
-
<p>if the <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p>
-
<h2 id="coap-content-format-codes">CoAP Content Format Codes</h2>
-
<p>CoAP doesn’t use a textual identifier for content types. Instead, numbers are used, which are maintained by the <a href="https://www.iana.org/">IANA</a>.
The <a href="https://www.iana.org/assignments/core-parameters/core-parameters.xhtml#content-formats">IANA - CoAP Content Formats</a> page lists all
(currently) registered codes and the corresponding media types.</p>
-
<h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2>
-
<p>The device is authenticated using PSK.</p>
-
<ul>
<li>URI: <code>/telemetry</code></li>
<li>Method: <code>POST</code></li>
<li>Type:
-
<ul>
<li><code>CON</code>: <em>at least once</em> delivery semantics</li>
<li><code>NON</code>: <em>at most once</em> delivery semantics</li>
-</ul></li>
+</ul>
+</li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2049,116 +2074,88 @@
In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its
response to the command.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device.</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require
devices to authenticate (which is the default).</p>
-
<p><strong>Examples</strong></p>
-
<p>The examples provided below make use of the <em>coap-client</em> command line tool which is part of the <a href="https://libcoap.net/">libcoap project</a>.
Precompiled packages should be available for different Linux variants.</p>
-
<p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
-
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<div class="alert alert-notice">
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div><em>coap-client</em> only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.</div>
</div>
-
<p>Publish some JSON data for device <code>4711</code> using message type <code>NON</code> (<em>at most once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -N -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -N -m POST coaps://hono.eclipseprojects.io/telemetry -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/telemetry?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<div class="alert alert-notice">
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>In the example above the response actually contains payload that should be used as input to a command to be executed by the device.
This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could
send any commands to the device.</div>
</div>
-
<h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2>
-
<ul>
<li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type:
-
<ul>
<li><code>CON</code>: <em>at least once</em> delivery semantics</li>
<li><code>NON</code>: <em>at most once</em> delivery semantics</li>
-</ul></li>
+</ul>
+</li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2171,102 +2168,77 @@
In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its
response to the command.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the
<code>HONO_COAP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using message type <code>NON</code> (<em>at most once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -N -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code> using message type <code>NON</code> (<em>at most once</em>):</p>
-
-<pre><code class="language-sh">coap-client -N -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
-
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
<ul>
<li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type:
-
<ul>
<li><code>CON</code>: <em>at least once</em> delivery semantics</li>
<li><code>NON</code>: <em>at most once</em> delivery semantics</li>
-</ul></li>
+</ul>
+</li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2280,110 +2252,82 @@
response to the command. Note that in both cases the <code>${tenantId}/${deviceId}</code> path segments indicate the device that
the command is targeted at.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li>
-<li>The device belongs to another tenant than the gateway.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The tenant that the gateway belongs to is not allowed to use this protocol adapter.
+* The device belongs to another tenant than the gateway.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the message type is <code>CON</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter
directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a>
or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the
protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway
publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em>
for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4712</code> using message type <code>NON</code> (<em>at most once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -N -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4712</code> using message type <code>NON</code> (<em>at most once</em>):</p>
-
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -N -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/telemetry/DEFAULT_TENANT/4712?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code>
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code>
which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
<h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2>
-
<p>The device is authenticated using PSK.</p>
-
<ul>
<li>URI: <code>/event</code></li>
<li>Method: <code>POST</code></li>
<li>Type:<code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2396,96 +2340,77 @@
In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its
response to the command.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish events. It is available only if the protocol adapter is configured to require
devices to authenticate (which is the default).</p>
-
<p><strong>Examples</strong></p>
-
<p>The examples provided below make use of the <em>coap-client</em> command line tool which is part of the <a href="https://libcoap.net/">libcoap project</a>.
Precompiled packages should be available for different Linux variants.</p>
-
<p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
-
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<div class="alert alert-notice">
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div><em>coap-client</em> only reports error response-codes, so the expected 2.04 response code will not be printed to the terminal.</div>
</div>
-
<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret -m POST coaps://hono.eclipseprojects.io/event?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<div class="alert alert-notice">
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>In the example above the response actually contains payload that should be used as input to a command to be executed by the device.
This is just for illustrative purposes. You will usually get an empty response because there is no downstream application attached which could
send any commands to the device.</div>
</div>
-
<h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
-
<ul>
<li>URI: <code>/event/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type:<code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2498,82 +2423,66 @@
In the latter case, the <em>location-path</em> option contains exactly the URI-path that the device must use when sending its
response to the command.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for the device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the
<code>HONO_COAP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">coap-client -m PUT coap://hono.eclipseprojects.io/event/DEFAULT_TENANT/4711?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
-
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
<ul>
<li>URI: <code>/event/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type:<code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-format</code>: The type of payload contained in the request body. Required, if request contains payload.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>empty</code>: Marks the request as an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a>.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if <code>URI-query: empty</code> is provided.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Options:
-
<ul>
<li>(optional) <code>content-format</code>: A media type describing the semantics and format of payload contained in the response body.
This option will only be present if the response contains a command to be executed by the device which requires input data.
@@ -2587,367 +2496,285 @@
response to the command. Note that in both cases the <code>${tenantId}/${deviceId}</code> path segments indicate the device that
the command is targeted at.
This option will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 2.05 (Content).</li>
<li>(optional) Error details, if status code is >= 4.00.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The data in the request body has been accepted for processing. The response may contain a command for a device to execute.
Note that if the message type is <code>NON</code> (<em>at most once</em> semantics), this status code does <strong>not</strong> mean that the message has been
delivered to any potential consumer (yet). However, if the message type is <code>CON</code> (<em>at least once</em> semantics), then the adapter waits
for the message to be delivered and accepted by a downstream consumer before responding with this status code.</li>
<li>4.00 (Bad Request): The request cannot be processed. Possible reasons include:
-
-<ul>
-<li>the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
-</ul></li>
+* the request body is empty, and the <em>URI-query</em> option doesn’t contain the <code>empty</code> parameter.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li>
-<li>The device belongs to another tenant than the gateway.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The tenant that the gateway belongs to is not allowed to use this protocol adapter.
+* The device belongs to another tenant than the gateway.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter
directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a>
or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the
protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway
publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em>
for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code> using default message type <code>CON</code> (<em>at least once</em>):</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712 -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -t application/json -e <span style="color:#e6db74">'{"temp": 5}'</span>
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712 -t application/json -e '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret -m PUT coaps://hono.eclipseprojects.io/event/DEFAULT_TENANT/4712?hono-ttd=10 -t application/json -e '{"temp": 5}'
-
-{
- "brightness": 87
-}
-</code></pre>
-
-<p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code>
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><p><strong>NB</strong> The examples above assume that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code>
which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
-<h2 id="command-control">Command & Control</h2>
-
+<h2 id="command--control">Command & Control</h2>
<p>The CoAP adapter enables devices to receive commands that have been sent by business applications. Commands are delivered to the device by means of a response message. That means a device first has to send a request, indicating how long it will wait for the response. That request can either be a telemetry or event message, with a <code>hono-ttd</code> query parameter (<code>ttd</code> for <code>time till disconnect</code>) specifying the number of seconds the device will wait for the response. The business application can react on that message by sending a command message, targeted at the device. The CoAP adapter will then send the command message as part of the response message to the device.</p>
-
<h3 id="commands-handled-by-gateways">Commands handled by gateways</h3>
-
-<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/#configuring-gateway-devices">Configuring Gateway Devices</a> for details.</p>
-
+<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/">Configuring Gateway Devices</a> for details.</p>
<p>A gateway can send a request with the <code>hono-ttd</code> query parameter on the <code>/event</code> or <code>/telemetry</code> URI, indicating its readiness to receive a command for <em>any</em> device it acts on behalf of. Note that in this case, the business application will be notified with the gateway id in the <code>device_id</code> property of the downstream message.</p>
-
<p>An authenticated gateway can also indicate its readiness to receive a command targeted at a <em>specific</em> device. For that, the <code>/event/${tenantId}/${deviceId}</code> or <code>/telemetry/${tenantId}/${deviceId}</code> URI is to be used, containing the id of the device to receive a command for. The business application will receive a notification with that device id.</p>
-
<p>If there are multiple concurrent requests with a <code>hono-ttd</code> query parameter, sent by the command target device and/or one or more of its potential gateways, the CoAP adapter will choose the device or gateway to send the command to as follows:</p>
-
<ul>
<li>A request done by the command target device or by a gateway specifically done for that device, has precedence. If there are multiple, concurrent such requests, the last one will get the command message (if received) in its response. Note that the other requests won’t be answered with a command message in their response event if the business application sent multiple command messages. That means commands for a single device can only be requested sequentially, not in parallel.</li>
<li>If the above doesn’t apply, a single <code>hono-ttd</code> request on the <code>/event</code> or <code>/telemetry</code> URI, sent by a gateway that the command target device is configured for, will get the command message in its response.</li>
<li>If there are multiple, concurrent such requests by different gateways, all configured for the command target device, the request by the gateway will be chosen, through which the target device has last sent a telemetry or event message. If the target device hasn’t sent a message yet and it is thereby unknown via which gateway the device communicates, then one of the requests will be chosen randomly to set the command in its response.</li>
</ul>
-
<h3 id="sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</h3>
-
<p>The device is authenticated using PSK.</p>
-
<ul>
<li>URI: <code>/command_response/${commandRequestId}</code></li>
<li>Method: <code>POST</code></li>
<li>Type: <code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body.
This option must be set if the result of processing the command on the device is non-empty. In this case the result data is
contained in the request body.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li>
<li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to respond to commands. It is available only if the protocol adapter is configured to require devices to
authenticate (which is the default).</p>
-
<p><strong>Example</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4711</code>:</p>
-
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/req-id-uuid?hono-cmd-status=200
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
<ul>
<li>URI: <code>/command_response/${tenantId}/${deviceId}/${commandRequestId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type: <code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body.
This option must be set if the result of processing the command on the device is non-empty. In this case the result data is
contained in the request body.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li>
<li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the
<code>HONO_HTTP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for the unauthenticated device <code>4711</code>:</p>
-
-<pre><code class="language-sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status=200 -e '{"brightness-changed": true}'
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u sensor1@DEFAULT_TENANT -k hono-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span> -e <span style="color:#e6db74">'{"brightness-changed": true}'</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
<ul>
<li>URI: <code>/command_response/${tenantId}/${deviceId}/${commandRequestId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Type: <code>CON</code></li>
<li>Request Options:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body.
This option must be set if the result of processing the command on the device is non-empty. In this case the result data is
contained in the request body.</li>
-</ul></li>
+</ul>
+</li>
<li>Query Parameters:
-
<ul>
<li>(required) <code>hono-cmd-status</code>: An HTTP status code indicating the outcome of processing the command.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Codes:
-
<ul>
<li>2.04 (Changed): The response has been successfully delivered to the application that has sent the command.</li>
<li>4.00 (Bad Request): The request cannot be processed because the command status or command request ID are missing/malformed.</li>
<li>4.03 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted.
Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>4.04 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>4.13 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>4.29 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>5.03 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to send the response to a command <em>on behalf of</em> other devices which do not connect
to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like
<a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during
connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used
to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to send responses to a command on behalf of the device implicitly by means of
-retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
+retrieving a <em>registration assertion</em> for the device from the [configured Device Registration service]
+(/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration).</p>
<p><strong>Examples</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4712</code>:</p>
-
-<pre><code class="language-sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4712/req-id-uuid?hono-cmd-status=200 -e '{"brightness-changed": true}'
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code> which is
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">coap-client -u gw@DEFAULT_TENANT -k gw-secret coaps://hono.eclipseprojects.io/command_response/DEFAULT_TENANT/4712/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span> -e <span style="color:#e6db74">'{"brightness-changed": true}'</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>psk</code> credentials with <em>auth-id</em> <code>gw</code> and secret <code>gw-secret</code> which is
authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
<h2 id="downstream-meta-data">Downstream Meta Data</h2>
-
<p>The adapter includes the following meta data in the application properties of messages being sent downstream:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier of the device that the message originates from.</td>
+<td style="text-align:left"><em>device_id</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">The identifier of the device that the message originates from.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_adapter</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The CoAP adapter’s type name is <code>hono-coap</code>.</td>
+<td style="text-align:left"><em>orig_adapter</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The CoAP adapter’s type name is <code>hono-coap</code>.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_address</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the (relative) URI that the device has originally posted the data to.</td>
+<td style="text-align:left"><em>orig_address</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the (relative) URI that the device has originally posted the data to.</td>
</tr>
-
<tr>
-<td align="left"><em>ttd</em></td>
-<td align="left"><em>integer</em></td>
-<td align="left">Contains the effective number of seconds that the device will wait for a response. This property is only set if the request contains the <code>hono-ttd</code> <em>URI-query</em> option.</td>
+<td style="text-align:left"><em>ttd</em></td>
+<td style="text-align:left"><em>integer</em></td>
+<td style="text-align:left">Contains the effective number of seconds that the device will wait for a response. This property is only set if the request contains the <code>hono-ttd</code> <em>URI-query</em> option.</td>
</tr>
</tbody>
</table>
-
<p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a> or the <a href="/hono/docs/dev/api/device-registration/#assert-device-registration">device level</a>. The values of the default properties are determined as follows:</p>
-
<ol>
<li>If the message already contains a non-empty property of the same name, the value if unchanged.</li>
<li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li>
<li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li>
</ol>
-
<p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p>
-
<h3 id="event-message-time-to-live">Event Message Time-to-live</h3>
-
<p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers.
In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed
from the persistent store if no consumer has attached to receive the event before the message expires.</p>
-
<p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the protocol adapter supports setting a
downstream event message’s <em>ttl</em> property based on the <em>hono-ttl</em> property set as a query parameter in the event requests by the devices.
-Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the <a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p>
-
+Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the [Tenant API]
+(/hono/docs/dev/api/tenant/#resource-limits-configuration-format).</p>
<h2 id="tenant-specific-configuration">Tenant specific Configuration</h2>
-
<p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-coap</code>.
The following properties are (currently) supported:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Default Value</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Default Value</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>enabled</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left"><code>true</code></td>
-<td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
+<td style="text-align:left"><em>enabled</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
</tr>
-
<tr>
-<td align="left"><em>max-ttd</em></td>
-<td align="left"><em>integer</em></td>
-<td align="left"><code>60</code></td>
-<td align="left">Defines a tenant specific upper limit for the <em>time until disconnect</em> property that devices may include in requests for uploading telemetry data or events. Please refer to the <a href="/hono/docs/dev/concepts/command-and-control/">Command & Control concept page</a> for a discussion of this parameter’s purpose and usage.<br>This property can be set for the <code>hono-coap</code> adapter type as an <em>extension</em> property in the adapter section of the tenant configuration.<br>If it is not set, then the default value of <code>60</code> seconds is used.</td>
+<td style="text-align:left"><em>max-ttd</em></td>
+<td style="text-align:left"><em>integer</em></td>
+<td style="text-align:left"><code>60</code></td>
+<td style="text-align:left">Defines a tenant specific upper limit for the <em>time until disconnect</em> property that devices may include in requests for uploading telemetry data or events. Please refer to the <a href="/hono/docs/dev/concepts/command-and-control/">Command & Control concept page</a> for a discussion of this parameter’s purpose and usage.<br>This property can be set for the <code>hono-coap</code> adapter type as an <em>extension</em> property in the adapter section of the tenant configuration.<br>If it is not set, then the default value of <code>60</code> seconds is used.</td>
</tr>
-
<tr>
-<td align="left"><em>timeoutToAck</em></td>
-<td align="left"><em>integer</em></td>
-<td align="left">-</td>
-<td align="left">This property has the same semantics as the <a href="/hono/docs/dev/admin-guide/coap-adapter-config/">corresponding property at the adapter level</a>. However, any (non-null) value configured for a tenant takes precedence over the adapter level value for all devices of the particular tenant.</td>
+<td style="text-align:left"><em>timeoutToAck</em></td>
+<td style="text-align:left"><em>integer</em></td>
+<td style="text-align:left">-</td>
+<td style="text-align:left">This property has the same semantics as the <a href="/hono/docs/dev/admin-guide/coap-adapter-config/">corresponding property at the adapter level</a>. However, any (non-null) value configured for a tenant takes precedence over the adapter level value for all devices of the particular tenant.</td>
</tr>
</tbody>
</table>
@@ -4074,19 +3901,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844324"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844324"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844324"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844324"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844324"></script>
+ <script src="/hono/docs/js/learn.js?1617844324"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844324"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844324" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844324"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/device-registry/index.html b/docs/dev/user-guide/device-registry/index.html
index 826f68a..6cfa1a0 100644
--- a/docs/dev/user-guide/device-registry/index.html
+++ b/docs/dev/user-guide/device-registry/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>Device Registries :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757974" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757974" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757974" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757974" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757974"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757974"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757974"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757974"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/device-registry/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/device-registry/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/device-registry/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/device-registry/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/device-registry/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/device-registry/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/device-registry/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/device-registry/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/device-registry/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/device-registry/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/device-registry/" selected>dev</option>
@@ -1963,7 +2009,7 @@
<div class="progress">
<div class="wrapper">
-
+<nav id="TableOfContents"></nav>
</div>
</div>
@@ -1986,10 +2032,8 @@
-<p>Eclipse Hono™ provides these device registry implementations:</p>
-
+<p>Eclipse Hono™ provides these device registry implementations:</p>
<p><a href="/hono/docs/dev/user-guide/file-based-device-registry/">File Based Device Registry</a></p>
-
<p><a href="/hono/docs/dev/user-guide/mongodb-based-device-registry/">MongoDB Based Device Registry</a>.</p>
@@ -3111,19 +3155,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/file-based-device-registry/index.html b/docs/dev/user-guide/file-based-device-registry/index.html
index 8b4315e..f86f8ae 100644
--- a/docs/dev/user-guide/file-based-device-registry/index.html
+++ b/docs/dev/user-guide/file-based-device-registry/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>File Based Device Registry :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/file-based-device-registry/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/file-based-device-registry/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/file-based-device-registry/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/file-based-device-registry/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/file-based-device-registry/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/file-based-device-registry/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/file-based-device-registry/">1.3</option>
@@ -1768,6 +1806,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/file-based-device-registry/" selected>dev</option>
@@ -1886,14 +1926,11 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#managing-tenants">Managing Tenants</a></li>
-<li><a href="#managing-devices">Managing Devices</a></li>
-<li><a href="#managing-credentials">Managing Credentials</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#managing-tenants">Managing Tenants</a></li>
+ <li><a href="#managing-devices">Managing Devices</a></li>
+ <li><a href="#managing-credentials">Managing Credentials</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -1918,34 +1955,23 @@
<p>The Device Registry component provides exemplary implementations of Hono’s <a href="/hono/docs/dev/api/tenant/">Tenant API</a>, <a href="/hono/docs/dev/api/device-registration/">Device Registration API</a> and <a href="/hono/docs/dev/api/credentials/">Credentials API</a>.</p>
-
<p>As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information and persists data in the local filesystem.</p>
-
<p>In addition, the Device Registry also exposes HTTP resources for managing the contents of the registry according to the <a href="/hono/docs/dev/api/management/">Device Registry HTTP API</a>.</p>
-
<div class="alert alert-warning">
<h4 class="alert-heading"><i class="fas fa-exclamation-triangle"></i> Warning</h4>
<div><p>The Device Registry is not intended to be used in production environments. In particular, access to the HTTP resources described below is not restricted to authorized clients only.</p>
-
<p>The resources have been designed to provide convenient access to the registry’s content using command line tools like <em>curl</em> or <em>HTTPie</em>.</p>
</div>
</div>
-
<h2 id="managing-tenants">Managing Tenants</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#tenants">Device Registry Management API</a> for information about managing tenants.</p>
-
<div class="alert alert-warning">
<h4 class="alert-heading"><i class="fas fa-exclamation-triangle"></i> Warning</h4>
<div>The file based device registry doesn’t support <a href="/hono/docs/dev/api/management/#tenants/searchTenants">search tenants</a> operation defined by the Device Registry Management API.</div>
</div>
-
<h2 id="managing-devices">Managing Devices</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#devices">Device Registry Management API</a> for information about managing devices.</p>
-
<h2 id="managing-credentials">Managing Credentials</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#credentials">Device Registry Management API</a> for information about managing credentials.</p>
<footer class="footline">
@@ -3070,19 +3096,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/http-adapter/index.html b/docs/dev/user-guide/http-adapter/index.html
index 5c525ee..6e22256 100644
--- a/docs/dev/user-guide/http-adapter/index.html
+++ b/docs/dev/user-guide/http-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>HTTP Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/http-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/http-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/http-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/http-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/http-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/http-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/http-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/http-adapter/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/http-adapter/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/http-adapter/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/http-adapter/" selected>dev</option>
@@ -1964,40 +2010,36 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#device-authentication">Device Authentication</a>
-<ul>
-<li><a href="#client-certificate">Client Certificate</a></li>
-<li><a href="#http-basic-auth">HTTP Basic Auth</a></li>
-</ul></li>
-<li><a href="#message-limits">Message Limits</a></li>
-<li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
-<li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
-<li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
-<li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
-<li><a href="#command-control">Command & Control</a>
-<ul>
-<li><a href="#specifying-the-time-a-device-will-wait-for-a-response">Specifying the Time a Device will wait for a Response</a>
-<ul>
-<li><a href="#using-an-http-header">Using an HTTP Header</a></li>
-<li><a href="#using-a-query-parameter">Using a Query Parameter</a></li>
-</ul></li>
-<li><a href="#commands-handled-by-gateways">Commands handled by gateways</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
-</ul></li>
-<li><a href="#downstream-meta-data">Downstream Meta Data</a>
-<ul>
-<li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
-</ul></li>
-<li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#device-authentication">Device Authentication</a>
+ <ul>
+ <li><a href="#client-certificate">Client Certificate</a></li>
+ <li><a href="#http-basic-auth">HTTP Basic Auth</a></li>
+ </ul>
+ </li>
+ <li><a href="#message-limits">Message Limits</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
+ <li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
+ <li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
+ <li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
+ <li><a href="#command--control">Command & Control</a>
+ <ul>
+ <li><a href="#specifying-the-time-a-device-will-wait-for-a-response">Specifying the Time a Device will wait for a Response</a></li>
+ <li><a href="#commands-handled-by-gateways">Commands handled by gateways</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
+ </ul>
+ </li>
+ <li><a href="#downstream-meta-data">Downstream Meta Data</a>
+ <ul>
+ <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
+ </ul>
+ </li>
+ <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -2021,74 +2063,57 @@
-<p>The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.</p>
-
+<p>The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.</p>
<h2 id="device-authentication">Device Authentication</h2>
-
<p>The HTTP adapter by default requires clients (devices or gateway components) to authenticate during connection establishment. The adapter supports both the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a> as well as client certificate based authentication as part of a TLS handshake for that purpose.</p>
-
<p>The adapter tries to authenticate the device using these mechanisms in the following order</p>
-
<h3 id="client-certificate">Client Certificate</h3>
-
<p>When a device uses a client certificate for authentication during the TLS handshake, the adapter tries to determine the tenant that the device belongs to, based on the <em>issuer DN</em> contained in the certificate. In order for the lookup to succeed, the tenant’s trust anchor needs to be configured by means of <a href="/hono/docs/dev/api/tenant/#tenant-information-format">registering the trusted certificate authority</a>. The device’s client certificate will then be validated using the registered trust anchor, thus implicitly establishing the tenant that the device belongs to. In a second step, the adapter then uses the Credentials API’s <em>get</em> operation with the client certificate’s <em>subject DN</em> as the <em>auth-id</em> and <code>x509-cert</code> as the <em>type</em> of secret as query parameters.</p>
-
-<p><strong>NB</strong> The HTTP adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/#http-adapter">configured for TLS</a> in order to support this mechanism.</p>
-
+<p><strong>NB</strong> The HTTP adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/">configured for TLS</a> in order to support this mechanism.</p>
<h3 id="http-basic-auth">HTTP Basic Auth</h3>
-
-<p>The <em>username</em> provided in the header must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>. The adapter verifies the credentials provided by the client against the credentials that the <a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">configured Credentials service</a> has on record for the client. The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record with the <em>tenant</em> and <em>auth-id</em> provided by the device in the <em>username</em> and <code>hashed-password</code> as the <em>type</em> of secret as query parameters.</p>
-
+<p>The <em>username</em> provided in the header must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>. The adapter verifies the credentials provided by the client against the credentials that the <a href="/hono/docs/dev/admin-guide/common-config/">configured Credentials service</a> has on record for the client. The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record with the <em>tenant</em> and <em>auth-id</em> provided by the device in the <em>username</em> and <code>hashed-password</code> as the <em>type</em> of secret as query parameters.</p>
<p>The examples below refer to devices <code>4711</code> and <code>gw-1</code> of tenant <code>DEFAULT_TENANT</code> using <em>auth-ids</em> <code>sensor1</code> and <code>gw1</code> and corresponding passwords. The example deployment as described in the <a href="/hono/docs/dev/deployment/">Deployment Guides</a> comes pre-configured with the corresponding entities in its device registry component.
Please refer to the <a href="/hono/docs/dev/api/credentials/#standard-credential-types">Credentials API</a> for details regarding the different types of secrets.</p>
-
<p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication. See <a href="/hono/docs/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p>
-
<h2 id="message-limits">Message Limits</h2>
-
<p>The adapter rejects</p>
-
<ul>
<li>a client’s request to upload data with status code <code>429 Too Many Requests</code> and</li>
<li>any AMQP 1.0 message containing a command sent by a north bound application</li>
</ul>
-
<p>if the <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p>
-
<h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2>
-
<ul>
<li>URI: <code>/telemetry</code></li>
<li>Method: <code>POST</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The device’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>qos-level</code>: The QoS level for publishing telemetry messages. The adapter supports <em>at most once</em> (<code>0</code>) and <em>at least once</em> (<code>1</code>) QoS levels. The default value of <code>0</code> is assumed if this header is omitted.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-target-device</code>: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The telemetry data has been accepted for processing. Note that if the <code>qos-level</code> request header is omitted (<em>at most once</em> semantics),
@@ -2096,112 +2121,83 @@
(<em>at least once</em> semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with
this status code.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty.</li>
-<li>The QoS header value is invalid.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty.
+* The QoS header value is invalid.</li>
<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using <em>at least once</em> QoS:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'qos-level: 1'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://localhost:8080/telemetry
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'hono-ttd: 10'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://localhost:8080/telemetry
-<p>Publish some JSON data for device <code>4711</code> using <em>at least once</em> QoS:</p>
-
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{"temp": 5}' http://localhost:8080/telemetry
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{"temp": 5}' http://localhost:8080/telemetry
-
-HTTP/1.1 200 OK
+HTTP/1.1 <span style="color:#ae81ff">200</span> OK
hono-command: set
hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92
-content-length: 23
+content-length: <span style="color:#ae81ff">23</span>
-{
- "brightness": 87
-}
-</code></pre>
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in base directory of Hono repository:</span>
+curl -i --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cacert demo-certs/certs/trusted-certs.pem -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> https://localhost:8443/telemetry
-<p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
-
-<pre><code class="language-sh"># in base directory of Hono repository:
-curl -i --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cacert demo-certs/certs/trusted-certs.pem -H 'content-type: application/json' --data-binary '{"temp": 5}' https://localhost:8443/telemetry
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that the HTTP adapter is <a href="/hono/docs/dev/admin-guide/secure_communication/#http-adapter">configured for TLS</a> and the secure port is used.</p>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that the HTTP adapter is <a href="/hono/docs/dev/admin-guide/secure_communication/">configured for TLS</a> and the secure port is used.</p>
<h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2>
-
<ul>
<li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>qos-level</code>: The QoS level for publishing telemetry messages. The adapter supports <em>at most once</em> (<code>0</code>) and <em>at least once</em> (<code>1</code>) QoS levels. The default value of <code>0</code> is assumed if this header is omitted.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The telemetry data has been accepted for processing. Note that if the <code>qos-level</code> request header is omitted (<em>at most once</em> semantics),
@@ -2209,103 +2205,78 @@
(<em>at least once</em> semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with
this status code.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty.</li>
-<li>The QoS header value is invalid.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty.
+* The QoS header value is invalid.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the <code>HONO_HTTP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4711
-<pre><code class="language-sh">curl -i -X PUT -H 'content-type: application/json' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4711
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using <em>at least once</em> QoS:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'qos-level: 1'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4711
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'hono-ttd: 10'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://localhost:8080/telemetry/DEFAULT_TENANT/4711
-<p>Publish some JSON data for device <code>4711</code> using <em>at least once</em> QoS:</p>
-
-<pre><code class="language-sh">curl -i -X PUT -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4711
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code>, indicating that the device will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">curl -i -X PUT -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{"temp": 5}' http://localhost:8080/telemetry/DEFAULT_TENANT/4711
-
-HTTP/1.1 200 OK
+HTTP/1.1 <span style="color:#ae81ff">200</span> OK
hono-command: set
hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92
-content-length: 23
+content-length: <span style="color:#ae81ff">23</span>
-{
- "brightness": 87
-}
-</code></pre>
-
-<h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
-
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
<ul>
<li>URI: <code>/telemetry/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The gateway’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>qos-level</code>: The QoS level for publishing telemetry messages. The adapter supports <em>at most once</em> (<code>0</code>) and <em>at least once</em> (<code>1</code>) QoS levels. The default value of <code>0</code> is assumed if this header is omitted.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-target-device</code>: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The telemetry data has been accepted for processing. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The telemetry data has been accepted for processing. Note that if the <code>qos-level</code> request header is omitted (<em>at most once</em> semantics),
@@ -2313,583 +2284,441 @@
(<em>at least once</em> semantics), then the adapter waits for the message to be delivered and accepted by a downstream consumer before responding with
this status code.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty.</li>
-<li>The QoS header value is invalid.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty.
+* The QoS header value is invalid.</li>
<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li>
-<li>The device belongs to another tenant than the gateway.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The tenant that the gateway belongs to is not allowed to use this protocol adapter.
+* The device belongs to another tenant than the gateway.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).</li>
-<li>If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
-
-<ul>
-<li>The consumer has indicated that it didn’t process the telemetry data.</li>
-<li>The consumer failed to indicate in time whether it has processed the telemetry data.</li>
-</ul></li>
-</ul></li>
-</ul></li>
+* There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits).
+* If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be:
+* The consumer has indicated that it didn’t process the telemetry data.
+* The consumer failed to indicate in time whether it has processed the telemetry data.</li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4712
-<pre><code class="language-sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4712
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4712</code> using <em>at least once</em> QoS:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'qos-level: 1'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4712
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'hono-ttd: 10'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://localhost:8080/telemetry/DEFAULT_TENANT/4712
-<p>Publish some JSON data for device <code>4712</code> using <em>at least once</em> QoS:</p>
-
-<pre><code class="language-sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' -H 'qos-level: 1' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry/DEFAULT_TENANT/4712
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p>Publish some JSON data for device <code>4712</code>, indicating that the gateway will wait for 10 seconds to receive the response:</p>
-
-<pre><code class="language-sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' -H 'hono-ttd: 10' --data-binary '{"temp": 5}' http://localhost:8080/telemetry/DEFAULT_TENANT/4712
-
-HTTP/1.1 200 OK
+HTTP/1.1 <span style="color:#ae81ff">200</span> OK
hono-command: set
hono-cmd-req-id: 1010a7249aa5-f742-4376-8458-bbfc88c72d92
-content-length: 23
+content-length: <span style="color:#ae81ff">23</span>
-{
- "brightness": 87
-}
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
+<span style="color:#f92672">{</span>
+ <span style="color:#e6db74">"brightness"</span>: <span style="color:#ae81ff">87</span>
+<span style="color:#f92672">}</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
<h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2>
-
<ul>
<li>URI: <code>/event</code></li>
<li>Method: <code>POST</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The device’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
-<li>(optional) <code>hono-ttl</code>: The <em>time-to-live</em> in number of seconds for event messages.<br /></li>
-</ul></li>
+<li>(optional) <code>hono-ttl</code>: The <em>time-to-live</em> in number of seconds for event messages.</li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-target-device</code>: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device and if the response goes to a gateway that acts on behalf of the target device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The event has been accepted for processing. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The event has been accepted for processing.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish events. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).</p>
-
<p><strong>Example</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"alarm": true}'</span> http://127.0.0.1:8080/event
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{"alarm": true}' http://127.0.0.1:8080/event
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
<ul>
<li>URI: <code>/event/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>hono-ttl</code>: The <em>time-to-live</em> in number of seconds for event messages.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The event has been accepted and put to a persistent store for delivery to consumers. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The event has been accepted and put to a persistent store for delivery to consumers.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the <code>HONO_HTTP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"alarm": true}'</span> http://127.0.0.1:8080/event/DEFAULT_TENANT/4711
-<pre><code class="language-sh">curl -i -X PUT -H 'content-type: application/json' --data-binary '{"alarm": true}' http://127.0.0.1:8080/event/DEFAULT_TENANT/4711
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
<ul>
<li>URI: <code>/event/${tenantId}/${deviceId}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The gateway’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(required) <code>content-type</code>: The type of payload contained in the request body.</li>
<li>(optional) <code>hono-ttd</code>: The number of seconds the device will wait for the response.</li>
<li>(optional) <code>hono-ttl</code>: The <em>time-to-live</em> in number of seconds for event messages.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(required) Arbitrary payload encoded according to the given content type.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of payload contained in the response body. This header will only be present if the response contains a command to be executed by the device which requires input data.</li>
<li>(optional) <code>hono-command</code>: The name of the command to execute. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-req-id</code>: An identifier that the device must include in its response to a command. This header will only be present if the response contains a command to be executed by the device.</li>
<li>(optional) <code>hono-cmd-target-device</code>: The id of the device that shall execute the command. This header will only be present if the response contains a command to be executed by the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Response Body:
-
<ul>
<li>(optional) Arbitrary data serving as input to a command to be executed by the device, if status code is 200.</li>
<li>(optional) Error details, if status code is >= 400.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>200 (OK): The event has been accepted and put to a persistent store for delivery to consumers. The response contains a command for the device to execute.</li>
<li>202 (Accepted): The event has been accepted and put to a persistent store for delivery to consumers.</li>
<li>400 (Bad Request): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>The content type header is missing.</li>
-<li>The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
-</ul></li>
+* The content type header is missing.
+* The request body is empty but the event is not of type <a href="/hono/docs/dev/api/event/#empty-notification">empty-notification</a>.</li>
<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The tenant that the gateway belongs to is not allowed to use this protocol adapter.</li>
-<li>The device belongs to another tenant than the gateway.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The tenant that the gateway belongs to is not allowed to use this protocol adapter.
+* The device belongs to another tenant than the gateway.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed because there is no consumer of events for the given tenant connected to Hono, or the consumer didn’t process the event.</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/event/DEFAULT_TENANT/4712
-<pre><code class="language-sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{"temp": 5}' http://127.0.0.1:8080/event/DEFAULT_TENANT/4712
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
-<h2 id="command-control">Command & Control</h2>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
+<h2 id="command--control">Command & Control</h2>
<p>The HTTP adapter enables devices to receive commands that have been sent by business applications. Commands are delivered to the device by means of an HTTP response message. That means a device first has to send a request, indicating how long it will wait for the response. That request can either be a telemetry or event message, with a <code>hono-ttd</code> header or query parameter (<code>ttd</code> for <code>time till disconnect</code>) specifying the number of seconds the device will wait for the response. The business application can react on that message by sending a command message, targeted at the device. The HTTP adapter will then send the command message as part of the HTTP response message with status <code>200</code> (OK) to the device. If the HTTP adapter receives no command message in the given time period, a <code>202</code> (Accepted) response will be sent to the device (provided the request was valid).</p>
-
<h3 id="specifying-the-time-a-device-will-wait-for-a-response">Specifying the Time a Device will wait for a Response</h3>
-
<p>The adapter lets devices indicate the number of seconds they will wait for a response by setting a header or a query parameter.</p>
-
<h4 id="using-an-http-header">Using an HTTP Header</h4>
-
<p>The (optional) <code>hono-ttd</code> header can be set in requests for publishing telemetry data or events.</p>
-
<p>Example:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> -H <span style="color:#e6db74">'hono-ttd: 60'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' -H 'hono-ttd: 60' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h4 id="using-a-query-parameter">Using a Query Parameter</h4>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h4 id="using-a-query-parameter">Using a Query Parameter</h4>
<p>Alternatively the <code>hono-ttd</code> query parameter can be used:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"temp": 5}'</span> http://127.0.0.1:8080/telemetry?hono-ttd<span style="color:#f92672">=</span><span style="color:#ae81ff">60</span>
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{"temp": 5}' http://127.0.0.1:8080/telemetry?hono-ttd=60
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h3 id="commands-handled-by-gateways">Commands handled by gateways</h3>
-
-<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/#configuring-gateway-devices">Configuring Gateway Devices</a> for details.</p>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h3 id="commands-handled-by-gateways">Commands handled by gateways</h3>
+<p>Authenticated gateways will receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/">Configuring Gateway Devices</a> for details.</p>
<p>A gateway can send a request with the <code>hono-ttd</code> header or query parameter on the <code>/event</code> or <code>/telemetry</code> URI, indicating its readiness to receive a command for <em>any</em> device it acts on behalf of. Note that in this case, the business application will be notified with the gateway id in the <code>device_id</code> property of the downstream message.</p>
-
<p>An authenticated gateway can also indicate its readiness to receive a command targeted at a <em>specific</em> device. For that, the <code>/event/${tenantId}/${deviceId}</code> or <code>/telemetry/${tenantId}/${deviceId}</code> URI is to be used, containing the id of the device to receive a command for. The business application will receive a notification with that device id.</p>
-
<p>If there are multiple concurrent requests with a <code>hono-ttd</code> header or query parameter, sent by the command target device and/or one or more of its potential gateways, the HTTP adapter will choose the device or gateway to send the command to as follows:</p>
-
<ul>
<li>A request done by the command target device or by a gateway specifically done for that device, has precedence. If there are multiple, concurrent such requests, the last one will get the command message (if received) in its response. Note that the other requests won’t be answered with a command message in their response event if the business application sent multiple command messages. That means commands for a single device can only be requested sequentially, not in parallel.</li>
<li>If the above doesn’t apply, a single <code>hono-ttd</code> request on the <code>/event</code> or <code>/telemetry</code> URI, sent by a gateway that the command target device is configured for, will get the command message in its response.</li>
<li>If there are multiple, concurrent such requests by different gateways, all configured for the command target device, the request by the gateway will be chosen, through which the target device has last sent a telemetry or event message. If the target device hasn’t sent a message yet and it is thereby unknown via which gateway the device communicates, then one of the requests will be chosen randomly to set the command in its response.</li>
</ul>
-
<h3 id="sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</h3>
-
<ul>
<li>URI: <code>/command/res/${commandRequestId}</code> or <code>/command/res/${commandRequestId}?hono-cmd-status=${status}</code></li>
<li>Method: <code>POST</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The device’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the device to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body. This header may be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body.</li>
<li>(optional) <code>hono-cmd-status</code>: The status of the command execution. If not set, the adapter expects that the URI contains it
as request parameter at the end.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>202 (Accepted): The response has been successfully delivered to the application that has sent the command.</li>
<li>400 (Bad Request): The request cannot be processed because the command status is missing.</li>
-<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.<br /></li>
+<li>401 (Unauthorized): The request cannot be processed because the request does not contain valid credentials.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this include:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to respond to commands. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default).</p>
-
<p><strong>Example</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"brightness-changed": true}'</span> http://127.0.0.1:8080/command/res/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span>
-<pre><code class="language-sh">curl -i -u sensor1@DEFAULT_TENANT:hono-secret -H 'content-type: application/json' --data-binary '{"brightness-changed": true}' http://127.0.0.1:8080/command/res/req-id-uuid?hono-cmd-status=200
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
<ul>
<li>URI: <code>/command/res/${tenantId}/${deviceId}/${commandRequestId}</code> or <code>/command/res/${tenantId}/${deviceId}/${commandRequestId}?hono-cmd-status=${status}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body (the outcome of processing the command).</li>
<li>(optional) <code>hono-cmd-status</code>: The status of the command execution. If not set, the adapter expects that the URI contains it
as request parameter at the end.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>202 (Accepted): The response has been successfully delivered to the application that has sent the command.</li>
<li>400 (Bad Request): The request cannot be processed because the command status is missing.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this might be:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This resource MUST be used by devices that have not authenticated to the protocol adapter. Note that this requires the <code>HONO_HTTP_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for the unauthenticated device <code>4711</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"brightness-changed": true}'</span> http://127.0.0.1:8080/command/res/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span>
-<pre><code class="language-sh">curl -i -X PUT -H 'content-type: application/json' --data-binary '{"brightness-changed": true}' http://127.0.0.1:8080/command/res/DEFAULT_TENANT/4711/req-id-uuid?hono-cmd-status=200
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
<ul>
<li>URI: <code>/command/res/${tenantId}/${deviceId}/${commandRequestId}</code> or <code>/command/res/${tenantId}/${deviceId}/${commandRequestId}?hono-cmd-status=${status}</code></li>
<li>Method: <code>PUT</code></li>
<li>Request Headers:
-
<ul>
<li>(optional) <code>authorization</code>: The gateway’s <em>auth-id</em> and plain text password encoded according to the <a href="https://tools.ietf.org/html/rfc7617">Basic HTTP authentication scheme</a>. If not set, the adapter expects the gateway to present a client certificate as part of the TLS handshake during connection establishment.</li>
<li>(optional) <code>content-type</code>: A media type describing the semantics and format of the payload contained in the request body (the outcome of processing the command).</li>
<li>(optional) <code>hono-cmd-status</code>: The status of the command execution. If not set, the adapter expects that the URI contains it
as request parameter at the end.</li>
-</ul></li>
+</ul>
+</li>
<li>Request Body:
-
<ul>
<li>(optional) Arbitrary data representing the result of processing the command on the device.</li>
-</ul></li>
+</ul>
+</li>
<li>Status Codes:
-
<ul>
<li>202 (Accepted): The response has been successfully delivered to the application that has sent the command.</li>
<li>400 (Bad Request): The request cannot be processed because the command status is missing.</li>
<li>403 (Forbidden): The request cannot be processed because the device’s registration status cannot be asserted. Possible reasons for this might be:
-
-<ul>
-<li>The given tenant is not allowed to use this protocol adapter.</li>
-<li>The given device does not belong to the given tenant.</li>
-<li>The gateway is not authorized to act <em>on behalf of</em> the device.</li>
-<li>The gateway associated with the device is not registered or disabled.</li>
-</ul></li>
+* The given tenant is not allowed to use this protocol adapter.
+* The given device does not belong to the given tenant.
+* The gateway is not authorized to act <em>on behalf of</em> the device.
+* The gateway associated with the device is not registered or disabled.</li>
<li>404 (Not Found): The request cannot be processed because the device is disabled or does not exist.</li>
<li>413 (Request Entity Too Large): The request cannot be processed because the request body exceeds the maximum supported size.</li>
<li>429 (Too Many Requests): The request cannot be processed because the tenant’s message limit for the current period is exceeded.</li>
<li>503 (Service Unavailable): The request cannot be processed. Possible reasons for this include:
-
-<ul>
-<li>There is no application listening for a reply to the given <em>commandRequestId</em>.</li>
-<li>The application has already given up on waiting for a response.</li>
-</ul></li>
-</ul></li>
+* There is no application listening for a reply to the given <em>commandRequestId</em>.
+* The application has already given up on waiting for a response.</li>
</ul>
-
+</li>
+</ul>
<p>This resource can be used by <em>gateway</em> components to send the response to a command <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to send responses to a command on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Send a response to a previously received command with the command-request-id <code>req-id-uuid</code> for device <code>4712</code>:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H <span style="color:#e6db74">'content-type: application/json'</span> --data-binary <span style="color:#e6db74">'{"brightness-changed": true}'</span> http://127.0.0.1:8080/command/res/DEFAULT_TENANT/4712/req-id-uuid?hono-cmd-status<span style="color:#f92672">=</span><span style="color:#ae81ff">200</span>
-<pre><code class="language-sh">curl -i -X PUT -u gw@DEFAULT_TENANT:gw-secret -H 'content-type: application/json' --data-binary '{"brightness-changed": true}' http://127.0.0.1:8080/command/res/DEFAULT_TENANT/4712/req-id-uuid?hono-cmd-status=200
-
-HTTP/1.1 202 Accepted
-content-length: 0
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
-
+HTTP/1.1 <span style="color:#ae81ff">202</span> Accepted
+content-length: <span style="color:#ae81ff">0</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code> which is authorized to publish data <em>on behalf of</em> device <code>4712</code>.</p>
<h2 id="downstream-meta-data">Downstream Meta Data</h2>
-
<p>The adapter includes the following meta data in the application properties of messages being sent downstream:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier of the device that the message originates from.</td>
+<td style="text-align:left"><em>device_id</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">The identifier of the device that the message originates from.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_adapter</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The HTTP adapter’s type name is <code>hono-http</code>.</td>
+<td style="text-align:left"><em>orig_adapter</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The HTTP adapter’s type name is <code>hono-http</code>.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_address</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the (relative) URI that the device has originally posted the data to.</td>
+<td style="text-align:left"><em>orig_address</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the (relative) URI that the device has originally posted the data to.</td>
</tr>
-
<tr>
-<td align="left"><em>ttd</em></td>
-<td align="left"><em>integer</em></td>
-<td align="left">Contains the effective number of seconds that the device will wait for a response. This property is only set if the HTTP request contains the <code>hono-ttd</code> header or request parameter.</td>
+<td style="text-align:left"><em>ttd</em></td>
+<td style="text-align:left"><em>integer</em></td>
+<td style="text-align:left">Contains the effective number of seconds that the device will wait for a response. This property is only set if the HTTP request contains the <code>hono-ttd</code> header or request parameter.</td>
</tr>
</tbody>
</table>
-
<p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a> or the <a href="/hono/docs/dev/api/device-registration/#assert-device-registration">device level</a>. The values of the default properties are determined as follows:</p>
-
<ol>
<li>If the message already contains a non-empty property of the same name, the value if unchanged.</li>
<li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li>
<li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li>
</ol>
-
<p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p>
-
<h3 id="event-message-time-to-live">Event Message Time-to-live</h3>
-
<p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers.
In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed
from the persistent store if no consumer has attached to receive the event before the message expires.</p>
-
<p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the protocol adapter supports setting a
downstream event message’s <em>ttl</em> property based on the <em>hono-ttl</em> property set as a header or a query parameter in the event requests by the devices.
-Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the <a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p>
-
+Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the [Tenant API]
+(/hono/docs/dev/api/tenant/#resource-limits-configuration-format).</p>
<h2 id="tenant-specific-configuration">Tenant specific Configuration</h2>
-
<p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-http</code>.
The following properties are (currently) supported:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Default Value</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Default Value</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>enabled</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left"><code>true</code></td>
-<td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
+<td style="text-align:left"><em>enabled</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
</tr>
-
<tr>
-<td align="left"><em>max-ttd</em></td>
-<td align="left"><em>integer</em></td>
-<td align="left"><code>60</code></td>
-<td align="left">Defines a tenant specific upper limit for the <em>time until disconnect</em> property that devices may include in requests for uploading telemetry data or events. Please refer to the <a href="/hono/docs/dev/concepts/command-and-control/">Command & Control concept page</a> for a discussion of this parameter’s purpose and usage.<br>This property can be set for the <code>hono-http</code> adapter type as an <em>extension</em> property in the adapter section of the tenant configuration.<br>If it is not set, then the default value of <code>60</code> seconds is used.</td>
+<td style="text-align:left"><em>max-ttd</em></td>
+<td style="text-align:left"><em>integer</em></td>
+<td style="text-align:left"><code>60</code></td>
+<td style="text-align:left">Defines a tenant specific upper limit for the <em>time until disconnect</em> property that devices may include in requests for uploading telemetry data or events. Please refer to the <a href="/hono/docs/dev/concepts/command-and-control/">Command & Control concept page</a> for a discussion of this parameter’s purpose and usage.<br>This property can be set for the <code>hono-http</code> adapter type as an <em>extension</em> property in the adapter section of the tenant configuration.<br>If it is not set, then the default value of <code>60</code> seconds is used.</td>
</tr>
</tbody>
</table>
@@ -4016,19 +3845,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844324"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844324"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844324"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844324"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844324"></script>
+ <script src="/hono/docs/js/learn.js?1617844324"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844324"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844324" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844324"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/index.html b/docs/dev/user-guide/index.html
index a1e4b00..19d6290 100644
--- a/docs/dev/user-guide/index.html
+++ b/docs/dev/user-guide/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>User Guide :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/" selected>dev</option>
@@ -1969,11 +2015,8 @@
-
-
-<h1 id="user-guide">User Guide</h1>
-
-<p>Learn how Eclipse Hono™ enables you to quickly send data from devices to business applications and vice versa.</p>
+ <h1 id="user-guide">User Guide</h1>
+<p>Learn how Eclipse Hono™ enables you to quickly send data from devices to business applications and vice versa.</p>
@@ -3099,19 +3142,19 @@
<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?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757973"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757973"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757973"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757973"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757973"></script>
- <script src="/hono/docs/js/learn.js?1617757973"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757973"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757973" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757973"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/index.xml b/docs/dev/user-guide/index.xml
index 84bf77d..f40258b 100644
--- a/docs/dev/user-guide/index.xml
+++ b/docs/dev/user-guide/index.xml
@@ -1,22 +1,19 @@
-<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
+<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>User Guide on Eclipse Hono&trade; Vers.: dev</title>
<link>https://www.eclipse.org/hono/docs/dev/user-guide/</link>
<description>Recent content in User Guide on Eclipse Hono&trade; Vers.: dev</description>
<generator>Hugo -- gohugo.io</generator>
- <language>en-us</language>
-
- <atom:link href="https://www.eclipse.org/hono/docs/dev/user-guide/index.xml" rel="self" type="application/rss+xml" />
-
-
+ <language>en-us</language><atom:link href="https://www.eclipse.org/hono/docs/dev/user-guide/index.xml" rel="self" type="application/rss+xml" />
<item>
<title>MongoDB Based Device Registry</title>
<link>https://www.eclipse.org/hono/docs/dev/user-guide/mongodb-based-device-registry/</link>
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/mongodb-based-device-registry/</guid>
- <description>The MongoDB based Device Registry component provides implementations of Hono&rsquo;s Tenant API, Device Registration API and Credentials API. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device&rsquo;s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.</description>
+ <description>The MongoDB based Device Registry component provides implementations of Hono&rsquo;s Tenant API, Device Registration API and Credentials API. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device&rsquo;s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.
+In addition to the above APIs, this Device Registry also exposes HTTP endpoints for managing the contents of the Device Registry according to the Device Registry Management API.</description>
</item>
<item>
@@ -25,7 +22,8 @@
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/jdbc-based-device-registry/</guid>
- <description>The JDBC based Device Registry component provides implementations of Hono&rsquo;s Tenant API, Device Registration API and Credentials API. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device&rsquo;s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.</description>
+ <description>The JDBC based Device Registry component provides implementations of Hono&rsquo;s Tenant API, Device Registration API and Credentials API. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device&rsquo;s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.
+In addition to the above APIs, this Device Registry also exposes HTTP endpoints for managing the contents of the Device Registry according to the Device Registry Management API.</description>
</item>
<item>
@@ -43,7 +41,7 @@
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/http-adapter/</guid>
- <description><p>The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono&trade;&rsquo;s south bound Telemetry, Event and Command &amp; Control APIs.</p></description>
+ <description><p>The HTTP protocol adapter exposes HTTP based endpoints for Eclipse Hono™&rsquo;s south bound Telemetry, Event and Command &amp; Control APIs.</p></description>
</item>
<item>
@@ -62,7 +60,7 @@
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/amqp-adapter/</guid>
<description><p>The AMQP protocol adapter allows clients (devices or gateway components) supporting the AMQP 1.0 protocol to publish
-messages to Eclipse Hono&trade;&rsquo;s Telemetry, Event and Command &amp; Control endpoints.</p></description>
+messages to Eclipse Hono™&rsquo;s Telemetry, Event and Command &amp; Control endpoints.</p></description>
</item>
<item>
@@ -71,7 +69,7 @@
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/coap-adapter/</guid>
- <description><p>The CoAP protocol adapter exposes <a href="https://tools.ietf.org/html/rfc7252">CoAP</a> based endpoints for Eclipse Hono&trade;&rsquo;s south bound Telemetry, Event and Command &amp; Control APIs.</p></description>
+ <description><p>The CoAP protocol adapter exposes <a href="https://tools.ietf.org/html/rfc7252">CoAP</a> based endpoints for Eclipse Hono™&rsquo;s south bound Telemetry, Event and Command &amp; Control APIs.</p></description>
</item>
<item>
@@ -80,7 +78,7 @@
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/kura-adapter/</guid>
- <description><p>The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura&trade; based gateways to publish <em>control</em> and <em>data</em> messages to Eclipse Hono&trade;&rsquo;s Telemetry and Event endpoints.</p></description>
+ <description><p>The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ based gateways to publish <em>control</em> and <em>data</em> messages to Eclipse Hono™&rsquo;s Telemetry and Event endpoints.</p></description>
</item>
<item>
@@ -99,10 +97,10 @@
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
<guid>https://www.eclipse.org/hono/docs/dev/user-guide/device-registry/</guid>
- <description>Eclipse Hono&trade; provides these device registry implementations:
+ <description>Eclipse Hono™ provides these device registry implementations:
File Based Device Registry
MongoDB Based Device Registry.</description>
</item>
</channel>
-</rss>
\ No newline at end of file
+</rss>
diff --git a/docs/dev/user-guide/jdbc-based-device-registry/index.html b/docs/dev/user-guide/jdbc-based-device-registry/index.html
index ea9fd76..65136cf 100644
--- a/docs/dev/user-guide/jdbc-based-device-registry/index.html
+++ b/docs/dev/user-guide/jdbc-based-device-registry/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>JDBC Based Device Registry :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/jdbc-based-device-registry/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/jdbc-based-device-registry/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/jdbc-based-device-registry/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/jdbc-based-device-registry/">1.6</option>
@@ -1690,6 +1722,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/jdbc-based-device-registry/" selected>dev</option>
@@ -1808,14 +1842,11 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#managing-tenants">Managing Tenants</a></li>
-<li><a href="#managing-devices">Managing Devices</a></li>
-<li><a href="#managing-credentials">Managing Credentials</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#managing-tenants">Managing Tenants</a></li>
+ <li><a href="#managing-devices">Managing Devices</a></li>
+ <li><a href="#managing-credentials">Managing Credentials</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -1839,32 +1870,21 @@
-
-
<p>The JDBC based Device Registry component provides implementations of Hono’s <a href="/hono/docs/dev/api/tenant/">Tenant API</a>, <a href="/hono/docs/dev/api/device-registration/">Device Registration API</a> and <a href="/hono/docs/dev/api/credentials/">Credentials API</a>. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.</p>
-
<p>In addition to the above APIs, this Device Registry also exposes HTTP endpoints for managing the contents of the Device Registry according to the <a href="/hono/docs/dev/api/management/">Device Registry Management API</a>. It uses a JDBC compliant database to persist the data. By default, this registry supports H2 and PostgreSQL. For more information on how to configure the JDBC based device registry, see <a href="/hono/docs/dev/admin-guide/jdbc-device-registry-config/">JDBC based Device Registry configuration</a>.</p>
-
<h2 id="managing-tenants">Managing Tenants</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#tenants">Device Registry Management API</a> for information about managing tenants.</p>
-
<div class="alert alert-warning">
<h4 class="alert-heading"><i class="fas fa-exclamation-triangle"></i> Warning</h4>
<div>The JDBC based device registry doesn’t support <a href="/hono/docs/dev/api/management/#tenants/searchTenants">search tenants</a> operation defined by the Device Registry Management API.</div>
</div>
-
<h2 id="managing-devices">Managing Devices</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#devices">Device Registry Management API</a> for information about managing devices.</p>
-
<div class="alert alert-warning">
<h4 class="alert-heading"><i class="fas fa-exclamation-triangle"></i> Warning</h4>
<div>The JDBC based device registry doesn’t support <a href="/hono/docs/dev/api/management/#devices/searchDevicesForTenant">search devices</a> operation defined by the Device Registry Management API.</div>
</div>
-
<h2 id="managing-credentials">Managing Credentials</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#credentials">Device Registry Management API</a> for information about managing credentials.</p>
@@ -2990,19 +3010,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/kura-adapter/index.html b/docs/dev/user-guide/kura-adapter/index.html
index 5bc07d8..ebb947a 100644
--- a/docs/dev/user-guide/kura-adapter/index.html
+++ b/docs/dev/user-guide/kura-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>Kura Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/kura-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/kura-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/kura-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/kura-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/kura-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/kura-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/kura-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/kura-adapter/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/kura-adapter/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/kura-adapter/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/kura-adapter/" selected>dev</option>
@@ -1964,29 +2010,29 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#authentication">Authentication</a>
-<ul>
-<li><a href="#client-certificate">Client Certificate</a></li>
-<li><a href="#username-password">Username/Password</a></li>
-</ul></li>
-<li><a href="#resource-limit-checks">Resource Limit Checks</a>
-<ul>
-<li><a href="#connection-limits">Connection Limits</a></li>
-<li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
-<li><a href="#message-limits">Message Limits</a></li>
-</ul></li>
-<li><a href="#connection-events">Connection Events</a></li>
-<li><a href="#publishing-data">Publishing Data</a></li>
-<li><a href="#downstream-meta-data">Downstream Meta Data</a>
-<ul>
-<li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
-</ul></li>
-<li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#authentication">Authentication</a>
+ <ul>
+ <li><a href="#client-certificate">Client Certificate</a></li>
+ <li><a href="#usernamepassword">Username/Password</a></li>
+ </ul>
+ </li>
+ <li><a href="#resource-limit-checks">Resource Limit Checks</a>
+ <ul>
+ <li><a href="#connection-limits">Connection Limits</a></li>
+ <li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
+ <li><a href="#message-limits">Message Limits</a></li>
+ </ul>
+ </li>
+ <li><a href="#connection-events">Connection Events</a></li>
+ <li><a href="#publishing-data">Publishing Data</a></li>
+ <li><a href="#downstream-meta-data">Downstream Meta Data</a>
+ <ul>
+ <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
+ </ul>
+ </li>
+ <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -2010,23 +2056,17 @@
-<p>The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ based gateways to publish <em>control</em> and <em>data</em> messages to Eclipse Hono™’s Telemetry and Event endpoints.</p>
-
+<p>The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ based gateways to publish <em>control</em> and <em>data</em> messages to Eclipse Hono™’s Telemetry and Event endpoints.</p>
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>The Kura adapter is supposed to be used with gateways running Kura version 3.x. Gateways running Kura version 4 and later should connect to the MQTT adapter instead.</div>
</div>
-
<h2 id="authentication">Authentication</h2>
-
<p>The Kura adapter by default requires devices (gateways) to authenticate during connection establishment.
The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT packet as well as client
certificate based authentication as part of a TLS handshake for that purpose.</p>
-
<p>The adapter tries to authenticate the device using these mechanisms in the following order</p>
-
<h3 id="client-certificate">Client Certificate</h3>
-
<p>When a device uses a client certificate for authentication during the TLS handshake, the adapter tries to determine the tenant
that the device belongs to based on the <em>issuer DN</em> contained in the certificate.
In order for the lookup to succeed, the tenant’s trust anchor needs to be configured by means of registering the
@@ -2035,73 +2075,50 @@
In a second step, the adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the client
certificate’s <em>subject DN</em> as the <em>auth-id</em>, <code>x509-cert</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the
request payload.</p>
-
-<p><strong>NB</strong> The adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/#mqtt-adapter">configured for TLS</a> in order to support this mechanism.</p>
-
-<h3 id="username-password">Username/Password</h3>
-
+<p><strong>NB</strong> The adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/">configured for TLS</a> in order to support this mechanism.</p>
+<h3 id="usernamepassword">Username/Password</h3>
<p>When a device wants to authenticate using this mechanism, it needs to provide a <em>username</em> and a <em>password</em> in the MQTT <em>CONNECT</em> packet
it sends in order to initiate the connection. The <em>username</em> must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>.
The adapter verifies the credentials provided by the client against the credentials that the
-<a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">configured Credentials service</a> has on record for the client.
+<a href="/hono/docs/dev/admin-guide/common-config/">configured Credentials service</a> has on record for the client.
The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the <em>tenant</em> and <em>auth-id</em> provided
by the client in the <em>username</em>, <code>hashed-password</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the request payload.</p>
-
<p>Please refer to the <a href="http://eclipse.github.io/kura/config/cloud-services.html">Eclipse Kura documentation</a> on how to configure the
gateway’s cloud service connection accordingly. It is important to set the gateway’s <em>topic.context.account-name</em> to the ID of the
Hono tenant that the gateway has been registered with whereas the gateway’s <em>client-id</em> needs to be set to the corresponding Hono
device ID. The <em>auth-id</em> used as part of the gateway’s <em>username</em> property needs to match the authentication identifier of a set of
credentials registered for the device ID in Hono’s Credentials service. In other words, the credentials configured on the gateway
need to belong to the corresponding device ID.</p>
-
<p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication.
See <a href="/hono/docs/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p>
-
<h2 id="resource-limit-checks">Resource Limit Checks</h2>
-
<p>The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.</p>
-
<h3 id="connection-limits">Connection Limits</h3>
-
<p>The adapter rejects a client’s connection attempt with return code <code>0x05</code>, indicating <code>Connection Refused: not authorized</code>, if</p>
-
<ul>
<li>the maximum number of connections per protocol adapter instance is reached, or</li>
<li>if the maximum number of simultaneously connected devices for the tenant is reached.</li>
</ul>
-
<p>Please refer to <a href="/hono/docs/dev/concepts/resource-limits/">resource-limits</a> for details.</p>
-
<h3 id="connection-duration-limits">Connection Duration Limits</h3>
-
<p>The adapter rejects a client’s connection attempt with return code <code>0x05</code>, indicating <code>Connection Refused: not authorized</code>, if the
-<a href="/hono/docs/dev/concepts/resource-limits/#connection-duration-limit">connection duration limit</a> that has been configured for
+<a href="/hono/docs/dev/concepts/resource-limits/">connection duration limit</a> that has been configured for
the client’s tenant is exceeded.</p>
-
<h3 id="message-limits">Message Limits</h3>
-
<p>The adapter</p>
-
<ul>
<li>discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and</li>
<li>rejects any AMQP 1.0 message containing a command sent by a north bound application</li>
</ul>
-
<p>if the <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p>
-
<h2 id="connection-events">Connection Events</h2>
-
<p>The adapter can emit <a href="/hono/docs/dev/api/event/#connection-event">Connection Events</a> for client connections being established and/or terminated.
-Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/#connection-event-producer-configuration">common configuration options</a>
+Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/">common configuration options</a>
for details regarding how to enable this behavior.</p>
-
<p>The adapter includes the <em>client identifier</em> from the client’s MQTT CONNECT packet as the Connection Event’s <em>remote-id</em>.</p>
-
<h2 id="publishing-data">Publishing Data</h2>
-
<p>Once the gateway has established a connection to the Kura adapter, all <em>control</em> and <em>data</em> messages published by applications running on
the gateway are sent to the adapter and mapped to Hono’s Telemetry and Event API endpoints as follows:</p>
-
<ol>
<li>The adapter treats all messages that are published to a topic starting with the configured <code>HONO_KURA_CONTROL_PREFIX</code> as control messages.
All other messages are considered to be data messages.</li>
@@ -2110,85 +2127,70 @@
<li><em>data</em> messages with QoS 0 are forwarded to the telemetry endpoint whereas messages with QoS 1 are forwarded to the event endpoint.
The corresponding AMQP 1.0 messages that are sent downstream have a content type of <code>application/vnd.eclipse.kura-data</code>.</li>
</ol>
-
<h2 id="downstream-meta-data">Downstream Meta Data</h2>
-
<p>The adapter includes the following meta data in messages being sent downstream:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Location</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Location</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier of the device that the message originates from.</td>
+<td style="text-align:left"><em>device_id</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">The identifier of the device that the message originates from.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_adapter</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The Kura adapter’s type name is <code>hono-kura-mqtt</code>.</td>
+<td style="text-align:left"><em>orig_adapter</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The Kura adapter’s type name is <code>hono-kura-mqtt</code>.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_address</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the name of the MQTT topic that the Kura gateway has originally published the data to.</td>
+<td style="text-align:left"><em>orig_address</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the name of the MQTT topic that the Kura gateway has originally published the data to.</td>
</tr>
</tbody>
</table>
-
<p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a> or the <a href="/hono/docs/dev/api/device-registration/#assert-device-registration">device level</a>. The values of the default properties are determined as follows:</p>
-
<ol>
<li>If the message already contains a non-empty property of the same name, the value if unchanged.</li>
<li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li>
<li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li>
</ol>
-
<p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p>
-
<h3 id="event-message-time-to-live">Event Message Time-to-live</h3>
-
<p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers.
In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed
from the persistent store if no consumer has attached to receive the event before the message expires.</p>
-
<p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the protocol adapter supports setting a
-downstream event message’s <em>ttl</em> property based on the default <em>ttl</em> and <em>max-ttl</em> values configured for a tenant/device as described in the <a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p>
-
+downstream event message’s <em>ttl</em> property based on the default <em>ttl</em> and <em>max-ttl</em> values configured for a tenant/device as described in the [Tenant API]
+(/hono/docs/dev/api/tenant/#resource-limits-configuration-format).</p>
<h2 id="tenant-specific-configuration">Tenant specific Configuration</h2>
-
<p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-kura-mqtt</code>.
The following properties are (currently) supported:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Default Value</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Default Value</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>enabled</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left"><code>true</code></td>
-<td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
+<td style="text-align:left"><em>enabled</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
</tr>
</tbody>
</table>
@@ -3315,19 +3317,19 @@
<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?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757973"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757973"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757973"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757973"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844324"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844324"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844324"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844324"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757973"></script>
- <script src="/hono/docs/js/learn.js?1617757973"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757973"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844324"></script>
+ <script src="/hono/docs/js/learn.js?1617844324"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844324"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757973" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757973"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844324" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844324"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/mongodb-based-device-registry/index.html b/docs/dev/user-guide/mongodb-based-device-registry/index.html
index 18f70f9..a8a3030 100644
--- a/docs/dev/user-guide/mongodb-based-device-registry/index.html
+++ b/docs/dev/user-guide/mongodb-based-device-registry/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>MongoDB Based Device Registry :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/mongodb-based-device-registry/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/mongodb-based-device-registry/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/mongodb-based-device-registry/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/mongodb-based-device-registry/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/mongodb-based-device-registry/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/mongodb-based-device-registry/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/mongodb-based-device-registry/">1.3</option>
@@ -1768,6 +1806,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/mongodb-based-device-registry/" selected>dev</option>
@@ -1886,15 +1926,12 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#authentication">Authentication</a></li>
-<li><a href="#managing-tenants">Managing Tenants</a></li>
-<li><a href="#managing-devices">Managing Devices</a></li>
-<li><a href="#managing-credentials">Managing Credentials</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#authentication">Authentication</a></li>
+ <li><a href="#managing-tenants">Managing Tenants</a></li>
+ <li><a href="#managing-devices">Managing Devices</a></li>
+ <li><a href="#managing-credentials">Managing Credentials</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -1918,26 +1955,15 @@
-
-
<p>The MongoDB based Device Registry component provides implementations of Hono’s <a href="/hono/docs/dev/api/tenant/">Tenant API</a>, <a href="/hono/docs/dev/api/device-registration/">Device Registration API</a> and <a href="/hono/docs/dev/api/credentials/">Credentials API</a>. As such it exposes AMQP 1.0 based endpoints for retrieving the relevant information. Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.</p>
-
<p>In addition to the above APIs, this Device Registry also exposes HTTP endpoints for managing the contents of the Device Registry according to the <a href="/hono/docs/dev/api/management/">Device Registry Management API</a>. It uses a MongoDB database to persist the data. The credentials, device and tenant information are stored in separate collections in a MongoDB database. For more information on how to configure the MongoDB based device registry, see <a href="/hono/docs/dev/admin-guide/mongodb-device-registry-config/">MongoDB based Device Registry configuration</a>.</p>
-
<h2 id="authentication">Authentication</h2>
-
-<p>This Device Registry secures its HTTP Endpoints using basic authentication mechanism. Thereby the clients connecting to the MongoDB based Device Registry are required to authenticate. For more information on how to enable the authentication and configure it, please refer to the <code>hono.registry.http.authenticationRequired</code> property in the <a href="/hono/docs/dev/admin-guide/mongodb-device-registry-config/#service-configuration">MongoDB based Device Registry configuration</a>.</p>
-
+<p>This Device Registry secures its HTTP Endpoints using basic authentication mechanism. Thereby the clients connecting to the MongoDB based Device Registry are required to authenticate. For more information on how to enable the authentication and configure it, please refer to the <code>hono.registry.http.authenticationRequired</code> property in the <a href="/hono/docs/dev/admin-guide/mongodb-device-registry-config/">MongoDB based Device Registry configuration</a>.</p>
<h2 id="managing-tenants">Managing Tenants</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#tenants">Device Registry Management API</a> for information about managing tenants.</p>
-
<h2 id="managing-devices">Managing Devices</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#devices">Device Registry Management API</a> for information about managing devices.</p>
-
<h2 id="managing-credentials">Managing Credentials</h2>
-
<p>Please refer to the <a href="/hono/docs/dev/api/management/#credentials">Device Registry Management API</a> for information about managing credentials.</p>
@@ -3060,19 +3086,19 @@
<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?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757973"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757973"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757973"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757973"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844323"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844323"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844323"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844323"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844323"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757973"></script>
- <script src="/hono/docs/js/learn.js?1617757973"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757973"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844323"></script>
+ <script src="/hono/docs/js/learn.js?1617844323"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844323"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757973" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757973"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844323" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844323"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/mqtt-adapter/index.html b/docs/dev/user-guide/mqtt-adapter/index.html
index 3d15304..6e8bf80 100644
--- a/docs/dev/user-guide/mqtt-adapter/index.html
+++ b/docs/dev/user-guide/mqtt-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>MQTT Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/mqtt-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/mqtt-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/mqtt-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/mqtt-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/mqtt-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/mqtt-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/mqtt-adapter/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/mqtt-adapter/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/mqtt-adapter/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/mqtt-adapter/" selected>dev</option>
@@ -1964,54 +2010,56 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#authentication">Authentication</a>
-<ul>
-<li><a href="#client-certificate">Client Certificate</a></li>
-<li><a href="#username-password">Username/Password</a></li>
-</ul></li>
-<li><a href="#resource-limit-checks">Resource Limit Checks</a>
-<ul>
-<li><a href="#connection-limits">Connection Limits</a></li>
-<li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
-<li><a href="#message-limits">Message Limits</a></li>
-</ul></li>
-<li><a href="#connection-events">Connection Events</a></li>
-<li><a href="#publishing-telemetry-data">Publishing Telemetry Data</a></li>
-<li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
-<li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
-<li><a href="#publishing-events">Publishing Events</a></li>
-<li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
-<li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
-<li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
-<li><a href="#command-control">Command & Control</a>
-<ul>
-<li><a href="#receiving-commands-authenticated-device">Receiving Commands (authenticated Device)</a></li>
-<li><a href="#receiving-commands-unauthenticated-device">Receiving Commands (unauthenticated Device)</a></li>
-<li><a href="#receiving-commands-authenticated-gateway">Receiving Commands (authenticated Gateway)</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
-<li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
-</ul></li>
-<li><a href="#error-reporting-via-error-topic">Error Reporting via Error Topic</a>
-<ul>
-<li><a href="#receiving-error-messages-authenticated-device">Receiving Error Messages (authenticated Device)</a></li>
-<li><a href="#receiving-error-messages-unauthenticated-device">Receiving Error Messages (unauthenticated Device)</a></li>
-<li><a href="#receiving-error-messages-authenticated-gateway">Receiving Error Messages (authenticated Gateway)</a></li>
-<li><a href="#error-message-payload">Error Message Payload</a></li>
-</ul></li>
-<li><a href="#error-handling">Error Handling</a></li>
-<li><a href="#custom-message-mapping">Custom Message Mapping</a></li>
-<li><a href="#downstream-meta-data">Downstream Meta Data</a>
-<ul>
-<li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
-</ul></li>
-<li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#authentication">Authentication</a>
+ <ul>
+ <li><a href="#client-certificate">Client Certificate</a></li>
+ <li><a href="#usernamepassword">Username/Password</a></li>
+ </ul>
+ </li>
+ <li><a href="#resource-limit-checks">Resource Limit Checks</a>
+ <ul>
+ <li><a href="#connection-limits">Connection Limits</a></li>
+ <li><a href="#connection-duration-limits">Connection Duration Limits</a></li>
+ <li><a href="#message-limits">Message Limits</a></li>
+ </ul>
+ </li>
+ <li><a href="#connection-events">Connection Events</a></li>
+ <li><a href="#publishing-telemetry-data">Publishing Telemetry Data</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</a></li>
+ <li><a href="#publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</a></li>
+ <li><a href="#publishing-events">Publishing Events</a></li>
+ <li><a href="#publish-an-event-authenticated-device">Publish an Event (authenticated Device)</a></li>
+ <li><a href="#publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</a></li>
+ <li><a href="#publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</a></li>
+ <li><a href="#command--control">Command & Control</a>
+ <ul>
+ <li><a href="#receiving-commands-authenticated-device">Receiving Commands (authenticated Device)</a></li>
+ <li><a href="#receiving-commands-unauthenticated-device">Receiving Commands (unauthenticated Device)</a></li>
+ <li><a href="#receiving-commands-authenticated-gateway">Receiving Commands (authenticated Gateway)</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</a></li>
+ <li><a href="#sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</a></li>
+ </ul>
+ </li>
+ <li><a href="#error-reporting-via-error-topic">Error Reporting via Error Topic</a>
+ <ul>
+ <li><a href="#receiving-error-messages-authenticated-device">Receiving Error Messages (authenticated Device)</a></li>
+ <li><a href="#receiving-error-messages-unauthenticated-device">Receiving Error Messages (unauthenticated Device)</a></li>
+ <li><a href="#receiving-error-messages-authenticated-gateway">Receiving Error Messages (authenticated Gateway)</a></li>
+ <li><a href="#error-message-payload">Error Message Payload</a></li>
+ </ul>
+ </li>
+ <li><a href="#error-handling">Error Handling</a></li>
+ <li><a href="#custom-message-mapping">Custom Message Mapping</a></li>
+ <li><a href="#downstream-meta-data">Downstream Meta Data</a>
+ <ul>
+ <li><a href="#event-message-time-to-live">Event Message Time-to-live</a></li>
+ </ul>
+ </li>
+ <li><a href="#tenant-specific-configuration">Tenant specific Configuration</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -2036,9 +2084,7 @@
<p>The MQTT protocol adapter exposes an MQTT topic hierarchy for publishing telemetry data and events to downstream consumers and for receiving commands from applications and sending back responses.</p>
-
<p>The MQTT adapter is <strong>not</strong> a general purpose MQTT broker. In particular the adapter</p>
-
<ul>
<li>supports MQTT 3.1.1 only.</li>
<li>does not maintain session state for clients and thus always sets the <em>session present</em> flag in its CONNACK packet to <code>0</code>, regardless of the value of the <em>clean session</em> flag provided in a client’s CONNECT packet.</li>
@@ -2046,17 +2092,12 @@
<li>only supports topic names/filters for devices to publish and subscribe to that are specific to Hono’s functionality as described in the following sections.</li>
<li>does not support <em>retaining</em> messages. However, if an event or telemetry message’s <em>retain</em> flag is set to <code>1</code> then the corresponding AMQP 1.0 message being sent downstream by the adapter will contain an <em>x-opt-retain</em> message annotation containing the boolean value <code>true</code>. A downstream consumer may then react according to the presence of this annotation.</li>
</ul>
-
<h2 id="authentication">Authentication</h2>
-
<p>The MQTT adapter by default requires clients (devices or gateway components) to authenticate during connection establishment.
The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT packet as well as client
certificate based authentication as part of a TLS handshake for that purpose.</p>
-
<p>The adapter tries to authenticate the device using these mechanisms in the following order</p>
-
<h3 id="client-certificate">Client Certificate</h3>
-
<p>When a device uses a client certificate for authentication during the TLS handshake, the adapter tries to determine the tenant
that the device belongs to based on the <em>issuer DN</em> contained in the certificate.
In order for the lookup to succeed, the tenant’s trust anchor needs to be configured by means of registering the
@@ -2065,940 +2106,658 @@
In a second step, the adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the client
certificate’s <em>subject DN</em> as the <em>auth-id</em>, <code>x509-cert</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the
request payload.</p>
-
-<p><strong>NB</strong> The adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/#mqtt-adapter">configured for TLS</a> in order to support this mechanism.</p>
-
-<h3 id="username-password">Username/Password</h3>
-
+<p><strong>NB</strong> The adapter needs to be <a href="/hono/docs/dev/admin-guide/secure_communication/">configured for TLS</a> in order to support this mechanism.</p>
+<h3 id="usernamepassword">Username/Password</h3>
<p>When a device wants to authenticate using this mechanism, it needs to provide a <em>username</em> and a <em>password</em> in the MQTT <em>CONNECT</em> packet
it sends in order to initiate the connection. The <em>username</em> must have the form <em>auth-id@tenant</em>, e.g. <code>sensor1@DEFAULT_TENANT</code>.
The adapter verifies the credentials provided by the client against the credentials that the
-<a href="/hono/docs/dev/admin-guide/common-config/#credentials-service-connection-configuration">configured Credentials service</a> has on record for the client.
+<a href="/hono/docs/dev/admin-guide/common-config/">configured Credentials service</a> has on record for the client.
The adapter uses the Credentials API’s <em>get</em> operation to retrieve the credentials on record, including the <em>tenant</em> and <em>auth-id</em> provided
by the client in the <em>username</em>, <code>hashed-password</code> as the <em>type</em> of secret and the MQTT client identifier as <em>client-id</em> in the request payload.</p>
-
<p>The examples below refer to devices <code>4711</code> and <code>gw-1</code> of tenant <code>DEFAULT_TENANT</code> using <em>auth-ids</em> <code>sensor1</code> and <code>gw1</code> and corresponding passwords.
The example deployment as described in the <a href="/hono/docs/dev/deployment/">Deployment Guides</a> comes pre-configured with the corresponding entities in its device registry component.</p>
-
<p><strong>NB</strong> There is a subtle difference between the <em>device identifier</em> (<em>device-id</em>) and the <em>auth-id</em> a device uses for authentication.
See <a href="/hono/docs/dev/concepts/device-identity/">Device Identity</a> for a discussion of the concepts.</p>
-
<h2 id="resource-limit-checks">Resource Limit Checks</h2>
-
<p>The adapter performs additional checks regarding <a href="/hono/docs/dev/concepts/resource-limits/">resource limits</a> when a client tries to connect and/or
send a message to the adapter.</p>
-
<h3 id="connection-limits">Connection Limits</h3>
-
<p>The adapter rejects a client’s connection attempt with return code</p>
-
<ul>
<li><code>0x03</code> (<em>Connection Refused: server unavailable</em>), if the maximum number of connections per protocol adapter instance is reached</li>
<li><code>0x05</code> (<em>Connection Refused: not authorized</em>), if the maximum number of simultaneously connected devices for the tenant is reached.</li>
</ul>
-
<h3 id="connection-duration-limits">Connection Duration Limits</h3>
-
<p>The adapter rejects a client’s connection attempt with return code <code>0x05</code> (<em>Connection Refused: not authorized</em>), if the
-<a href="/hono/docs/dev/concepts/resource-limits/#connection-duration-limit">connection duration limit</a> that has been configured for the client’s tenant is exceeded.</p>
-
+<a href="/hono/docs/dev/concepts/resource-limits/">connection duration limit</a> that has been configured for the client’s tenant is exceeded.</p>
<h3 id="message-limits">Message Limits</h3>
-
<p>The adapter</p>
-
<ul>
<li>rejects a client’s connection attempt with return code <code>0x05</code> (<em>Connection Refused: not authorized</em>),</li>
<li>discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and</li>
<li>rejects any AMQP 1.0 message containing a command sent by a north bound application</li>
</ul>
-
<p>if the <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> that has been configured for the device’s tenant is exceeded.</p>
-
<h2 id="connection-events">Connection Events</h2>
-
<p>The adapter can emit <a href="/hono/docs/dev/api/event/#connection-event">Connection Events</a> for client connections being established and/or terminated.
-Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/#connection-event-producer-configuration">common configuration options</a>
+Please refer to the <a href="/hono/docs/dev/admin-guide/common-config/">common configuration options</a>
for details regarding how to enable this behavior.</p>
-
<p>The adapter includes the <em>client identifier</em> from the client’s MQTT CONNECT packet as the Connection Event’s <em>remote-id</em>.</p>
-
<h2 id="publishing-telemetry-data">Publishing Telemetry Data</h2>
-
<p>The MQTT adapter supports the publishing of telemetry data by means of MQTT <em>PUBLISH</em> packets using either QoS 0 or QoS 1.
Using QoS 1 will result in the adapter sending an MQTT <em>PUBACK</em> packet to the client once the message has been settled with the <em>accepted</em> outcome by the AMQP 1.0 Messaging Network.</p>
-
<p>This requires that</p>
-
<ul>
<li>the AMQP 1.0 Messaging Network has capacity to process telemetry messages for the client’s tenant and</li>
<li>the messages published by the client comply with the format defined by the Telemetry API.</li>
</ul>
-
-<p>The protocol adapter checks the configured <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> before accepting any telemetry messages. An exceeded message limit will cause an error.</p>
-
+<p>The protocol adapter checks the configured [message limit] (/hono/docs/dev/concepts/resource-limits/) before accepting any telemetry messages. An exceeded message limit will cause an error.</p>
<p>Any kind of error when processing an incoming telemetry message will be reported back to the client if the client has subscribed on a dedicated error topic. See <a href="#error-reporting-via-error-topic">Error Reporting via Error Topic</a> for details.</p>
-
<p>If such an error subscription by the client exists, the error will by default be ignored after it got published on the error topic, otherwise the connection to the client will be closed. The handling of errors can further be controlled by means of an <em>on-error</em> property bag parameter set on the telemetry message topic. Refer to <a href="#error-handling">Error Handling</a> for details.</p>
-
<p>The devices can optionally indicate the content type of the payload by setting the <em>content-type</em> property explicitly in the <code>property-bag</code>. The <code>property-bag</code> is an optional collection of properties intended for the receiver of the message. A property bag is only allowed at the very end of a topic. It always starts with a <code>/?</code> character, followed by pairs of URL encoded property names and values that are separated by <code>&</code>. For example, a property bag containing two properties <em>seqNo</em> and <em>importance</em> looks like this: <code>/topic/name/?seqNo=10034&importance=high</code>.</p>
-
<h2 id="publish-telemetry-data-authenticated-device">Publish Telemetry Data (authenticated Device)</h2>
-
<ul>
<li>Topic: <code>telemetry</code> or <code>t</code></li>
<li>Authentication: required</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish telemetry data. It is available only if the protocol adapter is configured to require devices to authenticate (which is the default). When using this topic, the MQTT adapter determines the device’s tenant and device identity as part of the authentication process.</p>
-
<p><strong>Example</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t telemetry -m '{"temp": 5}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
-
-<pre><code class="language-sh"># in base directory of Hono repository:
-mosquitto_pub -p 8883 -t telemetry -m '{"temp": 5}' --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cafile demo-certs/certs/trusted-certs.pem
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that the MQTT adapter is <a href="/hono/docs/dev/admin-guide/secure_communication/#mqtt-adapter">configured for TLS</a> and the secure port is used.</p>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t telemetry -m <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> using a client certificate for authentication:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"><span style="color:#75715e"># in base directory of Hono repository:</span>
+mosquitto_pub -p <span style="color:#ae81ff">8883</span> -t telemetry -m <span style="color:#e6db74">'{"temp": 5}'</span> --cert demo-certs/certs/device-4711-cert.pem --key demo-certs/certs/device-4711-key.pem --cafile demo-certs/certs/trusted-certs.pem
+</code></pre></div><p><strong>NB</strong> The example above assumes that the MQTT adapter is <a href="/hono/docs/dev/admin-guide/secure_communication/">configured for TLS</a> and the secure port is used.</p>
<h2 id="publish-telemetry-data-unauthenticated-device">Publish Telemetry Data (unauthenticated Device)</h2>
-
<ul>
<li>Topic: <code>telemetry/${tenant-id}/${device-id}</code> or <code>t/${tenant-id}/${device-id}</code></li>
<li>Authentication: none</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the
<code>HONO_MQTT_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -t telemetry/DEFAULT_TENANT/4711 -m '{"temp": 5}'
-</code></pre>
-
-<h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t telemetry/DEFAULT_TENANT/4711 -m <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><h2 id="publish-telemetry-data-authenticated-gateway">Publish Telemetry Data (authenticated Gateway)</h2>
<ul>
<li>Topic: <code>telemetry/${tenant-id}/${device-id}</code> or <code>t/${tenant-id}/${device-id}</code></li>
<li>Authentication: required</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This topic can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code> via gateway <code>gw-1</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'gw@DEFAULT_TENANT' -P gw-secret -t telemetry/DEFAULT_TENANT/4712 -m '{"temp": 5}'
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t telemetry/DEFAULT_TENANT/4712 -m <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p>
<h2 id="publishing-events">Publishing Events</h2>
-
<p>The MQTT adapter supports the publishing of events by means of MQTT <em>PUBLISH</em> packets using QoS 1 only.
The adapter will send an MQTT <em>PUBACK</em> packet to the client once the event has been settled with the <em>accepted</em> outcome by the AMQP 1.0 Messaging Network.</p>
-
<p>This requires that</p>
-
<ul>
<li>the AMQP 1.0 Messaging Network has capacity to process events for the client’s tenant and</li>
<li>the events published by the client comply with the format defined by the Event API.</li>
</ul>
-
-<p>The protocol adapter checks the configured <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> before accepting any event messages. An exceeded message limit will cause an error.</p>
-
+<p>The protocol adapter checks the configured [message limit] (/hono/docs/dev/concepts/resource-limits/) before accepting any event messages. An exceeded message limit will cause an error.</p>
<p>Any kind of error when processing an incoming event message will be reported back to the client if the client has subscribed on a dedicated error topic. See <a href="#error-reporting-via-error-topic">Error Reporting via Error Topic</a> for details.</p>
-
<p>If such an error subscription by the client exists, the error will by default be ignored after it got published on the error topic, otherwise the connection to the client will be closed. The handling of errors can further be controlled by means of an <em>on-error</em> property bag parameter set on the event message topic. Refer to <a href="#error-handling">Error Handling</a> for details.</p>
-
<p>The devices can optionally indicate a <em>time-to-live</em> duration for event messages and the content type of the payload by setting the <em>hono-ttl</em> and <em>content-type</em> properties explicitly in the <code>property-bag</code>. The <code>property-bag</code> is an optional collection of properties intended for the receiver of the message. A property bag is only allowed at the very end of a topic. It always starts with a <code>/?</code> character, followed by pairs of URL encoded property names and values that are separated by <code>&</code>. For example, a property bag containing two properties <em>seqNo</em> and <em>importance</em> looks like this: <code>/topic/name/?seqNo=10034&importance=high</code>.</p>
-
<p>The MQTT adapter currently does not use any properties except <em>hono-ttl</em>.</p>
-
<h2 id="publish-an-event-authenticated-device">Publish an Event (authenticated Device)</h2>
-
<ul>
<li>Topic: <code>event</code> or <code>e</code></li>
<li>Authentication: required</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This is the preferred way for devices to publish events. It is available only if the protocol adapter has been configured to require devices to authenticate (which is the default).</p>
-
<p><strong>Example</strong></p>
-
<p>Upload a JSON string for device <code>4711</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t event -q 1 -m '{"alarm": 1}'
-</code></pre>
-
-<p>Upload a JSON string for device <code>4711</code> with <code>time-to-live</code> as 10 seconds:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t event/?hono-ttl=10 -q 1 -m '{"alarm": 1}'
-</code></pre>
-
-<h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t event -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><p>Upload a JSON string for device <code>4711</code> with <code>time-to-live</code> as 10 seconds:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t event/?hono-ttl<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span> -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><h2 id="publish-an-event-unauthenticated-device">Publish an Event (unauthenticated Device)</h2>
<ul>
<li>Topic: <code>event/${tenant-id}/${device-id}</code> or <code>e/${tenant-id}/${device-id}</code></li>
<li>Authentication: none</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This topic can be used by devices that have not authenticated to the protocol adapter. Note that this requires the
<code>HONO_MQTT_AUTHENTICATION_REQUIRED</code> configuration property to be explicitly set to <code>false</code>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4711</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -t event/DEFAULT_TENANT/4711 -q 1 -m '{"alarm": 1}'
-</code></pre>
-
-<p>Publish some JSON data for device <code>4711</code> with <code>time-to-live</code> as 15 seconds:</p>
-
-<pre><code class="language-sh">mosquitto_pub -t event/DEFAULT_TENANT/4711/?hono-ttl=15 -q 1 -m '{"alarm": 1}'
-</code></pre>
-
-<h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t event/DEFAULT_TENANT/4711 -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><p>Publish some JSON data for device <code>4711</code> with <code>time-to-live</code> as 15 seconds:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t event/DEFAULT_TENANT/4711/?hono-ttl<span style="color:#f92672">=</span><span style="color:#ae81ff">15</span> -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"alarm": 1}'</span>
+</code></pre></div><h2 id="publish-an-event-authenticated-gateway">Publish an Event (authenticated Gateway)</h2>
<ul>
<li>Topic: <code>event/${tenant-id}/${device-id}</code> or <code>e/${tenant-id}/${device-id}</code></li>
<li>Authentication: required</li>
<li>Payload:
-
<ul>
<li>(required) Arbitrary payload</li>
-</ul></li>
</ul>
-
+</li>
+</ul>
<p>This topic can be used by <em>gateway</em> components to publish data <em>on behalf of</em> other devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the topic name are used to identify the device that the gateway publishes data for.</p>
-
<p>The protocol adapter checks the gateway’s authority to publish data on behalf of the device implicitly by means of retrieving a <em>registration assertion</em> for the device from the <a href="/hono/docs/dev/admin-guide/common-config/#device-registration-service-connection-configuration">configured Device Registration service</a>.</p>
-
<p><strong>Examples</strong></p>
-
<p>Publish some JSON data for device <code>4712</code> via gateway <code>gw-1</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'gw@DEFAULT_TENANT' -P gw-secret -t event/DEFAULT_TENANT/4712 -q 1 -m '{"temp": 5}'
-</code></pre>
-
-<p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p>
-
-<h2 id="command-control">Command & Control</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t event/DEFAULT_TENANT/4712 -q <span style="color:#ae81ff">1</span> -m <span style="color:#e6db74">'{"temp": 5}'</span>
+</code></pre></div><p><strong>NB</strong> The example above assumes that a gateway device with ID <code>gw-1</code> has been registered with <code>hashed-password</code> credentials with <em>auth-id</em> <code>gw</code> and password <code>gw-secret</code>.</p>
+<h2 id="command--control">Command & Control</h2>
<p>The MQTT adapter enables devices to receive commands that have been sent by business applications by means of sending an MQTT <em>SUBSCRIBE</em> packet containing a device specific <em>topic filter</em> as described below. Devices can subscribe with QoS 1 or QoS 0. The adapter indicates the outcome of the subscription request by sending back a corresponding <em>SUBACK</em> packet. The SUBACK packet will contain <em>Success - QoS 0</em> (<code>0x00</code>) or <em>Success - QoS 1</em> (<code>0x01</code>) for a valid command topic filter indicating QoS 0 or 1 and will contain the <em>Failure</em> (<code>0x80</code>) value for an invalid or unsupported filter. When a device no longer wants to receive commands anymore, it can send an MQTT <em>UNSUBSCRIBE</em> packet to the adapter, including the same topic filter that has been used to subscribe.</p>
-
<p>When a device has successfully subscribed, the adapter sends an <a href="/hono/docs/dev/api/event/#empty-notification">empty notification</a> on behalf of the device to the downstream AMQP 1.0 Messaging Network with the <em>ttd</em> header set to <code>-1</code>, indicating that the device will be ready to receive commands until further notice. Analogously, the adapter sends an empty notification with the <em>ttd</em> header set to <code>0</code> when a device unsubscribes from commands.</p>
-
<p>Commands can be sent following a <em>request/response</em> pattern or being <em>one-way</em>.</p>
-
<p>For <em>Request/Response</em> commands, devices send their responses to commands by means of sending an MQTT <em>PUBLISH</em> message to a topic that is specific to the command that has been executed. The MQTT adapter accepts responses being published using either QoS 0 or QoS 1.</p>
-
-<p>The MQTT adapter checks the configured <a href="/hono/docs/dev/concepts/resource-limits/">message limit</a> before accepting any command requests and responses. In case of incoming command requests from business applications, if the message limit is exceeded, the Adapter rejects the message with the reason <code>amqp:resource-limit-exceeded</code>. And for the incoming command responses from devices, the Adapter rejects the message and closes the connection to the client.</p>
-
+<p>The MQTT adapter checks the configured [message limit] (/hono/docs/dev/concepts/resource-limits/) before accepting any command requests and responses. In case of incoming command requests from business applications, if the message limit is exceeded, the Adapter rejects the message with the reason <code>amqp:resource-limit-exceeded</code>. And for the incoming command responses from devices, the Adapter rejects the message and closes the connection to the client.</p>
<p>The following sections define the topic filters/names to use for subscribing to and responding to commands. The following <em>shorthand</em> versions of topic path segments are supported:</p>
-
<ul>
<li><code>c</code> instead of <code>command</code></li>
<li><code>q</code> instead of <code>req</code></li>
<li><code>s</code> instead of <code>res</code></li>
</ul>
-
<p>The following variables are used:</p>
-
<ul>
<li><code>${command}</code> : An arbitrary string that indicates the command to execute, e.g. <code>setBrightness</code>. The command is provided by the application that sends the command.</li>
<li><code>${req-id}</code> (only for <em>Request/Response</em> commands) : The unique identifier of the command execution request. The identifier is passed to the device as part of the name of the topic that the command is published to. The device needs to publish its response to the command to a topic which includes this identifier, thus allowing the adapter to correlate the response with the request.</li>
<li><code>${status}</code> : The HTTP status code indicating the outcome of executing the command. This status code is passed on to the application in the AMQP message’s <em>status</em> application property.</li>
</ul>
-
<h3 id="receiving-commands-authenticated-device">Receiving Commands (authenticated Device)</h3>
-
<p>An authenticated device MUST use the following topic filter for subscribing to commands:</p>
-
<p><code>command/[${tenant-id}]/[${device-id}]/req/#</code></p>
-
<p>Both the tenant and the device ID are optional. If specified, they MUST match the authenticated device’s tenant and/or device ID.
Note that the <em>authentication identifier</em> used in the device’s credentials is <em>not</em> necessarily the same as the device ID.</p>
-
<p>The protocol adapter will publish commands for the device to the following topic names</p>
-
<ul>
<li><strong>one-way</strong> <code>command/${tenant-id}/${device-id}/req//${command}</code></li>
<li><strong>request-response</strong> <code>command/${tenant-id}/${device-id}/req/${req-id}/${command}</code></li>
</ul>
-
<p>The <em>tenant-id</em> and/or <em>device-id</em> will be included in the topic name if the tenant and/or device ID had been included
in the topic filter used for subscribing to commands.</p>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4>
<div>Previous versions of Hono required authenticated devices to use <code>command/+/+/req/#</code> for subscribing to commands.
This old topic filter is deprecated. Devices MAY still use it until support for it will be removed in a future Hono version.</div>
</div>
-
<p><strong>Examples</strong></p>
-
<p>The following command can be used to subscribe to commands resulting in command messages being published to a
topic that does not include tenant nor device ID:</p>
-
-<pre><code class="language-sh">mosquitto_sub -v -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t command///req/#
-</code></pre>
-
-<p>A request/response command with name <code>setBrightness</code> from an application might look like this:</p>
-
-<pre><code class="language-plaintext">command///req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t command///req/#
+</code></pre></div><p>A request/response command with name <code>setBrightness</code> from an application might look like this:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command///req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>A corresponding <em>one-way</em> command might look like this:</p>
-
-<pre><code class="language-plaintext">command///req//setBrightness
+</code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command///req//setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>Note that the topic in the latter case doesn’t contain a request identifier.</p>
-
+</code></pre></div><p>Note that the topic in the latter case doesn’t contain a request identifier.</p>
<p>The following command can be used to subscribe to commands resulting in command messages being published to a
topic that includes the tenant ID:</p>
-
-<pre><code class="language-sh">mosquitto_sub -v -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t c/DEFAULT_TENANT//q/#
-</code></pre>
-
-<p>Note the usage of the abbreviated names (<code>c</code> and <code>q</code> instead of <code>command</code> and <code>req</code>) and the inclusion of the tenant ID
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t c/DEFAULT_TENANT//q/#
+</code></pre></div><p>Note the usage of the abbreviated names (<code>c</code> and <code>q</code> instead of <code>command</code> and <code>req</code>) and the inclusion of the tenant ID
in the topic filter.</p>
-
<p>A corresponding request/response command with name <code>setBrightness</code> from an application might look like this:</p>
-
-<pre><code class="language-plaintext">c/DEFAULT_TENANT//q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">c/DEFAULT_TENANT//q/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>A corresponding <em>one-way</em> command might look like this:</p>
-
-<pre><code class="language-plaintext">c/DEFAULT_TENANT//q//setBrightness
+</code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">c/DEFAULT_TENANT//q//setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>Note that the topic also includes the abbreviated names and the tenant identifier because the
+</code></pre></div><p>Note that the topic also includes the abbreviated names and the tenant identifier because the
topic filter used for subscribing did contain the tenant ID as well.</p>
-
<h3 id="receiving-commands-unauthenticated-device">Receiving Commands (unauthenticated Device)</h3>
-
<p>An unauthenticated device MUST use the topic filter <code>command/${tenant-id}/${device-id}/req/#</code> to subscribe to commands.</p>
-
<p><strong>Example</strong></p>
-
-<pre><code class="language-sh">mosquitto_sub -v -t command/DEFAULT_TENANT/4711/req/#
-</code></pre>
-
-<p>The adapter will then publish <em>Request/Response</em> commands for the device to topic <code>command/${tenant-id}/${device-id}/req/${req-id}/${command}</code>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -t command/DEFAULT_TENANT/4711/req/#
+</code></pre></div><p>The adapter will then publish <em>Request/Response</em> commands for the device to topic <code>command/${tenant-id}/${device-id}/req/${req-id}/${command}</code>
and <em>one-way</em> commands to topic <code>command/${tenant-id}/${device-id}/req//${command}</code>.</p>
-
<p>For example, a request/response command with name <code>setBrightness</code> from an application might look like this:</p>
-
-<pre><code class="language-plaintext">command/DEFAULT_TENANT/4711/req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command/DEFAULT_TENANT/4711/req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>A corresponding <em>one-way</em> command might look like this:</p>
-
-<pre><code class="language-plaintext">command/DEFAULT_TENANT/4711/req//setBrightness
+</code></pre></div><p>A corresponding <em>one-way</em> command might look like this:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command/DEFAULT_TENANT/4711/req//setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>Note that the topic in the latter case doesn’t contain a request identifier.</p>
-
+</code></pre></div><p>Note that the topic in the latter case doesn’t contain a request identifier.</p>
<h3 id="receiving-commands-authenticated-gateway">Receiving Commands (authenticated Gateway)</h3>
-
-<p><em>Gateway</em> components can receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/#configuring-gateway-devices">Configuring Gateway Devices</a> for details.</p>
-
+<p><em>Gateway</em> components can receive commands for devices which do not connect to a protocol adapter directly but instead are connected to the gateway, e.g. using some low-bandwidth radio based technology like <a href="https://www.sigfox.com">SigFox</a> or <a href="https://lora-alliance.org/">LoRa</a>. Corresponding devices have to be configured so that they can be used with a gateway. See <a href="/hono/docs/dev/admin-guide/file-based-device-registry-config/">Configuring Gateway Devices</a> for details.</p>
<p>An authenticated gateway MUST use one of the following topic filters for subscribing to commands:</p>
-
<table>
<thead>
<tr>
-<th align="left">Topic Filter</th>
-<th align="left">Description</th>
+<th style="text-align:left">Topic Filter</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><code>command//+/req/#</code></td>
-<td align="left">Subscribe to commands for all devices that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>command//+/req/#</code></td>
+<td style="text-align:left">Subscribe to commands for all devices that the gateway is authorized to act on behalf of.</td>
</tr>
-
<tr>
-<td align="left"><code>command/${tenant-id}/+/req/#</code></td>
-<td align="left">Subscribe to commands for all devices that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>command/${tenant-id}/+/req/#</code></td>
+<td style="text-align:left">Subscribe to commands for all devices that the gateway is authorized to act on behalf of.</td>
</tr>
-
<tr>
-<td align="left"><code>command//${device-id}/req/#</code></td>
-<td align="left">Subscribe to commands for a specific device that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>command//${device-id}/req/#</code></td>
+<td style="text-align:left">Subscribe to commands for a specific device that the gateway is authorized to act on behalf of.</td>
</tr>
-
<tr>
-<td align="left"><code>command/${tenant-id}/${device-id}/req/#</code></td>
-<td align="left">Subscribe to commands for a specific device that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>command/${tenant-id}/${device-id}/req/#</code></td>
+<td style="text-align:left">Subscribe to commands for a specific device that the gateway is authorized to act on behalf of.</td>
</tr>
</tbody>
</table>
-
<p>The protocol adapter will publish commands for devices to the following topic names</p>
-
<ul>
<li><strong>one-way</strong> <code>command//${device-id}/req//${command}</code> or <code>command/${tenant-id}/${device-id}/req//${command}</code></li>
<li><strong>request-response</strong> <code>command//${device-id}/req/${req-id}/${command}</code> or <code>command/${tenant-id}/${device-id}/req/${req-id}/${command}</code></li>
</ul>
-
<p>The <code>${tenant-id}</code> will be included in the topic name if the tenant ID had been included in the topic filter used for subscribing to commands.</p>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Deprecation</h4>
<div>Previous versions of Hono required authenticated gateways to use <code>command/+/+/req/#</code> for subscribing to commands.
This old topic filter is deprecated. Gateways MAY still use it until support for it will be removed in a future Hono version.</div>
</div>
-
<p>When processing an incoming command message, the protocol adapter will give precedence to a device-specific command subscription matching the command target device, whether the subscription comes from a gateway or the device itself. If there are multiple such subscriptions from multiple gateways and/or from the device itself, the subscription initiated last will get the command messages.</p>
-
<p>If no device-specific command subscription exists for a command target device, but <em>one</em> gateway, that may act on behalf of the device, has subscribed to commands for all its devices, then the command message is sent to that gateway.</p>
-
<p>If <em>multiple</em> gateways have initiated such generic subscriptions, the protocol adapter may have to decide to which gateway a particular command message will be sent to.
In case the command target device has already sent a telemetry, event or command response message via a gateway and if that gateway has created such a command subscription, that gateway will be chosen. Otherwise one gateway that may act on behalf of the command target device and that has an open subscription will be chosen randomly to receive the command message.</p>
-
<p><strong>Subscribe to all Devices</strong></p>
-
<p>A subscription to commands for all devices that a gateway acts on behalf of looks like this:</p>
-
-<pre><code class="language-sh">mosquitto_sub -v -u 'gw@DEFAULT_TENANT' -P gw-secret -t command/DEFAULT_TENANT/+/req/#
-</code></pre>
-
-<p>A request/response command for device <code>4711</code> with name <code>setBrightness</code> from an application might then look like this:</p>
-
-<pre><code class="language-plaintext">command/DEFAULT_TENANT/4711/req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t command/DEFAULT_TENANT/+/req/#
+</code></pre></div><p>A request/response command for device <code>4711</code> with name <code>setBrightness</code> from an application might then look like this:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">command/DEFAULT_TENANT/4711/req/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>Note that the tenant identifier is included in the topic name that the command has been published to because it had been
+</code></pre></div><p>Note that the tenant identifier is included in the topic name that the command has been published to because it had been
included in the topic filter used for subscribing to the commands.</p>
-
<p><strong>Subscribe to a specific Device</strong></p>
-
<p>A subscription to commands for a specific device can be done like this:</p>
-
-<pre><code class="language-sh">mosquitto_sub -v -u 'gw@DEFAULT_TENANT' -P gw-secret -t c//4711/q/#
-</code></pre>
-
-<p>Note the usage of the abbreviated names (<code>c</code> and <code>q</code> instead of <code>command</code> and <code>req</code>) in the topic filter.</p>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_sub -v -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t c//4711/q/#
+</code></pre></div><p>Note the usage of the abbreviated names (<code>c</code> and <code>q</code> instead of <code>command</code> and <code>req</code>) in the topic filter.</p>
<p>A corresponding <em>one-way</em> command might look like this:</p>
-
-<pre><code class="language-plaintext">c//4711/q//setBrightness
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-plaintext" data-lang="plaintext">c//4711/q//setBrightness
{
- "brightness": 79
+ "brightness": 79
}
-</code></pre>
-
-<p>Note that the topic also includes the abbreviated names and does not include the tenant identifier because the
+</code></pre></div><p>Note that the topic also includes the abbreviated names and does not include the tenant identifier because the
topic filter used for subscribing did not contain the tenant ID either.</p>
-
<h3 id="sending-a-response-to-a-command-authenticated-device">Sending a Response to a Command (authenticated Device)</h3>
-
<p>An authenticated device MUST send the response to a previously received command to the topic <code>command///res/${req-id}/${status}</code>.</p>
-
<p><strong>Example</strong></p>
-
<p>After a command has arrived as in the above example, you send a response using the arrived <code>${req-id}</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'sensor1@DEFAULT_TENANT' -P hono-secret -t command///res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{"lumen": 200}'
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'sensor1@DEFAULT_TENANT'</span> -P hono-secret -t command///res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-unauthenticated-device">Sending a Response to a Command (unauthenticated Device)</h3>
<p>An unauthenticated device MUST send the response to a previously received command to the topic <code>command/${tenant-id}/${device-id}/res/${req-id}/${status}</code>.</p>
-
<p><strong>Example</strong></p>
-
<p>After a command has arrived as in the above example, you send a response using the arrived <code>${req-id}</code>:</p>
-
-<pre><code class="language-sh">mosquitto_pub -t command/DEFAULT_TENANT/4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{"lumen": 200}'
-</code></pre>
-
-<h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -t command/DEFAULT_TENANT/4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span>
+</code></pre></div><h3 id="sending-a-response-to-a-command-authenticated-gateway">Sending a Response to a Command (authenticated Gateway)</h3>
<p>An authenticated gateway MUST send a device’s response to a command it has received on behalf of the device to the topic <code>command//${device-id}/res/${req-id}/${status}</code>.</p>
-
<p><strong>Example</strong></p>
-
<p>After a command has arrived as in the above example, the response is sent using the <code>${req-id}</code> from the topic that the command had been published to:</p>
-
-<pre><code class="language-sh">mosquitto_pub -u 'gw@DEFAULT_TENANT' -P gw-secret -t command//4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m '{"lumen": 200}'
-</code></pre>
-
-<h2 id="error-reporting-via-error-topic">Error Reporting via Error Topic</h2>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mosquitto_pub -u <span style="color:#e6db74">'gw@DEFAULT_TENANT'</span> -P gw-secret -t command//4711/res/1010f8ab0b53-bd96-4d99-9d9c-56b868474a6a/200 -m <span style="color:#e6db74">'{"lumen": 200}'</span>
+</code></pre></div><h2 id="error-reporting-via-error-topic">Error Reporting via Error Topic</h2>
<p>The default behaviour when an error occurs while publishing telemetry, event or command response messages is for the MQTT adapter to close the network connection to the device, as mandated by the MQTT 3.1.1 spec.</p>
-
<p>An alternative way of dealing with errors involves keeping the connection intact and letting the MQTT adapter publish a corresponding error message on a specific error topic to the device. To enable that behaviour, the device sends an MQTT <em>SUBSCRIBE</em> packet with a topic filter as described below on <em>the same MQTT connection</em> that is also used for publishing the telemetry, event or command response messages. Devices can subscribe with QoS 0 only. The adapter indicates the outcome of the subscription request by sending back a corresponding <em>SUBACK</em> packet. The SUBACK packet will contain <em>Success - QoS 0</em> (<code>0x00</code>) for a valid error topic filter and will contain the <em>Failure</em> (<code>0x80</code>) value for an invalid or unsupported filter. In order to again activate the default error handling behaviour, the device can send an MQTT <em>UNSUBSCRIBE</em> packet to the adapter, including the same topic filter that has been used to subscribe.</p>
-
<p>The following sections define the topic filters to use for subscribing to error messages and the resulting error message topic. Instead of the <code>error</code> topic path segment, the shorthand version <code>e</code> is also supported.</p>
-
<p>The following variables are used:</p>
-
<ul>
<li><code>${endpoint-type}</code>: The endpoint type of the device message that caused the error. Its value is either <code>telemetry</code>, <code>event</code> or the respective shorthand version. In case of a command response device message <code>command-response</code> or <code>c-s</code> is used.</li>
<li><code>${correlation-id}</code>: The identifier that may be used to correlate the error message with the device message that caused the error. The identifier is either the value of a <em>correlation-id</em> property bag value contained in the device message topic, or the identifier is the <em>packet-id</em> of the device message if it was sent with QoS 1. Otherwise, a value of <code>-1</code> is used.</li>
<li><code>${error-status}</code>: The HTTP status code of the error that was caused by the device message.</li>
</ul>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Examples</h4>
<div>Since the subscription on the error topic needs to be done on the same MQTT connection that is also used for publishing the telemetry, event or command response messages, the Mosquitto MQTT Command Line Client cannot be used. The <a href="https://hivemq.github.io/mqtt-cli/">MQTT CLI</a> tool with its <a href="https://hivemq.github.io/mqtt-cli/docs/shell.html">shell mode</a> is an alternative that supports using one MQTT connection for both subscribing and publishing.</div>
</div>
-
<h3 id="receiving-error-messages-authenticated-device">Receiving Error Messages (authenticated Device)</h3>
-
<p>An authenticated device MUST use the following topic filter for subscribing to error messages:</p>
-
<p><code>error/[${tenant-id}]/[${device-id}]/#</code></p>
-
<p>Both the tenant and the device ID are optional. If specified, they MUST match the authenticated device’s tenant and/or device ID.
Note that the <em>authentication identifier</em> used in the device’s credentials is <em>not</em> necessarily the same as the device ID.</p>
-
<p>The protocol adapter will publish error messages for the device to the following topic name</p>
-
<p><code>error/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status}</code></p>
-
<p>The <em>tenant-id</em> and/or <em>device-id</em> will be included in the topic name if the tenant and/or device ID had been included
in the topic filter used for subscribing to error messages.</p>
-
<p><strong>Example</strong></p>
-
<p>An example using the <a href="https://hivemq.github.io/mqtt-cli/">MQTT CLI</a> that will produce an error output provided there is no downstream consumer for the device messages.</p>
-
-<pre><code class="language-sh">mqtt shell
-con -V 3 -h [MQTT_ADAPTER_IP] -u [DEVICE]@[TENANT] -pw [PWD]
-sub -t error///# --qos 0 --outputToConsole
-pub -t telemetry -m '{"temp": 5}' --qos 1
-</code></pre>
-
-<p>Using an explicit correlation id:</p>
-
-<pre><code class="language-sh">pub -t telemetry/?correlation-id=123 -m '{"temp": 5}' --qos 1
-</code></pre>
-
-<h3 id="receiving-error-messages-unauthenticated-device">Receiving Error Messages (unauthenticated Device)</h3>
-
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">mqtt shell
+con -V <span style="color:#ae81ff">3</span> -h <span style="color:#f92672">[</span>MQTT_ADAPTER_IP<span style="color:#f92672">]</span> -u <span style="color:#f92672">[</span>DEVICE<span style="color:#f92672">]</span>@<span style="color:#f92672">[</span>TENANT<span style="color:#f92672">]</span> -pw <span style="color:#f92672">[</span>PWD<span style="color:#f92672">]</span>
+sub -t error///# --qos <span style="color:#ae81ff">0</span> --outputToConsole
+pub -t telemetry -m <span style="color:#e6db74">'{"temp": 5}'</span> --qos <span style="color:#ae81ff">1</span>
+</code></pre></div><p>Using an explicit correlation id:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">pub -t telemetry/?correlation-id<span style="color:#f92672">=</span><span style="color:#ae81ff">123</span> -m <span style="color:#e6db74">'{"temp": 5}'</span> --qos <span style="color:#ae81ff">1</span>
+</code></pre></div><h3 id="receiving-error-messages-unauthenticated-device">Receiving Error Messages (unauthenticated Device)</h3>
<p>An unauthenticated device MUST use the following topic filter for subscribing to error messages:</p>
-
<p><code>error/${tenant-id}/${device-id}/#</code></p>
-
<p>The protocol adapter will publish error messages for the device to the following topic name</p>
-
<p><code>error/${tenant-id}/${device-id}/${endpoint-type}/${correlation-id}/${error-status}</code></p>
-
<h3 id="receiving-error-messages-authenticated-gateway">Receiving Error Messages (authenticated Gateway)</h3>
-
<p>An authenticated gateway MUST use one of the following topic filters for subscribing to error messages:</p>
-
<table>
<thead>
<tr>
-<th align="left">Topic Filter</th>
-<th align="left">Description</th>
+<th style="text-align:left">Topic Filter</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><code>error//+/#</code><br/><code>error/${tenant-id}/+/#</code></td>
-<td align="left">Subscribe to error messages for all devices that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>error//+/#</code><br/><code>error/${tenant-id}/+/#</code></td>
+<td style="text-align:left">Subscribe to error messages for all devices that the gateway is authorized to act on behalf of.</td>
</tr>
-
<tr>
-<td align="left"><code>error//${device-id}/#</code><br/><code>error/${tenant-id}/${device-id}/#</code></td>
-<td align="left">Subscribe to error messages for a specific device that the gateway is authorized to act on behalf of.</td>
+<td style="text-align:left"><code>error//${device-id}/#</code><br/><code>error/${tenant-id}/${device-id}/#</code></td>
+<td style="text-align:left">Subscribe to error messages for a specific device that the gateway is authorized to act on behalf of.</td>
</tr>
</tbody>
</table>
-
<p>The protocol adapter will publish error messages for the device to the following topic name</p>
-
<p><code>error/[${tenant-id}]/[${device-id}]/${endpoint-type}/${correlation-id}/${error-status}</code></p>
-
<p>The <em>tenant-id</em> and/or <em>device-id</em> will be included in the topic name if the tenant and/or device ID had been included
in the topic filter used for subscribing to error messages.</p>
-
<h3 id="error-message-payload">Error Message Payload</h3>
-
<p>The MQTT adapter publishes error messages with a UTF-8 encoded JSON payload containing the following fields:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="center">Mandatory</th>
-<th align="left">JSON Type</th>
-<th align="left">Description</th>
+<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 align="left"><em>code</em></td>
-<td align="center"><em>yes</em></td>
-<td align="left"><em>number</em></td>
-<td align="left">The HTTP error status code. See the table below for possible values.</td>
+<td style="text-align:left"><em>code</em></td>
+<td style="text-align:center"><em>yes</em></td>
+<td style="text-align:left"><em>number</em></td>
+<td style="text-align:left">The HTTP error status code. See the table below for possible values.</td>
</tr>
-
<tr>
-<td align="left"><em>message</em></td>
-<td align="center"><em>yes</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The error detail message.</td>
+<td style="text-align:left"><em>message</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 error detail message.</td>
</tr>
-
<tr>
-<td align="left"><em>timestamp</em></td>
-<td align="center"><em>yes</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The date and time the error message was published by the MQTT adapter. The value is 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>
+<td style="text-align:left"><em>timestamp</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 date and time the error message was published by the MQTT adapter. The value is 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>
-
<tr>
-<td align="left"><em>correlation-id</em></td>
-<td align="center"><em>yes</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier that may be used to correlate the error message with the device message that caused the error. The identifier is either the value of a <em>correlation-id</em> property bag value contained in the device message topic, or the identifier is the <em>packet-id</em> of the device message if it was sent with QoS 1. Otherwise a value of <code>-1</code> is used.</td>
+<td style="text-align:left"><em>correlation-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 identifier that may be used to correlate the error message with the device message that caused the error. The identifier is either the value of a <em>correlation-id</em> property bag value contained in the device message topic, or the identifier is the <em>packet-id</em> of the device message if it was sent with QoS 1. Otherwise a value of <code>-1</code> is used.</td>
</tr>
</tbody>
</table>
-
<p>The error message’s <em>code</em> field may contain the following HTTP status codes:</p>
-
<table>
<thead>
<tr>
-<th align="left">Code</th>
-<th align="left">Description</th>
+<th style="text-align:left">Code</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>400</em></td>
-<td align="left">Bad Request, the request cannot be processed. A possible reason for this is an invalid <em>PUBLISH</em> topic.</td>
+<td style="text-align:left"><em>400</em></td>
+<td style="text-align:left">Bad Request, the request cannot be processed. A possible reason for this is an invalid <em>PUBLISH</em> topic.</td>
</tr>
-
<tr>
-<td align="left"><em>403</em></td>
-<td align="left">Forbidden, the device’s registration status cannot be asserted.</td>
+<td style="text-align:left"><em>403</em></td>
+<td style="text-align:left">Forbidden, the device’s registration status cannot be asserted.</td>
</tr>
-
<tr>
-<td align="left"><em>404</em></td>
-<td align="left">Not Found, the device is disabled or does not exist.</td>
+<td style="text-align:left"><em>404</em></td>
+<td style="text-align:left">Not Found, the device is disabled or does not exist.</td>
</tr>
-
<tr>
-<td align="left"><em>413</em></td>
-<td align="left">Request Entity Too Large, the request body exceeds the maximum supported size.</td>
+<td style="text-align:left"><em>413</em></td>
+<td style="text-align:left">Request Entity Too Large, the request body exceeds the maximum supported size.</td>
</tr>
-
<tr>
-<td align="left"><em>429</em></td>
-<td align="left">Too Many Requests, the tenant’s message limit for the current period is exceeded.</td>
+<td style="text-align:left"><em>429</em></td>
+<td style="text-align:left">Too Many Requests, the tenant’s message limit for the current period is exceeded.</td>
</tr>
-
<tr>
-<td align="left"><em>503</em></td>
-<td align="left">Service Unavailable, the request cannot be processed. Possible reasons for this include:<ul><li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). </li><li>If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be: <ul><li>The consumer has indicated that it didn’t process the telemetry data.</li> <li>The consumer failed to indicate in time whether it has processed the telemetry data.</li></ul></li></ul></td>
+<td style="text-align:left"><em>503</em></td>
+<td style="text-align:left">Service Unavailable, the request cannot be processed. Possible reasons for this include:<ul><li>There is no consumer of telemetry data for the given tenant connected to Hono, or the consumer has not indicated that it may receive further messages (not giving credits). </li><li>If the QoS level header is set to <code>1</code> (<em>at least once</em> semantics), the reason may be: <ul><li>The consumer has indicated that it didn’t process the telemetry data.</li> <li>The consumer failed to indicate in time whether it has processed the telemetry data.</li></ul></li></ul></td>
</tr>
</tbody>
</table>
-
<p>Example payload:</p>
-
-<pre><code class="language-json">{
-"code": 400,
-"message": "malformed topic name",
-"timestamp": "2020-12-24T19:00:00+0100",
-"correlation-id": "5"
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
+<span style="color:#f92672">"code"</span>: <span style="color:#ae81ff">400</span>,
+<span style="color:#f92672">"message"</span>: <span style="color:#e6db74">"malformed topic name"</span>,
+<span style="color:#f92672">"timestamp"</span>: <span style="color:#e6db74">"2020-12-24T19:00:00+0100"</span>,
+<span style="color:#f92672">"correlation-id"</span>: <span style="color:#e6db74">"5"</span>
}
-</code></pre>
-
-<h2 id="error-handling">Error Handling</h2>
-
+</code></pre></div><h2 id="error-handling">Error Handling</h2>
<p>When a device publishes a telemetry, event or command response message and there is an error processing the message, the handling of the error depends on whether there is a <a href="#error-reporting-via-error-topic">error topic subscription</a> for the device and whether a <em>on-error</em> property bag parameter was set on the topic used for sending the message.</p>
-
<p>If no error subscription is in place and no <em>on-error</em> parameter was set, the default error handling behaviour is to close the MQTT connection to the device.
If the device has a subscription on the error topic (on the same MQTT connection the device uses for sending messages), the default behaviour is to keep the
MQTT connection open unless a terminal error happens. The errors that are classified as terminal are listed below.</p>
-
<ul>
<li>The adapter is disabled for the tenant that the client belongs to.</li>
<li>The authenticated device or gateway is disabled or not registered.</li>
<li>The tenant is disabled or does not exist.</li>
</ul>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Note</h4>
<div>When a terminal error occurs, the connection will always be closed irrespective of any <em>on-error</em> parameter or error subscription.</div>
</div>
-
<p>The following table lists the different behaviours based on the value of the <em>on-error</em> property bag parameter and the existence of an error subscription:</p>
-
<table>
<thead>
<tr>
-<th align="left"><em>on-error</em> topic parameter</th>
-<th align="left">Error subscription exists</th>
-<th align="left">Description</th>
+<th style="text-align:left"><em>on-error</em> topic parameter</th>
+<th style="text-align:left">Error subscription exists</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>default</em> or value not set</td>
-<td align="left">no</td>
-<td align="left">The connection to the device will get closed (like with the <em>disconnect</em> option).</td>
+<td style="text-align:left"><em>default</em> or value not set</td>
+<td style="text-align:left">no</td>
+<td style="text-align:left">The connection to the device will get closed (like with the <em>disconnect</em> option).</td>
</tr>
-
<tr>
-<td align="left"><em>disconnect</em></td>
-<td align="left">no</td>
-<td align="left">The connection to the device will get closed.</td>
+<td style="text-align:left"><em>disconnect</em></td>
+<td style="text-align:left">no</td>
+<td style="text-align:left">The connection to the device will get closed.</td>
</tr>
-
<tr>
-<td align="left"><em>ignore</em></td>
-<td align="left">no</td>
-<td align="left">The error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent.</td>
+<td style="text-align:left"><em>ignore</em></td>
+<td style="text-align:left">no</td>
+<td style="text-align:left">The error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent.</td>
</tr>
-
<tr>
-<td align="left"><em>skip-ack</em></td>
-<td align="left">no</td>
-<td align="left">The error will be ignored and no <em>PUBACK</em> for the message that caused the error will get sent.</td>
+<td style="text-align:left"><em>skip-ack</em></td>
+<td style="text-align:left">no</td>
+<td style="text-align:left">The error will be ignored and no <em>PUBACK</em> for the message that caused the error will get sent.</td>
</tr>
-
<tr>
-<td align="left"><em>default</em> or value not set</td>
-<td align="left">yes</td>
-<td align="left">After having sent an error message on the error topic, the error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent (like with the <em>ignore</em> option).</td>
+<td style="text-align:left"><em>default</em> or value not set</td>
+<td style="text-align:left">yes</td>
+<td style="text-align:left">After having sent an error message on the error topic, the error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent (like with the <em>ignore</em> option).</td>
</tr>
-
<tr>
-<td align="left"><em>disconnect</em></td>
-<td align="left">yes</td>
-<td align="left">After having sent an error message on the error topic, the connection to the device will get closed.</td>
+<td style="text-align:left"><em>disconnect</em></td>
+<td style="text-align:left">yes</td>
+<td style="text-align:left">After having sent an error message on the error topic, the connection to the device will get closed.</td>
</tr>
-
<tr>
-<td align="left"><em>ignore</em></td>
-<td align="left">yes</td>
-<td align="left">After having sent an error message on the error topic, the error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent.</td>
+<td style="text-align:left"><em>ignore</em></td>
+<td style="text-align:left">yes</td>
+<td style="text-align:left">After having sent an error message on the error topic, the error will be ignored and a <em>PUBACK</em> for the message that caused the error will get sent.</td>
</tr>
-
<tr>
-<td align="left"><em>skip-ack</em></td>
-<td align="left">yes</td>
-<td align="left">After having sent an error message on the error topic, the error will be ignored and no <em>PUBACK</em> for the message that caused the error will get sent.</td>
+<td style="text-align:left"><em>skip-ack</em></td>
+<td style="text-align:left">yes</td>
+<td style="text-align:left">After having sent an error message on the error topic, the error will be ignored and no <em>PUBACK</em> for the message that caused the error will get sent.</td>
</tr>
</tbody>
</table>
-
<p><strong>Example</strong></p>
-
<p>An authenticated device wanting to have errors always be ignored can for example publish telemetry messages on this topic:</p>
-
<p><code>telemetry/?on-error=ignore</code></p>
-
<h2 id="custom-message-mapping">Custom Message Mapping</h2>
-
<p>This protocol adapter supports transformation of messages that have been uploaded by devices before they get forwarded to downstream consumers.</p>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Experimental</h4>
<div>This is an experimental feature. The names of the configuration properties, potential values and the overall functionality are therefore
subject to change without prior notice.</div>
</div>
-
<p>This feature is useful in scenarios where devices are connected to the adapter via a gateway but the gateway is not able to include
the device ID in the topic that the gateway publishes data to. The gateway will use the plain <code>telemetry</code> or <code>event</code> topics in this case.
The message payload will usually contain the identifier of the device that the data originates from.</p>
-
<p>The same functionality can also be used to transform the payload of messages uploaded by a device. This can be used for example to
transform binary encoded data into a JSON document which can be consumed more easily by downstream consumers.</p>
-
<p>The mechanism works as follows:</p>
-
<ol>
-<li>A client uploads a message to the MQTT adapter.</li>
-<li>The adapter invokes the Device Registration service’s <em>assert Registration</em> operation using either
+<li>
+<p>A client uploads a message to the MQTT adapter.</p>
+</li>
+<li>
+<p>The adapter invokes the Device Registration service’s <em>assert Registration</em> operation using either
the authenticated device’s identifier, if the topic does not contain a device ID, or the device ID from the
-topic.</li>
-<li>If the assertion succeeds, the adapter creates the downstream message using the original message’s payload and
-the asserted device ID as the origin device.</li>
-
-<li><p>If the <em>assert Registration</em> response payload contains a value for the <em>mapper</em> property, the adapter tries to
+topic.</p>
+</li>
+<li>
+<p>If the assertion succeeds, the adapter creates the downstream message using the original message’s payload and
+the asserted device ID as the origin device.</p>
+</li>
+<li>
+<p>If the <em>assert Registration</em> response payload contains a value for the <em>mapper</em> property, the adapter tries to
find a <em>mapper endpoint</em> configuration for the given value. If a mapper endpoint with a matching name has been
configured for the adapter,</p>
-
<ol>
<li>the adapter sends an HTTP request to the endpoint which contains the original message’s payload in the request body.</li>
<li>If the response body is not empty, it is used as the downstream message’s payload, replacing the original payload.</li>
<li>If the response contains a <em>device_id</em> header and its value is different from the original device ID, then the adapter
invokes the <em>assert Registration</em> operation again, this time using the mapped device ID instead of the original device ID.
If the assertion succeeds, the adapter uses the asserted (mapped) device ID for the downstream message.</li>
-</ol></li>
-
-<li><p>The adapter forwards the downstream message.</p></li>
</ol>
-
+</li>
+<li>
+<p>The adapter forwards the downstream message.</p>
+</li>
+</ol>
<p>Please refer to the <a href="/hono/docs/dev/api/management/#/devices/createDeviceRegistration">Device Registry Management API</a>
for how to register a <em>mapper</em> for a device.
Please refer to the <a href="/hono/docs/dev/admin-guide/mqtt-adapter-config/#custom-message-mapping">MQTT Adapter Admin Guide</a>
for how to configure custom mapper endpoints.</p>
-
<h2 id="downstream-meta-data">Downstream Meta Data</h2>
-
<p>The adapter includes the following meta data in messages being sent downstream:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Location</th>
-<th align="left">Type</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Location</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>device_id</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">The identifier of the device that the message originates from.</td>
+<td style="text-align:left"><em>device_id</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">The identifier of the device that the message originates from.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_adapter</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The MQTT adapter’s type name is <code>hono-mqtt</code>.</td>
+<td style="text-align:left"><em>orig_adapter</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the adapter’s <em>type name</em> which can be used by downstream consumers to determine the protocol adapter that the message has been received over. The MQTT adapter’s type name is <code>hono-mqtt</code>.</td>
</tr>
-
<tr>
-<td align="left"><em>orig_address</em></td>
-<td align="left"><em>application</em></td>
-<td align="left"><em>string</em></td>
-<td align="left">Contains the name of the MQTT topic that the device has originally published the data to.</td>
+<td style="text-align:left"><em>orig_address</em></td>
+<td style="text-align:left"><em>application</em></td>
+<td style="text-align:left"><em>string</em></td>
+<td style="text-align:left">Contains the name of the MQTT topic that the device has originally published the data to.</td>
</tr>
-
<tr>
-<td align="left"><em>x-opt-retain</em></td>
-<td align="left"><em>message-annotations</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left">Contains <code>true</code> if the device has published an event or telemetry message with its <em>retain</em> flag set to <code>1</code></td>
+<td style="text-align:left"><em>x-opt-retain</em></td>
+<td style="text-align:left"><em>message-annotations</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left">Contains <code>true</code> if the device has published an event or telemetry message with its <em>retain</em> flag set to <code>1</code></td>
</tr>
</tbody>
</table>
-
<p>The adapter also considers <em>defaults</em> registered for the device at either the <a href="/hono/docs/dev/api/tenant/#tenant-information-format">tenant</a>
or the <a href="/hono/docs/dev/api/device-registration/#assert-device-registration">device level</a>.
The values of the default properties are determined as follows:</p>
-
<ol>
<li>If the message already contains a non-empty property of the same name, the value if unchanged.</li>
<li>Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.</li>
<li>Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.</li>
</ol>
-
<p>Note that of the standard AMQP 1.0 message properties only the <em>content-type</em> and <em>ttl</em> can be set this way to a default value.</p>
-
<h3 id="event-message-time-to-live">Event Message Time-to-live</h3>
-
<p>Events published by devices will usually be persisted by the AMQP Messaging Network in order to support deferred delivery to downstream consumers.
In most cases the AMQP Messaging Network can be configured with a maximum <em>time-to-live</em> to apply to the events so that the events will be removed
from the persistent store if no consumer has attached to receive the event before the message expires.</p>
-
<p>In order to support environments where the AMQP Messaging Network cannot be configured accordingly, the MQTT protocol adapter supports setting a
downstream event message’s <em>ttl</em> property based on the <em>hono-ttl</em> property set as <em>property-bag</em> at the end of the event topic.
-Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the <a href="/hono/docs/dev/api/tenant/#resource-limits-configuration-format">Tenant API</a>.</p>
-
+Also the default <em>ttl</em> and <em>max-ttl</em> values can be configured for a tenant/device as described in the [Tenant API]
+(/hono/docs/dev/api/tenant/#resource-limits-configuration-format).</p>
<h2 id="tenant-specific-configuration">Tenant specific Configuration</h2>
-
<p>The adapter uses the <a href="/hono/docs/dev/api/tenant/#get-tenant-information">Tenant API</a> to retrieve <em>tenant specific configuration</em> for adapter type <code>hono-mqtt</code>.
The following properties are (currently) supported in the <em>Adapter</em> object:</p>
-
<table>
<thead>
<tr>
-<th align="left">Name</th>
-<th align="left">Type</th>
-<th align="left">Default Value</th>
-<th align="left">Description</th>
+<th style="text-align:left">Name</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Default Value</th>
+<th style="text-align:left">Description</th>
</tr>
</thead>
-
<tbody>
<tr>
-<td align="left"><em>enabled</em></td>
-<td align="left"><em>boolean</em></td>
-<td align="left"><code>true</code></td>
-<td align="left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
+<td style="text-align:left"><em>enabled</em></td>
+<td style="text-align:left"><em>boolean</em></td>
+<td style="text-align:left"><code>true</code></td>
+<td style="text-align:left">If set to <code>false</code> the adapter will reject all data from devices belonging to the tenant.</td>
</tr>
</tbody>
</table>
@@ -4125,19 +3884,19 @@
<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?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757973"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757973"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757973"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757973"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757973"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844324"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844324"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844324"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844324"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757973"></script>
- <script src="/hono/docs/js/learn.js?1617757973"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757973"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844324"></script>
+ <script src="/hono/docs/js/learn.js?1617844324"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844324"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757973" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757973"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844324" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844324"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
diff --git a/docs/dev/user-guide/sigfox-adapter/index.html b/docs/dev/user-guide/sigfox-adapter/index.html
index 57b7a65..61d2569 100644
--- a/docs/dev/user-guide/sigfox-adapter/index.html
+++ b/docs/dev/user-guide/sigfox-adapter/index.html
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="Hugo 0.58.3" />
+ <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">
@@ -21,21 +21,21 @@
<title>Sigfox Adapter :: Eclipse Hono™ Vers.: dev</title>
- <link href="/hono/docs/css/nucleus.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/fontawesome-all.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hybrid.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/featherlight.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/perfect-scrollbar.min.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/auto-complete.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/theme.css?1617757973" rel="stylesheet">
- <link href="/hono/docs/css/hugo-theme.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/nucleus.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/fontawesome-all.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hybrid.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/featherlight.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/perfect-scrollbar.min.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/auto-complete.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/atom-one-dark-reasonable.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/theme.css?1617844323" rel="stylesheet">
+ <link href="/hono/docs/css/hugo-theme.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/theme-hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/theme-hono.css?1617844323" rel="stylesheet">
- <link href="/hono/docs/css/hono.css?1617757973" rel="stylesheet">
+ <link href="/hono/docs/css/hono.css?1617844323" rel="stylesheet">
- <script src="/hono/docs/js/jquery-3.3.1.min.js?1617757973"></script>
+ <script src="/hono/docs/js/jquery-3.3.1.min.js?1617844323"></script>
<style>
:root #header + #content > #left > #rlblock_left{
@@ -83,14 +83,14 @@
<span data-search-clear=""><i class="fas fa-times"></i></span>
</div>
-<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617757973"></script>
-<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/lunr.min.js?1617844323"></script>
+<script type="text/javascript" src="/hono/docs/js/auto-complete.js?1617844323"></script>
<script type="text/javascript">
var baseurl = "https:\/\/www.eclipse.org\/hono\/docs\/\/dev";
</script>
-<script type="text/javascript" src="/hono/docs/js/search.js?1617757973"></script>
+<script type="text/javascript" src="/hono/docs/js/search.js?1617844323"></script>
</div>
@@ -1624,7 +1624,37 @@
- <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/sigfox-adapter/">stable (1.6)</option>
+ <option id="stable" value="https://www.eclipse.org/hono/docs/user-guide/sigfox-adapter/">stable (1.7)</option>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <option id="1.7" value="https://www.eclipse.org/hono/docs/1.7/user-guide/sigfox-adapter/">1.7</option>
@@ -1650,6 +1680,8 @@
+
+
<option id="1.6" value="https://www.eclipse.org/hono/docs/1.6/user-guide/sigfox-adapter/">1.6</option>
@@ -1678,6 +1710,8 @@
+
+
<option id="1.5" value="https://www.eclipse.org/hono/docs/1.5/user-guide/sigfox-adapter/">1.5</option>
@@ -1706,6 +1740,8 @@
+
+
<option id="1.4" value="https://www.eclipse.org/hono/docs/1.4/user-guide/sigfox-adapter/">1.4</option>
@@ -1734,6 +1770,8 @@
+
+
<option id="1.3" value="https://www.eclipse.org/hono/docs/1.3/user-guide/sigfox-adapter/">1.3</option>
@@ -1762,6 +1800,8 @@
+
+
<option id="1.2" value="https://www.eclipse.org/hono/docs/1.2/user-guide/sigfox-adapter/">1.2</option>
@@ -1790,6 +1830,8 @@
+
+
<option id="1.1" value="https://www.eclipse.org/hono/docs/1.1/user-guide/sigfox-adapter/">1.1</option>
@@ -1818,6 +1860,8 @@
+
+
<option id="1.0" value="https://www.eclipse.org/hono/docs/1.0/user-guide/sigfox-adapter/">1.0</option>
@@ -1846,6 +1890,8 @@
+
+
<option id="dev" value="https://www.eclipse.org/hono/docs/dev/user-guide/sigfox-adapter/" selected>dev</option>
@@ -1964,22 +2010,20 @@
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
-<ul>
-<li>
-<ul>
-<li><a href="#pre-requisites">Pre-requisites</a></li>
-<li><a href="#devices-and-credentials">Devices and credentials</a></li>
-<li><a href="#setup-example">Setup example</a>
-<ul>
-<li><a href="#registering-devices">Registering devices</a></li>
-<li><a href="#setting-up-callbacks">Setting up callbacks</a></li>
-<li><a href="#enabling-command-control">Enabling command & control</a></li>
-</ul></li>
-<li><a href="#events">Events</a></li>
-<li><a href="#consuming-data">Consuming data</a></li>
-<li><a href="#known-bugs-and-limitations">Known bugs and limitations</a></li>
-</ul></li>
-</ul>
+ <ul>
+ <li><a href="#pre-requisites">Pre-requisites</a></li>
+ <li><a href="#devices-and-credentials">Devices and credentials</a></li>
+ <li><a href="#setup-example">Setup example</a>
+ <ul>
+ <li><a href="#registering-devices">Registering devices</a></li>
+ <li><a href="#setting-up-callbacks">Setting up callbacks</a></li>
+ <li><a href="#enabling-command--control">Enabling command & control</a></li>
+ </ul>
+ </li>
+ <li><a href="#events">Events</a></li>
+ <li><a href="#consuming-data">Consuming data</a></li>
+ <li><a href="#known-bugs-and-limitations">Known bugs and limitations</a></li>
+ </ul>
</nav>
</div>
</div>
@@ -2005,90 +2049,66 @@
<p>The Sigfox protocol adapter exposes an HTTP endpoint for connecting up with
the Sigfox backend for publishing telemetry, events and use command & control.</p>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Tech preview</h4>
<div>This protocol adapter is not considered production ready. Its APIs might still
be subject to change without warning.</div>
</div>
-
<h2 id="pre-requisites">Pre-requisites</h2>
-
<p>This Sigfox adapter only connects to the Sigfox backend system
(<code>backend.sigfox.com</code>). It does not allow direct access to Sigfox devices.</p>
-
<p>So you need to set up your Sigfox devices on <code>backend.sigfox.com</code> and then
configure the callbacks connect to your installation of Hono.</p>
-
<h2 id="devices-and-credentials">Devices and credentials</h2>
-
<p>In a nutshell, the Sigfox adapter requires a single <em>device</em> identity, acting
as a gateway device. This identity will be used to connect to Hono. All devices
registered with Sigfox (the actual Sigfox devices), will be registered in Hono
to allow this first identity as their gateway device.</p>
-
<h2 id="setup-example">Setup example</h2>
-
<p>The following sub-sections walk you through an example setup.</p>
-
<h3 id="registering-devices">Registering devices</h3>
-
<p>This example assumes that the Sigfox protocol adapter is available as
<code>https://iot-sigfox-adapter.my.hono</code>.</p>
-
<p>Create a new <em>gateway device</em> with the following registration:</p>
-
-<pre><code class="language-json">{
- "device-id": "sigfox-backend"
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
+ <span style="color:#f92672">"device-id"</span>: <span style="color:#e6db74">"sigfox-backend"</span>
}
-</code></pre>
-
-<p>Create new credentials for the <em>gateway device</em>. For example, using
+</code></pre></div><p>Create new credentials for the <em>gateway device</em>. For example, using
a username of <code>sigfox</code> and a password of <code>test12</code>:</p>
-
-<pre><code class="language-json">{
- "auth-id": "sigfox",
- "device-id": "sigfox-backend",
- "enabled": true,
- "secrets": [
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
+ <span style="color:#f92672">"auth-id"</span>: <span style="color:#e6db74">"sigfox"</span>,
+ <span style="color:#f92672">"device-id"</span>: <span style="color:#e6db74">"sigfox-backend"</span>,
+ <span style="color:#f92672">"enabled"</span>: <span style="color:#66d9ef">true</span>,
+ <span style="color:#f92672">"secrets"</span>: [
{
- "pwd-plain": "test12"
+ <span style="color:#f92672">"pwd-plain"</span>: <span style="color:#e6db74">"test12"</span>
}
],
- "type": "hashed-password"
+ <span style="color:#f92672">"type"</span>: <span style="color:#e6db74">"hashed-password"</span>
}
-</code></pre>
-
-<p>Create a new <em>device</em>, referencing the previous <em>gateway device</em>. The
+</code></pre></div><p>Create a new <em>device</em>, referencing the previous <em>gateway device</em>. The
<em>device id</em> must be your Sigfox device ID (e.g. <code>1AB2C3</code>):</p>
-
-<pre><code class="language-json">{
- "device-id": "1AB2C3",
- "via": "sigfox-backend"
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-json" data-lang="json">{
+ <span style="color:#f92672">"device-id"</span>: <span style="color:#e6db74">"1AB2C3"</span>,
+ <span style="color:#f92672">"via"</span>: <span style="color:#e6db74">"sigfox-backend"</span>
}
-</code></pre>
-
-<h3 id="setting-up-callbacks">Setting up callbacks</h3>
-
+</code></pre></div><h3 id="setting-up-callbacks">Setting up callbacks</h3>
<p>Log in to the Sigfox backend at <a href="https://backend.sigfox.com">https://backend.sigfox.com</a> and then open up
the view <code>Device Type</code> -> <code>Callbacks</code>.</p>
-
<p>Create a new “Custom” callback, with the following settings
(replacing <code><TENANT></code> with the name of the tenant):</p>
-
<ul>
<li><strong>Type</strong>: <code>DATA</code> – <code>UPLINK</code></li>
<li><strong>Channel</strong>: <code>URL</code></li>
<li><strong>Url pattern</strong>: <code>https://iot-sigfox-adapter.my.hono/data/telemetry/<TENANT>?device={device}&data={data}</code></li>
<li><strong>Use HTTP Method</strong>: <code>GET</code></li>
<li><strong>Headers</strong>
-
<ul>
<li><code>Authorization</code> – <code>Basic …</code> (see note below)</li>
-</ul></li>
+</ul>
+</li>
<li><strong>Send SNI</strong>: ☑ (Enabled)</li>
</ul>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Credentials</h4>
<div><p>At the moment you need to manually put in the <code>Authorization</code> header,
@@ -2096,46 +2116,30 @@
Sigfox backend, which cannot be fixed by Hono. The backend does not
properly escape the <code>@</code> character, and thus sends <code>foo%40tenant</code>
instead of <code>foo@tenant</code> to the Hono protocol adapter.</p>
-
<p>As a workaround, you can explicitly set the <code>Authorization</code> header to a
value of <code>Basic <base64 encoded credentials></code>. You can encode the
credentials using:</p>
-
-<pre><code class="language-sh">echo -n "sigfox@tenant:password" | base64
-</code></pre>
-
-<p>To get the full value, including the <code>Basic</code> you may use:</p>
-
-<pre><code class="language-sh">echo "Basic $(echo -n "sigfox@tenant:password" | base64)"
-</code></pre>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">echo -n <span style="color:#e6db74">"sigfox@tenant:password"</span> | base64
+</code></pre></div><p>To get the full value, including the <code>Basic</code> you may use:</p>
+<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">echo <span style="color:#e6db74">"Basic </span><span style="color:#66d9ef">$(</span>echo -n <span style="color:#e6db74">"sigfox@tenant:password"</span> | base64<span style="color:#66d9ef">)</span><span style="color:#e6db74">"</span>
+</code></pre></div></div>
</div>
-</div>
-
-<h3 id="enabling-command-control">Enabling command & control</h3>
-
+<h3 id="enabling-command--control">Enabling command & control</h3>
<p>It is possible to enable command & control as well. For this you need to:</p>
-
<ul>
<li>Switch the <strong>Type</strong> of the <code>DATA</code> callback from <code>UPLINK</code> to <code>BIDIR</code></li>
<li>Add the <code>ack</code> query parameter to the <strong>Url pattern</strong>, e.g. <code>https://iot-sigfox-adapter.my.hono/data/telemetry/<TENANT>?device={device}&data={data}&ack={ack}</code></li>
</ul>
-
<div class="alert alert-notice">
<h4 class="alert-heading"><i class="fas fa-info-circle"></i> Command requirements</h4>
<div>Sigfox allows only a very specific payload in command messages. You must send
exactly 8 bytes of data. It only supports <em>one way commands</em>.</div>
</div>
-
<h2 id="events">Events</h2>
-
<p>You can send events by using the path <code>/data/event</code> on the URL.</p>
-
<h2 id="consuming-data">Consuming data</h2>
-
<p>Use the standard way of consuming Hono messages.</p>
-
<h2 id="known-bugs-and-limitations">Known bugs and limitations</h2>
-
<ul>
<li>Only the simple <code>URL</code> and only <em>data</em> (no <em>service</em> or <em>device events</em> are
currently supported.</li>
@@ -3263,19 +3267,19 @@
<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?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.min.js?1617757974"></script>
- <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617757974"></script>
- <script src="/hono/docs/js/jquery.sticky.js?1617757974"></script>
- <script src="/hono/docs/js/featherlight.min.js?1617757974"></script>
- <script src="/hono/docs/js/highlight.pack.js?1617757974"></script>
+ <script src="/hono/docs/js/clipboard.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.min.js?1617844324"></script>
+ <script src="/hono/docs/js/perfect-scrollbar.jquery.min.js?1617844324"></script>
+ <script src="/hono/docs/js/jquery.sticky.js?1617844324"></script>
+ <script src="/hono/docs/js/featherlight.min.js?1617844324"></script>
+ <script src="/hono/docs/js/highlight.pack.js?1617844324"></script>
<script>hljs.initHighlightingOnLoad();</script>
- <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617757974"></script>
- <script src="/hono/docs/js/learn.js?1617757974"></script>
- <script src="/hono/docs/js/hugo-learn.js?1617757974"></script>
+ <script src="/hono/docs/js/modernizr.custom-3.6.0.js?1617844324"></script>
+ <script src="/hono/docs/js/learn.js?1617844324"></script>
+ <script src="/hono/docs/js/hugo-learn.js?1617844324"></script>
- <link href="/hono/docs/mermaid/mermaid.css?1617757974" rel="stylesheet" />
- <script src="/hono/docs/mermaid/mermaid.js?1617757974"></script>
+ <link href="/hono/docs/mermaid/mermaid.css?1617844324" rel="stylesheet" />
+ <script src="/hono/docs/mermaid/mermaid.js?1617844324"></script>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
