Vehicle Locating

Vehicle Locating Protocol

The Vehicle Locating communication protocol describes the format of a request (also referred to as need) for locating a lost vehicle, and the response (bid) sent by other vehicles that are able to help locating it. The need would typically be sent by the vehicle owner, the vehicle itself, or a rescue service.

For example, a drone on a delivery mission runs out of battery and performs an emergency landing. The drone owner that lost the connection with their drone sends a request for locating assistance, along with the drone's last known coordinates, its model, color, and any other information that might help in finding it.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"last_latitude\": \"55.770279\", \
    \"last_longitude\": \"37.781467\", \
    \"vehicle_type\": \"drone\", \
    \"vehicle_manufacturer\": \"Copter Express\", \
    \"vehicle_model\": \"COPTEREXPRESS X1\", \
    \"vehicle_color\": \"White\", \
    \"vehicle_contact\": \"Andrei Ivanov, mobile: +7 555-338-5943\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    last_latitude: '55.770279',
    last_longitude: '37.781467',
    vehicle_type: 'drone',
    vehicle_manufacturer: 'Copter Express',
    vehicle_model: 'COPTEREXPRESS X1',
    vehicle_color: 'White',
    vehicle_contact: 'Andrei Ivanov, mobile: +7 555-338-5943',
  }),
});

import requests
payload = {
    "last_latitude": "55.770279",
    "last_longitude": "37.781467",
    "vehicle_type": "drone",
    "vehicle_manufacturer": "Copter Express",
    "vehicle_model": "COPTEREXPRESS X1",
    "vehicle_color": "White",
    "vehicle_contact": "Andrei Ivanov, mobile: +7 555-338-5943",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, an autonomous robot might send back a bid with a price for the mission, the distance from the lost vehicle's location and the estimated time of arrival at the location.

Bid

curl "bidding_endpoint_here" \
  --data "{ \
    \"request_uid\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"20000000000000000,10000000000000\", \
    \"price_type\": \"flat,minute\", \
    \"price_description\": \"Finders fee,Price per minute\", \
    \"current_latitude\": \"55.756951\", \
    \"current_longitude\": \"37.633839\", \
    \"arrival_at\": \"1513005534000\", \
    \"vehicle_type\": \"robot\", \
    \"vehicle_manufacturer\": \"Husarion\", \
    \"vehicle_model\": \"ROSBot\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,10000000000000',
    price_type: 'flat,minute',
    price_description: 'Finders fee,Price per minute',
    current_latitude: '55.756951',
    current_longitude: '37.633839',
    arrival_at: '1513005534000',
    vehicle_type: 'robot',
    vehicle_manufacturer: 'Husarion',
    vehicle_model: 'ROSBot',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,10000000000000",
    "price_type": "flat,minute",
    "price_description": "Finders fee,Price per minute",
    "current_latitude": "55.756951",
    "current_longitude": "37.633839",
    "arrival_at": "1513005534000",
    "vehicle_type": "robot",
    "vehicle_manufacturer": "Husarion",
    "vehicle_model": "ROSBot",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for locating a vehicle. Typically this will be sent by a vehicle owner that is looking for assistance in finding their lost vehicle.

This request is sent to the decentralized discovery engine which responds with status 200 and a unique identifier for this request. The details of this request are then broadcasted to DAV entities that can provide this service. Bids are later received as separate calls.

Arguments

Post request to a local/remote discovery endpoint

curl "discovery_endpoint_here" \
  --data "{ \
    \"last_latitude\": \"43.610159\", \
    \"last_longitude\": \"-116.783196\", \
    \"vehicle_type\": \"car\", \
    \"vehicle_manufacturer\": \"Tesla\", \
    \"vehicle_model\": \"Model S\", \
    \"vehicle_color\": \"Black\", \
    \"vehicle_license_number\": \"6GDG486\", \
    \"vehicle_contact\": \"James McGill, mobile: 555-338-5943\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    last_latitude: '43.610159',
    last_longitude: '-116.783196',
    vehicle_type: 'car',
    vehicle_manufacturer: 'Tesla',
    vehicle_model: 'Model S',
    vehicle_color: 'Black',
    vehicle_license_number: '6GDG486',
    vehicle_contact: 'James McGill, mobile: 555-338-5943',
  }),
});

import requests
payload = {
    "last_latitude": "43.610159",
    "last_longitude": "-116.783196",
    "vehicle_type": "car",
    "vehicle_manufacturer": "Tesla",
    "vehicle_model": "Model S",
    "vehicle_color": "Black",
    "vehicle_license_number": "6GDG486",
    "vehicle_contact": "James McGill, mobile: 555-338-5943",
  }
requests.post("discovery_endpoint_here", data=payload)

`last_latitude` required	The last recorded latitude coordinate of the lost vehicle
`last_longitude` required	The last recorded longitude coordinate of the lost vehicle
`vehicle_type` required	The type of vehicle that was lost. See full list of options here
`vehicle_manufacturer` required	Name of the manufacturer of the lost vehicle
`vehicle_model` required	Name of the model of the lost vehicle
`vehicle_color` optional	The color of the lost vehicle
`vehicle_license_number` optional	The license plate number of the lost vehicle
`vehicle_contact` optional	Human readable information regarding the lost vehicle (e.g., `Vehicle owner: James McGill, mobile: 555-338-5943`)

Bid

A bid to provide a vehicle locating service. Typically sent by a vehicle with locating capabilities, with the price for the mission, the distance from the lost vehicle's location and the estimated time of arrival.

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{
    \"request_uid\": \"ae7bd8f67f3089c\",
    \"expires_at\": \"1513005539000\",
    \"price\": \"20000000000000000,10000000000000\",
    \"price_type\": \"flat,minute\",
    \"price_description\": \"Finders fee,Price per minute\",
    \"current_latitude\": \"43.611626\",
    \"current_longitude\": \"-116.392593\",
    \"arrival_at\": \"1513005534000\",
    \"vehicle_type\": \"drone\",
    \"vehicle_manufacturer\": \"Dronster\",
    \"vehicle_model\": \"Res-Q\",
    \"vehicle_contact\": \"Dronster Rescue Missions LTD. www.dronster.com\",
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,10000000000000',
    price_type: 'flat,minute',
    price_description: 'Finders fee,Price per minute',
    current_latitude: '43.611626',
    current_longitude: '-116.392593',
    arrival_at: '1513005534000',
    vehicle_type: 'drone',
    vehicle_manufacturer: 'Dronster',
    vehicle_model: 'Res-Q',
    vehicle_contact: 'Dronster Rescue Missions LTD. www.dronster.com',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,10000000000000",
    "price_type": "flat,minute",
    "price_description": "Finders fee,Price per minute",
    "current_latitude": "43.611626",
    "current_longitude": "-116.392593",
    "arrival_at": "1513005534000",
    "vehicle_type": "drone",
    "vehicle_locating_technology": "Object Recognition Camera",
    "vehicle_manufacturer": "Dronster",
    "vehicle_model": "Res-Q",
    "vehicle_contact": "Dronster Rescue Missions LTD. www.dronster.com",
  }
requests.post("bidding_endpoint_here", data=payload)

`need_id` required	The unique identifier of the 'need' this bid is for. This ID arrives as part of the 'need' request
`expires_at` required	This bid will expire at this time. Specified as time in seconds since Epoch/Unix Time
`price` required	A comma separated list of prices. Each price is specified as an integer representing Vinci 1 DAV == 1e18 Vinci == 1000000000000000000 Vinci
`price_type` required	A list of price types describing the `price` parameter(s). Specified as a comma separated list. See Price Types for available values
`price_description` required	A comma separated list of strings describing the `price` parameter(s) in human readable terms
`current_latitude` required	The latitude coordinate of of where the vehicle is currently located
`current_longitude` required	The longitude coordinate of where the vehicle is currently located
`arrival_at` required	The estimated time of arrival at the location where the lost vehicle was last seen. Specified as time in seconds since Epoch/Unix Time
`vehicle_type` required	The type of vehicle used for the locating mission. See full list of options here
`vehicle_manufacturer` optional	Name of the manufacturer of the vehicle
`vehicle_model` optional	Name of the model of the vehicle
`vehicle_contact` optional	Human readable information regarding the vehicle (e.g `James McGill, mobile: 555-338-5943`)

Vehicle Types

The type of vehicles and their unique identifier.

Vehicle Type
`drone`
`car`
`truck`
`van`
`ship`
`robot`
`bike`

Price Types

Price types and their unique identifier.

Price Type	Description
`second`	Cost per second
`minute`	Cost per minute
`hour`	Cost per hour
`day`	Cost per day
`week`	Cost per week
`km`	Cost per km
`mile`	Cost per mile
`flat`	The listed `price` is a flat price