| |
| <!DOCTYPE HTML> |
| <html lang="" > |
| <head> |
| <meta charset="UTF-8"> |
| <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> |
| <title>Simulator · Eclipse Kapua™ User Guide</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge" /> |
| <meta name="description" content=""> |
| <meta name="generator" content="GitBook 3.2.2"> |
| |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/style.css"> |
| |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css"> |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css"> |
| |
| |
| |
| <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <meta name="HandheldFriendly" content="true"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> |
| <meta name="apple-mobile-web-app-capable" content="yes"> |
| <meta name="apple-mobile-web-app-status-bar-style" content="black"> |
| <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png"> |
| <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon"> |
| |
| |
| <link rel="next" href="jwt_security.html" /> |
| |
| |
| <link rel="prev" href="community.html" /> |
| |
| |
| </head> |
| <body> |
| |
| <div class="book"> |
| <div class="book-summary"> |
| |
| |
| <div id="book-search-input" role="search"> |
| <input type="text" placeholder="Type to search" /> |
| </div> |
| |
| |
| <nav role="navigation"> |
| |
| |
| |
| <ul class="summary"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="chapter " data-level="1.1" data-path="./"> |
| |
| <a href="./"> |
| |
| |
| Introduction |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.2" data-path="rest.html"> |
| |
| <a href="rest.html"> |
| |
| |
| REST API |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.3" data-path="community.html"> |
| |
| <a href="community.html"> |
| |
| |
| Community |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter active" data-level="1.4" data-path="simulator.html"> |
| |
| <a href="simulator.html"> |
| |
| |
| Simulator |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.5" data-path="jwt_security.html"> |
| |
| <a href="jwt_security.html"> |
| |
| |
| Setup JWT security |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.6" data-path="Permissions.html"> |
| |
| <a href="Permissions.html"> |
| |
| |
| Kapua Permissions |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.7" data-path="mfa.html"> |
| |
| <a href="mfa.html"> |
| |
| |
| Multi Factor Authentication |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| <li class="chapter " data-level="1.8" data-path="credentials.html"> |
| |
| <a href="credentials.html"> |
| |
| |
| Credentials |
| |
| </a> |
| |
| |
| |
| </li> |
| |
| |
| |
| |
| <li class="divider"></li> |
| |
| <li> |
| <a href="https://www.gitbook.com" target="blank" class="gitbook-link"> |
| Published with GitBook |
| </a> |
| </li> |
| </ul> |
| |
| |
| </nav> |
| |
| |
| </div> |
| |
| <div class="book-body"> |
| |
| <div class="body-inner"> |
| |
| |
| |
| <div class="book-header" role="navigation"> |
| |
| |
| <!-- Title --> |
| <h1> |
| <i class="fa fa-circle-o-notch fa-spin"></i> |
| <a href="." >Simulator</a> |
| </h1> |
| </div> |
| |
| |
| |
| |
| <div class="page-wrapper" tabindex="-1" role="main"> |
| <div class="page-inner"> |
| |
| <div id="book-search-results"> |
| <div class="search-noresults"> |
| |
| <section class="normal markdown-section"> |
| |
| <h1 id="simulator">Simulator</h1> |
| <p>The Kura simulator is a simulator framework which can act as a Kura gateway instance, without the necessary |
| OSGi runtime and the required hardware abstractions. It can be used to create gateway simulations, testing |
| Kapua.</p> |
| <p>The following sections assume that you are located in the project folder <code>simulator-kura</code> and using a |
| bash-like shell running on Linux. While other environments are possible, some commands might need adaption |
| for this.</p> |
| <h2 id="starting">Starting</h2> |
| <p>The default main class is <code>org.eclipse.kapua.kura.simulator.main.SimulatorRunner</code>. It can be run after |
| the module was built by executing e.g. (which will print out some basic help):</p> |
| <pre><code>java -jar target/kapua-simulator-kura-*-app.jar -? |
| </code></pre><p>Once properly started the simulator will keep running (other forever or until the specified time elapsed) |
| and then exit. While it is running it will try to stay connected to the broker. For more details about the |
| behavior of the simulator see: <a href="#behavior-of-the-simulator">Behavior of the simulator</a>.</p> |
| <h2 id="controlling-the-simulator">Controlling the simulator</h2> |
| <p>The application's behavior can be configured either by using command line arguments or by setting |
| environment variables (not Java system properties).</p> |
| <p>Environment variables will take precedence over command line arguments.</p> |
| <h3 id="simulator-options">Simulator options</h3> |
| <p>The following options are supported:</p> |
| <dl> |
| |
| <dt> |
| <code>-?</code>, |
| <code>--help</code> |
| </dt> |
| <dd> |
| Show help and exit |
| </dd> |
| |
| <dt> |
| <code>-a</code>, |
| <code>--account-name</code>, |
| <code>KSIM_ACCOUNT_NAME</code> |
| <NAME> |
| </dt> |
| <dd> |
| Set the Kapua account name, defaults to <code>kapua-sys</code> |
| </dd> |
| |
| <dt> |
| <code>-c</code>, |
| <code>--count</code>, |
| <code>KSIM_NUM_GATEWAYS</code> |
| <COUNT> |
| </dt> |
| <dd> |
| The number of instances to simulate, defaults to <code>1</code> |
| </dd> |
| |
| <dt> |
| <code>-n</code>, |
| <code>--base-name</code>, |
| <code>KSIM_BASE_NAME</code> |
| <PREFIXS> |
| </dt> |
| <dd> |
| The prefix used to construct the simulator id when using the <code>default</code> name factory, defaults to <code>sim-</code> |
| </dd> |
| |
| |
| <dt> |
| <code>--name-factory</code>, |
| <code>KSIM_NAME_FACTORY</code> |
| <NAME> |
| </dt> |
| <dd> |
| The name factory to use for creating simulator names based on the instance number. |
| Also see <a href="#name-factories">Name Factories</a> below. |
| </dd> |
| |
| <dt> |
| <code>-s</code>, |
| <code>--seconds</code> |
| <SECONDS> |
| </dt> |
| <dd> |
| The number of seconds after which the simulator will exit. The default is to keep running. |
| </dd> |
| |
| </dl> |
| |
| <h3 id="logging-options">Logging Options</h3> |
| <p>Only one of the following options may be active:</p> |
| <dl> |
| |
| <dt> |
| <code>-q</code>, |
| <code>--quiet</code> |
| </dt> |
| <dd> |
| Suppress output |
| </dd> |
| |
| <dt> |
| <code>-v</code>, |
| <code>--verbose</code> |
| </dt> |
| <dd> |
| Show more details |
| </dd> |
| |
| <dt> |
| <code>-d</code>, |
| <code>--debug</code> |
| </dt> |
| <dd> |
| Enable debug output |
| </dd> |
| |
| </dl> |
| |
| <h3 id="broker-connection-options">Broker connection options</h3> |
| <p>The connection to the broker requires a URL. It is possible to either specify the full URL or specify only |
| parts and let the simulator create the final URL. Both ways are mutually exclusive. </p> |
| <p>For specifying the full URL use the following option:</p> |
| <dl> |
| |
| <dt> |
| <code>-b</code>, |
| <code>--broker</code>, |
| <code>KSIM_BROKER_URL</code> |
| </dt> |
| <dd> |
| The full URL to the broker |
| </dd> |
| |
| </dl> |
| |
| <p>If the full URI is not specified then the simulator will create one based on the following |
| pattern: <code><schema>://<user>:<password>@<host>:<port></code> using the following options or |
| their defaults:</p> |
| <dl> |
| |
| |
| <dt> |
| <code>KSIM_BROKER_SCHEMA</code> |
| </dt> |
| <dd> |
| The transport schema of the broker, defaults to <code>tcp</code>. The following options are available: |
| |
| <dl> |
| <dt>tcp</dt><dd>MQTT over TCP</dd> |
| <dt>ssl</dt><dd>MQTT over TCP with TLS</dd> |
| <dt>ws</dt><dd>MQTT over WebSockets</dd> |
| <dt>wss</dt><dd>MQTT over WebSockets with TLS</dd> |
| </dl> |
| |
| <p></dd></p> |
| <p><dt> |
| <code>-h</code>, |
| <code>--broker-host</code>, |
| <code>KSIM_BROKER_HOST</code> |
| </dt></p> |
| <dd> |
| The hostname of the broker, defaults to <code>localhost</code> |
| </dd> |
| |
| <p><dt> |
| <code>KSIM_BROKER_PORT</code> |
| </dt></p> |
| <dd> |
| The port number of the broker, defaults to <code>1883</code> |
| </dd> |
| |
| <p><dt> |
| <code>KSIM_BROKER_USER</code> |
| </dt></p> |
| <dd> |
| The user name to use for the MQTT connection to the broker, defaults to <code>kapua-broker</code> |
| </dd> |
| |
| <p><dt> |
| <code>KSIM_BROKER_PASSWORD</code> |
| </dt></p> |
| <dd> |
| The password to use for the MQTT connection to the broker, defaults to <code>kapua-password</code> |
| </dd> |
| |
| <p></dl></p> |
| <p>If no broker connection options are specified this will result in a broker URL of: <code>tcp://kapua-broker:kapua-password@localhost:1883</code>.</p> |
| <h3 id="data-generation">Data generation</h3> |
| <p>The simulator runner can also provide a stream of metrics to be sent to Kapua. For this it is necessary to provide a |
| <a href="#simple-simulation-model">simple simulation model</a> which maps data generators with the actual metrics names.</p> |
| <p>The simulation configuration is read from a JSON configuration file and can be specified using a local file system path, |
| a URI from which the file can be loaded or a plain JSON content through an environment variable.</p> |
| <dl> |
| |
| <dt> |
| <code>-f</code>, |
| <code>--simulation</code>, |
| <code>KSIM_SIMULATION_URL</code> |
| </dt> |
| <dd> |
| A local file system path or a URI to the JSON configuration file of the data simulation. |
| </dd> |
| |
| <dt> |
| <code>KSIM_SIMULATION_CONFIGURATION</code> |
| </dt> |
| <dd> |
| The actual JSON content for the simulation. |
| </dd> |
| |
| </dl> |
| |
| <h3 id="name-factories">Name factories</h3> |
| <p>The following name factories are available:</p> |
| <dl> |
| |
| <dt><code>default</code></dt> |
| <dd>Use the "base name" as prefix and append the instance number</dd> |
| |
| <dt><code>host:name</code></dt> |
| <dd> |
| Use the local hostname as prefix, appending <code>-</code> and the instance number. |
| All special characters will get replaces with dashes (<code>-</code>). |
| </dd> |
| |
| <dt><code>host:addr</code></dt> |
| <dd> |
| Use the IP address of the local hostname as prefix, appending <code>-</code> and the instance number. |
| All special characters will get replaces with dashes (<code>-</code>). |
| </dd> |
| |
| <dt><code>host:iface:name</code></dt> |
| <dd> |
| Use the hostname of the main interface as prefix, appending <code>-</code> and the instance number. |
| All special characters will get replaces with dashes (<code>-</code>). |
| </dd> |
| |
| <dt><code>host:iface:index</code></dt> |
| <dd> |
| Use the index number of the main interface as prefix, appending <code>-</code> and the instance number. |
| All special characters will get replaces with dashes (<code>-</code>). |
| </dd> |
| |
| <dt><code>host:iface:mac</code></dt> |
| <dd> |
| Use the hex encoded MAC address of the main interface as prefix, appending <code>-</code> and the instance number. |
| All special characters will get replaces with dashes (<code>-</code>). |
| </dd> |
| |
| </dl> |
| |
| <h2 id="behavior-of-the-simulator">Behavior of the simulator</h2> |
| <p>Once the connection to the broker is established it will issue a "birth certificate" including some dummy information. |
| The information is intended to identify the different fields also by their content and the simulator ID.</p> |
| <p>The simulator currently supports the following control applications:</p> |
| <ul> |
| <li><strong>Command</strong> The simulated command application will simply reply with some text indicating that the command could not be found.</li> |
| <li><strong>Deployment</strong> The deployment application will allow to view and controls OSGi bundles and allow to "download" DP archives. |
| However the list of reported OSGi bundles and the download process are only simulated. But adding and removing DP archive will |
| result in more or less OSGi bundles to be reported.</li> |
| </ul> |
| <h2 id="simple-simulation-model">Simple simulation model</h2> |
| <p>This section describes the simple simulation model which is available in the basic simulation runner. The model |
| is intended to provide a stream of telemetry data for testing.</p> |
| <p>The basic runner allows to read a JSON representation of the model. Programmatically it is possible to |
| also other means of configuring a data simulator. This section will however focus on the JSON representation.</p> |
| <p>A default model would look like:</p> |
| <pre><code>{ |
| "applications": { |
| "example1": { |
| "scheduler": { "period": 2000 }, |
| "topics": { |
| "t1/data": { |
| "positionGenerator": "spos", |
| "metrics": { |
| "temp1": { "generator": "sine1", "name": "value" }, |
| "temp2": { "generator": "sine2", "name": "value" } |
| } |
| }, |
| "t2/data": { |
| "metrics": { |
| "temp1": { "generator": "sine1", "name": "value" }, |
| "temp2": { "generator": "sine2", "name": "value" } |
| } |
| } |
| }, |
| "generators": { |
| "sine1": { |
| "type": "sine", "period": 1000, "offset": 50, "amplitude": 100 |
| }, |
| "sine2": { |
| "type": "sine", "period": 2000, "shift": 45.5, "offset": 30, "amplitude": 100 |
| }, |
| "spos": { |
| "type": "spos" |
| } |
| } |
| } |
| } |
| } |
| </code></pre><p>Each model consists of a number of "applications", which represent actual Kura applications.</p> |
| <p>Each application consists of a scheduler, topics and generators. The scheduler defines when |
| the generator values will be refreshed. The topics then map the generated data to topics and metrics.</p> |
| <p>Generators typically generate their values on a function which maps from timestamp to a value. This |
| makes the generated values comparable as it is clear what can be expected as values. As the scheduler |
| runs all generators with exactly the same timestamp all generators in an application will generate the |
| same values. For simulators which spawn multiple instances in a single JVM, the scheduler will pass |
| the same timestamp to all applications of all simulator instances.</p> |
| <p>Under the "generators" section the generator instances get defined. The key can be later on used for |
| referencing the generator. The simulation runner will search, using the Java <code>ServiceLoader</code> mechanism |
| for generator implementations which can provide a generator. Typically the field <code>type</code> is used to |
| identify a generator. However every generator factory can opt-in to provide a working generation. If no |
| generator can be found, then the simulator will fail during startup. This way it is also possible |
| providing additional generator factories.</p> |
| <p>Generators can provide three different kinds of payload (body, position, metrics). It depends on the |
| generator implementation which kinds (maybe multiple) it provides. For metrics it also depends on the |
| generator which metric names it provides.</p> |
| <p>For example the "sine" generator provide a single metric named "value".</p> |
| <p>The topics section defines a map of topic and their payload mappings. The key of the map is the |
| name of the topic. The available field then are:</p> |
| <dl> |
| <dt>bodyGenerator</dt><dd>The name of the generator providing the body (BLOB) content</dd> |
| <dt>positionGenerator</dt><dd>The name of the generator providing the position information</dd> |
| <dt>metrics</dt><dd>A map for mapping generator values to metric entries</dd> |
| </dl> |
| |
| <p>Each metric mapping again has a key (which is used a metric name) and the reference to the |
| generator (field <code>generator</code>) and a value of the generator (field <code>name</code>), as each |
| generator can technically provide a map of values.</p> |
| <p>In the above example there are three generators: sine1, sine2 and spos. The first two are |
| sine generators with different configurations and the last one is a position generator with |
| no further configuration.</p> |
| <p>There is only one application configured (<code>example1</code>), which has two topics (<code>t1/data</code> |
| and <code>t2/data</code>). Each topic has two metrics (<code>temp1</code> and <code>temp2</code>), which each reference |
| to the same generator (<code>temp1</code> ⇒ <code>sine1</code> : <code>value</code>).</p> |
| <h3 id="provided-generators">Provided generators</h3> |
| <p>The following generators are available out of the box.</p> |
| <h4 id="sine-generator">Sine generator</h4> |
| <p><strong>Processes:</strong> <code>type = "sine"</code></p> |
| <p><strong>Generates:</strong> metrics</p> |
| <dl> |
| <dt>value</dt><dd>A sine curve based on the provided parameters</dd> |
| </dl> |
| |
| <table> |
| <thead><tr><th>Name</th><th>Default</th><th>Description</th></tr></thead> |
| <tbody> |
| |
| <tr><td><code>period</code></td> <td>60000</td> <td>The period (in ms) for a full cycle of the curve</td></tr> |
| <tr><td><code>amplitude</code></td> <td>100</td> <td>The amplitude of the curve</td></tr> |
| <tr><td><code>offset</code></td> <td>0</td> <td>The offset of the curve</td></tr> |
| <tr><td><code>shift</code></td> <td></td> <td>The shift in degrees (0-360) of the curve</td></tr> |
| |
| </tbody> |
| </table> |
| |
| <h4 id="straight-position-generator">Straight position generator</h4> |
| <p><strong>Processes:</strong> <code>type = "spos"</code></p> |
| <p><strong>Generates:</strong> position</p> |
| <p>Generates a position on the map which will move straight east on the equator. Circling the earth every 80 days. |
| Speed, number of satellites, precision and altitude will be sine curves.</p> |
| <h2 id="examples">Examples</h2> |
| <p>To start simulator with an example simulation configuration, run:</p> |
| <pre><code>export KSIM_SIMULATION_CONFIGURATION=$(curl -s https://raw.githubusercontent.com/eclipse/kapua/develop/simulator-kura/src/test/resources/example1.json) |
| java -jar target/kapua-simulator-kura-*-app.jar |
| </code></pre></dd></dl> |
| |
| </section> |
| |
| </div> |
| <div class="search-results"> |
| <div class="has-results"> |
| |
| <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1> |
| <ul class="search-results-list"></ul> |
| |
| </div> |
| <div class="no-results"> |
| |
| <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1> |
| |
| </div> |
| </div> |
| </div> |
| |
| </div> |
| </div> |
| |
| </div> |
| |
| |
| |
| <a href="community.html" class="navigation navigation-prev " aria-label="Previous page: Community"> |
| <i class="fa fa-angle-left"></i> |
| </a> |
| |
| |
| <a href="jwt_security.html" class="navigation navigation-next " aria-label="Next page: Setup JWT security"> |
| <i class="fa fa-angle-right"></i> |
| </a> |
| |
| |
| |
| </div> |
| |
| <script> |
| var gitbook = gitbook || []; |
| gitbook.push(function() { |
| gitbook.page.hasChanged({"page":{"title":"Simulator","level":"1.4","depth":1,"next":{"title":"Setup JWT security","level":"1.5","depth":1,"path":"jwt_security.md","ref":"jwt_security.md","articles":[]},"previous":{"title":"Community","level":"1.3","depth":1,"path":"community.md","ref":"community.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"eclipse/kapua","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Eclipse Kapua™ User Guide","links":{"home":"http://eclipse.org/kapua"},"gitbook":"3.x.x","description":"Eclipse Kapua™ User Guide"},"file":{"path":"simulator.md","mtime":"2020-11-26T08:22:34.032Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2020-11-26T08:23:37.956Z"},"basePath":".","book":{"language":""}}); |
| }); |
| </script> |
| </div> |
| |
| |
| <script src="gitbook/gitbook.js"></script> |
| <script src="gitbook/theme.js"></script> |
| |
| |
| <script src="gitbook/gitbook-plugin-search/search-engine.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-search/search.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-sharing/buttons.js"></script> |
| |
| |
| |
| <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script> |
| |
| |
| |
| </body> |
| </html> |
| |
