signalk-server

{ "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" } } } } } }