Drone Delivery Protocol

The following document describes the communication protocol for a cargo delivery service provided by an autonomous drone. It includes the format for both the request for a delivery service (also referred to as need) and the response sent by drones that bid on providing the delivery service.

For example, a user is looking for a drone to pick up a small tube containing corrosive materials from their doorstep and deliver it to a friend's backyard.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"pickup_at\": \"1513005534000\", \
    \"pickup_latitude\": \"32.787793\", \
    \"pickup_longitude\": \"-79.500593\", \
    \"dropoff_latitude\": \"32.937778\", \
    \"dropoff_longitude\": \"-79.500593\", \
    \"cargo_type\": \"11\", \
    \"hazardous_goods\": \"8\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    pickup_at: '1513005534000',
    pickup_latitude: '32.787793',
    pickup_longitude: '-79.500593',
    dropoff_latitude: '32.937778',
    dropoff_longitude: '-79.500593',
    cargo_type: '11',
    hazardous_goods: '8',
  }),
});

import requests
payload = {
    "pickup_at": "1513005534000",
    "pickup_latitude": "32.787793",
    "pickup_longitude": "-79.500593",
    "dropoff_latitude": "32.937778",
    "dropoff_longitude": "-79.500593",
    "cargo_type": "11",
    "hazardous_goods": "8",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, a drone might send back a bid with a price, the estimated time of arrival at the pickup location, and the estimated time of arrival at the dropoff location.

Bid

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"2000000000000000,20000000000000000\", \
    \"price_type\": \"second,flat\", \
    \"price_description\": \"Price per second,Tax\", \
    \"eta_pickup\": \"1513005719000\", \
    \"eta_dropoff\": \"1513006460000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '2000000000000000,20000000000000000',
    price_type: 'second,flat',
    price_description: 'Price per second,Tax',
    eta_pickup: '1513005719000',
    eta_dropoff: '1513006460000',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "2000000000000000,20000000000000000",
    "price_type": "second,flat",
    "price_description": "Price per second,Tax",
    "eta_pickup": "1513005719000",
    "eta_dropoff": "1513006460000",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for a delivery service. Typically this will be sent by a user that is looking to deliver a package using a drone.

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 "{ \
    \"pickup_at\": \"1513005534000\", \
    \"pickup_latitude\": \"32.787793\", \
    \"pickup_longitude\": \"-79.500593\", \
    \"dropoff_latitude\": \"32.937778\", \
    \"dropoff_longitude\": \"-79.500593\", \
    \"requester_name\": \"Jessie Bourne\", \
    \"requester_phone_number\": \"+1 415 123 5983\", \
    \"external_reference_id\": \"jb84723\", \
    \"cargo_type\": \"11\", \
    \"hazardous_goods\": \"8\", \
    \"ip_protection_level\": \"68\", \
    \"height\": \"8\", \
    \"width\": \"2\", \
    \"length\": \"2\", \
    \"weight\": \"50\", \
    \"insurance_required\": \"true\", \
    \"insured_value\": \"675\", \
    \"insured_value_currency\": \"USD\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    pickup_at: '1513005534000',
    pickup_latitude: '32.787793',
    pickup_longitude: '-79.500593',
    dropoff_latitude: '32.937778',
    dropoff_longitude: '-79.500593',
    requester_name: 'Jessie Bourne',
    requester_phone_number: '+1 415 123 5983',
    external_reference_id: 'jb84723',
    cargo_type: '11',
    hazardous_goods: '8',
    ip_protection_level: '68',
    height: '8',
    width: '2',
    length: '2',
    weight: '50',
    insurance_required: 'true',
    insured_value: '675',
    insured_value_currency: 'USD',
  }),
});

import requests
payload = {
    "pickup_at": "1513005534000",
    "pickup_latitude": "32.787793",
    "pickup_longitude": "-79.500593",
    "dropoff_latitude": "32.937778",
    "dropoff_longitude": "-79.500593",
    "requester_name": "Jessie Bourne",
    "requester_phone_number": "+1 415 123 5983",
    "external_reference_id": "jb84723",
    "cargo_type": "11",
    "hazardous_goods": "8",
    "ip_protection_level": "68",
    "height": "8",
    "width": "2",
    "length": "2",
    "weight": "50",
    "insurance_required": "true",
    "insured_value": "675",
    "insured_value_currency": "USD",
  }
requests.post("discovery_endpoint_here", data=payload)

Bid

A bid to provide a delivery service. Typically sent from a delivery drone to the user who requested the service

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1519093577681\", \
    \"price\": \"200000000000000\",20000000000000000”, \
    \"price_type\": \"secon\",flat”, \
    \"price_description\": \"Pric\" per second,Tax”, \
    \"eta_pickup\": \"1513005719000\", \
    \"eta_dropoff\": \"1513006460000\", \
    \"insured\": \"true\", \
    \"insurer_dav_id\": \"0x17325a469aef3472aa58dfdcf672881d79b31d58\", \
    \"drone_contact\": \"Megadronix\", \
    \"drone_manufacturer\": \"DXY\", \
    \"drone_model\": \"m6000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1519093577681',
    price: '2000000000000000,20000000000000000',
    price_type: 'second,flat',
    price_description: 'Price per second,Tax',
    eta_pickup: '1513005719000',
    eta_dropoff: '1513006460000',
    insured: 'true',
    insurer_dav_id: '0x17325a469aef3472aa58dfdcf672881d79b31d58',
    drone_contact: 'Megadronix',
    drone_manufacturer: 'DXY',
    drone_model: 'm6000',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1519093577681",
    "price": "2000000000000000,20000000000000000",
    "price_type": "second,flat",
    "price_description": "Price per second,Tax",
    "eta_pickup": "1513005719000",
    "eta_dropoff": "1513006460000",
    "insured": "true",
    "insurer_dav_id": "0x17325a469aef3472aa58dfdcf672881d79b31d58",
    "drone_contact": "Megadronix",
    "drone_manufacturer": "DXY",
    "drone_model": "m6000",
  }
requests.post("bidding_endpoint_here", data=payload)

Select Bid

A selection of one bid that wins over the rest. Sent by the service requester (a user that is looking to deliver a package using a drone)

Arguments

Post request to a local/remote endpoint representing the service provider

curl "discovery_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("discovery_endpoint_here", data=payload)

Starting

A message sent by the service provider (the delivery drone) to the service requester, notifying it that the delivery mission has started

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\", \
    \"current_latitude\": \"32.785889\", \
    \"current_longitude\": \"-79.935569\", \
    \"current_altitude\": \"80\", \
    \"azimuth_angle\": \"15\", \
    \"eta_pickup\": \"1513005719000\", \
    \"eta_dropoff\": \"1513006460000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
    current_latitude: '32.785889',
    current_longitude: '-79.935569',
    current_altitude: '80',
    azimuth_angle: '15',
    eta_pickup: '1513005719000',
    eta_dropoff: '1513006460000',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
    "current_latitude": "32.785889",
    "current_longitude": "-79.935569",
    "current_altitude": "80",
    "azimuth_angle": "15",
    "eta_pickup": "1513005719000",
    "eta_dropoff": "1513006460000",
  }
requests.post("bidding_endpoint_here", data=payload)

Decline

A cancellation message sent by the service provider (the delivery drone) to the service requester, notifying it that the mission has been declined

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("bidding_endpoint_here", data=payload)

Request Status

A request message sent by the service requester to the service provider, asking for a status update

Arguments

Post request to a local/remote endpoint representing the service provider

curl "discovery_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("discovery_endpoint_here", data=payload)

Status

A status update sent by the service provider to the service requester

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\", \
    \"current_latitude\": \"32.785889\", \
    \"current_longitude\": \"-79.935569\", \
    \"current_altitude\": \"80\", \
    \"azimuth_angle\": \"15\", \
    \"eta_pickup\": \"1513005719000\", \
    \"eta_dropoff\": \"1513006460000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
    current_latitude: '32.785889',
    current_longitude: '-79.935569',
    current_altitude: '80',
    azimuth_angle: '15',
    eta_pickup: '1513005719000',
    eta_dropoff: '1513006460000',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
    "current_latitude": "32.785889",
    "current_longitude": "-79.935569",
    "current_altitude": "80",
    "azimuth_angle": "15",
    "eta_pickup": "1513005719000",
    "eta_dropoff": "1513006460000",
  }
requests.post("bidding_endpoint_here", data=payload)

Pickup Arrival

A message sent by the service provider to the service requester, notifying it that the drone has arrived at the pickup location (for the user to load the package)

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("bidding_endpoint_here", data=payload)

Pickup Leave

A message sent by the service provider to the service requester, notifying it that the drone has left the pickup location

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\", \
    \"eta_dropoff\": \"1513006460000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
    eta_dropoff: '1513006460000',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
    "eta_dropoff": "1513006460000",
  }
requests.post("bidding_endpoint_here", data=payload)

Dropoff Arrival

A message sent by the service provider to the service requester, notifying it that the drone has arrived at the dropoff location

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("bidding_endpoint_here", data=payload)

Dropoff Leave

A message sent by the service provider to the service requester, notifying it that the drone has left the dropoff location

Arguments

Post request to a local/remote endpoint representing the service requester

curl "bidding_endpoint_here" \
  --data "{ \
    \"bid_id\": \"bv43nmw65eef03e\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    bid_id: 'bv43nmw65eef03e',
  }),
});

import requests
payload = {
    "bid_id": "bv43nmw65eef03e",
  }
requests.post("bidding_endpoint_here", data=payload)

Cargo Types

The following table describes the different types of cargo according to international delivery standards

Hazardous Goods

The following table describes the different types of hazardous goods according to international delivery standards

IP Protection Level

A drone may provide a certain level of protection from solids and/or liquids (mainly water and dust). The following table describes the standard levels of protection according to the International Protection Marking, IEC standard 60529.

The first digit indicates the level of protection that the enclosure provides against access to hazardous parts (e.g., electrical conductors, moving parts) and the ingress of solid foreign objects.

The second digit indicates the level of protection that the enclosure provides against harmful ingress of water.

For a full listing of all available codes, read more about International Protection Marking, IEC standard 60529

Price Types

Price types and their unique identifier