Requests can accept angle values in radians (default) or degrees

SignalK · Dec 2, 2024 · 6df30a5 · 6df30a5
1 parent 3be751e
commit 6df30a5
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 65 deletions.
diff --git a/docs/src/develop/plugins/autopilot_provider_plugins.md b/docs/src/develop/plugins/autopilot_provider_plugins.md
@@ -272,7 +272,7 @@ setMode('gps', 'mypilot1');
 ---
 **`setTarget(value, deviceId)`**: This method sets target for the autopilot device with the supplied identifier to the supplied value.
 
-- `value:` target value in degrees.
+- `value:` target value in radians.
 - `deviceId:` identifier of the autopilot device to query.
 
 returns: `Promise<{void}>`
@@ -291,7 +291,7 @@ setTarget(129, 'mypilot1');
 ---
 **`adjustTarget(value, deviceId)`**: This method adjusts target for the autopilot device with the supplied identifier by the supplied value.
 
-- `value:` value in degrees to add to current target value.
+- `value:` value in radians to add to current target value.
 - `deviceId:` identifier of the autopilot device to query.
 
 returns: `Promise<{void}>`
@@ -382,9 +382,9 @@ gybe('starboard', 'mypilot1');
 ```
 
 ---
-**`dodge(value, deviceId)`**: This method instructs the autopilot device with the supplied identifier to enter / exit dodge mode and alter the current course by the supplied value (degrees) direction.
+**`dodge(value, deviceId)`**: This method instructs the autopilot device with the supplied identifier to enter / exit dodge mode and alter the current course by the supplied value (radians) direction.
 
-- `value`: +/- value indicating the number of degrees 'port (-ive)' or 'starboard' to alter direction. _Setting the value to `null` indicates exit of dodge mode._
+- `value`: +/- value in radians 'port (-ive)' or 'starboard' to change direction. _Setting the value to `null` indicates exit of dodge mode._
 - `deviceId:` identifier of the autopilot device to query.
 
 returns: `Promise<{void}>`

diff --git a/docs/src/develop/rest-api/autopilot_api.md b/docs/src/develop/rest-api/autopilot_api.md
@@ -254,23 +254,31 @@ _Response:_
 
 ### Setting the Target value
 
-Autopilot target value can be set by submitting an HTTP `PUT` request to the `/signalk/v2/api/vessels/self/autopilots/{id}/target` endpoint containing the desired value in degrees.
+Autopilot target value can be set by submitting an HTTP `PUT` request to the `/signalk/v2/api/vessels/self/autopilots/{id}/target` endpoint containing the desired value.
 
 _Note: The value supplied should be a number within the valid range for the selected `mode`._
 
 ```typescript
-HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target" {"value": 129}
+// Set target to 129 degrees
+HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target" {"value": 129, "units": "deg"}
+
+// Set target to 0.349066 radians (20 degrees)
+HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target" {"value": 0.349066}
 ```
 
-The target value can be adjusted a +/- value by submitting an HTTP `PUT` request to the `/signalk/v2/api/vessels/self/autopilots/{id}/target/adjust` endpoint with the value to add to the current `target` value in degrees.
+The target value can be adjusted a +/- value by submitting an HTTP `PUT` request to the `/signalk/v2/api/vessels/self/autopilots/{id}/target/adjust` endpoint with the value to add to the current `target` value.
 
 ```typescript
-HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target/adjust" {"value": -2}
+// Adjust target 2 degrees port
+HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target/adjust" {"value": -2, , "units": "deg"}
+
+// Adjust target 0.0349066 radians (2 degrees) starboard
+HTTP PUT "signalk/v2/api/vessels/self/autopilots/{id}/target/adjust" {"value": 0.0349066}
 ```
 
 ### Getting the current Target value
 
-The current autopilot target value _(in degrees)_ can be retrieved by submitting an HTTP `GET` request to the `target` endpoint.
+The current autopilot target value _(in radians)_ can be retrieved by submitting an HTTP `GET` request to the `target` endpoint.
 
 ```typescript
 HTTP GET "/signalk/v2/api/vessels/self/autopilots/{id}/target"
@@ -280,7 +288,7 @@ _Response:_
 
 ```JSON
 {
-  "value":"3.14",
+  "value": 2.2345,
 }
 ```
 
@@ -349,12 +357,12 @@ POST /signalk/v2/api/vessels/self/autopilots/{id}/dodge
 
 **To enter dodge mode and change course by 5 degrees starboard**
 ```javascript
-PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": 5}
+PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": 5, "units": "deg"}
 ```
 
 **To enter dodge mode and change course by 5 degrees port**
 ```javascript
-PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": -5}
+PUT /signalk/v2/api/vessels/self/autopilots/{id}/dodge {"value": -5, "units": "deg"}
 ```
 
 **To cancel dodge mode**

diff --git a/src/api/autopilot/index.ts b/src/api/autopilot/index.ts
@@ -46,7 +46,7 @@ export class AutopilotApi {
   private deviceToProvider: Map<string, string> = new Map()
 
   private settings: AutopilotApiSettings = {
-    maxTurn: 20
+    maxTurn: 20 * (Math.PI / 180)
   }
 
   constructor(private server: AutopilotApplication) {}
@@ -438,11 +438,19 @@ export class AutopilotApi {
           res.status(Responses.invalid.statusCode).json(Responses.invalid)
           return
         }
-        const v =
-          req.body.value < -180
-            ? Math.max(...[-180, req.body.value])
-            : Math.min(...[360, req.body.value])
 
+        const u: string = req.body.units ?? 'rad'
+        let v =
+          typeof u === 'string' && u.toLocaleLowerCase() === 'deg'
+            ? req.body.value * (Math.PI / 180)
+            : req.body.value
+
+        v =
+          v < 0 - Math.PI
+            ? Math.max(...[0 - Math.PI, v])
+            : Math.min(...[2 * Math.PI, v])
+
+        debug('target = ', v)
         this.useProvider(req)
           .setTarget(v, req.params.id)
           .then(() => {
@@ -466,12 +474,13 @@ export class AutopilotApi {
           res.status(Responses.invalid.statusCode).json(Responses.invalid)
           return
         }
-
+        const u: string = req.body.units ?? 'rad'
         const v =
-          req.body.value < 0
-            ? Math.max(...[0 - this.settings.maxTurn, req.body.value])
-            : Math.min(...[this.settings.maxTurn, req.body.value])
+          typeof u === 'string' && u.toLocaleLowerCase() === 'deg'
+            ? req.body.value * (Math.PI / 180)
+            : req.body.value
 
+        debug('target = ', v)
         this.useProvider(req)
           .adjustTarget(v, req.params.id)
           .then(() => {
@@ -610,11 +619,19 @@ export class AutopilotApi {
           return
         }
 
-        const v =
-          req.body.value < 0
-            ? Math.max(...[0 - this.settings.maxTurn, req.body.value])
-            : Math.min(...[this.settings.maxTurn, req.body.value])
+        const u: string = req.body.units ?? 'rad'
+        let v =
+          typeof u === 'string' && u.toLocaleLowerCase() === 'deg'
+            ? req.body.value * (Math.PI / 180)
+            : req.body.value
+
+        debug('dodge pre-normalisation) = ', v)
+        v =
+          v < 0
+            ? Math.max(...[0 - this.settings.maxTurn, v])
+            : Math.min(...[this.settings.maxTurn, v])
 
+        debug('dodge = ', v)
         this.useProvider(req)
           .dodge(v, req.params.id)
           .then(() => {

diff --git a/src/api/autopilot/openApi.json b/src/api/autopilot/openApi.json
@@ -74,6 +74,23 @@
             "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": {
@@ -268,9 +285,9 @@
                       "example": "compass"
                     },
                     "target": {
-                      "description": "Current target value (degrees)",
+                      "description": "Current target value (radians)",
                       "type": "number",
-                      "example": 75.2
+                      "example": 2.8762
                     },
                     "options": {
                       "$ref": "#/components/schemas/autopilotOptions"
@@ -492,8 +509,8 @@
       ],
       "get": {
         "tags": ["autopilot"],
-        "summary": "Retrieve the current target value (degrees).",
-        "description": "Value in degrees of the current target value.",
+        "summary": "Retrieve the current target value.",
+        "description": "The current target value in radians.",
         "responses": {
           "default": {
             "description": "Autopilot value response",
@@ -505,8 +522,8 @@
                   "properties": {
                     "value": {
                       "type": "number",
-                      "description": "Value in degrees",
-                      "example": 129
+                      "description": "Value in radians",
+                      "example": 2.456
                     }
                   }
                 }
@@ -520,24 +537,15 @@
       },
       "put": {
         "tags": ["autopilot"],
-        "summary": "Set autopilot `target` value (degrees).",
-        "description": "Value supplied must be in the valid range between -180 & 360.",
+        "summary": "Set autopilot `target` value.",
+        "description": "Value supplied must fall within the valid range (-180 & 360 degrees / PI & 2 * PI radians).",
         "requestBody": {
-          "description": "Value in degrees within the bounds of the current autopilot mode. (i.e. compass: 0 to 360, wind angle: -180 to 180)",
+          "description": "Value within the valid range.",
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "properties": {
-                  "value": {
-                    "type": "number",
-                    "description": "Value in degrees",
-                    "min": -180,
-                    "max": 360,
-                    "example": 129
-                  }
-                }
+                "$ref": "#/components/schemas/angleInput"
               }
             }
           }
@@ -560,22 +568,15 @@
       ],
       "put": {
         "tags": ["autopilot"],
-        "summary": "Adjust autopilot target value by +/- degrees.",
-        "description": "Value supplied will be added to the current target value. The result must be in the valid range between -PI & 2*PI.",
+        "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": "A value in degrees to add to the current `target` value.",
+          "description": "Value to add to the current `target`.",
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "properties": {
-                  "value": {
-                    "type": "number",
-                    "description": "Value in degrees (-ive = port).",
-                    "example": -2
-                  }
-                }
+                "$ref": "#/components/schemas/angleInput"
               }
             }
           }
@@ -705,21 +706,14 @@
       "put": {
         "tags": ["autopilot"],
         "summary": "Steer port / starboard to dodge obstacles.",
-        "description": "Override the current course to change direction the supplied number of degrees.",
+        "description": "Override the current course to change direction the supplied number of degrees / radians.",
         "requestBody": {
-          "description": "+/- value in degrees to turn (-ive = port).",
+          "description": "+/- value to change direction (-ive = port).",
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "properties": {
-                  "value": {
-                    "type": "number",
-                    "description": "Value in degrees.",
-                    "example": -2
-                  }
-                }
+                "$ref": "#/components/schemas/angleInput"
               }
             }
           }