SAP Dynamic Edge Processing IoT Edge Services Developer Guide Version 2.0 FP01

Transcription

1 SAP Dynamic Edge Processing IoT Edge Services Developer Guide Version 2.0 FP01

2 TABLE OF CONTENTS PLUGIN DEVELOPMENT... 3 Introduction to Plugins for IoT Edge Services... 3 Protocol Plugins... 3 Enterprise Plugins... 3 Writing a Custom Plugin (Java)... 3 IPlugin Interface... 4 IProtocolPlugin Interface... 4 IProtocolAdapter Interface... 5 IEnterprisePlugin Interface... 6 Configuring a Custom Plugin... 8 Location of Custom Plugin JAR... 8 Registering and Configuring a Custom Protocol Plugin... 8 Registering and Configuring a Custom Enterprise Plugin... 8 EXTERNAL CUSTOM RULE - STREAMING LITE CCL PROJECT DEVELOPMENT... 9 Input Schema... 9 Output Schema... 9 Input Schema Details Debugging Compiling the CCL into a CCX File Start the Custom Project Starting the Custom Project with User Authentication APPENDIX Custom CCL Sample Template

3 PLUGIN DEVELOPMENT Introduction to Plugins for IoT Edge Services IoT edge services has been designed to be extensible. Plugins can be written in the form of Java classes conforming to a particular interface. This allows support for a multitude of IoT devices and enterprise destinations. There are two types of plugins that can be written by developers: protocol plugins and enterprise plugins. Protocol Plugins Protocol plugins are the entry point for data ingestion into IoT edge services. They are used to listen for and receive messages sent from smart devices, format the received data into an Object representing the sensor s value or state, and send it to the IoT edge services IIoTAdapter. As such, custom protocol plugins can be written to support any type of protocol that a smart device may make use of in order to get data into IoT edge services. Protocol plugins must also support receiving messages from the IoT edge services IIoTAdapter. However, the plugin does not necessarily need to do anything with the message. For example, message output is not supported via the REST portion of the provided HttpProtocolPlugin. Messages are sent from the IIoTAdapter to the plugin if a field message is generated as an action in response to an event. The plugin can make use of the received data as it sees fit. Enterprise Plugins Enterprise plugins are output end points for Dynamic Edge Processing. If a rule is configured to send to an enterprise plugin, every time an event or fidelity reading is generated by the rule, it is forwarded to the configured enterprise plugins. Enterprise plugins are a very flexible way of using Dynamic Edge Processing because the received information can be used in any way the developer wishes. Writing a Custom Plugin (Java) To implement a plugin, a number of interfaces must be satisfied. The IPlugin interface outlines methods common to all types of plugins. The IProtocolPlugin interface outlines methods for protocol plugins, while the IEnterprisePlugin interface outlines methods for enterprise plugins. Both of these interfaces extend the IPlugin interface, so both protocol plugins and enterprise plugins must implement these methods. Protocol plugins must implement the IProtocolPlugin interface and all of its methods and enterprise plugins must implement the IEnterprisePlugin interface and all of its methods. These interfaces as well as all other com.sap.dep. classes referenced in this guide are located in the DEPPluginClient JAR file located in /opt/dep_iot_edge/java_lib. In addition, this JAR contains the com.sap.dep.logging.logmanager class through which you can get access to a com.sap.dep.logging.ilogger logger instance for your plugin via the getlogger(class component) method. This logger will write to a file in /opt/dep_iot_edge/log/ named <YourPluginClassName>.log. 3

4 IPlugin Interface Signals to the plug-in that it should clean up resources and shutdown public void stopplugin(); Allows the IIoTAdapter to periodically verify that the plug-in has the active connections it requires. If false} is returned, #reconnectrequest} will be called. boolean isconnected(); Called by the IIoTAdapter after #isconnected} returns false}. void reconnectrequest(); Allows the IIoTAdapter to notify the plug-in of a change to the plug-ins log level. void changeloglevel(ilogger.level level); The stopplugin method, defined as part of the IPlugin interface, is called by the IIoTAdapter before IoT edge services is shut down. This method has no parameters. An implementation of this method should close any closeable objects the plugin is using and do any necessary cleanup. The isconnected method is defined in order for the plugin to report its connection status in the form of a boolean to the IIoTAdapter. This method has no parameters. An implementation of this method should return false if the plugin requires a reconnection attempt. Otherwise, true should be returned. If false is returned, reconnectrequest is called. The counterpart to isconnected is reconnectrequest which is called when isconnected returns false. This method has no parameters. The implementation of this method should ensure that the plugin is in a valid state for interactions with smart devices and/or the IIoTAdapter. Lastly, a changeloglevel method is defined. An implementation of this method should switch the logging level to the given ILogger.Level enum argument. Following is an example of where logger is an ILogger object that handles logging for the plugin and level is the passed ILogger.Level. logger.setlevel(level); IProtocolPlugin Interface Starts the plug-in 4

5 @param adapter an IProtocolAdapter} which can be used to input messages destined for pluginconfig a {@link Properties} instance that holds the mapped configuration for the StartupFailureException if the plugin fails to startup properly and cannot recover void startplugin(iprotocoladapter adapter, Properties pluginconfig) throws StartupFailureException; Handles a message being output from one of the {@link IEnginePlugin} plug-ins to this message The message being given for the plug-in to handle. Class type is specific to the {@link IEnginePlugin} sending the message void handleenginemessage(object message); The IProtocolPlugin interface defines a startplugin method with two parameters: an IProtocolAdapter object used to route messages to the IIoTAdapter, and a Properties object containing all configuration information stored in the database (see Registering and Configuring a Custom Protocol Plugin). This method is called from the main thread of the IIoTAdapter so that any blocking calls should be made on a separate thread. If at any point the plugin startup fails, a StartupFailureException should be thrown by the method. Implementation of this method should prepare the plugin for use, which may require making use of the Properties object. The method should also continuously listen for messages over the desired protocol. The IProtocolAdapter interface defines one method, sendmessagetoengineplugins method, which sends the given message Object to all registered engine plugins (see Plugin Development) using the sourceplugin argument to identify the sending plugin. To input sensor readings to the Streaming Lite Engine Plugin, the message should be an instance of com.sap.dep.client.inboundmessage populated with the reading data via the InboundMessage.fromJSON(jsonMessage) method. The required JSON format can be found in the SAP Dynamic Edge Processing IoT Edge Services - Configuration Guide, under the Sending Data to a Protocol Plugin section. IProtocolAdapter Interface Passes the provided input message to the desired Engine plug-in, provided it message the message to forward on. The plug-in you are attempting to input a message into likely has a format or object it is expecting to receive. Ensure you are conforming to these sourceplugin the IProtocolPlugin object that is sending to its registered destination IEnginePlugin(s) This is done using the canonical name of the Protocol plug-in class sending the message. Example: 5

6 UnsupportedMessageTypeException void sendmessagetoengineplugins(object message, IProtocolPlugin sourceplugin) throws UnsupportedMessageTypeException, UnsupportedSensorException; Following is an example using this method, where protocoladapter is an IProtocolAdapter object, message is a com.sap.dep.client.inboundmessage, and this implements IProtocolPlugin. protocoladapter.sendmessagetoengineplugins(message, this); The IProtocolPlugin interface also defines a handleenginemessage method. This method takes a single argument, a generic Object that is the message. This method is called by IIoTAdapter when the Streaming Lite Engine Plugin has generated a field message as a result of an action associated to a triggered rule. In that case, the message object is an instance of com.sap.dep.client.fieldmessage. Implementations that handle field messages can gain access to a JSON string version of the field message by calling message.tostring(). In order for Protocol Plugins to be loaded by Dynamic Edge Processing, the JAR file containing the plugin classes must have the appropriate service provider interface file in the META-INF directory, as outlined below. This only applies to protocol plugins. File Path & Name File Contents META- INF/services/com.sap.dep.interfaces.IProtocolPlugin Canonical Name for the class implementing IProtocolPlugin Example: com.example.protocolplugin.mypluginclass IEnterprisePlugin Interface Starts the config A {@link Properties} instance that holds mapping of configuration for the Exception public void startplugin(properties config) throws Exception The plugin must throw an exception if it fails to handle an event and wants it to be put in a retry queue public void handleenterpriseevent(enterpriseevent event) throws Exception; 6

7 @param Exception The plugin must throw an exception if it fails to handle an event and wants it to be put in a retry queue public void handlefidelityevent(sensorfidelityevent event) throws Exception; Enterprise plugins can be configured to allow multiple simultaneous instances of the plugin with different configuration properties. The IEnterprisePlugin defines a startplugin method with a Properties object parameter containing all configuration information stored in the database (see Registering and Configuring a Custom Protocol Plugin). If at any point the plugin startup fails, a StartupFailureException should be thrown by the implemented method. Implementation of this method should prepare the plugin for use, which may require making use of the Properties object. Next, the interface defines a handleenterpriseevent method which takes a com.sap.dep.client.enterpriseevent object as an argument. This method is called every time an event is generated by a rule that has this plugin associated to it. Implementation of this method should make use of the EnterpriseEvent object and perform any follow-up actions necessary to handle the particular event. An exception can be thrown by this method in order for the EnterpriseEvent to be put into a re-attempt queue. The get methods listed below allow access to the event s data. / List of EnterpriseEvent object get methods String getdeviceid(); String getdevicetag(); String getsensorprofileid(); String getsensorprofilename(); String getsensorid(); String getsensortag(); String getsourceruletype(); String getsourceruleid(); String getsourcerulename(); String getsensorinformation(); Date getdatecreated(); Finally, the interface defines a handlefidelityevent method that takes a com.sap.dep.client.sensorfidelityevent object as an argument. This method is called every time a sensor fidelity reading is sent to the enterprise plugin, as determined by the sensor s fidelity rule settings. An exception can be thrown by this method in order for the SensorFidelityEvent to be put into a re-attempt queue. The get methods listed below allow access to the event s data. / List of SensorFidelityEvent object get methods String getdeviceid(); String getdevicetag(); String getsensorprofileid(); String getsensorprofilename(); 7

8 String getsensorid(); String getsensortag(); String getsensorreadingvalue(); String getsourceruleid(); String getcontext(); Date getdatecreated(); Configuring a Custom Plugin Once the java file(s) has/have been written for the custom plugin and a JAR file has been created, it must be placed in the designated installation subdirectory. Next, the custom plugin must be configured via the database. Location of Custom Plugin JAR The custom JAR file needs to be placed in the /opt/dep_iot_edge/java_lib directory. This is the directory where Dynamic Edge Processing will look for plugins to start. Registering and Configuring a Custom Protocol Plugin The protocol plugin must be configured for integration with IoT edge services. Please refer to the SAP Dynamic Edge Processing IoT edge services - Configuration Guide. Registering and Configuring a Custom Enterprise Plugin The enterprise plugin must be configured for integration with IoT edge services. Please refer to the SAP Dynamic Edge Processing IoT edge services - Configuration Guide. 8

9 EXTERNAL CUSTOM RULE - STREAMING LITE CCL PROJECT DEVELOPMENT NOTE: This document assumes you are familiar with CCL development. If this is not the case, please refer to the Smart Data Streaming developer information found at for further information. Streaming Lite does not support the full functionality offered by Smart Data Streaming. The external custom rule provides the ability define custom processing logic to be used as a rule. The custom CCL project must satisfy these two requirements to integrate into IoT edge services. 1. The custom CCL project has an Input Stream named iscustomsl with a schema matching the Input Schema outlined below. 2. The custom CCL project has an Output Stream named oscustomsl with a schema matching the Output Schema outlined below. The RuleId being output needs to match either the Rule ID or Rule Name of the External Custom Rule configured to use the custom CCL project. It is recommended to use the Rule Name as it isn t system generated and can be consistent across deployments. Between these streams, the custom CCL can consume the data from iscustomsl and define the logic required for the custom rule. Once the conditions for the rule have been met, an output to oscustomsl must be made with all of the input stream data, except Context, and the Rule ID or Rule Name of the triggered event. The output is consumed by IoT edge services, and IoT edge services performs scoping and enforces the Max Event Frequency for the rule. If scoping is met and the event hasn t occurred too recently, the actions configured for the rule will fire, the event will be sent to the configured enterprise endpoints, and the event will be saved to the edge database if the rule has been configured to do so. A basic sample template for a custom CCL project can be found in the appendix. Input Schema SCHEMA ( DeviceId string, DeviceTag string, SensorId string, SensorTag string, SensorProfileId string, SensorReadingValue string, Context string, DateCreated msdate ) Output Schema SCHEMA ( DeviceId string, DeviceTag string, SensorId string, SensorTag string, SensorProfileId string, SensorReadingValue string, DateCreated msdate, RuleId string ) 9

10 IOT EDGE SERVICES - DEVELOPER Input Schema Details The only required and guaranteed non-null fields are DeviceId, SensorProfileId, SensorReadingValue, and DateCreated. SensorReadingValue can be cast to an integer or a float using the to_integer() or to_float() CCL functions. Debugging To debug using Streaming Lite, make use of the print(string) function and direct the output to a file or watch the terminal hosting the streamingproject. If the value of the print statement is null or any of the values being concatenated are null, an empty line will be output. An easy way to get prevent this is to use firstnonnull(thepossiblenullvalue, 'null'). Compiling the CCL into a CCX File Use the streamingcompiler executable in $STREAMING_HOME/bin to compile the CCL file. Replace the placeholders in the following example with your path and files. $STREAMING_HOME/bin/streamingcompiler i <path-to-ccl>/<ccl-file-name>.ccl o <output-path>/<compiled-file-name>.ccx The -i flag is used to specify the input file and the -o flag is used to specify the output file. Start the Custom Project Start the project using the streamingproject executable in $STREAMING_HOME/bin to start the compiled ccx as a process. Replace the placeholder paths and file with those for your CCX file. NOTE: Port 9230 is used by the primary IoT Edge Services streaming project and should not be used for custom projects. $STREAMING_HOME/bin/streamingproject --ccx <path-to-ccx>/<compiled-file-name>.ccx - -command-port host localhost The --ccx flag is used to specify the CCX file to run, the --command-port flag is used to specify the port that the custom project listens to, and the --host flag specifies the host address the custom project listens on. To redirect the terminal output to a file, add the following to the end of the previous command. Customize the path and file name, as necessary. >> ~/customprojectoutput.log 2>&1 Starting the Custom Project with User Authentication Starting the project using the streamingproject executable in with the -V flag will enable user authentication. Custom projects are authenticated using the same user credentials as the main IoT edge services streaming lite project. See the SAP Dynamic Edge Processing: Edge Business Services - Configuration Guide for instructions to configure the Streaming Lite authentication mechanism 10

11 APPENDIX Custom CCL Sample Template / Copyright (c) 2016 SAP SE or an affiliate company. All rights reserved. This is a sample template that may be used to create custom CCL project that integrates with SAP Dynamic Edge Processing / You MUST have an input stream with this name and this schema CREATE INPUT STREAM iscustomsl SCHEMA ( DeviceId string, DeviceTag string, SensorId string, SensorTag string, SensorProfileId string, SensorReadingValue string, Context string, DateCreated msdate ); / You may call this flex operator or any window operation and its output stream whatever you wish CREATE FLEX ThisCanBeRenamed IN iscustomsl OUT OUTPUT STREAM ThisCanBeRenamed SCHEMA ( DeviceId string, DeviceTag string, SensorId string, SensorTag string, SensorProfileId string, SensorReadingValue string, DateCreated msdate, RuleId string ) BEGIN ON iscustomsl { OUTPUT [ DeviceId=isCustomSL.DeviceId; DeviceTag=isCustomSL.DeviceTag; SensorId=isCustomSL.SensorId; SensorTag=isCustomSL.SensorTag; SensorProfileId=isCustomSL.SensorProfileId; SensorReadingValue=isCustomSL.SensorReadingValue; DateCreated=isCustomSL.DateCreated; RuleId='This will be the Id or Name of the Rule your custom logic triggers'; ]; }; END; / You MUST have an output stream with this name and this schema CREATE OUTPUT STREAM oscustomsl 11

12 AS SELECT ThisCanBeRenamed.DeviceId DeviceId, ThisCanBeRenamed.DeviceTag DeviceTag, ThisCanBeRenamed.SensorId SensorId, ThisCanBeRenamed.SensorTag SensorTag, ThisCanBeRenamed.SensorProfileId SensorProfileId, ThisCanBeRenamed.SensorReadingValue SensorReadingValue, ThisCanBeRenamed.DateCreated DateCreated, ThisCanBeRenamed.RuleId RuleId FROM ThisCanBeRenamed; 12

13 SAP SE or an SAP affiliate company. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. Please see for additional trademark information and notices. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors. National product specifications may vary. These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP SE or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. In particular, SAP SE or its affiliated companies have no obligation to pursue any course of business outlined in this document or any related presentation, or to develop or release any functionality mentioned therein. This document, or any related presentation, and SAP SE s or its affiliated companies strategy and possible future developments, products, and/or platform directions and functionality are all subject to change and may be changed by SAP SE or its affiliated companies at any time for any reason without notice. The information in this document is not a commitment, promise, or legal obligation to deliver any material, code, or functionality. All forward-looking statements are subject to various risks and uncertainties that could cause actual results to differ materially from expectations. Readers are cautioned not to place undue reliance on these forward-looking statements, which speak only as of their dates, and they should not be relied upon in making purchasing decisions.