{
    "openapi": "3.0.0",
    "info": {
        "version": "2.0.0",
        "title": "Signal K Autopilot API",
        "termsOfService": "http://signalk.org/terms/",
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "externalDocs": {
        "url": "http://signalk.org/specification/",
        "description": "Signal K specification."
    },
    "servers": [
        {
            "url": "/signalk/v2/api/vessels/self/autopilots"
        }
    ],
    "tags": [
        {
            "name": "autopilot",
            "description": "Signal K Autopilot API"
        }
    ],
    "components": {
        "schemas": {
            "autopilotStateOption": {
                "type": "object",
                "title": "Autopilot state option definition",
                "description": "Autopilot `state` option and indication whether pilot is actively steering.",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "State name / label",
                        "example": "enabled"
                    },
                    "engaged": {
                        "type": "boolean",
                        "description": "Set `true` if pilot is actively steering when in this `state`.",
                        "example": true
                    }
                },
                "example": [
                    { "name": "auto", "engaged": true },
                    { "name": "standby", "engaged": false }
                ]
            },
            "autopilotOptions": {
                "type": "object",
                "title": "Autopilot configuration options",
                "description": "A collection of configuration options and their valid values",
                "additionalProperties": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "properties": {
                    "states": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/autopilotStateOption"
                        },
                        "description": "List of valid autopilot states."
                    },
                    "modes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "List of valid Mode values.",
                        "example": ["compass", "gps"]
                    }
                }
            },
            "angleInput": {
                "type": "object",
                "required": ["value"],
                "properties": {
                    "value": {
                        "type": "number",
                        "description": "Value of (degrees / radians).",
                        "example": 2.12
                    },
                    "units": {
                        "type": "string",
                        "enum": ["deg", "rad"],
                        "description": "Units of supplied value.",
                        "example": "deg"
                    }
                }
            }
        },
        "responses": {
            "200ActionResponse": {
                "description": "PUT OK response",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "state": {
                                    "type": "string",
                                    "enum": ["COMPLETED"]
                                },
                                "statusCode": {
                                    "type": "number",
                                    "enum": [200]
                                }
                            },
                            "required": ["statusCode", "state"]
                        }
                    }
                }
            },
            "ErrorResponse": {
                "description": "Failed operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "description": "Request error response",
                            "properties": {
                                "state": {
                                    "type": "string",
                                    "enum": ["FAILED"]
                                },
                                "statusCode": {
                                    "type": "number",
                                    "enum": [400, 404]
                                },
                                "message": {
                                    "type": "string"
                                }
                            },
                            "required": ["state", "statusCode", "message"]
                        }
                    }
                }
            }
        },
        "parameters": {
            "AutopilotIdParam": {
                "name": "id",
                "in": "path",
                "description": "autopilot id",
                "required": true,
                "schema": {
                    "type": "string"
                }
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            },
            "cookieAuth": {
                "type": "apiKey",
                "in": "cookie",
                "name": "JAUTHENTICATION"
            }
        }
    },
    "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }],
    "paths": {
        "/": {
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve list of autopilots.",
                "description": "Returns a list of autopilots indexed by their identifier.",
                "responses": {
                    "default": {
                        "description": "Autopilot device list response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "additionalProperties": {
                                        "type": "object",
                                        "required": ["provider", "isDefault"],
                                        "properties": {
                                            "provider": {
                                                "type": "string",
                                                "description": "Provider plugin managing the autopilot device.",
                                                "example": "my-pilot-provider"
                                            },
                                            "isDefault": {
                                                "type": "boolean",
                                                "description": "Set to true when the autopilot is currently set as the default.",
                                                "example": "false"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/_providers/_default": {
            "get": {
                "tags": ["autopilot"],
                "summary": "Get the default autopilot device id.",
                "description": "Returns the device id of the autopilot assigned as the default.",
                "responses": {
                    "default": {
                        "description": "Autopilot configuration response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["id"],
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/_providers/_default/{id}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Set the default autopilot device.",
                "description": "Sets the autopilot with the supplied `id` as the default.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve autopilot information.",
                "description": "Returns the current state autopilot information including the available options for `state` and `mode`.",
                "responses": {
                    "default": {
                        "description": "Autopilot configuration response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["state", "mode", "target", "engaged"],
                                    "properties": {
                                        "engaged": {
                                            "type": "boolean",
                                            "description": "Autopilot is engaged and actively steering the vessel",
                                            "example": "true"
                                        },
                                        "state": {
                                            "type": "string",
                                            "description": "Autopilot state",
                                            "example": "auto"
                                        },
                                        "mode": {
                                            "type": "string",
                                            "description": "Autopilot operational mode",
                                            "example": "compass"
                                        },
                                        "target": {
                                            "description": "Current target value (radians)",
                                            "type": "number",
                                            "example": 2.8762
                                        },
                                        "options": {
                                            "$ref": "#/components/schemas/autopilotOptions"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/options": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve autopilot options.",
                "description": "Returns the selectable options and the values that can be applied (e.g. for`state` and `mode`).",
                "responses": {
                    "default": {
                        "description": "Autopilot configuration response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/autopilotOptions"
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/engage": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Engage autopilot to steer vessel",
                "description": "Provider plugin will set the autopilot to a `state` where it is actively steering the vessel. `state` selected is determined by the provider plugin.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/disengage": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Disengage autopilot from steering vessel.",
                "description": "Provider plugin will set the autopilot to a `state` where it is NOT actively steering the vessel. `state` selected is determined by the provider plugin.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/state": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve the current state.",
                "description": "Returns the current `state` value from the autopilot.",
                "responses": {
                    "default": {
                        "description": "Autopilot value response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["value"],
                                    "properties": {
                                        "value": {
                                            "type": "string",
                                            "example": "standby"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            },
            "put": {
                "tags": ["autopilot"],
                "summary": "Set autopilot state.",
                "description": "Set the autopilot to the supplied valid `state` value.",
                "requestBody": {
                    "description": "Supply valid `state` value (as per response from autopilot information request).",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "value": {
                                        "type": "string",
                                        "description": "Value representing the `state` the autopilot is to enter.",
                                        "example": "enabled"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/mode": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve the current mode.",
                "description": "Returns the current `mode` value from the autopilot.",
                "responses": {
                    "default": {
                        "description": "Autopilot value response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["value"],
                                    "properties": {
                                        "value": {
                                            "type": "string",
                                            "example": "compass"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            },
            "put": {
                "tags": ["autopilot"],
                "summary": "Set autopilot mode",
                "description": "Set the autopilot to the supplied valid `mode` value.",
                "requestBody": {
                    "description": "Supply valid `mode` value (as per response from autopilot information request).",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "value": {
                                        "type": "string",
                                        "description": "Value representing the `mode` the autopilot is to enter.",
                                        "example": "compass"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/target": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "get": {
                "tags": ["autopilot"],
                "summary": "Retrieve the current target value.",
                "description": "The current target value in radians.",
                "responses": {
                    "default": {
                        "description": "Autopilot value response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": ["value"],
                                    "properties": {
                                        "value": {
                                            "type": "number",
                                            "description": "Value in radians",
                                            "example": 2.456
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "error": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            },
            "put": {
                "tags": ["autopilot"],
                "summary": "Set autopilot `target` value.",
                "description": "Value supplied must fall within the valid range (-180 & 360 degrees / PI & 2 * PI radians).",
                "requestBody": {
                    "description": "Value within the valid range.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/angleInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/target/adjust": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "put": {
                "tags": ["autopilot"],
                "summary": "Adjust autopilot target value by +/- degrees / radians.",
                "description": "Value supplied will be added to the current target. The result must fall within the valid range (-180 & 360 degrees / PI & 2 * PI radians).",
                "requestBody": {
                    "description": "Value to add to the current `target`.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/angleInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/tack/port": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Tack to port.",
                "description": "Execute a port tack.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/tack/starboard": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Tack to starboard.",
                "description": "Execute a starboard tack.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/gybe/port": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Gybe to port.",
                "description": "Execute a gybe to port.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/gybe/starboard": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Gybe to starboard.",
                "description": "Execute a gybe to starboard.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        },
        "/{id}/dodge": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/AutopilotIdParam"
                }
            ],
            "post": {
                "tags": ["autopilot"],
                "summary": "Turn on dodge mode.",
                "description": "Enter dodge mode at the current course setting.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            },
            "delete": {
                "tags": ["autopilot"],
                "summary": "Turn Off dodge mode.",
                "description": "Resume steering original course.",
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            },
            "put": {
                "tags": ["autopilot"],
                "summary": "Steer port / starboard to dodge obstacles.",
                "description": "Override the current course to change direction the supplied number of degrees / radians.",
                "requestBody": {
                    "description": "+/- value to change direction (-ive = port).",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/angleInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200ActionResponse": {
                        "$ref": "#/components/responses/200ActionResponse"
                    },
                    "default": {
                        "$ref": "#/components/responses/ErrorResponse"
                    }
                }
            }
        }
    }
}