Forwarders

/forwarders

Forwarders are realtime redirections of data to any endpoint. They are useful when you want to obtain all the data from all your entities and store it in a database.
Forwarders have an active queue and require a confirmation that a message was received by the endpoint, thus with forwarders you're able to achieve database replication.

Pegasus supports forwarding data in an array of JSON objects where each object corresponds to an entity's (vehicle's) event which includes any location information or data reported by the entity's device.

Intro

The way it works is that you define a URL (endpoint) that's going to be used as a receiver for the HTTP POST requests sent from Pegasus.

Pegasus forwards

>>>> [{"lat": 25.23432, "lon": -80.24912, "id":10001},{"lat": 25.23435, "lon": -80.24913, "id":10002}]

The forwarder service expects the endpoint to 'confirm' the reception of the message Pegasus sends.

In order to confirm the reception of all events successfully, you can respond with an empty array []

Response from client

<<<< []

Should there be any events that we sent in the forward that you did not process correctly in your database you can reply with the ID of the event that was not processed

<<<< [10002]

and Pegasus forwards that event again

>>>> [{"lat": 25.23435, "lon": -80.24913, "id":10002}]

In order for Pegasus to forward data to your endpoint you must allow HTTP traffic to a path in your server where the code will reside.
Check to make sure there are no firewall restrictions and the site is reachable by an external application.

By default the fields that are forwarded are the one's found in the Master Fields List.

Depending on what accessories the device has connected, the fields will be sent accordingly. In other words only a device with an ECU Monitor accessory connected will report ecu_ related fields, otherwise these fields will not be forwarded in the POST request.

At the moment, forwarders can only be created by DCT, once created however, if you are an administrator you'll be able to edit it.

Tutorials

PHP & phpMyAdmin

The following tutorial demonstrates how to handle the messages forwarded by the Pegasus Sites through PHP (version 5.3 or later).

To start download or clone the receiver code from our repo

The root file must be allowed access from a url, such as http[s]://[YOURDOMAIN]/[PATH TO TEMPLATE]/ this will be your endpoint.

In the config.php, modify the constants to suit your PHP installation and Database access credentials.

date_default_timezone_set("UTC");

define("DB_SERVER", "YOURDATABASE_SERVER");
define("DB_USER", "DATABSE_USER");
define("DB_PASS", "DATABASEP_PW");
define("DB_NAME", "DATABASE_NAME");
define('DB_TABLE_NAME', 'UNIT_EVENTS_RPC');

Once you have verified your Database credentials, remove/comment the first exit() statement within the ‘index.php’ file.

// in the index.php comment or remove the following line
//exit()

// make sure to have the PEGASUS_PROTOCOL as JSON
define('PEGASUS_PROTOCOL', JSON);

By default, when you test the forwarder it will create a table with the following keys (assuming it's not already created)
eventKeysMySQL.sql

If you do not want to store the data to a database, you can disable it by setting the variable ‘$db_storage’ to false within the ‘config.php’ file. This will prevent the table from being created, and will prevent all new events from being inserted into the database.

// set to true to to store the data in the db
$db_store = true;

Note: This does not delete the table if it has been previously created, this only prevents the sql statement that creates the table from executing.

Events Object data structure

In most cases, it may be may be suitable for the events object to be handled differently or in addition to the database storage mechanism discussed in the previous section.

In this instance you may add your logic directly into the peg_insert_array function of the config.php file.
You can use the $data object at your discretion, and modify it to your will. The $data object is a PHP associative array which contains all the events sent from the pegasus gateway. You may add any logic here, which can include sending emails, forwarding the data to another script, or storing to a file. You must make sure that any errors are handled appropriately.

NOTE: It is important that you make sure your logic returns an empty array []. As this lets pegasus know that the events have been handled accordingly and the queue can be cleared.

Once done you can test the forward here:
Testing the Forward

Windows, .NET, Microsoft SQL

Download the following zip ms_receiver.zip

In the receiver.ashx
there’s 3 places where you must input data

Line 50: Replace [dbo].[UNIT_EVENTS_RPC] with your Database Table Name

Line 105: Replace SERVERNAME with the name of your server

Line 106: Replace Pegasus_db with the name of your database

Please note that this solution uses:
Windows Authentication Mode

Run the following in Microsoft SQL Server to create the DB.
eventKeysMSSQL.sql

Make sure your Microsoft server has IIS, Active Directory services running and port binding correctly done.
DNS/DHCP services are optional but recommended.

Testing the forward

In order to simulate what Pegasus would send to your server/database you may use an application that sends HTTP requests, like POSTman, or cURL.
Just use the URL with the path to your JSON listener and follow one of the examples on the right.

Full example with all keys

curl -X POST "http://yourlistener.com/path/to/receiver" \
-H "Content-Type: application/json" \
-d '[{"io_pwr": true, "ac": 2, "code": 1, "type": 10, "vid": 1392, "cf_lac": 103, "ip": "208.131.186.63", "port": 26052, "pid": 110, "al": 521, "vo": 6356212, "io_ign": true, "event_time": "2016-01-12T19:40:31+00:00", "source": 3, "lon": -77.32573, "io_exp_state": false, "id": 4348333385, "cv10": 580, "cv11": 0, "cv12": 268, "cv13": 0, "head": 315, "vdop": 83, "hdop": 97, "bl": 4394, "mph": 28, "valid_position": true, "lat": 18.08918, "pdop": 128, "device_id": 357666050758579, "system_time": "2016-01-12T19:40:32.799671+00:00", "cf_rssi": "10", "age": 2, "sv": 9, "io_out1": false, "io_out2": false, "io_in1": false, "io_in2": false, "io_in3": false}]'

Tips & Recommendations

Receiving data from multiple forwarders

If you are looking to receive data in your database from multiple forwarders, it is recommended that you create tables based on the PID field. This field corresponds to the Pegasus site ID, every forwarder received from different servers will have a unique PID per site.

Working with large data

When working with large data it is important to separate the database into manageable tables. For example, you could have a table for every 1 or 2 vehicles.

You may partition the vehicle tables per week or trimester. Every partition has a constraint over the Date column that way you only look over the table with the dates you're looking for. This is especially important when you have to drop tables in the future.

Enabling a Forwarder on your site

In order to enable to create the forwarder please make sure you test with cURL or POSTman.
After successfully testing you may request enabling your forwarder on your site using the following form:
Submit Application

It takes approximately 8-24 hours to enable the application on your Gateway.

Source IP addresses

A list of source IP addresses can be found here IP Addresses.