Solution Components

Device Simulator Microservices

The IoT Device Simulator microservices are a series of AWS Lambda functions that provide the business logic and data access layer for all device simulation operations. Each Lambda function assumes an AWS Identity and Access Management (IAM) role with least privilege access (minimum permissions necessary) to perform its designated functions.

Admin Microservice

The iot-sim-admin-service Lambda function processes device simulator API requests sent to the /admin/* endpoints. All /admin/* API endpoints are configured as Lambda proxy endpoints that pass the full request payload to the iot-sim-admin-service function. The admin microservice handles all administrative services, including users and general settings.

Metrics Microservice

The iot-sim-metrics-service Lambda function processes device simulator API requests sent to the /metrics/* endpoints. All /metrics/* API endpoints are configured as Lambda proxy endpoints that pass the full request payload to the iot-sim-metrics-service function. The metrics microservice handles all metrics operations for the IoT Device Simulator.

Device Microservice

The iot-sim-device-service Lambda function processes device simulator API requests sent to the /device/* endpoints. All /device/* API endpoints are configured as Lambda proxy endpoints that pass the full request payload to the iot-sim-device-service function. The device microservice handles all device and device type operations, including list, add device, remove device, list device types, add device type, update device type, start simulation, and stop simulation.

Profile Microservice

The iot-sim-profile-service Lambda function processes device simulator API requests sent to the /profile/* endpoints. All /profile/* API endpoints are configured as Lambda proxy endpoints that pass the full request payload to the iot-sim-profile-service function. The profile microservice handles reading user profile information for the IoT Device Simulator.

Amazon DynamoDB

The IoT Device Simulator uses Amazon DynamoDB to persist metadata for devices, device types, settings, and metrics. Each DynamoDB table is provisioned using Amazon DynamoDB on-demand, a flexible billing option for DynamoDB capable of serving thousands of requests per second without capacity planning. DynamoDB on-demand offers simple pay-per-request pricing for read and write requests so that you only pay for what you use, making it easy to balance costs and performance. On-demand mode instantly accommodates workloads as they ramp up or down to any previously observed traffic level. If the level of traffic hits a new peak, DynamoDB adapts rapidly to accommodate the workload.

The solution creates four DynamoDB tables: iot-sim-device-widgets, iot-sim-device-types, iot-sim-metrics, and iot-sim-settings.

The iot-sim-device-widgets table stores the following information on virtual devices:

Category: The category of the device widget. This is defined by the device type.
CreatedAt: The date and time (in UTC) when the device widget was created
EndedAt: The date and time (in UTC) when the last simulation run ended
Id: The unique identifier for the device widget. This is generated automatically.
Metadata: The metadata associated with the device widget
Runs: The number of simulation runs performed by the device widget
Stage: The current simulation stage of the device widget. For more information, see Simulation Stage.
StartedAt: The date and time (in UTC) when the last simulation run started
Subcategory: The subcategory of the device widget. This is defined by the device type.
TypeId: The device type identifier
UpdatedAt: The date and time (in UTC) when the device widget was updated
UserId: The user id of the owner of the device widget
Visibility: The visibility (private or shared) of the device types for other IoT Device Simulator users. Use private to prevent other users from creating devices using the device type. Use shared to allow other users to create devices using the device type.



{
  "category": "custom widget",
  "createdAt": "2018-04-09T20:01:58Z",
  "endedAt": "2018-04-09T20:04:13Z",
  "id": "B1OJ6UHtoG",
  "metadata": {},
  "runs": 1,
  "stage": "sleeping",
  "startedAt": "2018-04-09T20:02:10Z",
  "subCategory": "weather station",
  "typeId": "rkbZDGsOf",
  "shared": "private",
  "updatedAt": "2018-04-09T20:04:13Z",
  "userId": "sample_user"
}

Figure 2: Sample device record

The iot-sim-device-types table stores the following information on device types:

CreatedAt: The date and time (in UTC) when the device type was created
Custom: Identifies whether the device type is user created (true) or system generated (false)
Name: The name of the device widget
Spec: The specification of the device type
Duration: The duration a simulation will run for a particular device type
Interval: The interval at which devices will publish data to AWS IoT
Payload: The JSON definition of the attributes to be simulated
Topic: The AWS IoT topic where the device will publish data
TypeId: The device type identifier
UpdatedAt: The date and time (in UTC) when the device type was updated
UserId: The user id of the owner of the device type



{
  "createdAt": "2018-03-05T19:14:00Z",
  "custom": true,
  "name": "weather station",
  "spec": {
    "duration": "120000",
    "interval": 2000,
    "payload": [
      {
        "_id_": "HJpJGapuf",
        "name": "stationid",
        "smax": 20,
        "smin": 10,
        "static": true,
        "type": "string"
      },
      {
        "_id_": "H1ea1fTTuM",
        "dmax": 99,
        "dmin": 0,
        "imax": 200,
        "imin": 0,
        "name": "temperature",
        "precision": 2,
        "type": "float"
      },
      {
        "_id_": "H1f61z6aOz",
        "max": 100,
        "min": 0,
        "name": "humidity",
        "type": "int"
      },
      {
        "_id_": "HkQa1G6p_M",
        "name": "timestamp",
        "tsformat": "default",
        "type": "timestamp"
      },
      {
        "_id_": "r1IfpsQ3M",
        "arr": [
          "running",
          "stopped",
          "starting",
          "error",
          "warning"
        ],
        "name": "state",
        "type": "pickOne"
      }
    ],
    "topic": "/weather/data"
  },
  "typeId": "rkbZDGsOf",
  "updatedAt": "2018-04-17T17:21:33Z",
  "userId": "sample_user"
}

Figure 3: Sample device type record

The iot-sim-metrics table stores the following logging information:

CreatedAt: The date and time (in UTC) when the metric record was created
DeviceBreakdown: A breakdown of the total number of simulation runs per device type by a specific user for the current month
Id: The unique identifier for the device widget. This is generated automatically.
Simulations: The number of simulation runs broken down by category
MonthlyRuns: A breakdown of the last six months of simulation runs
TotalDuration: The total number of simulation minutes by a user
TotalRuns: The total number of simulation runs by a user
UpdatedAt: The date and time (in UTC) when the metric record was updated
UserId: The user id of the simulation owner



{
  "createdAt": "2018-03-08T16:47:30Z",
  "deviceBreakdown": {
    "id": "201804",
    "simulations": [
      {
        "category": "weather station",
        "runs": 57
      },
      {
        "category": "vehicle",
        "runs": 2
      },
      {
        "category": "Sub Sensor",
        "runs": 5
      },
      {
        "category": "torque sensor",
        "runs": 25
      }
    ]
  },
  "monthlyRuns": [
    {
      "auto": 242,
      "generic": 164,
      "id": "201803",
      "month": "Mar",
      "runs": 147
    },
    {
      "auto": 0,
      "generic": 0,
      "id": "201802",
      "month": "Feb",
      "runs": 0
    },
    {
      "auto": 59,
      "generic": 8830,
      "id": "201804",
      "month": "Apr",
      "runs": 89
    }
  ],
  "totalDuration": 9295,
  "totalRuns": 236,
  "updatedAt": "2018-04-17T17:29:47Z",
  "userId": "sample_user"
}

Figure 4: Sample metrics record

The iot-sim-settings table stores the following settings information:

SettingID: The unique identifier of the setting record
CreatedAt: The date and time (in UTC) when the setting was created
Setting: The JSON description of the configuration setting details
Type: The type of setting record (config)
UpdatedAt: The date and time (in UTC) when the setting was updated

Device Simulation

The IoT Device Simulator leverages Amazon Simple Queue Service (Amazon SQS), Amazon Elastic Container Service (Amazon ECS), and AWS Fargate to simulate virtual devices sending data to AWS IoT endpoints.

Users make simulation requests via the included web console. Simulation requests are added to the Amazon SQS queue where they are stored until they are processed.

Amazon ECS containers provisioned by AWS Fargate contain a simulation engine that periodically polls the simulation queue for simulation requests. The simulation engine launches a virtual device and starts the device publishing simulated data to the AWS IoT endpoint. After the specified duration, the simulation engine stops the simulation, terminates the virtual device, and updates the device state and metrics in the iot-sim-device-widgets table.

Device Types

Device types are used to define the type of data your simulated IoT devices will send. When you create a device type, you define the structure of the data and specific attributes for each item in the payload. Device types contain the follow properties:

Name: The name of the device type
Data topic: The topic where the data will be sent in AWS IoT
Data transmission duration: The duration, in milliseconds, your device will send data
Data transmission interval: The interval, in milliseconds, at which your device will send data

Attributes

Attributes define what each payload contains. Attributes include the follow fields:

Attribute name: The name of the attribute
Attribute data type: The data type of the payload. The following data types are available:
- Boolean: Sends a random true or false value based on seeding. You set a minimum value, a maximum value, and seed value.
- Decay: Generates a number that exponentially decreases at a rate proportional to its current value.
- Float: Sends a random decimal value. You set the precision of the value, a minimum value, a maximum value, a decimal precision minimum value, and a decimal precision maximum value.
- Integer: Sends a random integer value. You set a minimum value and a maximum value.
- Object: Adds a nested object to the payload.
- Sinusoidal: Generates values on a mathematical curve that represents periodic oscillation with noise.
- String: Sends a random string value. You set a minimum length and a maximum length of the string.
- Unique Identifier: Sends a random UUID value
- Unique Short Identifier: Sends a random short UUID value
- UTC Timestamp: Sends a random UTC timestamp in YYYY-MM-DDTHH:mm:ss. For example, 2018-04-10T12:21:22. You can also specify a timestamp in Unix time format. For example, 1523377324.
- Location: Sends a random latitude and longitude coordinated within a radius of a defined point. You specify a latitude for the center position, a longitude for the center position, and a radius from the center position.
- Pick One from Array: Sends a random string value from a user-defined, comma-separated list of strings.
Static: Choose whether the value stays the same for the duration of the simulation
Default Value: A fixed value that will always be sent in the payload

Widgets

Widgets are virtual IoT devices that send simulated data to AWS IoT endpoints. With the IoT Device Simulator, you can create up to 100 widgets at a time. For example, to launch 400 widgets, you can create four batches of 100 widgets. The solution allows you to run up to 1,000 simultaneous simulations across the simulation engine. If you request more than 1,000 simulations at a given time, they will be queued and executed when the number of current simulations is less than 1,000.

Simulation Stage

Device widgets can be in one of three stages:

Simulating: The device widget is sending simulated data to the IoT endpoint
Provisioning: The device widget is launching
Sleeping: The device widget is stopped and not sending simulated data

You can view each widget’s simulation stage as well as a breakdown of the total number of widgets in each stage in the web console’s device view.

Logging Level

By default, this solution logs informational messages for the simulation engine. To change the logging level, open the IoT Device Simulator console and navigate to the Settings menu option. On the Simulation Engine tab, you can change the Logging Level to INFO, ROBUST, or DEBUG.

Level	Description
INFO	Logs will include high-level information about how the simulation engine is operating.
ROBUST	Logs will include information on anything that can potentially cause inconsistencies in the simulation engine but might not necessarily cause the engine to fail.
DEBUG	Logs will include information that might be helpful when debugging a problem with the simulation engine.

Device Simulator Console

The IoT Device Simulator features a web console that you use to manage simulations. The console displays information about virtual devices and device types, simulation states, and user profiles. You use the console to create and terminate virtual devices, start and stop simulations, and view metrics.

Dashboard

The console includes a dashboard you can use to view how many simulations you have run, how many simulation hours you have run, and a breakdown of the different device types you have created.

Figure 5: Sample dashboard

Device View

The console also includes a device view that shows all devices in your pool of created devices, as well as the simulation state of the devices.

Figure 6: Sample devices view

Device Types View

The console includes a device types view that displays a list of device types, and allows you to create new device types.

Figure 7: Sample device types view

The console includes a custom widget view that displays your list of widgets, and allows you to create and delete widgets, and start and stop simulations. This view also provides a count of the widgets in various simulation stages.

Figure 8: Sample widgets view

Authentication

This solution takes advantage of the user authentication features of Amazon Cognito User Pools. After successfully authenticating a user, Amazon Cognito issues a JSON web token that is used to allow the console to submit requests to the device simulator API. HTTPS requests are sent by the console to the simulator API with the authorization header that includes the token.

User Management

After the device simulator is deployed, administrators can invite privileged users and customize their permissions to implement granular access-control policies. Administrators can also change settings. For more information, see Appendix D.

Logging and Metrics

The device simulator solution logs API calls, latency, and error rates to Amazon CloudWatch which you can use to set alarms based on defined thresholds. The solution also monitors traffic at the REST API level. Optionally, you can enable detailed metrics for each method of the device simulator REST API from the Amazon API Gateway deployment configuration console. Detailed metrics will incur an extra cost.

Amazon ECS

This solution leverages Amazon Elastic Container Service (Amazon ECS) for the solution’s simulation engine. Amazon ECS uses AWS Identity and Access Management (IAM) service-linked roles. A service-linked role is a unique type of IAM role that is linked directly to an AWS service. Service-linked roles are predefined by the service and include all the permissions that the service requires to call other AWS services on your behalf.

Amazon ECS uses the AWSServiceRoleForECS role to allow the service to manage your cluster. If you have not already created a service-linked role for Amazon ECS, you must create one before you use this solution. For instructions on how to create the role, see Creating a Service-Linked Role for Amazon ECS in the Amazon ECS Developer Guide. For more information on service-linked roles, see Using Service Linked Roles in the AWS Identity and Access Management User Guide.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »