Greg

November 28, 2024 09:35
Updated

RabbitMQ Integration

GpsGate integrates with RabbitMQ. This allows you to forward devices' track data and live events to a RabbitMQ installation and consume it as you wish.

RabbitMQ is open-source message-broker software that originally implemented the Advanced Message Queuing Protocol and has since been extended with a plug-in architecture to support Streaming Text Oriented Messaging Protocol, MQ Telemetry Transport, and other protocols.

Setup

1. Log in to Site Admin (Legacy) and navigate to Plugins.

2. Click on Get More Plugins and install RabbitMQ

3. Navigate now to Integrations, select RabbitMQ, and click on Add.

This is an example of how to fill this form:

4. Fill all the fields and save the configuration.

5. Click on Test in order to test if your configuration is correct, you should see this message if everything is correct:

6. Once saved and tested, navigate to Manage Applications.

7. Enable RabbitMQ, as well as the configuration you’ve created.

Screenshot 2024-09-17 at 15.48.39.png

8. Click on Save.

Track Messages

Login to the Vehicle Tracker application you’ve enabled RabbitMQ in.
Click on Main Menu > Admin > Roles. The Roles window will open.
Click on Create copy of an already existing role and give it a new name, such as RabbitMQ.
Select all the users for which you want to enable the Track data to be forwarded to your RabbitMQ installation.
Enable the _RabbitMQ privilege and the configuration created in Site Admin (Legacy), in this case 'RabbitMQ Server 1'.
Click on Save.

Event Message

Login to the Vehicle Tracker application you’ve enabled RabbitMQ in.
Click on Main Menu > Admin > Event Rule. The Event Rule list window will open.
Create a new Event Rule or modify a current one. About Event Rules.
In the Notifier section, add a new Notifier of type RabbitMQ
Select the RabbitMQ configuration to which you want to post the Event messages
Optionally add a Value. This can be some text and/or different signal values selected from the dropdown menu
Select when to Nofity: Start, End, Start, and End, or Always
Save the Event Rule

Date Type

There are 2 types of data supported:

Tracks: Vehicle track data which includes current position and all the vehicle signals (including field script and accumulators)
Events: Live events using an Event Rule RabbitMQ Notifier

Serializer Type

We support two serialization types: JSON and Protobuf. Protobuf is recommended since its data is much smaller which will make the data forward faster.

JSON definition for Track messages:

{
    "type": "object",
    "properties": {
        "imei": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "userID": {
            "required": true,
            "type": "integer"
        },
        "utc": {
            "required": true,
            "type": "integer"
        },
        "valid": {
            "required": true,
            "type": "boolean"
        },
        "heading": {
            "required": true,
            "type": "number"
        },
        "speed": {
            "required": true,
            "type": "number"
        },
        "lng": {
            "required": true,
            "type": "number"
        },
        "lat": {
            "required": true,
            "type": "number"
        },
        "alt": {
            "required": true,
            "type": "number"
        },
        "fields": {
            "required": true,
            "type": [
                "object",
                "null"
            ],
            "additionalProperties": {
                "type": [
                    "object",
                    "null"
                ],
                "properties": {}
            }
        }
    }
}

Protobuf definition for Track messages:

syntax = "proto3";
option csharp_namespace = "GpsGate.RabbitMQ.API.Protobuf";
option optimize_for = SPEED;
package google.protobuf;

message TrackMessage {
  string imei = 1;
  int64 utc = 2;
  bool Valid = 3;
  double Heading = 4;
  double Speed = 5;
  double lng = 6;
  double lat = 7;
  double alt = 8;
  map<string, FieldData> fields = 9;
  int32 userId = 10;
}
message FieldData {
  oneof kind {
    int64 DateTime_value = 1;
    double double_value = 2;
    string string_value = 3;
    bool bool_value = 4;
    int32 int32_value = 5;
  }
}

Json definition for Event messages:

{
    "type": "object",
    "properties": {
        "id": {
            "required": true,
            "type": "integer"
        },
        "userID": {
            "required": true,
            "type": "integer"
        },
        "RuleName": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "UserName": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "Namespace": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "Value": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "State": {
            "required": true,
            "type": [
                "string",
                "null"
            ]
        },
        "lng": {
            "required": true,
            "type": "number"
        },
        "lat": {
            "required": true,
            "type": "number"
        },
        "alt": {
            "required": true,
            "type": "number"
        },
        "utc": {
            "required": true,
            "type": "integer"
        }
    }
}

Protobuf definition for Event messages:

syntax = "proto3";
option csharp_namespace = "GpsGate.RabbitMQ.API.Protobuf";
option optimize_for = SPEED;
package google.protobuf;

message EventMessage {
    int64 id = 1;
    string RuleName = 2;
    string UserName = 3;
    string Namespace = 4;
    string Value = 5; 
    string State = 6;
    double lng = 7;
    double lat = 8;
    double alt = 9;
    int64 utc = 10;
    int32 userId = 11;
}

Independently of the serialization, UTC is the track timestamp in milliseconds since Unix Epoch and Speed is in m/s.

Technical details

The RabbitMQ is set up to go through a RabbitMQ Exchange of type topic. Read more here: RabbitMQ topic exchange. This allows you to create multiple queues which will be routed using the Exchange Key.

The RabbitMQ plugin uses AMQP protocol and it acts as a RabbitMQ client.

Routing Key

The Routing Key is a template table, meaning you can use several user-specific data to compose the Routing Key. Currently, we support three templates:

username - the username of the user
name - the name of the user
imei - the IMEI of the reporting device

Here are a few examples of how to use it:

Tracks.[imei]
User.[username]
[imei]