Understanding a Template

A template is a javascript document which describes the behavior of your virtual device during the simulation. A template consists of Device Model, Protocol Settings are Security Parameters.

Once we have figured out what our device lifecycle looks like and what kind of device state variables we will have, we can jump to writing a templates. A template is essentially a javascript document which describes how a single simulation will be executed. It's important to clarify that template describe only a single device behavior. When you run a template, you may create multiple devices out of it. Each of these multiple device could behave differently based on their unique client IDs. Every aspect of device behavior which needs to be modeled therefore should be described in the template.

How are the Templates used in the simulation? When a simulation is started, the simulation engine will parse the template and create virtual devices out of it. Each virtual device will have its own memory, state, and connect to the IoT cloud platform, until your simulation is running. Following diagram describes the instantiation of the template.

Generation of virtual objects from a single template

If you are familiar with C++ or any other object oriented design, think of templates as Classes and virtual devices as Objects. Once a template is defined, you could create as many instances of it as you want.

You could also create multiple templates to simulator an end to end system. E.g. when simulating a smart city environment, you would create a separate template to simulate a street light, trash can, parking slot etc. When you need a complete simulation, you will run all these templates together. These templates would also be able to talk to each other, as we will see in the later documentation.

Device Model

A device model encapsulates the behavior of device in Javascript function. Currently there are 4 functions which create a device model. Each of these template function is passed a javascript object called state which could be used to hold a device specific information. A model is independent of the connection protocol and the security parameters i.e. you could reuse a device model across HTTP and MQTT. IoTIFY provides you several sample device models to get started with.

A device model consists of 4 Javascript functions

So how are these device model functions executed? Let's understand this with the help of picture.

X Axis on this picture is time which moves in the right direction. The setup function in the device model is triggered as the very first function before even the connection is attempted to the backend. Use this function to retrieve values from persistent storage, initialize one time variables and assign some random names. The setup function doesn't need to return any value.

Once the setup is done, the message function will be invoked with the same state object which was passed earlier. The message function is the core function of the simulation and will define most of the simulation logic. The function is invoked for the specified number of iterations in the template run. The duration between each iteration is also configurable and needs to be specified in the template run parameters.

During the simulation, the cloud platform could send you data asynchronously (MQTT) or you would like to process the response of HTTP POST action. The response handler function enables you to do that.

At the end, when all messages have been sent, the finish function will be invoked. Here you could clean up any server side resources or summarize your test results.

Other component of the template are as follows:-

Protocol

Protocol specifies the server settings and underlying option for the chosen connectivity. The details are specific to each protocol. It's important to note that many of these protocol parameters are scriptable i.e. you could change dynamically with the help of state objects or other helper function. This is particularly interesting for MQTT e.g. where you would like to listen to a device specific MQTT Topic. You could simply subscribe with the following string

/device/{{client()}}/command

When the template is executed, the part within the double parenthesis will be evaluated and client() function will return a unique client ID, starting from Zero. E.g. if you are simulating 100 clients, each one of them will have its own unique client ID. The string would thus evaluate to the following for client 66

/device/65/command

Security

Security tab specifies the client specific security settings such as username/password or preshared keys/certificates etc. The fields are also scriptable as with the case of the protocol.

Summary

A template consists of a device model, protocol and security details. Each template is passed a unique Javascript object called state which could be used to maintain the device status through its run time. There are several helper functions and scripting options which makes fields configurable inside the protocol and security tab.

Should we describe the entire behavior of a device into the single template? Not necessarily. We will learn in the later chapters about glob key-value stores which could save device states in persistent memory. Using these storage, we could create separate templates which retrieve the last known value of a device state, run a scenario and then save the latest state back in the memory.

Now we have a good overview of what template is, let's jump to the finer details of a template.