| <!doctype html> |
| <html lang="en"> |
| |
| <head> |
| |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> |
| |
| <link rel="stylesheet" href="/packages/assets/bootstrap/bootstrap.min.css"> |
| |
| <title>Gateway</title> |
| |
| <link rel="stylesheet" href="/packages/assets/css/style.css"> |
| <script src="/packages/assets/js/code.js"></script> |
| |
| <meta name="twitter:card" content="summary"/> |
| <meta name="twitter:image" content="https://eclipse.org/packages/images/icon/twitter_icon.png"/> |
| <meta name="twitter:title" content="Telemetry end-to-end | Installation"/> |
| <meta name="twitter:description" content="Installations instructions for the Telemetry end-to-end package."/> |
| |
| |
| <link rel="icon" type="image/svg+xml" href="/packages/images/icon/icon.svg" sizes="any"> |
| <link rel="icon" href="/packages/images/icon/icon.png" sizes="192x192"> |
| <link rel="apple-touch-icon-precomposed" href="/packages/images/icon/icon_apple.png" sizes="180x180"> |
| |
| </head> |
| |
| <body> |
| |
| <header> |
| <nav class="navbar navbar-expand-md fixed-top navbar-light bg-light"> |
| <div class="container"> |
| <a class="navbar-brand" href="/packages/"> |
| <img src="/packages/images/icon_brand_navbar.svg" width="30" height="30" alt="Eclipse IoT Packages™"> |
| </a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="collapse navbar-collapse" id="navbarCollapse"> |
| <ul class="navbar-nav mr-auto"><li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/about/">About</a> |
| </li> |
| <li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/faq/">FAQ</a> |
| </li> |
| <li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/contribute/">Contribute</a> |
| </li> |
| <li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/prereqs/">Prerequisites</a> |
| </li> |
| <li class="nav-item"> |
| <a |
| class="nav-link" |
| href="/packages/repository/">Repository</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav></header> |
| |
| <main id="main" role="main" > |
| |
| |
| <div><div class="container mt-5"> |
| <div class="row"> |
| <div class="col-12 col-sm-9 col-xl-8"> |
| <h1>Telemetry end-to-end</h1> |
| <p class="lead">A package showing telemetry data acquisition end-to-end: Microcontroller firmware to cloud side data processing, using Drogue IoT and Apache Kafka in the process.</p></div> |
| |
| <div class="col-12 col-sm-3 col-xl-4 d-flex flex-sm-row-reverse"> |
| <img alt="Page logo" src="/packages/packages/telemetry-e2e/images/telemetry-e2e-logo.svg" class="img-fluid m-lg-3 d-block align-self-center " style="max-height: 10rem;"/> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| |
| <nav class="nav nav-pills nav-fill mt-2 mb-5"><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/">Overview</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/10-installation-cloud/">Cloud</a><a class="nav-item nav-link active" href="/packages/packages/telemetry-e2e/20-installation-gateway/">Gateway</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/30-installation-device/">Device</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/40-using/">Using it</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/50-understand/">Understanding it</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/60-alternatives/">Alternatives</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/70-cheating/">Cheating</a><a class="nav-item nav-link " href="/packages/packages/telemetry-e2e/90-learn/">Learn more</a></nav> |
| <div class="row"> |
| |
| <div class="col-12 col-md-8 col-lg-9"> |
| |
| <p>The installation of Eclipse Kura™ will require a <a href="https://www.raspberrypi.org/products/raspberry-pi-4-model-b/">Raspberry Pi 3+</a>. |
| Kura itself will run on other hardware too, and it should not be a problem to run this tutorial on an AMD64 device or |
| another 32bit or 64bit ARM device. However, the following instructions are tested with a Raspberry Pi 3+ and commands |
| maybe be different when you choose a different target.</p> |
| |
| <p>What you do require however is a device with a Linux supported Bluetooth device attached, and support for running |
| containers.</p> |
| |
| <h2 id="network--ip-addresses">Network & IP addresses</h2> |
| |
| <p>Eclipse Kura, running on the Raspberry Pi, will need to connect to the MQTT endpoint running on your Minikube |
| cluster. As this cluster is running on your local machine, inside a virtual machine, Kura cannot directly access |
| the MQTT endpoint.</p> |
| |
| <p>In order to establish a connection between Kura on the Raspberry Pi and the MQTT endpoint inside the Minikube |
| cluster VM, you will need to:</p> |
| |
| <ul> |
| <li>Connect the Raspberry Pi to a network that can reach the machine your Minikube cluster runs on</li> |
| <li>Open a port forward from your machines network interface, to the MQTT endpoint service</li> |
| <li>Open this port on your machine’s firewall</li> |
| </ul> |
| |
| <p>The port forward can easily be created using <code class="language-plaintext highlighter-rouge">kubectl</code> on the host machine running the Minikube VM:</p> |
| |
| <div class="clipboard"><pre><code>kubectl port-forward deployment/mqtt-endpoint --address 0.0.0.0 1883</code></pre></div> |
| |
| <div role="alert" class="alert alert-info"><h4 class="alert-heading">Firewall </h4> |
| |
| Assuming you have a firewall, you also need to open access to port <code>1883</code> from your local network. |
| |
| <hr /><p class="mb-0"> |
| <p> |
| On Linux, you can temporarily open a port using the following command: |
| </p> |
| |
| <div class="clipboard"><pre><code>sudo firewall-cmd --add-port=1883/tcp</code></pre></div> |
| |
| </p> |
| |
| </div> |
| |
| <h2 id="set-up-the-device">Set up the device</h2> |
| |
| <div role="alert" class="alert alert-info"><h4 class="alert-heading">Alternate installation methods </h4> |
| The following instructions are the bare minimal instructions required to set up a new Raspberry Pi when using |
| a Linux machine. If you are unsure how this works, or don't use a Linux like environment, check out the standard <a href="https://www.raspberrypi.org/software/" target="_blank" class="alert-link">installation instructions for Raspberry Pi OS</a>. |
| </div> |
| |
| <p>Download a Debian “buster” based Raspberry OS image:</p> |
| |
| <div class="clipboard"><pre><code>wget https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2021-05-28/2021-05-07-raspios-buster-armhf-lite.zip</code></pre></div> |
| |
| <p>And write it so an SD card:</p> |
| |
| <div role="alert" class="alert alert-warning"><h4 class="alert-heading">Possible data loss </h4> |
| The next command will erase the target disk or SD card. Be sure that you are specifying the correct target device you |
| want to flash the image to. Once the process of flashing has started, there is no way to undo these changes. |
| </div> |
| |
| <div class="clipboard"><pre><code># replace XXX with your SD card drive that you want to erase (e.g. sdb) |
| xzcat 2021-05-07-raspios-buster-armhf-lite.img.xz | sudo dd of=/dev/XXX bs=1M status=progress oflag=sync</code></pre></div> |
| |
| <p>Before you boot for the first time, ensure that you enable SSH:</p> |
| |
| <div class="clipboard"><pre><code>touch boot/ssh</code></pre></div> |
| |
| <p>Also, it is recommended to enable WiFi:</p> |
| |
| <ul> |
| <li> |
| <p>Create a new file</p> |
| |
| <div class="clipboard"><pre><code>vi boot/wpa_supplicant.conf</code></pre></div> |
| </li> |
| <li> |
| <p>Edit configuration</p> |
| |
| <div class="clipboard"><pre><code>country=<XX> # use your ISO 3166 country code, e.g. DE for Germany |
| ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev |
| update_config=1 |
| network={ |
| ssid="<your ssid>" |
| psk="<our password>" |
| }</code></pre></div> |
| </li> |
| </ul> |
| |
| <h2 id="boot-and-check-access">Boot and check access</h2> |
| |
| <p>Once you flashed the SD card, put it into your Raspberry Pi and ensure that you can log into the device remotely using |
| <code class="language-plaintext highlighter-rouge">ssh</code>.</p> |
| |
| <p>Also, ensure that Docker is installed. If you are missing docker, you can easily install this be executing the |
| following command:</p> |
| |
| <div class="clipboard"><pre><code>sudo apt-get install docker.io</code></pre></div> |
| |
| <div role="alert" class="alert alert-info"><h4 class="alert-heading">Accessing as non-root user </h4> |
| <p> |
| By default, most installations of docker require a "root" user to manage containers. |
| <a href="https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user" target="_blank" class="alert-link">Read here</a> |
| to learn how to grant non-root users direct access to docker. |
| </p> |
| <p>Alternatively, you can issue the following docker commands as "root", or use <code>sudo</code> to achieve the same.</p> |
| </div> |
| |
| <h2 id="install-kura">Install Kura</h2> |
| |
| <p>Kura is not installed directly on the gateway, but run inside a container. We do this, as we plan to amend the |
| tutorial in the future, using an edge orchestration solution to deploy the IoT workload. For now, we manually start |
| the container.</p> |
| |
| <h3 id="create-the-kura-container">Create the Kura container</h3> |
| |
| <p>Create and start the Kura container using:</p> |
| |
| <div class="clipboard"><pre><code>docker run -dti -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket --name kura -p 443:443 ghcr.io/ctron/kura-test:0.1.1 -console -consoleLog</code></pre></div> |
| |
| <p>It will start in the background. Should the container should get stopped, you can restart it with the following command:</p> |
| |
| <div class="clipboard"><pre><code>docker start kura</code></pre></div> |
| |
| <h3 id="login-to-the-web-console">Login to the web console</h3> |
| |
| <p>Once it is fully started, you can also connect to using your web browser:</p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>https://<host-ip> |
| </code></pre></div> </div> |
| |
| <div role="alert" class="alert alert-secondary"><h4 class="alert-heading">Self-signed certificates </h4> |
| Your browser will warn you about a self-signed certificate. That is ok in this case, as the Kura instance doesn't |
| know its hostname, it uses a self-signed certificate to offer TLS. You can replace the certificate if you prefer. |
| </div> |
| |
| <p>The default access credentials are:</p> |
| |
| <ul> |
| <li>Username: <code class="language-plaintext highlighter-rouge">admin</code></li> |
| <li>Password: <code class="language-plaintext highlighter-rouge">admin</code></li> |
| </ul> |
| |
| <div role="alert" class="alert alert-secondary"><h4 class="alert-heading">Default passwords </h4> |
| Using the Web UI, you can of course change the username and password. |
| </div> |
| |
| <h3 id="attaching-to-the-container-console">Attaching to the container console</h3> |
| |
| <p>You can also attach to the console of Kura using:</p> |
| |
| <div class="clipboard"><pre><code>docker attach --sig-proxy=false kura</code></pre></div> |
| |
| <h2 id="setup-connection">Setup connection</h2> |
| |
| <p>Kura needs to be connected to the Drogue IoT cloud instance. The configuration must be done using the Web UI. The |
| following steps will walk you through the process.</p> |
| |
| <h3 id="connecting-the-gateway">Connecting the gateway</h3> |
| |
| <ul> |
| <li> |
| <p>Navigate to [System > Cloud Connections] and then select the tab labeled “MqttDataTransport”.</p> |
| </li> |
| <li> |
| <p>Set the following fields:</p> |
| |
| <dl class="row"> |
| <dt class="col-sm-3">Broker-url</dt> |
| <dd class="col-sm-9"> |
| <p><code>mqtt://<your-host-ip>:1883</code></p> |
| The IP address is the IP the machine you are running |
| <code>kubectl port-forward</code> on. |
| </dd> |
| <dt class="col-sm-3">Username</dt> |
| <dd class="col-sm-9"><code>device-1@eclipse</code></dd> |
| <dt class="col-sm-3">Password</dt> |
| <dd class="col-sm-9"><code>device12</code></dd> |
| </dl> |
| </li> |
| <li> |
| <p>Afterwards click on <kbd>Apply</kbd> and confirm to store the settings.</p> |
| </li> |
| <li> |
| <p>Next, test the settings by manually connecting. Click on the button <kbd>Connect/Disconnect</kbd> once, and wait.</p> |
| </li> |
| <li> |
| <p>When the column status changes to “Connected” you can move on to the next step. Otherwise, check the connection settings.</p> |
| </li> |
| </ul> |
| |
| <h3 id="creating-a-cloud-publisher">Creating a cloud publisher</h3> |
| |
| <ul> |
| <li> |
| <p>Navigate to [System > Cloud Connections] and click on the button <kbd>New Pub/Sub</kbd>.</p> |
| </li> |
| <li> |
| <p>In the dialog, select <code class="language-plaintext highlighter-rouge">org.eclipse.kura.cloud.publisher.CloudPublisher</code> as a factory, and enter the new ID <code class="language-plaintext highlighter-rouge">microbit</code>.</p> |
| </li> |
| <li> |
| <p>Confirm using the <kbd>Apply</kbd> button.</p> |
| </li> |
| </ul> |
| |
| <h3 id="configuring-the-microbit-demo">Configuring the micro:bit demo</h3> |
| |
| <ul> |
| <li> |
| <p>Navigate to [Services > micro:bit] and update the following settings:</p> |
| |
| <dl class="row"> |
| <dt class="col-sm-3">CloudPublisher Target Filter</dt> |
| <dd class="col-sm-9">Select the target <code>(kura.service.pid=microbot)</code></dd> |
| |
| <dt class="col-sm-3">Enabled</dt> |
| <dd class="col-sm-9"><code>true</code></dd> |
| </dl> |
| </li> |
| <li> |
| <p>Afterwards click on <kbd>Apply</kbd> and confirm to store the settings.</p> |
| </li> |
| </ul> |
| |
| <h2 id="what-is-next">What is next?</h2> |
| |
| <p>Go to the next page and set up the micro:bit.</p> |
| |
| <h2 id="when-things-go-wrong">When things go wrong</h2> |
| |
| <h3 id="unable-to-connect-gateway-to-the-cluster">Unable to connect gateway to the cluster</h3> |
| |
| <p>If the gateway cannot connect to the cluster here are a few things to check.</p> |
| |
| <h4 id="check-if-the-connection-reaches-the-port-forward">Check if the connection reaches the port forward</h4> |
| |
| <p>If the connection reaches the port forward, you should see a corresponding message on the console:</p> |
| |
| <div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>kubectl port-forward deployment/mqtt-endpoint <span class="nt">--address</span> 0.0.0.0 1883 |
| Forwarding from 0.0.0.0:1883 -> 1883 |
| Handling connection <span class="k">for </span>1883 |
| </code></pre></div> </div> |
| |
| <p>If you don’t see <code class="language-plaintext highlighter-rouge">Handling connection for 1883</code>, this means that the gateway cannot reach port <code class="language-plaintext highlighter-rouge">1883</code> on your local |
| machine. Possible causes for this can be a firewall blocking access to the port or a wrong IP address or port number |
| in the Kura configuration.</p> |
| |
| <p>If you see the message, but see errors directly after it, this means that Kura was connecting to the correct address |
| and port, but something fails with the port forward. The error message should provide additional information.</p> |
| |
| </div> |
| |
| <div class="col-12 col-md-4 col-lg-3 |
| |
| "> |
| |
| <div class="position-sticky" style="top: 4rem;"> |
| |
| |
| <aside> |
| <div class="card"> |
| <div class="card-body"> |
| <h5 class="card-title">Table of contents</h5> |
| <div id="toc" class="toc"></div> |
| </div> |
| </div> |
| </aside> |
| |
| <script>generateToc("#toc", "h2[id], h3[id], h4[id]");</script> |
| |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| </div> |
| |
| </main> |
| |
| <footer class="page-footer"> |
| |
| <div class="container"> |
| |
| <div class="row"> |
| |
| |
| |
| |
| |
| <div class="col-6 col-md"> |
| |
| |
| <h5>Eclipse IoT Packages</h5> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a class="text-muted" href="/packages/">Home</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="/packages/about">About</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="/packages/contribute">Contribute</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://eclipse.org/security">Security</a> |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| |
| <div class="col-6 col-md"> |
| |
| |
| <h5>Eclipse IoT</h5> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a class="text-muted" href="https://iot.eclipse.org">Top Level Project</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/org/workinggroups/iotwg_charter.php">Working group</a> |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| |
| <div class="col-6 col-md"> |
| |
| |
| <h5>Legal</h5> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/legal/epl-2.0/">Eclipse Public License</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/legal">Legal Resources</a> |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| |
| <div class="col-6 col-md"> |
| |
| |
| <h5>Eclipse Foundation</h5> |
| <ul class="list-unstyled"> |
| |
| <li> |
| <a class="text-muted" href="https://eclipse.org/org">About us</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/org/foundation/contact.php">Contact us</a> |
| </li> |
| |
| <li> |
| <a class="text-muted" href="https://www.eclipse.org/org/foundation/directors.php">Board of Directors</a> |
| </li> |
| |
| </ul> |
| |
| </div> |
| |
| |
| |
| </div> |
| |
| |
| <div class="row"> |
| <div class="col-12 col-md text-muted">Copyright © Eclipse Foundation, Inc. All Rights Reserved.</div> |
| </div> |
| |
| |
| </div> |
| |
| </footer> |
| |
| |
| <script src="/packages/assets/popper.min.js"></script> |
| <script src="/packages/assets/jquery.min.js"></script> |
| <script src="/packages/assets/bootstrap/bootstrap.min.js"></script> |
| |
| <script src="/packages/assets/clipboard.min.js"></script> |
| <script src="/packages/assets/clipboard.js"></script> |
| |
| </body> |
| |
| </html> |
