仿真器

Kura仿真器是用于模拟Kura网关实例的仿真框架，不包含OSGi运行时和硬件抽象。仿真器能创建网关仿真并测试Kapua。

以下章节假定位于目录simulator-kura 和Linux命令行环境。

启动

默认main class为org.eclipse.kapua.kura.simulator.main.SimulatorRunner。在模块构造后通过如下命令行运行(同时会输出一些帮助信息)：

java -jar target/kapua-simulator-kura-*-app.jar -?

仿真器一旦启动将保持运行(永远或直到指定时间)然后退出。运行时将尝试保持连接broker。更多仿真器行为细节参考：仿真器行为。

控制仿真器

通过命令行参数或环境变量(非Java系统属性)可以设置仿真器的行为。

环境变量优先于命令行参数。

仿真器选项

支持以下选项：

-?, --help

显示帮助并退出

-a, --account-name, KSIM_ACCOUNT_NAME<NAME>

设置Kapua账户名，默认为kapua-sys

-c, --count, KSIM_NUM_GATEWAYS<COUNT>

仿真实例个数，默认为1

-n, --base-name, KSIM_BASE_NAME<PREFIXS>

仿真器id前缀，使用default命名构造工厂时有效，默认为sim-

--name-factory, KSIM_NAME_FACTORY<NAME>

基于实例编号创建仿真器名字的命名构造工厂，参考命名构造工厂。

-s, --seconds<SECONDS>

仿真器运行时长，默认持续运行。

日志选项

以下选项只会起效一个：

-q, --quiet

不输出日志

-v, --verbose

输出更多细节

-d, --debug

输出调试信息

Broker连接选项

连接broker需要URL地址。支持指定URL地址全名，或指定部分并由仿真器生成最终URL地址。只能选择一种URL地址指定方式。

指定URL地址全名使用以下选项：

-b, --broker, KSIM_BROKER_URL

broker的URL地址全名

如果未指定URL地址全名，仿真器通过样式：<schema>://<user>:<password>@<host>:<port> 生成URL地址并使用如下选项或默认值：

KSIM_BROKER_SCHEMA

broker传输样式，默认tcp。支持以下选项：

• tcp ：MQTT over TCP

• ssl ：MQTT over TCP with TLS

• ws ：MQTT over WebSockets

• wss ：MQTT over WebSockets with TLS

-h,--broker-host,KSIM_BROKER_HOST

broker主机名，默认为localhost

KSIM_BROKER_PORT

broker端口号，默认为1883

KSIM_BROKER_USER

MQTT连接用户名，默认为kapua-broker

KSIM_BROKER_PASSWORD

MQTT连接密码，默认为kapua-password

如果未指定broker连接选项，默认URL为：tcp://kapua-broker:kapua-password@localhost:1883。

数据生成

通过简单仿真模型映射数据生成器到特定度量名，仿真器可以生成大量度量数据并发送到Kapua。

仿真配置通过JSON配置文件读取，支持本地文件路径或URI地址，支持通过环境变量指定JSON内容。

-f, --simulation, KSIM_SIMULATION_URL

数据仿真JSON配置文件的本地文件路径或URI地址。

KSIM_SIMULATION_CONFIGURATION

仿真JSON配置内容。

命名构造工厂

支持以下命名构造工厂：

default

使用选项--base-name作为实例前缀并追加编号。

host:name

使用本地主机名作为前缀，追加-和实例编号。所有特殊字符将被替换为(-)。

host:addr

使用本机IP地址作为前缀，追加-和实例编号。所有特殊字符将被替换为(-)。

host:iface:name

使用网络接口名作为前缀，追加-和实例编号。所有特殊字符将被替换为(-)。

host:iface:index

使用网络接口序号作为前缀，追加-和实例编号。所有特殊字符将被替换为(-)。

host:iface:mac

使用网络接口16进制MAC地址作为前缀，追加-和实例编号。所有特殊字符将被替换为(-)。

仿真器行为

一旦与broker建立连接，仿真器将发布虚拟的“出生证明”信息。The information is intended to identify the different fields also by their content and the simulator ID.

仿真器目前支持以下行为应用：

• 命令 命令仿真应用将回复命令无法找到。
• 部署 部署仿真应用支持查看OSGi组件和下载DP包。虽然是仿真，添加或删除DP包同样会影响OSGi组件信息。

简单仿真模型

本节介绍适用于基础仿真器的简单仿真模型。该模型可用作生成大量用于测试的遥测数据。

基础仿真器支持读取JSON模型描述。尽管也存在其他编程形式的仿真器配置方式，本节只关注JSON模型描述。

默认JSON模型描述如下：

{
    "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"
                }
            }
        }
    }
}

每个模型由多个表示实际Kura应用的"applications"组成。

每个应用由一个定时器，多个话题和生成器组成。定时器定义生成器数据刷新周期，话题映射数据到相应度量名。

生成器通过时间函数生成数据。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 wil 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.

在"生成器"小节中定义了各个生成器实例。The key can be later on used for referencing the generator. The simulation runner will search, using the Java ServiceLoader mechanism for generator implementations which can provide a generator. Typically the field type 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.

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.

For example the "sine" generator provide a single metric named "value".

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:

bodyGenerator

The name of the generator providing the body (BLOB) content

positionGenerator

The name of the generator providing the position information

metrics

A map for mapping generator values to metric entries

Each metric mapping again has a key (which is used a metric name) and the reference to the generator (field generator) and a value of the generator (field name), as each generator can technically provide a map of values.

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.

There is only one application configured (example1), which has two topics (t1/data and t2/data). Each topic has two metrics (temp1 and temp2), which each reference to the same generator (temp1 ⇒ sine1 : value).

内置生成器

支持以下生成器。

正弦生成器

Processes:type = "sine"

Generates: metrics

value

基于以下参数的正弦曲线

直线位置生成器

Processes:type = "spos"

Generates: position

生成在赤道上一直往东移动的位置数据。每80天绕地球一周。使用正弦函数生成速度，卫星个数，精度和海拔数据。

实例

通过实例仿真配置启动仿真器：

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