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. Useshared
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
Custom Widget 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.