diff options
| -rw-r--r-- | docs/ocf.md | 207 | ||||
| -rw-r--r-- | src/zjs_ocf_ble.c | 11 | ||||
| -rw-r--r-- | src/zjs_ocf_ble.h | 5 | ||||
| -rw-r--r-- | src/zjs_ocf_common.c | 4 |
4 files changed, 185 insertions, 42 deletions
diff --git a/docs/ocf.md b/docs/ocf.md index 4275f46..1bf43c5 100644 --- a/docs/ocf.md +++ b/docs/ocf.md @@ -3,8 +3,14 @@ ZJS API for OCF * [Introduction](#introduction) * [Web IDL](#web-idl) -* [API Documentation](#api-documentation) -* [Sample Apps](#sample-apps) +* [OCF Object](#the-ocf-object) +* [OCF API Documentation](#ocf-api-documentation) +* [OCF Server](#ocf-server) +* [Server API Documentation](#server-api-documentation) +* [Server Samples](#server-samples) +* [OCF Client](#ocf-client) +* [Client API Documentation](#client-api-documentation) +* [Client Samples](#client-samples) Introduction ------------ @@ -13,13 +19,71 @@ protocol. Web IDL ------- -This IDL provides an overview of the interface; see below for documentation of -specific API functions. +This IDL provides an overview of the interfaces for OCF common, OCF Server and +OCF Client; see below for documentation of specific API functions. + +The OCF Object +-------------- +The OCF object is the top level object containing either OCF Server, +OCF Client, or both, as well as device and platform information. ```javascript // require returns an OCFObject // var ocf = require('ocf'); +interface OCFObject { + Server server; // OCF server object + Client client; // OCF client object + Platform platform; // OCF platform info + Device device // OCF device info +}; + +dictionary Platform { + string id; + string osVersion; + string model; + string manufacturerName; + string manufacturerURL; + string manufacturerDate; + string platformVersion; + string firmwareVersion; + string supportURL; +} + +dictionary Device { + string uuid; + string name; + string dataModels; + string coreSpecVersion; +} + +``` +The OCF device and platform objects can be set up after requiring 'ocf'. An +example of this can be found in [OCF Server sample](../samples/OcfServer.js). +The properties are registered to the system (and available during discovery) +once either `OCFServer.registerResource()` or `OCFClient.findResources()` +is called. + +OCF API Documentation +--------------------- + +### OCFObject.setBleAddress +`void setBleAddress(string address);` + +Sets the device's BLE MAC address. This function is only defined on +Zephyr boards with BLE capabilities (e.g. Arduino 101). + +The `address` parameter should be a MAC address string in the format +`XX:XX:XX:XX:XX:XX` where each character is in HEX format (0-9, A-F). + +OCF Server +---------- +```javascript +// OCFServer is an EventEmitter +interface Server { + Promise<OCFResource> register(ResourceInit init); +}; + dictionary ResourceInit { string resourcePath; // OCF resource path string[] resourceTypes; // List of resource types @@ -31,46 +95,27 @@ dictionary ResourceInit { object properties; // Dictionary of resource properties }; -interface OCFResource { +interface Resource { string resourcePath; // Path for this resource object properties; // Application specific resource properties }; -interface OCFRequest { +interface Request { OCFResource target; // Target/destination resource OCFResource source; // Source/origin resource Promise<void> respond(object data); }; -// OCFServer is an EventEmitter -interface OCFServer { - Promise<OCFResource> register(ResourceInit init); -}; - -interface OCFObject { - OCFServer server; // OCF server object -}; - // listener for onretrieve event -callback RetrieveCallback = void (OCFRequest request, boolean observe); +callback RetrieveCallback = void (Request request, boolean observe); // listener for onupdate event -callback UpdateCallback = void (OCFRequest request); +callback UpdateCallback = void (Request request); ``` -API Documentation +Server API Documentation ----------------- - -### setBleAddress -`void setBleAddress(string address);` - -Sets the devices BLE MAC address. This function is in the global scope. It -is only defined on Zephyr boards with BLE capabilities (e.g. Arduino 101). - -The `address` parameter should be a MAC address string in the format -`XX:XX:XX:XX:XX:XX` where each character is in HEX format (0-9, A-F). - -### OCFServer.register +### Server.register `Promise<OCFResource> register(ResourceInit init);` Register a new resource with the server. @@ -79,17 +124,17 @@ The `init` contains the resource initalization information. Returns a promise which resolves to an `OCFResource`. -### OCFServer.on('retrieve', RetrieveCallback listener) +### Server.on('retrieve', RetrieveCallback listener) Register an `onretrieve` listener. This event will be emitted when a remote client retrieves this servers resource(s). -### OCFServer.on('update', UpdateCallback listener) +### Server.on('update', UpdateCallback listener) Register an `onupdate` listener. This event will be emitted when a remote client updates this servers resource(s). -### OCFRequest.respond +### Request.respond `Promise<void> respond(object data);` Respond to an OCF `onretrieve` or `onupdate` event. @@ -101,7 +146,101 @@ the retrieved property data. Returns a promise which resolves successfully if there was no network error sending out the data. -Sample Apps +Server Samples ----------- * [OCF Server sample](../samples/OcfServer.js) -* [OCF Sensor sample](../samples/OcfSensorServer.js) +* [OCF Sensor Server](../samples/OcfSensorServer.js) + +OCF Client +---------- +```javascript +// OCFClient is an EventEmitter +interface Client { + Promise<Resource> findResources(ClientOptions options, optional FoundListener listener); + Promise<Resource> retrieve(string deviceId, object options); + Promise<Resource> update(Resource resource); + Promise<Platform> getPlatformInfo(string deviceId); + Promise<Device> getDeviceInfo(string deviceId); +}; + +dictionary ClientOptions { + string deviceId; + string resourceType; + string resourcePath; +} + +interface Resource { + string resourcePath; // Path for this resource + object properties; // Application specific resource properties +}; + +callback FoundListener = void (ClientResource); +``` + +Client API Documentation +------------------------ +### Client.findResources +`Promise<ClientResource> findResources(ClientOptions options, optional FoundListener listener);` + +Find remote resources matching `options` filter. + +The `options` parameter should contain a filter of resource options. Only +resources matching these options will be found. + +The `listener` parameter is an optional event listener callback. This +callback will be called if a resource is found (`onfound` event). + +Returns a promise which resolves with a `ClientResource` object if a resource +was found. + +### Client.retrieve +`Promise<Resource> retrieve(string deviceId, object options);` + +Retrieve (GET) a remote resource. + +The `deviceId` parameter is the device ID of the resource you are retrieving. +This ID must match a resource which has been found with `findResources()`. + +The `options` object properties contain flag information for this GET request +e.g. `observable=true`. + +Returns a promise which resolves to a `ClientResource` containing the resource +properties. + +### Client.update +`Promise<Resource> update(Resource resource);` + +Update remote resource properties. + +The `resource` parameter should contain a `deviceId` for the resource to +update. The `properties` parameter will be sent to the resource and updated. + +Returns a promise which resolves to a resource `Resource` containing the +updated properties. + +### Client.getPlatformInfo +`Promise<Platform> getPlatformInfo(string deviceId);` + +Get `Platform` information for a resource. + +The `deviceId` parameter should be the ID for a resource found with +`findResources()`. + +Returns a promise which resolves to a `Platform` containing the platform +information for the resource. + +### Client.getDeviceInfo +`Promise<Device> getDeviceInfo(string deviceId);` + +Get `Device` information for a resource. + +The `deviceId` parameter should be the ID for a resource found with +`findResources()`. + +Returns a promise which resolves to a `Device` containing the device +information for the resource. + +Client Samples +------------------ +* [OCF Client sample](../samples/OcfClient.js) +* [OCF Sensor Client](../samples/OcfSensorClient.js) diff --git a/src/zjs_ocf_ble.c b/src/zjs_ocf_ble.c index 27ee19d..85b9522 100644 --- a/src/zjs_ocf_ble.c +++ b/src/zjs_ocf_ble.c @@ -54,10 +54,10 @@ static int str2bt_addr_le(const char *str, const char *type, bt_addr_le_t *addr) return 0; } -static jerry_value_t ocf_set_ble_address(const jerry_value_t function_val, - const jerry_value_t this, - const jerry_value_t argv[], - const jerry_length_t argc) +jerry_value_t zjs_ocf_set_ble_address(const jerry_value_t function_val, + const jerry_value_t this, + const jerry_value_t argv[], + const jerry_length_t argc) { // args: address ZJS_VALIDATE_ARGS(Z_STRING); @@ -99,7 +99,4 @@ void zjs_init_ocf_ble() BT_ADDR_SET_STATIC(&id_addr.a); bt_storage_register(&storage); #endif - jerry_value_t global_obj = jerry_get_global_object(); - zjs_obj_add_function(global_obj, ocf_set_ble_address, "setBleAddress"); - jerry_release_value(global_obj); } diff --git a/src/zjs_ocf_ble.h b/src/zjs_ocf_ble.h index 6aa4418..e36a18e 100644 --- a/src/zjs_ocf_ble.h +++ b/src/zjs_ocf_ble.h @@ -9,4 +9,9 @@ void zjs_init_ocf_ble(); +jerry_value_t zjs_ocf_set_ble_address(const jerry_value_t function_val, + const jerry_value_t this, + const jerry_value_t argv[], + const jerry_length_t argc); + #endif /* SRC_ZJS_OCF_BLE_H_ */ diff --git a/src/zjs_ocf_common.c b/src/zjs_ocf_common.c index 9e4f6b7..d039cea 100644 --- a/src/zjs_ocf_common.c +++ b/src/zjs_ocf_common.c @@ -475,7 +475,9 @@ jerry_value_t zjs_ocf_init() zjs_set_property(ocf_object, "server", server); jerry_release_value(server); #endif - +#ifdef ZJS_CONFIG_BLE_ADDRESS + zjs_obj_add_function(ocf_object, zjs_ocf_set_ble_address, "setBleAddress"); +#endif return ocf_object; } |