diff --git a/Documentation/API Backend/openrpc/README.md b/Documentation/API Backend/openrpc/README.md new file mode 100644 index 0000000..1cb9335 --- /dev/null +++ b/Documentation/API Backend/openrpc/README.md @@ -0,0 +1,16 @@ +# OpenRPC Document + +The API is documented here using the OpenRPC 1.2.4 standard. Note that there are later published versions of the standard, but the available tooling is implemented for the v1.2.4 spec. + +The full api is defined in openrpc.json, however, this means reading and updating a single file would become unwieldy and merge conflicts would arise. To mitigate this, [open-rpc-compiler](https://www.npmjs.com/package/open-rpc-compiler?activeTab=readme) is used to break each method and schema into its own file organized in this directory's subdirectories, named for the elements they comprise in the openrpc.json doc. + + +## Install +``` +npm install open-rpc-compiler --no-save +``` + +To compile the elements into the openrpc.json file run the following command from this directory. +``` +open-rpc-compile > openrpc.json +``` diff --git a/Documentation/API Backend/openrpc/components/schemas/jointPosition.json b/Documentation/API Backend/openrpc/components/schemas/jointPosition.json new file mode 100644 index 0000000..52a4f40 --- /dev/null +++ b/Documentation/API Backend/openrpc/components/schemas/jointPosition.json @@ -0,0 +1,11 @@ +{ + "type": "object", + "properties": { + "jointIndex": { + "type": "integer" + }, + "position": { + "type": "integer" + } + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/components/schemas/jointPositions.json b/Documentation/API Backend/openrpc/components/schemas/jointPositions.json new file mode 100644 index 0000000..2818af0 --- /dev/null +++ b/Documentation/API Backend/openrpc/components/schemas/jointPositions.json @@ -0,0 +1,6 @@ +{ + "type": "array", + "items": { + "$ref": "#/components/schemas/jointPosition" + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/components/schemas/state.json b/Documentation/API Backend/openrpc/components/schemas/state.json new file mode 100644 index 0000000..e916310 --- /dev/null +++ b/Documentation/API Backend/openrpc/components/schemas/state.json @@ -0,0 +1,11 @@ +{ + "type": "object", + "properties": { + "robotOnline": { + "type": "boolean" + }, + "jointPositions": { + "$ref": "#/components/schemas/jointPositions" + } + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/info.json b/Documentation/API Backend/openrpc/info.json new file mode 100644 index 0000000..daa7ffd --- /dev/null +++ b/Documentation/API Backend/openrpc/info.json @@ -0,0 +1,4 @@ +{ + "version": "0.1.0", + "title": "Motion Controller API" +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/methods/getActiveSubscriptions.json b/Documentation/API Backend/openrpc/methods/getActiveSubscriptions.json new file mode 100644 index 0000000..ff858c3 --- /dev/null +++ b/Documentation/API Backend/openrpc/methods/getActiveSubscriptions.json @@ -0,0 +1,15 @@ +{ + "name": "getActiveSubscriptions", + "description": "Get a list of state keys for which the client is currently subscribed to value changes", + "params": [], + "result": { + "name": "activeStateKeySubscriptions", + "description": "the state keys to which the client is currently subsribed", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/methods/getState.json b/Documentation/API Backend/openrpc/methods/getState.json new file mode 100644 index 0000000..b386e0b --- /dev/null +++ b/Documentation/API Backend/openrpc/methods/getState.json @@ -0,0 +1,43 @@ +{ + "name": "getState", + "description": "Get the current state and optionally subscribe to changes", + "params": [ + { + "name": "include", + "description": "state keys that should be included in the response. If undefined, all keys except any specifially excluded are included.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "exclude", + "description": "state keys that should not be included in the response.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "subscribeToChanges", + "required": false, + "description": "Subscribe to changes in the keys included in the request", + "schema": { + "type": "boolean" + } + } + ], + "result": { + "name": "state", + "description": "the current state. For subscription updates, only keys for changed values will be included.", + "schema": { + "$ref": "#/components/schemas/state" + } + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/methods/tags/motion/getPosition.json b/Documentation/API Backend/openrpc/methods/tags/motion/getPosition.json new file mode 100644 index 0000000..0058dc1 --- /dev/null +++ b/Documentation/API Backend/openrpc/methods/tags/motion/getPosition.json @@ -0,0 +1,34 @@ +{ + "name": "getPosition", + "description": "Get current joint positions", + "params": [], + "result": { + "name": "jointPositions", + "description": "updated joint positions", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/jointPosition" + } + } + }, + "examples": [ + { + "name": "getPosition", + "params": [], + "result": { + "name": "jointPositions", + "value": [ + { + "jointIndex": 1, + "position": 393 + }, + { + "jointIndex": 5, + "position": 1829 + } + ] + } + } + ] +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/methods/tags/motion/jogJoint.json b/Documentation/API Backend/openrpc/methods/tags/motion/jogJoint.json new file mode 100644 index 0000000..238a800 --- /dev/null +++ b/Documentation/API Backend/openrpc/methods/tags/motion/jogJoint.json @@ -0,0 +1,56 @@ +{ + "name": "jogJoint", + "description": "Jog an joint with a specified velocity", + "params": [ + { + "name": "jointIndex", + "description": "The index of the joint to jog", + "schema": { + "type": "integer" + } + }, + { + "name": "direction", + "description": "Direction to jog the joint.", + "schema": { + "type": "integer" + } + }, + { + "name": "speed", + "description": "The speed at which to jog.", + "schema": { + "type": "integer" + } + } + ], + "result": { + "name": "noResult", + "schema": { + "type": "null" + } + }, + "examples": [ + { + "name": "jogJoint", + "params": [ + { + "name": "jointIndex", + "value": 3 + }, + { + "name": "direction", + "value": 1 + }, + { + "name": "speed", + "value": 88 + } + ], + "result": { + "name": "noResult", + "value": null + } + } + ] +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/methods/unsubscribeState.json b/Documentation/API Backend/openrpc/methods/unsubscribeState.json new file mode 100644 index 0000000..c6da8ad --- /dev/null +++ b/Documentation/API Backend/openrpc/methods/unsubscribeState.json @@ -0,0 +1,34 @@ +{ + "name": "unsubscribeState", + "description": "Unsubscribe from changes to state", + "params": [ + { + "name": "include", + "description": "state keys that should be unsubscribed from. If undefined, all keys except any specifially excluded are included.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "exclude", + "description": "state keys that should not be unsubscribed from", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "result": { + "name": "noResult", + "schema": { + "type": "null" + } + } +} \ No newline at end of file diff --git a/Documentation/API Backend/openrpc/openrpc.json b/Documentation/API Backend/openrpc/openrpc.json new file mode 100644 index 0000000..1c02b16 --- /dev/null +++ b/Documentation/API Backend/openrpc/openrpc.json @@ -0,0 +1,233 @@ +{ + "openrpc": "1.2.4", + "info": { + "version": "0.1.0", + "title": "Motion Controller API" + }, + "methods": [ + { + "name": "getActiveSubscriptions", + "description": "Get a list of state keys for which the client is currently subscribed to value changes", + "params": [], + "result": { + "name": "activeStateKeySubscriptions", + "description": "the state keys to which the client is currently subsribed", + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + { + "name": "getState", + "description": "Get the current state and optionally subscribe to changes", + "params": [ + { + "name": "include", + "description": "state keys that should be included in the response. If undefined, all keys except any specifially excluded are included.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "exclude", + "description": "state keys that should not be included in the response.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "subscribeToChanges", + "required": false, + "description": "Subscribe to changes in the keys included in the request", + "schema": { + "type": "boolean" + } + } + ], + "result": { + "name": "state", + "description": "the current state. For subscription updates, only keys for changed values will be included.", + "schema": { + "$ref": "#/components/schemas/state" + } + } + }, + { + "name": "getPosition", + "description": "Get current joint positions", + "params": [], + "result": { + "name": "jointPositions", + "description": "updated joint positions", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/jointPosition" + } + } + }, + "examples": [ + { + "name": "getPosition", + "params": [], + "result": { + "name": "jointPositions", + "value": [ + { + "jointIndex": 1, + "position": 393 + }, + { + "jointIndex": 5, + "position": 1829 + } + ] + } + } + ], + "tags": [ + { + "name": "motion" + } + ] + }, + { + "name": "jogJoint", + "description": "Jog an joint with a specified velocity", + "params": [ + { + "name": "jointIndex", + "description": "The index of the joint to jog", + "schema": { + "type": "integer" + } + }, + { + "name": "direction", + "description": "Direction to jog the joint.", + "schema": { + "type": "integer" + } + }, + { + "name": "speed", + "description": "The speed at which to jog.", + "schema": { + "type": "integer" + } + } + ], + "result": { + "name": "noResult", + "schema": { + "type": "null" + } + }, + "examples": [ + { + "name": "jogJoint", + "params": [ + { + "name": "jointIndex", + "value": 3 + }, + { + "name": "direction", + "value": 1 + }, + { + "name": "speed", + "value": 88 + } + ], + "result": { + "name": "noResult", + "value": null + } + } + ], + "tags": [ + { + "name": "motion" + } + ] + }, + { + "name": "unsubscribeState", + "description": "Unsubscribe from changes to state", + "params": [ + { + "name": "include", + "description": "state keys that should be unsubscribed from. If undefined, all keys except any specifially excluded are included.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + }, + { + "name": "exclude", + "description": "state keys that should not be unsubscribed from", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "result": { + "name": "noResult", + "schema": { + "type": "null" + } + } + } + ], + "components": { + "schemas": { + "jointPosition": { + "type": "object", + "properties": { + "jointIndex": { + "type": "integer" + }, + "position": { + "type": "integer" + } + } + }, + "jointPositions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/jointPosition" + } + }, + "state": { + "type": "object", + "properties": { + "robotOnline": { + "type": "boolean" + }, + "jointPositions": { + "$ref": "#/components/schemas/jointPositions" + } + } + } + } + } +}