Starting the project

Prerequisites:

Node.js and npm should be installed.

To start the project:

run in terminal npm i to install dependencies;
add .env file to the project root;
- add all env variables to the .env. Currently it is used to connect to the Firebase;
run npm run start to start sever locally;

Schemas

Schemas are used to verify requests and responses produced by client/server and adhere AT-protocol. Schemas can be found in: src/core/operations/schemas

Emulator

TBD;

ATP (Auto tracker protocol) description

1. Scope

TBD

2. Terminology and Conventions

TBD

3. Definitions

Definitions
Central System	The server that gathers and processes beacon data
Beacon	Hardware device that gathers GPS data and send it to CS
Response/request	Data transferred from Central System to Beacon or vice versa

4. Abbreviations

Abbreviations
CS	Central System
Bcn	Beacon
HTTP(s)	Hyper Text Transfer Protocol
WS	WebSocket
ATP	Auto tracker protocol

5. TimeZone

Both beacon(s) and CS(s) must use GMT timeZone in order to prevent errors in speed calculations. Also, time should be updated after Start Notification. By default, the time should be sent using UNIX timestamp.

6. Response / Request structure

6.1. Basic structure

There are three types of requests:

CALL - Normally Emitted by a client(Bcn). CS can act as a client as well, if it sends requests to the Bcn.
CALLRESULT - Normally Emitted by Server(CS).
ERROR - Normally emitted by Server on operation processing errors.

CALL request Scheme: [<MessageTypeId>, "<UniqueId>", "<Action>", {<Payload>}]

CALLRESULT request Scheme: [<MessageTypeId>, "<UniqueId>", {<Payload>}]

ERROR request Scheme: [<MessageTypeId>, "<UniqueId>", "<errorCode>", "<errorDescription>", {<errorDetails>}]

Response/Request consists of the following parts:

MessageTypeId - shows the type of the request, whether it's made by CS nor by Bcn, or it contains error.
UniqueId - indicator of the message. It is a randomly generated UUID. id is used to track the Bcn request and CS response and match them. If id of response and request do not match, response must be ignored.
Payload - data of the request
Action - must be sent by Beacon. Contains the name of the operation made by Bcn.
errorCode - Action-like string contains short name of the error
errorDescription - description of the error.
errorDetail - Payload-like object, containing error-related data.

6.2. Possible MessageTypeIds

2 - request by client
3 - request by server
4 - Error

if CS receives message type id that differs from the listed above, such a message should be ignored.

7. URL structure

The path, WS client (Bcn) connects to the CS must contain the name of the beacon. Name of the beacon is preregistered on CS and stored in a database. If the name is not presented the connection would be refused.

The structure: <host>/<path>/<bcnName>

8. Requests initiated by beacon

8.1. Start Notification

When the tracking beacon is switched on it has to send Start Notification request to the Central System (CS) ( Server). Start Notification must be sent each time beacon switches on / reboots. It should be made to check and update the time to calculate speed more accurately.

Beacon Request example:

[2, id, "StartNotification",
    {
        beaconSerialNumber: "",
        imsi: "",
        iccid: "",
        firmwareVersion: "",
        vehicleVIN: "",          // optional
        vehicleLicensePlate: "", // optional
        vehicleBrand: "",        // optional 
        vehicleModel: "",        // optional
    }
]

Central System Response example

[3, id, {status: 'Accepted', currentTime: '', interval: ''}]

Possible Statuses

Accepted
Pending
Rejected

After successful start of the beacon, CS send back currentTime and heartbeatInterval that must be applied to the beacon config.

If error occurs: Central System Response example:

[4, id, '', '', {status: 'Error', code: '', message: ''}]

8.2. Heartbeat

Heartbeat is request that is made at the interval. The interval is set in the configuration of the Central System and received after StartNotification.

Heartbeat is intended to provide data about position (coordinates), current speed, time, of the beacon. Current speed should be calculated on the beacon. If the beacon is not able to calculate current speed, then it has to provide additional payload param: { noSpeed: true }, by default it is false.

Bcn example:

[2, id, 'Heartbeat', {
    speed: '',
    position: ['', ''],   // latitude and longitude
    noSpeed: false,       // default,
    currentTime: '',      // GMT time ISOString
    previousTime: '',
    previousPosition: '',
    systemOfMeasures: '',
}]

CS should reply to the request sending currentTime in response payload.

CS example:

[3, id, {currentTime: '', status: 'Accepted'}]

Another function of the heartbeat is to check whether the connection is still alive or not.

8.3. EmergencyNotification

This request is intended to be used in emergency situations. It can be used if an accident or similar happened.

Possible situations:

Accident
Speed limits noncompliance
Fuel leak

Request example:

[2, id, 'EmergencyNotification', {
    type: 'Accident',
    data: {} // any data
}]

Response example:

[3, id, {status: 'Accepted'}]

9. Operations initiated by Central System

9.1. Status

TBD;

This operation is intended to ask Bcn to send vehicle status. The data that could be provided by a beacon: current speed, mileage, ignition off/on, fuel left, etc.

9.2. Reset

The operation is intended to be used to reset the bcn if something goes wrong. The reset can be hard or soft.

Hard reset - reset without saving current session, closing ws connection properly.
Soft reset - close ws connection, save current session and reload. Reset type: Hard, Soft