Skip to content

Capability Module

Jump to bottom
Iak edited this page Mar 10, 2023 · 1 revision

Here is an overview of the capability process on the PROCEED Engine:

PROCEED-Engine_Capability_Module

On some native implementations, e.g. Node.JS, it is possible to add capabilities at runtime. So the Universal part registers a callback for this case (Every native part has to implement its own strategy to find this out: poll, watch, interface). On other platforms, e.g. on Android, IOS and a Web Browser, it is not possible to add capabilities at runtime. They are hard-coded inside the native implementation.

Every native implementation (Node.js, iOS, Android, etc.) has to define its own way how to add Capabilities. The semantic description (capability.jsonld) must only state what a capabilities does and how to call it, but not where to find it. So, it is not important that there is a reference in capability.jsonld to a function or file name -- but, there can be. This are optional information in the semantic description and depends, if the native implementation define to use it.

Background, why this is the case:

In some programming languages, e.g. Swift, it is not possible to have a dynamic function call where a string (in the semantic description) defines the function name. This has to be hard-coded.

Something like this in JavaScript is not always possible in other languages:

const obj = { myCapability: funtion (){}}

//Call the function, depending on the string given in the semantic description
obj["myCapability"]();

Since the native engine part can be written in different languages (JS, Java, Swift, ...) it is not strictly a JS file that is needed for the capability implementation. And in some native implementations (e.g. with Node.JS) it is possible to interact with other running programs on a platform. So it is possible to code the capability in a completely different language and use JS just for the connection to the other implementation.

Details for the Capability Package

1.

  • The <id-for-native-impl-of-capability> is generated by the native implementation and is used to recognize the implementation for the semantic description.
  • for recognizing a second capability with the same concept, see the Node.JS section later on.

3.

The methods startCapability( <„Capability-Name“>, [<{ Parameter-Object }>], [<clb function>] ): if clb then null else Promise and executeNativeCapability( <id-for-native-impl-of-capability>, [<{ Parameter-Object }>], [< clb function >] ): if clb then null else Promise contain the same behaviour:

  • it is optional to insert a callback function in the end of the parameter list
    • it is useful if you expects to get values multiple times, e.g. getting the height information of a drone (you only do something if a specific value is reached)
    • if a callback is given, it immediately returns null
    • the callback function should have the following signature: function( error, {value-object} ){}
  • if no callback is given the method is a Promise -- so you can use then, catch or await

Furthermore under 3. there is an alternative call of startCapability(), where the parameter are written in a special form with value and unit: startCapability( „PhotographAction“, { height: { value: 80, unit: “px” } )

  • this does not have much influence on the Cap-Manager! it is only needed for the Management System to determine the correct Capability Description if there are multiple Description of the same Capability kind (e.g. two times "PhotoAction") with different Parameter units, e.g. "cm" and "pt"
  • the Cap-Manager should work as always and call the native Capability implementation with its value (disregard the unit)

Furthermore under 3. there is an alternative call of startCapability(), where the parameter are written in an extended form with their complete vocabulary URIs: startCapability( „https://schema.org/PhotographAction“, { “https://schema.org/height”: 80 } )

  • this does not have much influence on the Cap-Manager! it is only needed for the Management System to determine the correct Capability Description if there are multiple descriptions of the same capability kind or its parameter (e.g. "height" from "schema.org/height" and from "vocab.org/height")
  • the Cap-Manager should work as always and call the corresponding native Capability implementation

Capabilities in the Node.JS Native Implementation

If the PROCEED Engine is installed, you can add new capabilities with: npm run install-capability <URL|NPM Package> [FolderName] Therewith a new capability is added into the capabilities folder. The name of the new folder is not important - but it at least needs to contain one capability.jsonld and a JS file.

proceed-engine-bundled-with-capabilities

By default the capability implementation is assumed to be in index.js, but the actual filename can also be set in the package.json main entry. (The filename is not set in the capability.jsonld, because this would mean that the native part understands JSON-LD)

It is only allowed to have one Capability of the same concept on one machine, e.g. only one PhotographAction on one machine. This is checked in the universal part (because native part would need to interpret the JSON-LD file). If the Engine recognizes two times the same capability at startup, it fails and stops the Engine. If the Engine recognizes that the same capability is added at runtime, it only throws an error message (don't stops the engine) and continues to use the first added capability.

Clone this wiki locally