NAV Navbar
javascript typescript
  • Vessel Charging Protocol
  • Need
  • Need filter
  • Bid
  • Starting
  • Request Status
  • Provider Status
  • Vessel Status
  • Charging Arrival
  • Charging Started
  • Charging Complete
  • Energy Sources
  • Amenities
  • Price Types
  • Vessel Charging

    Vessel Charging Protocol

    The communication protocol for vessel charging describes the format of a request for a charging service (need), and the response sent by a charging provider (bid).

    For example, an autonomous boat might search for charging stations within 2 km of the given coordinates that are capable of docking a 1200 kg boat.

    In response, a charging station might send back a bid with a price for the service, the opening and closing times, and the full list of services it offers.

    Need

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

    This request is sent to the discovery engine which broadcasts the need to DAV identities that can provide this service. Bids are later received in response.

    Arguments

    const { SDKFactory } = require('dav-js');
    const { NeedParams, enums } = require('dav-js/dist/vessel-charging');
    const DAV = SDKFactory({
      apiSeedUrls,
      kafkaSeedUrls,
    });
    const boat = await DAV.getIdentity(boatDavId);
    
    const needParams = new NeedParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
      radius: 20,
      startAt: 1538995253092,
      dimensions: {
        length: 50,
        width: 15,
        height: 20,
      },
      weight: 50000,
      batteryCapacity: 4,
      currentBatteryCharge: 45,
      energySource: enums.EnergySources.Solar,
      amenities: [enums.Amenities.Docking],
    });
    const need = await boat.publishNeed(needParams);
    
    import { SDKFactory } from 'dav-js';
    import { NeedParams, enums } from 'dav-js/dist/vessel-charging';
    const DAV = SDKFactory({
      apiSeedUrls,
      kafkaSeedUrls,
    });
    const boat = await DAV.getIdentity(boatDavId);
    
    const needParams = new NeedParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
      radius: 20,
      startAt: 1538995253092,
      dimensions: {
        length: 50,
        width: 15,
        height: 20,
      },
      weight: 50000,
      batteryCapacity: 4,
      currentBatteryCharge: 45,
      energySource: enums.EnergySources.Solar,
      amenities: [enums.Amenities.Docking],
    });
    const need = await boat.publishNeed(needParams);
    
    location
    required
    The coordinates around which to search
    radius
    required
    Radius in meters around the coordinates in which to listen for bids. Specified as an integer
    startAt
    optional
    The time at which the requester would like to arrive at charger (if undefined, the arrival time will be ASAP). Specified as time in seconds since Epoch/Unix Time
    dimensions
    optional
    The minimum length, width, and height clearance that this vessel requires from the charger. Specified as an object containing integers representing centimeters
    weight
    optional
    The weight of this vessel. Specified as an integer representing grams
    batteryCapacity
    optional
    The vessel's total battery capacity, specified in kWh
    currentBatteryCharge
    optional
    The vessel's current battery charge level, as it was at the time the request was sent. Specified as an integer denoting percentage of full capacity
    energySource
    optional
    Limit the request to only receive bids from chargers using a specific source of energy. Specified as an energy source id. See Energy Sources
    amenities
    optional
    A list of amenities that need to be present at charging station. Specified as an array of amenity ids. See Amenities

    Need filter

    Begin listening for incoming needs that match certain requirements. Typically this will be a charging station subscribing to incoming needs from electric boats.

    Arguments

    const { SDKFactory } = require('dav-js');
    const { NeedFilterParams } = require('dav-js/dist/vessel-charging');
    const DAV = SDKFactory({
      apiSeedUrls,
      kafkaSeedUrls,
    });
    const charger = await DAV.getIdentity(chargerDavId);
    
    const needFilterParams = new NeedFilterParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
      radius: 1000,
      maxDimensions: {
        length: 120,
        width: 80,
        height: 100,
      },
    });
    const needs = await charger.needsForType(needFilterParams);
    
    import { SDKFactory } from 'dav-js';
    import { NeedFilterParams } from 'dav-js/dist/vessel-charging';
    const DAV = SDKFactory({
      apiSeedUrls,
      kafkaSeedUrls,
    });
    const charger = await DAV.getIdentity(chargerDavId);
    
    const needFilterParams = new NeedFilterParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
      radius: 1000,
      maxDimensions: {
        length: 120,
        width: 80,
        height: 100,
      },
    });
    const needs = await charger.needsForType(needFilterParams);
    
    location
    required
    The coordinates around which to listen for bids
    radius
    required
    Radius in meters around the coordinates in which to listen for bids. Specified as an integer
    maxDimensions
    optional
    The maximum length, width, and height clearance that this charger can accomodate. Specified as an object containing integers representing centimeters

    Bid

    A bid to provide a charging service. Typically sent from a charger to an electric boat.

    Arguments

    const { BidParams } = require('dav-js/dist/vessel-charging');
    
    needs.subscribe(need => {
      const bidParams = new BidParams({
        ttl: Date.now() + 3600000,
        price: [
          '15000000000000000000',
          { amount: '1000000000000000000', type: 'flat', description: 'Tax' },
        ],
        entranceLocation: {
          lat: 32.050382,
          long: 34.766149,
        },
        exitLocation: {
          lat: 32.050382,
          long: 34.766149,
        },
        locationName: 'Marine Programs Naval Science'
        locationNameLang: 'eng'
        locationCity: 'Vallejo',
        locationPostalCode: '94590',
        locationCounty: 'Solano',
        locationState: 'CA',
        locationCountry: 'USA',
        availableFrom: Date.now(),
        availableUntil: Date.now() + 3600000,
        energySource: EnergySources.Hydro,
        amenities: [Amenities.Park],
        provider: 'HoldenCharge',
        manufacturer: 'Holden Tech LLC',
        model: 'MegaBolt',
      });
      const bid = await need.createBid(bidParams);
    });
    
    import { BidParams } from 'dav-js/dist/vessel-charging';
    
    needs.subscribe((need: Need<NeedParams>) => {
      const bidParams = new BidParams({
        ttl: Date.now() + 3600000,
        price: [
          '15000000000000000000',
          { amount: '1000000000000000000', type: 'flat', description: 'Tax' },
        ],
        entranceLocation: {
          lat: 32.050382,
          long: 34.766149,
        },
        exitLocation: {
          lat: 32.050382,
          long: 34.766149,
        },
        locationName: 'Marine Programs Naval Science'
        locationNameLang: 'eng'
        locationCity: 'Vallejo',
        locationPostalCode: '94590',
        locationCounty: 'Solano',
        locationState: 'CA',
        locationCountry: 'USA',
        availableFrom: Date.now(),
        availableUntil: Date.now() + 3600000,
        energySource: EnergySources.Hydro,
        amenities: [Amenities.Park],
        provider: 'HoldenCharge',
        manufacturer: 'Holden Tech LLC',
        model: 'MegaBolt',
      });
      const bid = await need.createBid(bidParams);
    });
    
    ttl
    optional
    This bid will expire at this time. Specified as time in seconds since Epoch/Unix Time
    price
    required
    A single price or an array containing prices. If an array is given, all the prices will be charged (e.g., a price per kWh plus a flat rate tax). Each price is specified as either an string representing Vinci, or a price object containing amount, price type, and an optional description
    1 DAV == 1e18 Vinci == 1000000000000000000 Vinci
    entranceLocation
    optional
    The coordinates of the charger entrance
    exitLocation
    optional
    The coordinates of the exit from to the charger
    locationName
    optional
    A human readable name/description of the charger location (e.g., Cal Maritime Dock C)
    locationNameLang
    optional
    The language used in location_name. Specified using the 3 letter ISO 639-3 language code
    locationHouseNumber
    optional
    The house number where the station is located
    locationStreet
    optional
    The street name where the station is located
    locationCity
    optional
    The city where the station is located
    locationPostalCode
    optional
    The postal code where the station is located
    locationCounty
    optional
    The county where the charger is located
    locationState
    optional
    The state where the charger is located
    locationCountry
    optional
    The country where the charger is located
    availableFrom
    required
    The time from which the charger can be made available for the vessel requesting a charge. Specified as time in seconds since Epoch/Unix Time
    availableUntil
    optional
    The time until which the charger can be made available for the vessel requesting a charge. Specified as time in seconds since Epoch/Unix Time
    energySource
    optional
    The source of the energy used by this charger. Specified as an energy source id. See Energy Sources
    amenities
    optional
    A list of amenities that are present at this charger. Specified as an array of amenity ids. See Amenities
    provider
    optional
    Name of the service provider or charging network operating this charger
    manufacturer
    optional
    Name of the manufacturer of this charger
    model
    optional
    Name of the model of this charger

    Starting

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

    Arguments

    const { StartingMessageParams } = require('dav-js/dist/vessel-charging');
    
    const startingMessage = new StartingMessageParams();
    mission.sendMessage(startingMessage);
    
    import { StartingMessageParams } from 'dav-js/dist/vessel-charging';
    
    const startingMessageParams = new StartingMessageParams();
    mission.sendMessage(startingMessage);
    
    None

    Request Status

    A request message sent by either party, asking the other party for a status update

    Arguments

    const { StatusRequestMessageParams } = require('dav-js/dist/vessel-charging');
    
    const statusRequestMessage = new StatusRequestMessageParams({});
    mission.sendMessage(statusRequestMessage);
    
    import { StatusRequestMessageParams } from 'dav-js/dist/vessel-charging';
    
    const statusRequestMessage = new StatusRequestMessageParams({});
    mission.sendMessage(statusRequestMessage);
    
    None

    Provider Status

    A status update sent by the service provider (usually a charging station) to the vessel

    Arguments

    const { ProviderStatusMessageParams } = require('dav-js/dist/vessel-charging');
    
    const providerStatusMessage = new ProviderStatusMessageParams({
      chargeCompletionEstimatedTime: Date.now() + 5000,
    });
    mission.sendMessage(providerStatusMessage);
    
    import { ProviderStatusMessageParams } from 'dav-js/dist/vessel-charging';
    
    const providerStatusMessage = new ProviderStatusMessageParams({
      chargeCompletionEstimatedTime: Date.now() + 5000,
    });
    mission.sendMessage(providerStatusMessage);
    
    chargeCompletionEstimatedTime
    optional
    The estimated time at which charging will be complete. Specified as time in seconds since Epoch/Unix Time

    Vessel Status

    A status update sent by the service requester (the vessel) to the service provider (charger)

    Arguments

    const { VesselStatusMessageParams } = require('dav-js/dist/vessel-charging');
    
    const vesselStatusMessage = new VesselStatusMessageParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
    });
    mission.sendMessage(vesselStatusMessage);
    
    import { VesselStatusMessageParams } from 'dav-js/dist/vessel-charging';
    
    const vesselStatusMessage = new VesselStatusMessageParams({
      location: {
        lat: 32.050382,
        long: 34.766149,
      },
    });
    mission.sendMessage(vesselStatusMessage);
    
    location
    optional
    The current coordinates of the vehicle's location

    Charging Arrival

    A message sent by the service requester (the vessel) to the service provider (charger), notifying it that it has arrived at the charger's location

    Arguments

    const { ChargingArrivalMessageParams } = require('dav-js/dist/vessel-charging');
    
    const chargingArrivalMessage = new ChargingArrivalMessageParams();
    mission.sendMessage(chargingArrivalMessage);
    
    import { ChargingArrivalMessageParams } from 'dav-js/dist/vessel-charging';
    
    const chargingArrivalMessage = new ChargingArrivalMessageParams();
    mission.sendMessage(chargingArrivalMessage);
    
    None

    Charging Started

    A message sent by the service provider to the service requester, notifying it that charging has begun

    Arguments

    import { ChargingStartedMessageParams } from 'dav-js/dist/vessel-charging';
    
    const chargingStartedMessage = new ChargingStartedMessageParams();
    mission.sendMessage(chargingStartedMessage);
    
    const { ChargingStartedMessageParams } = require('dav-js/dist/vessel-charging');
    
    const chargingStartedMessage = new ChargingStartedMessageParams();
    mission.sendMessage(chargingStartedMessage);
    
    None

    Charging Complete

    A message sent by the service provider to the service requester, notifying it that charging has completed

    Arguments

    const {
      ChargingCompleteMessageParams,
    } = require('dav-js/dist/vessel-charging');
    
    const chargingCompleteMessage = new ChargingCompleteMessageParams();
    mission.sendMessage(chargingCompleteMessage);
    
    import { ChargingCompleteMessageParams } from 'dav-js/dist/vessel-charging';
    
    const chargingCompleteMessage = new ChargingCompleteMessageParams();
    mission.sendMessage(chargingCompleteMessage);
    
    None

    Energy Sources

    The energy source used by the charger.

    Level 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% hydro power energy
    geothermal Uses 100% geothermal energy

    Amenities

    A list of amenities can be included in both requests and responses.

    ID Description
    1 Lodging
    2 Dining
    3 Restrooms
    4 Docking
    5 Park
    6 WiFi
    7 Shopping
    8 Grocery

    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