IoTIFY specific helper functions

We have written several helper functions which will help you simulate complex behavior easily.

Current index()

While simulating, you will specify the number of iterations for template. The current iteration can be determined within the template by using keyword index(). Here is an example

{
return "This is the "+index()+" iteration";
}

Above template will send a message containing the current iteration index, starting from 0.

Current client()

While simulating, you will need to implement a device specific behavior. The current client ID can be determined within the template by using keyword client(). Here is an example

{
return "This is the client "+client() + " on "+index()+" iteration";
}

Above template will send a message containing the current client with iteration index, starting from 0.

The drive() function

To simulate a vehicle driving from one location to another is simply a matter of specifying the starting and end address. Use the following function in your template:

state['location'] = drive({start:'Munich,DE',end:'Berlin,DE',accuracy:5});
return JSON.stringify(state, null, 2);

Above template will generate drive coordinates starting from Munich to Berlin on real traffic conditions.

Following are the input parameters:-

drive({start:'Disneyland, CA',end:'Universal Studios'})

What is the output of the drive() function?

The output of the drive() function is a JSON object, that’s why it is important to save this into a string with JSON.stringify(). Here is what the output looks like:

{
latitude: 34.123456, // decimal
longitude: 23.123455, // decimal
speed : 6, // meter per second
accuracy: 2 // meter radius
}

Note: once the drive has been finished, the output will contain an additional field finished set to true to indicate that the current drive has been finished. Use the field to calculate the next set of drive or return.

The location() function

Location function converts an address to its GPS coordinates, again with given accuracy parameter.

state['location'] = location({address:'Delhi,IN',accuracy:5})

This will generate a GPS coordinate near delhi with an accuracy of 5 meters.
Similar to drive function, you could also pass the actual address in the parameter and it will convert that to a set of GPS coordinates. The accuracy of this could be still controlled by the accuracy parameter. The output of location function is following:

{
latitude: 34.123456, // decimal
longitude: 23.123455 // decimal
}

Manipulating Locations

Templates allow manipulating locations using geolib, a useful geo computing library. Example:

{
var bearing = geolib.getBearing( location('Delhi'), {latitude: 51.519475, longitude: 7.46694444}) ;
}

Check out the geolib documentation to learn more about it.
Want to check out How to use drive function in real world? Check our guide.

Get the real world weather

temperature() and humidity function will query weather API to get the current weather of a city. Example:

{
var temperature = temperature({location: 'London, UK', unit: 'c'});
var humidity = humidity({location: 'London, UK');
}

This will return the current temperature of London in degree celcius and relative humidity in percentage. If the waether can not be found or if the location is incorrect, -1 will be returned.

To change the temperature to Fahrenheit, use unit as ‘f’ instead.

Mock CPU and memory

cpu() and memory() functions will return mock CPU and memory usage of a running system in percentage points.

{
state['cpu'] = cpu();
state['memory'] = memory();
}

Volatile variable

A volatile variable is useful while modelling a complex value such as stock price or temperature. The value of volatile variable is dependent upon its last value.

{
state['temperature'] = volatile({min : -10, max: 100, delta: 4});
}

A volatile variable takes 3 parameters, min range, max range and delta value as an input.

The value of volatile will start from the middle of min and max, i.e. min+max/2
Upon each iteration, volatile will shift 0 to delta in either positive or negative direction from its last value. e.g.

var chart = volatile({min : 10, max: 20, delta: 3})

chart will be initialized to 15 at iteration 0. (10+20)/2

At iteration 1, chart can be anywhere +/-3 of 15, i.e. min 12 and max 18. Let’s say it reaches 14

At iteration 2, chart can be anywhere +/-3 of 14, i.e. min 11 and max 17 and so on.

Volatile is useful for modelling dependent values such as stock prices and temperature graphs, where next value depends upon the last value.

REST apis (get/post/put/patch/delete)

Within your template, you could call a REST API and get data from an external source. You could even post data to the external server within the template. Following helper APIs are available in the template.

get/delete({ url:’myurl.com/api’ })

post/put/patch({ url:’myurl.com/api’, data: { key: ‘value’} })

All API returns the response in either a parsed JSON object or string.

In the following example, we will get the current public IP address of our node and send this address to our backend application to whitelist our client.

{
// state is a hash which can be used as local storage
//Getting the current IP address of the server executing the template
state['myip'] = get({url: 'http://ifconfig.co/ip'}).trim();
// posting the IP to my application to whitelist the source
state.response = post({url: 'http://httpbin.org/post', data: { ip: state.myip }});
//return a string value which will be sent as the message payload
return JSON.stringify(state, null, 2);
}

assert function

When using IOTIFY for testing, a test assertion can be done using assert() function.

assert(condition, message) function takes two parameters

condition: A boolean condition which should be tested for truth (true)
message: A string describing the cause of assertion failure which can be stored in test results.

E.g. following statement checks for an assertion failure in your template and marks the test result as failed, if retval doesnt equal 123.

assert(retval == 123, "Return value doesnt equal"+123);

The assertion will overwrite the usual results, i.e. Even if the message has been successfully processed by the endpoint, the failure of assertion will mark the test result as failed.