NAV Navbar
shell javascript python
  • Drone Charging Protocol
  • Need
  • Bid
  • Plug Types
  • Energy Sources
  • Drone Protection Level
  • Price Types
  • Drone Charging

    Drone Charging Protocol

    The following document describes the communication protocol for drone charging. It includes the format for both the request for a charging service sent by the drone (also referred to as need) and the response sent by a charging provider (bid).

    For example, a drone may look for a charging station that supports 2mm bullet connectors within 2 km of its current location.

    Need

    curl "discovery_endpoint_here" \
      --data "{ \
        \"start_at\": \"1513005534000\", \
        \"latitude\": \"32.787793\", \
        \"longitude\": \"-79.935005\", \
        \"radius\": \"2000\", \
        \"plug_type\": \"bullet_2mm\" \
      }"
    
    const discoveryEndPoint = 'discovery_endpoint_here';
    
    fetch(discoveryEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        start_at: '1513005534000',
        latitude: '32.787793',
        longitude: '-79.935005',
        radius: '2000',
        plug_type: 'bullet_2mm',
      }),
    });
    
    import requests
    payload = {
        "start_at": "1519093577681",
        "latitude": "32.787793",
        "longitude": "-79.935005",
        "radius": "2000",
        "plug_type": "bullet_2mm",
      }
    requests.post("discovery_endpoint_here", data=payload)
    

    In response, a charging station might send back a bid with a price per kWh.

    Bid

    curl "bidding_endpoint_here" \
      --data "{ \
        \"need_id\": \"ae7bd8f67f3089c\", \
        \"expires_at\": \"1513005539000\", \
        \"price\": \"2300000000000000000,30000000000000000\", \
        \"price_type\": \"kwh,kwh\", \
        \"price_description\": \"Price per kWh,VAT per kWh\", \
        \"latitude\": \"32.785889\", \
        \"longitude\": \"-79.935569\", \
        \"available_from\": \"1513005534000\", \
        \"available_until\": \"1513091934000\" \
      }"
    
    const biddingEndPoint = 'bidding_endpoint_here';
    
    fetch(biddingEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        need_id: 'ae7bd8f67f3089c',
        expires_at: '1513005539000',
        price: '2300000000000000000,30000000000000000',
        price_type: 'kwh,kwh',
        price_description: 'Price per kWh,VAT per kWh',
        latitude: '32.785889',
        longitude: '-79.935569',
        available_from: '1513005534000',
        available_until: '1513091934000',
      }),
    });
    
    import requests
    payload = {
        "need_id": "ae7bd8f67f3089c",
        "expires_at": "1519093577681",
        "price": "2300000000000000000,30000000000000000",
        "price_type": "kwh,kwh",
        "price_description": "Price per kWh,VAT per kWh",
        "latitude": "32.785889",
        "longitude": "-79.935569",
        "available_from": "1513005534000",
        "available_until": "1513091934000",
      }
    requests.post("bidding_endpoint_here", data=payload)
    

    Need

    A statement of need for drone charging services. Typically this will be sent by a drone that is looking for a charging station around certain coordinates.

    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 "{ \
        \"start_at\": \"1513005534000\", \
        \"latitude\": \"32.787793\", \
        \"longitude\": \"-79.935005\", \
        \"radius\": \"10000\", \
        \"drone_type\": \"DXY M6000\", \
        \"battery_capacity\": \"4500\", \
        \"charge_level\": \"23\", \
        \"plug_type\": \"bullet_4mm\", \
        \"height\": \"50\", \
        \"width\": \"30\", \
        \"length\": \"30\", \
        \"weight\": \"2500\", \
        \"charge_pad_type\": \"enclosed\", \
        \"droneport_protection_level\": \"56\" \
        \"energy_source\": \"solar\" \
      }"
    
    const discoveryEndPoint = "discovery_endpoint_here";
    
    fetch(discoveryEndPoint, {
      method: "POST",
      body: JSON.stringify({
        "start_at": "1513005534000",
        "latitude": "32.787793",
        "longitude": "-79.935005",
        "radius": "10000",
        "drone_type": "DXY M6000",
        "battery_capacity": "4500",
        "charge_level": "23",
        "plug_type": "bullet_4mm",
        "height": "50",
        "width": "30",
        "length": "30",
        "weight": "2500",
        "charge_pad_type": "enclosed",
        "droneport_protection_level": "56"
        "energy_source": "solar",
      })
    });
    
    import requests
    payload = {
        "start_at": "1513005534000",
        "latitude": "32.787793",
        "longitude": "-79.935005",
        "radius": "10000",
        "drone_type": "DXY M6000",
        "battery_capacity": "4500",
        "charge_level": "23",
        "plug_type": "bullet_4mm",
        "height": "50",
        "width": "30",
        "length": "30",
        "weight": "2500",
        "charge_pad_type": "enclosed",
        "droneport_protection_level": "56"
        "energy_source": "solar",
      }
    requests.post("discovery_endpoint_here", data=payload)
    
    start_at
    optional
    The time at which the requester would like to arrive at charging station (if undefined, the arrival time will be ASAP). Specified as time in seconds since Epoch/Unix Time
    latitude
    required
    The latitude coordinate around which to search
    longitude
    required
    The longitude coordinate around which to search
    radius
    required
    Radius in meters around the search coordinates to limit the search to. Specified as an integer
    drone_type
    optional
    The manufacturer and/or the model number of the drone. An unformatted string
    battery_capacity
    optional
    The capacity of the drone's battery, specified in mAh
    charge_level
    optional
    The drone's current battery charge level, as it was by the time the request was sent. Specified in %
    plug_type
    required
    The drone's plug type ID. See Plug Types for possible values
    height
    optional
    The minimum height clearance that the drone requires from the charging station. Specified as an integer representing centimeters
    width
    optional
    The minimum width clearance that the drone requires from the charging station. Specified as an integer representing centimeters
    length
    optional
    The minimum length clearance that the drone requires from the charging station. Specified as an integer representing centimeters
    weight
    optional
    The weight of the drone. Charging stations that cannot support a drone weighing this much should not respond. Specified as an integer representing grams
    charge_pad_type
    optional
    The type of charging pad. Accepted values can be either open (for an outdoor pad) or enclosed (for an enclosed charging pad)
    droneport_protection_level
    optional
    Charging stations may also provide protection services for drones. This parameter specifies the level of protection given to a drone. See possible codes under Drone Protection Level
    energy_source
    optional
    Limit the request to only receive bids from charging stations using a specific source of the energy. Specified as an energy source id. See Energy Sources

    Bid

    A bid to provide a charging service. Typically sent from a charging station to a drone.

    Arguments

    Post request to a local/remote bidding endpoint

    curl "bidding_endpoint_here" \
      --data "{ \
        \"need_id\": \"ae7bd8f67f3089c\", \
        \"expires_at\": \"1513005539000\", \
        \"price\": \"2300000000000000000,30000000000000000\", \
        \"price_type\": \"kwh,kwh\", \
        \"price_description\": \"Price per kWh,VAT per kWh\", \
        \"latitude\": \"32.785889\", \
        \"longitude\": \"-79.935569\", \
        \"available_from\": \"1513005534000\", \
        \"available_until\": \"1513091934000\", \
        \"location_name\": \"IKEA parking lot B\", \
        \"location_name_lang\": \"eng\", \
        \"location_house_number\": \"372\", \
        \"location_street\": \"King\", \
        \"location_city\": \"Charleston\", \
        \"location_postal_code\": \"29401\", \
        \"location_county\": \"Charleston\", \
        \"location_state\": \"SC\", \
        \"location_country\": \"USA\", \
        \"height\": \"5000\", \
        \"width\": \"1000\", \
        \"length\": \"1000\", \
        \"weight\": \"100000\", \
        \"plug_types\": \"bullet_2mm,bullet_3_5mm,bullet_4mm\", \
        \"energy_source\": \"solar\", \
        \"provider\": \"City Charge\", \
        \"manufacturer\": \"GeoCharge\", \
        \"model\": \"gc2910\" \
      }"
    
    const biddingEndPoint = 'bidding_endpoint_here';
    
    fetch(biddingEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        need_id: 'ae7bd8f67f3089c',
        expires_at: '1513005539000',
        price: '2300000000000000000,30000000000000000',
        price_type: 'kwh,kwh',
        price_description: 'Price per kWh,VAT per kWh',
        latitude: '32.785889',
        longitude: '-79.935569',
        available_from: '1513005534000',
        available_until: '1513091934000',
        location_name: 'IKEA parking lot B',
        location_name_lang: 'eng',
        location_house_number: '372',
        location_street: 'King',
        location_city: 'Charleston',
        location_postal_code: '29401',
        location_county: 'Charleston',
        location_state: 'SC',
        location_country: 'USA',
        height: '5000',
        width: '1000',
        length: '1000',
        weight: '100000',
        plug_types: 'bullet_2mm,bullet_3_5mm,bullet_4mm',
        energy_source: 'solar',
        provider: 'City Charge',
        manufacturer: 'GeoCharge',
        model: 'gc2910',
      }),
    });
    
    import requests
    payload = {
        "need_id": "ae7bd8f67f3089c",
        "expires_at": "1513005539000",
        "price": "2300000000000000000,30000000000000000",
        "price_type": "kwh,kwh",
        "price_description": "Price per kWh,VAT per kWh",
        "latitude": "32.785889",
        "longitude": "-79.935569",
        "available_from": "1513005534000",
        "available_until": "1513091934000",
        "location_name": "IKEA parking lot B",
        "location_name_lang": "eng",
        "location_house_number": "372",
        "location_street": "King",
        "location_city": "Charleston",
        "location_postal_code": "29401",
        "location_county": "Charleston",
        "location_state": "SC",
        "location_country": "USA",
        "height": "5000",
        "width": "1000",
        "length": "1000",
        "weight": "100000",
        "plug_types": "bullet_2mm,bullet_3_5mm,bullet_4mm",
        "energy_source": "solar",
        "provider": "City Charge",
        "manufacturer": "GeoCharge",
        "model": "gc2910",
      }
    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
    latitude
    required
    The latitude coordinate of the charging station
    longitude
    required
    The longitude coordinate of the charging station
    available_from
    required
    The time from which the charging station can be made available. Specified as time in seconds since Epoch/Unix Time
    available_until
    optional
    The time until which the charging station can be made available. Specified as time in seconds since Epoch/Unix Time
    location_name
    optional
    A human readable name/description of the charging station location (e.g., Lund Train Station parking)
    location_name_lang
    optional
    The language used in location_name. Specified using the 3 letter ISO 639-3 language code
    location_house_number
    optional
    The house number where the station is located
    location_street
    optional
    The street name where the station is located
    location_city
    optional
    The city where the station is located
    location_postal_code
    optional
    The postal code where the station is located
    location_county
    optional
    The county where the station is located
    location_state
    optional
    The state where the station is located
    location_country
    optional
    The country where the station is located
    height
    optional
    The maximum drone height this station can accommodate. Specified as an integer representing centimeters
    width
    optional
    The maximum drone width this station can accommodate. Specified as an integer representing centimeters
    length
    optional
    The maximum drone length this station can accommodate. Specified as an integer representing centimeters
    weight
    optional
    The maximum drone weight this station can accommodate. Specified as an integer representing grams
    plug_types
    required
    A list of plug types available at this charging station. Specified as a comma separated list of plug type ids. See Plug Types for available values
    energy_source
    optional
    The source of the energy used by this charging station. Specified as an energy source id. See Energy Sources
    provider
    optional
    Name of the service provider or charging network operating this charging station
    manufacturer
    optional
    Name of the manufacturer of this charging station
    model
    optional
    Name of the model of this charging station

    Plug Types

    Below is a list of all the supported drone plug types.

    Plug Type ID Name Amp Tolerance to Plug Type
    jst_739 JST Connector 739 Up to 5 Amps
    bullet_2mm 2mm bullet connectors Up to 20 Amps
    bullet_3_5mm 3.5mm bullet connectors Up to 40 Amps
    xt_60_420 XT60 connectors 420 Up to 60 Amps
    t_plug_204 T-Plug 204 Up to 60 Amps
    ec3_306 EC3 connector 306 Up to 60 Amps
    bullet_4mm 4mm bullet connectors Up to 70 Amps
    ec5_678 EC5 connectors 678 Up to 120 Amps
    bullet_6mm 6mm bullet connectors Up to 120 Amps
    bullet_8mm 8mm bullet connectors Up to 200 Amps

    Energy Sources

    The energy source used by the charging station.

    Source Description
    grid Connected to the electrical grid and using an unspecified energy source, or an unspecified mix of energy source
    renewable Uses 100% renewable energy of an unspecified source, or a mix of different renewable energy sources
    solar Uses 100% solar energy
    wind Uses 100% wind energy
    hydro Uses 100% hydropower energy
    geothermal Uses 100% geothermal energy

    Drone Protection Level

    A charging station may also 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.

    Rating Code IP Rating Solid Particle Protection Liquid Ingress Protection
    54 IP54 Protected from limited dust ingress Protected from water spray from any direction, limited ingress protection
    55 IP55 Protected from limited dust ingress Protected from low pressure water jets from any direction, limited ingress protection
    56 IP56 Protected from limited dust ingress Protected from high pressure water jets from any direction, limited ingress protection
    57 IP57 Protected from limited dust ingress Protected from immersion between 15 centimeters and 1 meter in depth, limited ingress protection
    58 IP58 Protected from limited dust ingress Protected from long term immersion up to a specified pressure, limited ingress protection
    60 IP60 Protected from total dust ingress Not protected from liquids, limited ingress protection
    61 IP61 Protected from total dust ingress Protected from condensation, limited ingress protection
    62 IP62 Protected from total dust ingress Protected from water spray less than 15 degrees from vertical, limited ingress protection
    63 IP63 Protected from total dust ingress Protected from water spray less than 60 degrees from vertical, limited ingress protection
    64 IP64 Protected from total dust ingress Protected from water spray from any direction, limited ingress protection
    65 IP65 Protected from total dust ingress Protected from low pressure water jets from any direction, limited ingress protection
    66 IP66 Protected from total dust ingress Protected from high pressure water jets from any direction, limited ingress protection
    67 IP67 Protected from total dust ingress Protected from immersion between 15 centimeters and 1 meter in depth, limited ingress protection
    68 IP68 Protected from total dust ingress Protected from long term immersion up to a specified pressure, limited ingress protection
    69k IP69K Protected from total dust ingress Protected from steam-jet cleaning, limited ingress protection

    Price Types

    Price types and their unique identifier.

    Price Type Description
    kwh Cost per kWh
    second Cost per second
    minute Cost per minute
    hour Cost per hour
    day Cost per day
    week Cost per week
    flat The listed price is a flat price