api_spec.yml

openapi: 3.0.2
info:
  title: MissionPlanner Scripts
  version: 2.0.0
  description: "This is the API that the MissionPlanner Scripts server exposes to GCOM."
  contact:
    name: Amin Fahiminia, Hansen Dan
servers:
  - url: http://localhost:9000
tags:
  - name: queue
    description: Access to the waypoint queue
  - name: status
    description: Access to aircraft status
  - name: takeoff
    description: Access to takeoff and arming motors
  - name: landing
    description: Access to landing, RTL, and home waypoint
  - name: options
    description: Access to flight options
paths:
  /:
    get:
      summary: Call this to see if the server's running.
      responses:
        "200":
          description: server is running
  /queue:
    get:
      tags:
        - queue
      summary: Returns the current list of waypoints remaining in the queue
      description: >-
        Returns the current list of queue of waypoints to hit. 
        Waypoints that have been passed and removed from the queue are not displayed.
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Waypoint"
    post: 
      tags:
        - queue
      summary: Overwrite the queue with a new list of waypoints 
      description: >-
        POST request containing a list of waypoints with names and longitude, 
        latitude, and altitude values. If the altitude for a waypoint is null, 
        uses the altitude of the previous waypoint (in the case of the first 
        waypoint, uses the current altitude of the drone).
        The existing waypoint queue will be overwritten and lost.
        Longitude, name, and latitude must not be null/empty. Returns a Bad 
        Request status code and error message in that case. Longitude and 
        latitude in degrees, altitude in meters.
      requestBody:
        content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Waypoint"
      responses:
        "200":
          description: successful operation
        "400":
          description: bad request
  /insert:
    post:
      tags:
       - queue
      summary: Inserts waypoints immediately before the current waypoint
      requestBody:
        content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Waypoint"
      responses:
        "200":
          description: successful operation
        "400":
          description: bad request
  /clear:
    get:
      tags:
        - queue
      summary: Clear the waypoint queue. 
      description: >-
        Idempotent with POST'ing an empty queue to /queue.
      responses:
        "200":
          description: Queue successfully emptied.
  /status:
    get:
      tags:
        - status
      summary: Obtain the aircraft status
      description: >-
        GET request returns the aircraft status. Velocity in m/s. Altitude 
        in meters and is relative to sea level. Longitude, latitude, heading 
        in degrees.
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
  /takeoff:
    post:
      tags:
        - takeoff
      summary: Lift off to a given altitude
      description: >-
        POST request containing an altitude to take off to.
        Don't put an altitude that would be underground.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                altitude:
                  type: number
                  format: float64
      responses:
        "200":
          description: Successful operation
        "400":
          description: Takeoff unsuccessful or motors disarmed
  /rtl:
    get:
      tags:
        - landing
      summary: return to launch
      description: >-
        Aircraft returns to home waypoint and lands (return-to-launch). 
        Returns a Bad Request status code and error message if the drone 
        could not execute the operation.
      responses:
        "200":
          description: Successful, drone has initiated RTL procedure
        "400":
          description: Could not initiate RTL
    post:
      tags:
        - landing
      summary: return to launch at specified altitude
      description: >-
        Aircraft returns to home waypoint and lands (return-to-launch). 
        Returns a Bad Request status code and error message if the drone 
        could not execute the operation.
        POST request body contains the altitude the drone should be at 
        while transiting back towards the launch point.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                altitude:
                  type: number
                  format: float64
      responses:
        "200":
          description: Successful, drone has initiated RTL procedure
        "400":
          description: Could not initiate RTL
  /land:
    get:
      tags:
        - landing
      summary: immediately descend and land
      description: >-
        Aircraft stops at its current position and lands. 
        Returns a Bad Request status code and error message if the drone 
        could not execute the operation.
      responses:
        "200":
          description: Successful, drone has started landing procedure
        "400":
          description: Could not initiate landing
    post: 
      tags: 
        - landing 
      summary: land at designated location
      description: >-
        Land at the location in the request.
      requestBody:
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/Waypoint"
      responses:
        "200":
          description: Successful, drone has started landing procedure 
        "400":
          description: Invalid coordinates - latitude and/or longitude value was null 
  /home:
    post:
      tags:
        - landing
      summary: set the home waypoint of the drone
      description: >-
        POST request containing a waypoint whose longitude, latitiude and 
        altitiude will be the basis for the new home waypoint. All other 
        fields will be ignored.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Waypoint"
      responses:
        "200":
          description: Successfully set new home position
        "400":
          description: Home position could not be set
  /diversion:
    post: 
      tags: 
        - queue
      summary: divert the aircraft around an exclusion zone
      description: >-
        Include the waypoints that define the exclusion polygon in 
        order in the exclude array, and the waypoint to rejoin the 
        normal queue at in the rejoin_at property. The server will 
        process the information, produce a diverted path, and pass 
        that to the aircraft, returning 200. Note that 200 will be 
        returned whether or not the new path is applied or not.
      requestBody:
        content:
          application/json:
            schema:
              type: object 
              properties:
                exclude:
                  type: array
                  items:
                    $ref: '#/components/schemas/Waypoint'
                rejoin_at:
                  $ref: '#/components/schemas/Waypoint'
      responses:
        "200":
          description: Diversion processed
  /flightmode:
    put:
      tags:
        - options
      summary: Change flight mode of the aircraft
      description: >-
        Set the flight mode of the aircraft to Loiter, Stabilize, Auto, or Guided, or set the current aircraft type to Copter or Plane.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: ['copter', 'plane', 'loiter', 'stabilize', 'auto', 'guided']
      responses:
        "200":
          description: Operation processed
        "400":
          description: Unrecognized mode
  /arm:
    put:
      tags:
        - takeoff
      summary: Arm or disarm the motors. Take care.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                arm:
                  type: integer
                  enum: [0, 1]
      responses:
        "200":
          description: Arm/disarm successful.
        "400":
          description: Arm/disarm failed - drone is NOT in the requested state
  /altstandard:
    put:
      tags:
        - options
      summary: UNIMPLEMENTED
      description: >-
        UNIMPLEMENTED
      requestBody:
        content:
          application/json:
            schema: 
              type: object
              properties:
                standard:
                  type: string
                  enum: ['AGL', 'MSL']
      responses:
        "410":
          description: "UNIMPLEMENTED"
components:
  schemas:
    Waypoint:
      type: object
      properties:
        id:
          type: number
          format: integer
        name:
          type: string
        longitude:
          type: number
          format: float64
        latitude:
          type: number
          format: float64
        altitude:
          type: number
          format: float64
        command:
          type: string
          description: "Put the waypoint command here as in MissionPlanner, i.e., `LOITER_UNLIM` or `DO_CHANGE_SPEED`. Default value: `WAYPOINT`"
        param1:
          type: number
          format: integer
        param2:
          type: number
          format: integer
        param3:
          type: number
          format: integer
        param4:
          type: number
          format: integer
    Status:
      type: object
      properties:
        timestamp:
          type: integer
        current_wpn:
          type: integer
        latitude:
          type: number
          format: float64
        longitude:
          type: number
          format: float64
        altitude:
          type: number
          format: float64
        roll:
          type: number
          format: float64
        pitch:
          type: number
          format: float64
        yaw:
          type: number
          format: float64
        airspeed:
          type: number
          format: float64
        groundspeed:
          type: number
          format: float64
        heading:
          type: number
          format: float64
        batteryvoltage:
          type: number
          format: float64
        winddirection:
          type: number
          format: float64
        windvelocity:
          type: number
          format: float64