VSM C++ SDK
Vehicle Specific Modules SDK
UCS-VSM protocol example

Sample scenario

This sample demonstrates UCS-VSM protocol in action.

Scenario description

  • We use sample vehicle with the following features:
    • "mypilot" autopilot on quad frame
    • It reports gps coordinates, icao code and flight mode in telemetry
    • It supports camera_trigger, "return_to_home", "mission_upload", takeoff and "auto" as standalone commands.
    • It supports camera_trigger, waypoint and takeoff as mission items
  • Demonstrate vehicle registration, telemetry, mission upload and responses to requests.

Protocol control flow

  1. UCS establishes connection with VSM.

    VSM sends VSM notification message and waits for UCS notification message before sending anything into this connection.

  2. UCS sends UCS notification message.

    Main purpose is to tell VSM the UCS ID which VSM will use to detect duplicate connections from the same UCS instance. It is a Vsm_message with register_peer payload. VSM notes the UCS id and if this is the first connection from ucs then it will start communicating. If VSM already has a connection with this id it will keep the connection idle and use it only if other connection breaks.

  3. VSM sends Vehicle registration message for each already connected vehicle.
  4. VSM detects new vehicle. VSM sends Vehicle registration message to all connected servers.
  5. VSM starts sending telemetry packets from vehicle. See Telemetry message.
  6. VSM reports command availability to UCS via Command availability message.
  7. User issues Camera trigger command for vehicle.
  8. VSM sends successful command completion via Camera trigger response.
  9. User uploads mission to the vehicle. VSM receives Mission upload command.

    Mission consists of takeoff command and two waypoints.

  10. VSM fails mission with Mission upload response.

    VSM uses custom error reporting feature to send error description.

Sample messages

UCS notification message

Vsm_message from UCS to VSM:

device_id: 0
register_peer {
  peer_id: 341235662
}

VSM notification message

Vsm_message from VSM to UCS:

device_id: 0
register_peer {
  peer_id: 3337720787
}

Vehicle registration message

Vsm_message from VSM to UCS:

device_id: 131
register_device {
  begin_of_epoch: 1471529736786
  properties {
    name: "system_id"
    value {
      int_value: 1133413007
    }
  }
  register_vehicle {
    vehicle_serial: "MC13"
    vehicle_name: "MyCopter"
    frame_type: "generic_quad_x"
    port_name: "tcp:127.0.0.1:14556"
    vehicle_type: VEHICLE_TYPE_FIXED_WING
    register_flight_controller {
      autopilot_type: "mypilot"
      autopilot_serial: "123456"
      telemetry_fields {
        name: "native_flight_mode"
        field_id: 5
        semantic: FIELD_SEMANTIC_ENUM
        enumeration {
          id: 3
          description: "Auto"
        }
        enumeration {
          id: 2
          description: "Loiter"
        }
        enumeration {
          id: 1
          description: "Guided"
        }
        enumeration {
          id: 0
          description: "Stabilize"
        }
      }
      telemetry_fields {
        name: "latitude"
        field_id: 19
        semantic: FIELD_SEMANTIC_LATITUDE
      }
      telemetry_fields {
        name: "longitude"
        field_id: 20
        semantic: FIELD_SEMANTIC_LONGITUDE
      }
      telemetry_fields {
        name: "altitude_raw"
        field_id: 13
        semantic: FIELD_SEMANTIC_ALTITUDE_RAW
      }

      commands {
        name: "takeoff"
        id: 49
        available_in_mission: true
        available_as_command: true
      }
      commands {
        name: "auto"
        id: 28
        available_in_mission: false
        available_as_command: true
      }
      commands {
        name: "rth"
        id: 48
        available_in_mission: false
        available_as_command: true
      }
      commands {
        name: "waypoint"
        id: 50
        parameters {
          name: "ground_elevation"
          field_id: 59
          semantic: FIELD_SEMANTIC_GROUND_ELEVATION
        }
        parameters {
          name: "heading"
          field_id: 58
          semantic: FIELD_SEMANTIC_HEADING
        }
        parameters {
          name: "vertical_speed"
          field_id: 57
          semantic: FIELD_SEMANTIC_VERTICAL_SPEED
        }
        parameters {
          name: "ground_speed"
          field_id: 56
          semantic: FIELD_SEMANTIC_GROUND_SPEED
        }
        parameters {
          name: "altitude_origin"
          field_id: 55
          semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
        }
        parameters {
          name: "acceptance_radius"
          field_id: 54
          semantic: FIELD_SEMANTIC_ACCEPTANCE_RADIUS
        }
        parameters {
          name: "altitude_amsl"
          field_id: 53
          semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
        }
        parameters {
          name: "longitude"
          field_id: 52
          semantic: FIELD_SEMANTIC_LONGITUDE
        }
        parameters {
          name: "latitude"
          field_id: 51
          semantic: FIELD_SEMANTIC_LATITUDE
        }
        available_in_mission: true
        available_as_command: true
      }
      commands {
        name: "mission_upload"
        id: 40
        parameters {
          name: "low_battery_action"
          field_id: 45
          semantic: FIELD_SEMANTIC_ENUM
        }
        parameters {
          name: "gps_loss_action"
          field_id: 44
          semantic: FIELD_SEMANTIC_ENUM
        }
        parameters {
          name: "rc_loss_action"
          field_id: 43
          semantic: FIELD_SEMANTIC_ENUM
        }
        parameters {
          name: "safe_altitude"
          field_id: 42
          semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
        }
        parameters {
          name: "altitude_origin"
          field_id: 41
          semantic: FIELD_SEMANTIC_ALTITUDE_AMSL
        }
        available_in_mission: false
        available_as_command: true
      }
    }
    register_camera {
      commands {
        name: "camera_trigger"
        id: 116
        parameters {
          name: "state"
          field_id: 117
          semantic: FIELD_SEMANTIC_ENUM
          enumeration {
            id: 2
            description: "single_photo"
          }
          enumeration {
            id: 3
            description: "serial_photo"
          }
          enumeration {
            id: 0
            description: "on"
          }
          enumeration {
            id: 1
            description: "off"
          }
        }
        available_in_mission: true
        available_as_command: true
      }
    }
  }
}

Telemetry message

Vsm_message from VSM to UCS:

device_id: 131
device_status {
  telemetry_fields {
    field_id: 13
    ms_since_epoch: 3404
    value {
      float_value: 0
    }
  }
  telemetry_fields {
    field_id: 19
    ms_since_epoch: 3404
    value {
      double_value: 0.99443216383835942
    }
  }
  telemetry_fields {
    field_id: 20
    ms_since_epoch: 3404
    value {
      double_value: 0.4201642634865152
    }
  }
}

Command availability message

Vsm_message from VSM to UCS:

device_id: 131
device_status {
  command_availability {
    id: 50
    is_available: true
    is_enabled: true
  }
  command_availability {
    id: 28
    is_available: true
    is_enabled: true
  }
}

Camera trigger command

Vsm_message from UCS to VSM:

device_id: 131
message_id: 112
response_required: true
device_commands {
  command_id: 1126
  parameters {
    field_id: 117
    value {
      int_value: 2
    }
  }
}

Camera trigger response

Vsm_message from VSM to UCS:

device_id: 131
message_id: 112
device_response {
  code: STATUS_INVALID_OK
  status: "Camera triggered"
}

Mission upload command

Vsm_message from UCS to VSM:

device_id: 131
message_id: 1111
response_required: true
device_commands {
  command_id: 40
  parameters {
    field_id: 41
    value {
      float_value: 134.13
    }
  }
  sub_commands {
    command_id: 49
  }
  sub_commands {
    command_id: 50
    parameters {
      field_id: 51
      value {
        double_value: 1.2
      }
    }
    parameters {
      field_id: 52
      value {
        double_value: 0.2
      }
    }
    parameters {
      field_id: 53
      value {
        float_value: 154.13
      }
    }
  }
  sub_commands {
    command_id: 50
    parameters {
      field_id: 51
      value {
        double_value: 1.2
      }
    }
    parameters {
      field_id: 52
      value {
        double_value: 22.2
      }
    }
    parameters {
      field_id: 53
      value {
        float_value: 154.13
      }
    }
  }
}

Mission upload response

Vsm_message from VSM to UCS:

device_id: 131
message_id: 1111
device_response {
  code: STATUS_INVALID_PARAMETER
  arguments: "Bad waypoint"
  arguments: "2"
  status: "longitude must be in range 0..2Pi"
}