Skip to content

JSON Protocol Reference

This is a comprehensive reference on how to effectively utilise the JSON interface. You will find detailed explanations and practical examples that illustrate how to interact with and leverage the capabilities of the JSON interface.

Getting State

Get Version

Sending this JSON object will request the current version information

Command

{
 "@type": "type.googleapis.com/sonardyne.api.pub.common.VersionRequest"
}

Response

{
 "@type": "type.googleapis.com/sonardyne.api.pub.common.VersionResponse",
 "major": 2,
 "minor": 0,
 "patch": 0
}
Get Configuration

Sending this JSON object will request the current state of the instrument

Command

{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationRequest",
  "requestor": "Source of Request"
}

Response

{
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1894856.99781867
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.AidingConfiguration",
   "enable_gnss": {
    "value": "ENABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_xpos": {
    "value": "ENABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_usbl": {
    "value": "DISABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   }
  },
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.SoundVelocityConfiguration",
   "sound_velocity_type": {
    "value": "EXTERNAL",
    "valid_values": [
     "EXTERNAL",
     "INTERNAL_SALINITY",
     "INTERNAL_MANUAL"
    ]
   },
   "manual_salinity_value_parts_per_thousand": {
    "value": 32.1,
    "min": 0,
    "max": 40
   },
   "manual_velocity_value_metres_per_second": {
    "value": 1500,
    "min": 1400,
    "max": 1600
   }
  },
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.DvlConfiguration",
   "update_rate": {
    "value": "FIXED_1HZ",
    "valid_values": [
     "MAX_RATE",
     "FIXED_1HZ",
     "FIXED_2HZ",
     "FIXED_5HZ",
     "FIXED_10HZ",
     "TRIGGER_RISING",
     "TRIGGER_FALLING"
    ]
   }
  }
 ]
}

Setting State

Set State (Introduction)

Command

The root JSON object contains two properties :'@type' and configuration

  • @type is a string property with the value type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope
  • configuration is an array which can contain one or more configuration types, each configuration has its own @type property
  • {ConfigurationType} shown in the command below is a placeholder and should be replaced with a specific configuration type. This allows the configuration array to hold various types of configuration objects, each identified by their own type
{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
  "configuration": [
    {
    "@type": "type.googleapis.com/sonardyne.api.pub.configuration.{ConfigurationType}"             
    }
  ]
}

Response

The response message is also a type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope type sharing the same properties as the command structure. The array of returned {ConfigurationType} will correspond to the configurations sent.

{
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1898031.49847554
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.{ConfigurationType}",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },      
  }
 ]
}

Valid Values

All returned values where applicable within a configuration will contain an array with the valid range of values for that property, for example : 
"update_rate": {
    "value": "FIXED_1HZ",
    "valid_values": [
     "MAX_RATE",
     "FIXED_1HZ",
     "FIXED_2HZ",
     "FIXED_5HZ",
     "FIXED_10HZ",
     "TRIGGER_RISING",
     "TRIGGER_FALLING"
    ]
   }

Nested Result

Each nested {ConfigurationType} response will contain a 'result' property. This will indicate the success state of all command requests
  • success A string indicating command success [SUCCESS,FAILURE,INVALID,RESTRICTED]
  • message A string for any additional messages that may be pertinent if the command is not successful
"result": {
   "success": "SUCCESS",
   "message": ""
  }
Set Aiding Configuration

Command & Parameters

  • enableGnss valid values [ENABLED,DISABLED]
  • enableXpos valid values [ENABLED,DISABLED]
  • enableUsbl valid values [ENABLED,DISABLED]
{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
  "configuration": [
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.AidingConfiguration",
      "enableGnss": {
        "value": "ENABLED"
      },
      "enableXpos": {
        "value": "DISABLED"
      },
      "enableUsbl": {
        "value": "DISABLED"
      }
    }
  ]
}
Note : Not all properties need to be set, individual properties can be configured separately

Response

{
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1919664.02866484
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.AidingConfiguration",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "enable_gnss": {
    "value": "ENABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_xpos": {
    "value": "DISABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_usbl": {
    "value": "DISABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   }
  }
 ]
}
Set DVL Configuration

Command & Parameters

  • updateRate valid values [MAX_RATE, FIXED_1HZ, FIXED_2HZ, FIXED_5HZ, FIXED_10HZ, TRIGGER_RISING, TRIGGER_FALLING]
{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
  "configuration": [
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.DvlConfiguration", 
      "updateRate": {
        "value": "FIXED_1HZ"
      }
    }
  ]
}
Note : Not all properties need to be set, individual properties can be configured separately

Response

{
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1916074.48673176
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.DvlConfiguration",   
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "update_rate": {
    "value": "FIXED_1HZ",
    "valid_values": [
     "MAX_RATE",
     "FIXED_1HZ",
     "FIXED_2HZ",
     "FIXED_5HZ",
     "FIXED_10HZ",
     "TRIGGER_RISING",
     "TRIGGER_FALLING"
    ]
   }
  }
 ]
Set Sound Velocity Configuration

Command & Parameters

  • soundVelocityType valid values are [EXTERNAL, INTERNAL_SALINITY, INTERNAL_MANUAL]
  • manualSalinityValuePartsPerThousand valid values are 0 to 40
  • manualVelocityValueMetresPerSecond valid values are 1400 to 1600
{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
  "configuration": [
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.SoundVelocityConfiguration",
      "soundVelocityType": {
        "value": "EXTERNAL"
      },
      "manualSalinityValuePartsPerThousand": {
        "value": 40.0
      },
      "manualVelocityValueMetresPerSecond": {
        "value": 1500.0
      }
    }
  ]
}
Note : Not all properties need to be set, individual properties can be configured separately

Response

{
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1918491.19956508
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.SoundVelocityConfiguration",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "sound_velocity_type": {
    "value": "EXTERNAL",
    "valid_values": [
     "EXTERNAL",
     "INTERNAL_SALINITY",
     "INTERNAL_MANUAL"
    ]
   },
   "manual_salinity_value_parts_per_thousand": {
    "value": 40,
    "min": 0,
    "max": 40
   },
   "manual_velocity_value_metres_per_second": {
    "value": 1500,
    "min": 1400,
    "max": 1600
   }
  }
 ]
}
Set Multiple Configurations Simultaneously

Command

The following command show how to embed multiple configuration objects in the configuration array 
{
  "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
  "configuration": [
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.AidingConfiguration",       
      "enableGnss": {
        "value": "ENABLED"
      },
      "enableXpos": {
        "value": "DISABLED"
      },
      "enableUsbl": {
        "value": "DISABLED"
      }
    },
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.SoundVelocityConfiguration",
      "soundVelocityType": {
        "value": "EXTERNAL"
      },
      "manualSalinityValuePartsPerThousand": {
        "value": 40.0
      },
      "manualVelocityValueMetresPerSecond": {
        "value": 1500.0
      }
    },
    {
      "@type": "type.googleapis.com/sonardyne.api.pub.configuration.DvlConfiguration",
      "updateRate": {
        "value": "FIXED_1HZ"
      }
    }
  ]
}

Response

The response show how multiple responses being delivered, each one with a result object indicating success state 
 "@type": "type.googleapis.com/sonardyne.api.pub.configuration.ConfigurationEnvelope",
 "timestamp": {
  "common_time_seconds": 0,
  "instrument_time_seconds": 1922242.57665971
 },
 "configuration": [
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.AidingConfiguration",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "enable_gnss": {
    "value": "ENABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_xpos": {
    "value": "DISABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   },
   "enable_usbl": {
    "value": "DISABLED",
    "valid_values": [
     "ENABLED",
     "DISABLED"
    ]
   }
  },
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.SoundVelocityConfiguration",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "sound_velocity_type": {
    "value": "EXTERNAL",
    "valid_values": [
     "EXTERNAL",
     "INTERNAL_SALINITY",
     "INTERNAL_MANUAL"
    ]
   },
   "manual_salinity_value_parts_per_thousand": {
    "value": 40,
    "min": 0,
    "max": 40
   },
   "manual_velocity_value_metres_per_second": {
    "value": 1500,
    "min": 1400,
    "max": 1600
   }
  },
  {
   "@type": "type.googleapis.com/sonardyne.api.pub.configuration.DvlConfiguration",
   "result": {
    "success": "SUCCESS",
    "message": ""
   },
   "update_rate": {
    "value": "FIXED_1HZ",
    "valid_values": [
     "MAX_RATE",
     "FIXED_1HZ",
     "FIXED_2HZ",
     "FIXED_5HZ",
     "FIXED_10HZ",
     "TRIGGER_RISING",
     "TRIGGER_FALLING"
    ]
   }
  }
 ]
}