# ICMP JavaScript API

## Introduction

This API allows users to send PING operations to an IP address.

### Icmp Object

The `icmp object` is the main object of the ICMP client. It allows sending a PING operation to an IP address, and receiving the response (in synchronous or asynchronous mode).

### Icmp Object Properties

| Property  | Type    | Default | Description                                                          |
|-----------|-------- |---------|----------------------------------------------------------------------|
| ip        | string  | (*)     | IP address to send PING.                                             |
| retries   | number  | 5       | Number of PING delivery retries.                                     |
| timeout   | number  | 2500    | Timeout in milliseconds of retry.                                    |
| async     | boolean | true    | Decide if the request is asynchronous (true) or synchronous (false). |

(*) By default, select the IP of the device or the provisioned subscription.

### Icmp Object Methods

#### icmp.send()

Send PING using the properties of the `icmp object`:

* `ip`: IP address to send PING.
* `retries`: Number of PING delivery retries.
* `timeout`: Timeout in milliseconds of retry.
* `async`: Decide if the request is asynchronous or synchronous.

- **RETURN**: If the **async** property is **false**, then returns an object with the following properties:

    * `result`: String. The value will be **"OK"** when the result is successfull or **"NOK"** when the result of the request had error, for example, timeout. 
    * `deviceId`: String. Entity receiving the ping.
    * `datastreams`: An array with the information of the request result.

Example of use:

```javascript
icmp.ip = "10.10.10.174";
icmp.send();
```

Result:

* `SUCESSFULL`:

```json
{
  "result": "OK",
  "datastreams": [
    {
        "id":"device.communicationModules[].subscription.address",
        "datapoints":[
            {
                "value":{
                    "value": "10.10.10.174"
                }
            }
        ]
    },
    {
        "id":"device.communicationModules[].subscription.presence.ip",
        "datapoints":[
            {
                "value": "OK"
            }
        ]
    },
    {
        "id":"device.communicationModules[].subscription.presence.ipRtt",
        "datapoints":[
            {
                "value": 6
            }
        ]
    }
  ]
}
```

* `ERROR`:

```json
{
  "result": "NOK",
  "deviceId": "deviceId",
  "datastreams": [
    {
      "datastreamId": "collected.device.communicationModules.subscription.address",
      "value": "172.19.18.95"
    },
    {
      "datastreamId": "collected.device.communicationModules.subscription.presence.ip",
      "value": "NOK"
    }
  ]
}
```