RFC 0010: Actions (PUT/POST)

[sbender9]

RFC 0010: Actions (PUT/POST)

Summary

We do not currently detail the way to take actions to control things on a boat. There should be a well defined way to do things like turn lights on and off and control an autopilot, etc.

Motivation

This is currently being done in proprietary ways making it difficult for app developers to add support. 'update' deltas are one way this could be done and that has been proposed in the past. That does not work because displays and devices need to be able to tell the difference between a request to change the state of thing and an update of the current state.

Detailed design

There has been some discussion already about the exact methods used to do this. PUT/POST over HTTP and/or put deltas over ws. I'm just going to use the word PUT for now here.

Making a request to change a value

To change a value, a PUT request should be sent via HTTP or using a SignalK 'put' delta.

The "source" field is optional. If a request is sent without the source and their is more than one source for the value, that will result in a 400 HTTP error response.

via http

PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/headingTrue
{
  "value" = 1.52,
  "source": "actisense.204",
}

via a delta

{
  "context": "vessels.self",
  "put": {
    "path": "steering.autopilot.target.headingTrue",
    "source": "actisense.204",
    "value": 1.52
  }
}

The response to a request to change a value

The possible responses the server can make to this request.

• Permission denied
• The request is not supported
• There was an error processing the request
• The request was processed and the value has been changed
• The request has been received and is being worked on asynchronously

I will cover these for HTTP methods since there is no defined way to do request/response over ws or other protocols.

HTTP response for permission denied

HTTP response code 403 (Forbidden)

HTTP response when the request is not supported

HTTP response code 405 (Method Not Allowed)

HTTP response when there is an error processing the request

HTTP response codes:
400 (something wrong with the client's request)
502 (something went wrong carrying out the request on the server side)
504 (timeout on the server side trying to carry out the request

JSON response body:

{
  "state": "COMPLETED",
  "message": "Unable to reach device"
}

HTTP Response to a successful PUT request

HTTP response code 200 (OK)
JSON response body:

{
  "state": "COMPLETED",
}

HTTP Response to a request that is being worked on asynchronously

The response in this case includes an optional href that can be used to check the status of the request.

HTTP response code 202 (Accepted)
JSON response body:

{
  "state":"PENDING",
  "action": {
    "id":12567,
    "href": "/signalk/v1/api/actions/12567"
   }
}

Response to /signalk/v1/api/actions/12567 when the request has completed successfully

{
   "context" : "vessels.self",
   "path" : "steering.autopilot.target.headingTrue",
   "source": "actisense.204",
   "user": "john@smith.com",
   "requestedValue" : 1.57,
   "startTime" : "2018-02-27T20:59:21.868Z",
   "id" : 12567,
   "endTime" : "2018-02-27T20:59:41.871Z",
   "state": "COMPLETED"
   "result" : "SUCCESS"
}

Response to /signalk/v1/api/actions/12567 when the request has failed

{
   "context" : "vessels.self",
   "path" : "steering.autopilot.target.headingTrue",
   "source": "actisense.204",
   "user": "john@smith.com",
   "requestedValue" : 1.57,
   "startTime" : "2018-02-27T20:59:21.868Z",
   "id" : 12567,
   "endTime" : "2018-02-27T20:59:41.871Z",
   "state": "COMPLETED"
   "result" : "FAILURE",
   "message": "Unable to reach device"
}

Response to /signalk/v1/api/actions/12567 when the request is pending

(note that percentComplete is optional)

{
   "context" : "vessels.self",
   "path" : "steering.autopilot.target.headingTrue",
   "source": "actisense.204",
   "user": "john@smith.com",
   "requestedValue" : 1.57,
   "startTime" : "2018-02-27T20:59:21.868Z",
   "id" : 12567,
   "state": "PENDING",
   "percentComplete": 0.45
}

Unresolved questions

It is not clear how to handle this with protocols like WS, TCP, etc. I propose that at least initially, the client will assume that the request is "PENDING" and watch for a delta update of the value to confirm that it was changed.

[sbender9]

This is currently prototyped in node server at https://github.com/SignalK/signalk-server-node/tree/put-support

[mpvader]

That does not work because displays and devices need to be able to tell the difference between a request to change the state of thing and an update of the current state.

Exactly!

[mpvader]

I’m impressed, looks like a good spec to me.

[bkp7]

This looks good to me too.

One point though, rather than creating many new leaves with names prepended with target, would it not make more sense to have the target property at the same level as the existing value. ie

{
  "context": "vessels.self",
  "put": {
    "path": "navigation.headingTrue.target",
    "value": 1.52
  }
}

resulting in:

{
  "uuid": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "navigation": {
    "headingTrue": {
      "value": 1.48,
      "$source": "foo.bar",
      "timestamp": "2017-08-15T19:00:15.402Z"
      "target": {
        "value": 1.52,
        "$source": "foo.baz",
        "timestamp": "2017-08-15T19:00:03.381Z"
      }
    }
  }
}

[sbender9]

I’m not proposing that the target information go in to the schema at all.

[sbender9]

Oh, I see the confusion, my example uses 'targetHeadingTrue', which is incorrect. (Not sure where I got that) . Updating now...

The paths in the put requests would always be something already in the schema.

[fabdrol]

Overall: looks very good. One note;
Shouldn’t the error response use a non-200 value? The proposed error response will result in a “successful” request in most HTTP clients, which means the code must include an extra inspection of the response body to detect the error, on top of the error handler for HTTP errors. Not DRY

[bkp7]

Steering is the only schema which currently has 'target' sections so it is not a good generic example. For all other areas your proposal would require a new 'target' branch or leaf to be added, eg. zone temperature/humidity, all switching,/controls, etc. Given that gauges and displays would want to be able show the current value and the target value I would have thought it better to put the target at the same level as the value rather than in a separate unlinked leaf, so your proposed:

{
  "uuid": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "navigation": {
    "headingTrue": {
      "value": 1.48
    }
  },
  "steering": {
    "rudderAngle": {
      "value": 0.09
    },
    "rudderAngleTarget": {
      "value": 0.07
    },
    "autopilot": {
      "target": {
        "headingTrue": {
          "value": 1.52
}}}}}

becomes:

{
  "uuid": "urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "navigation": {
    "headingTrue": {
      "value": 1.48,
      "target": {
        "value": 1.52
      }
    }
  },
  "steering": {
    "rudderAngle": {
      "value": 0.09,
      "target": {
        "value": 0.07
}}}}

[tkurki]

You're misinterpreting the word targethere. The example is trying to set the heading that the autopilot is set to hold, whose SK path just happens to contain the word target.

It is not the target of the action and no new paths are added to the data model.

If you want to set for example the temperature your fridge is supposed to hold there willl be no word target in the path.

[bkp7]

@tkurki, sorry I don't understand what you mean.

A fridge has both an actual and 'target' temperature. The fridge control unit is responsible for trying to maintain the target temperature.

A vessel has both an actual and 'target' heading. The autopilot is responsible for trying to maintain the target heading.

These 2 cases look identical to me and both need to have the actual and target values somewhere in the model as the actual and target will rarely (if ever) be exactly the same.

This also extends nicely to lighting and switching:
A light has an actual dimmed value of 50% and target value of 20%. The lighting control unit is responsible for fading the lights to the target value.

[sbender9]

I get what you're saying @bkp7 , but I'm not proposing to change the scheme here in any way.

I think in cases where we think it makes sense to have the 'target' value in the schema, we should add it explicitly. Like we have done for the autopilot target heading.

And we should look to the real world for examples.

It totally makes sense to have a target temperature for a fridge or other thermostats. We would see this on a real world thermostat. Both current and target temps. These both should be in the schema.

I'm not sure it makes sense for a light switch or dimmer. We'd be overly complicating things in this case. If I want to turn a light on, I should just PUT to electrical.switches.anchorLight.state = on. In this case, the only reason to have both current and target in the schema is to give the user an indication that things are not currently in the state that the user requested. I think this protocol deals with that because the UI can show this to the user by displaying an error message if the request fails and by indicating the current state in the UI.

[tkurki]

Oh sorry, my mistake, I was misunderstanding what you were saying @bkp7.

But still some points: a vessel has a heading but an autopilot has a target heading. You can even set the target heading without engaging the autopilot. A fridge has a temperature but the fridge thermostat has a set temperature, and there may be just an icebox. Many of the sk paths are not subject to control.

[tkurki]

Or maybe more accurately: the measurement is not the control mechanism, as with heading.

[bkp7]

OK, I agree that adding explicit target values where they are needed is a way forward.

However, that relies on either maintaining a map between the underlying value and the target, or relying on a strictly enforced naming convention in order to find the associated target.

So for example a display unit wanting data for a compass would subscribe to navigation.headingMagnetic which would include all metadata to render the compass except for the heading bug, which is found at steering.autopilot.target.headingMagnetic. How is the display meant to know this? Even if it has the schema there is no logical link between the two.

In my example above I also picked rudder angle because at least these are close together, ie. subscribe to steering.rudderAngle to get everything needed to render the gauge except for the commanded position which is found at steering.rudderAngleTarget. This is what I mean by needing to have a strictly enforced naming convention to know to add 'Target' to the path.

In my proposal the commanded/target/bug position would be included in the same place, meaning the display unit does not need to keep a map of values and target, nor does it need the schema. I understood this to be one of the goals for display units? Also the heading bug (autopilot target heading) can be set even if the autopilot is not engaged, but should still be able to be displayed on the compass.