Clients

Clients take the Synth output and send it into an IoT system to simulate IoT devices. The client is typically specified in an On*.json file in ../synth_accounts.

DevicePilot client

This client posts event data into DevicePilot. It is also capable of doing historical bulk uploads and being interactive. It can also delete devices, create DevicePilot filters, events and actions.

To find your DevicePilot access key:

1. Log on to your DevicePilot account
2. Click Settings / My User and find your key in the API Key section

DevicePilot client specification

The client accepts the following parameters (usually found in the “On*.json” file in ../synth_accounts):

"client" : {
    "type" : "devicepilot",
    "devicepilot_api" : "https://api.devicepilot.com",
    "devicepilot_key" : "xxxxxxxxxxxxxxxxxxxx", # Your key from DevicePilot Settings page
    "devicepilot_min_post_period" : "PT10S",    # Optional. Do not post more often than this.
    "devicepilot_max_items_per_post" : 500,     # Optional. Individual posts cannot be bigger than this (the DP /device endpoint has a 1MB payload limit per post)
    "devicepilot_mode" : "bulk|interactive",    # In bulk mode, events are written to DevicePilot in bulk. In interactive mode they are written one-by-one (this mode is entered automatically when real-time is reached)
    "aws_dp_account" :      # For bulk uploads, the DevicePilot account code ("acc_*/accountname"). If this is specified then this client automatically defaults to "bulk" mode 
    "aws_dp_bucket" :       # (optional) For bulk mode, an alternative bucket to upload to (defaults to production)
    "merge_posts" : true    # Spots cases where different device properties are being updated at the same time (and therefore could be merged into a single post)
}

To make AWS bulk uploads work, you must run “aws configure” on your command line. To create the credentials go to https://console.aws.amazon.com/iam/home and select Users, then yourself.

DevicePilot client event actions

If you’re using the DevicePilot client then the following client-specific actions are available:

Create arbitrary DevicePilot filters:

"action" :
{
    "client.create_filters" : [
        {
            "$description" : "Down (test)",
            "where" : "$ts < ago(300)",
            "monitor" : true,
            "action" : {
                "$description": "Notify Synth of timeout (test)",
                "body": "{\n\"deviceId\" : \"{device.$id}\",\n\"eventName\" : \"notifyTimeout\"\n}",
                "headers": {
                    "Instancename": "<<<instance_name>>>",
                    "Key": "<<<web_key>>>"
                },
                "method": "POST",
                "target": "request",
                "url": "https://synth.devicepilot.com/event"
            }
        }
    ]
}

Delete all DevicePilot filters:

"action" : { "client.delete_all_filters" : {} }

Synchronise with DevicePilot (i.e. wait until all data we’ve posted into DevicePilot has been ingested and is now available):

"action" : { "client.sync" : {} }

Query DevicePilot (you’ll probably want to do a client.sync first). Parameters are passed straight through to the /query endpoint, so you can use all the combinations that that supports.

"action": {
    "client.query" : {
        "start" : "2017-01-01T00:00:00",
        "end" : "2017-01-02T00:00:00",
        "op" : "duration",
        "valueFilterStr" : "$ts > ago(86400)",
        "expect" : { <optionally define this parameter to throw an error if the query result doesn't match> }
    }
}

The DevicePilot client has two modes of pushing events into DevicePilot:

• bulk mode generates JSON files locally, and then does a bulk-upload to DevicePilot (via AWS)
• interactive mode send events directly into the /devices DevicePilot API (slower, but will trigger actions and is interactive)

The client defaults to interactive mode, and automatically changes to interactive mode either at the end of the simulation, or when real-time is reached, whichever comes first. If you want to change to interactive mode within your simulation, you can use the “set_mode” command:

"action" : {
    "set_mode" : "bulk|interactive"
}

AWS client

This client posts event data into AWS-IoT. The credentials are the standard AWS tokens generated by using the IAM pages on your AWS account.

AWS client specification

The client accepts the following parameters (usually found in the “On*.json” file in ../synth_accounts):

"client" : {
    "aws_access_key_id" : "xxxxxxxxxxxx",
    "aws_secret_access_key" : "xxxxxxxxxxxxx",
    "aws_region" : "us-west-2"
}

There are no event actions specific to the AWS client.

Filesystem client

This client posts event data to the local filesystem, and is useful for offline testing of scenarios. In addition to the .evt file that Synth emits, the Filesystem client also emits one .csv file (columnar for easy analysis in e.g. Excel) and multiple .json files (for easy ingestion into programs or batch upload into e.g. AWS S3).

Filesystem client specification

The client accepts the following parameters (usually found in the “On*.json” file in ../synth_accounts):

"client" :
{
    "type" : "filesystem",
    "filename" :"OnFStest"
}

There are no client event actions specific to the Filesystem client.