Scope and Purpose of this Guideline 1 Requirements 2 MindSphere MindConnect LIB Developer Guideline Limitations 3 Testing 4 Branding 5 07/2017
Legal information Warning notice system This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger. DANGER indicates that death or severe personal injury will result if proper precautions are not taken. WARNING indicates that death or severe personal injury may result if proper precautions are not taken. CAUTION indicates that minor personal injury can result if proper precautions are not taken. NOTICE indicates that property damage can result if proper precautions are not taken. If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage. Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems. Proper use of Siemens products Note the following: WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed. Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions. Siemens AG Division Digital Factory Postfach 48 48 90026 NÜRNBERG GERMANY P 07/2017 Subject to change Copyright Siemens AG 2017. All rights reserved
Table of contents 1 Scope and Purpose of this Guideline... 5 2 Requirements... 7 3 Limitations... 9 4 Testing... 11 5 Branding... 13 System Manual, 07/2017 3
Scope and Purpose of this Guideline 1 The MindConnect LIB is a collection of functionalities provided as source code which allows software to connect with and transmit data from devices, systems and equipment to the MindSphere. The connection to the MindSphere is secured by using SSL/TLS in order to protect client's transferred data. All developers, operators and providers of software must meet or exceed these specifications for all software. Any capitalized terms not defined herein have the meaning given to them in the MindConnect LIB Terms ( LIB Terms ). The requirements and recommendations described in this MindConnect LIB Developer Guideline ( Guideline ) are not exhaustive and are supplemental to additional requirements set out in the LIB Terms. This Guideline is provided as-is and will be updated from time to time. Information in this Guideline, including URL and other website references, may change without notice. This Guideline has been reviewed to ensure consistency with the services described. Since variance cannot be precluded entirely, full consistency cannot be guaranteed. However, the information in this Guideline is reviewed regularly and any necessary corrections are included in subsequent editions. No license to any software or service, know-how or other intellectually property right is granted, conveyed or implied, by this document and all rights are expressly reserved by Siemens. You may copy and use this document solely for your internal, reference purposes. You may not use any Siemens trademarks, brands or other intellectual property to label, advertise or otherwise describe your Custom Agent or its functionality, unless you have obtained Siemens prior written approval. System Manual, 07/2017 5
Requirements 2 In order to build the MindConnect LIB you need the cross make tool "cmake (3.5.2 and newer)" and appropriate toolchain including compiler, linker, etc. for desired target environment. The current version of the MindConnect LIB works only (together with Libcurl V7.52.1 and OpenSSL V1.0.2k. Other versions of the mentioned third party libraries are not tested yet. It is also possible to replace HTTP client and security module by your implementation. In this case it is in your responsibility to ensure transport and security related requirements (s. Testing). Please make sure, that your Libcurl installation is configured to use OpenSSL as the TLS v1.2 implementation. To use OpenSSL with your implementation, one of following ciphers must be supported and configured for SSL handshaking: DHE-DSS-AES128-GCM-SHA256 DHE-DSS-AES256-GCM-SHA384 DHE-RSA-AES128-GCM-SHA256 DHE-RSA-AES256-GCM-SHA384 DHE-RSA-CHACHA20-POLY1305 ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-RSA-CHACHA20-POLY1305 In order to verify the correctness of the MindSphere certificate please enable host and peer verification. System Manual, 07/2017 7
Limitations 3 Upload cycle of data Custom Agents using the MindConnect LIB must upload timeseries data in the allowed cycle of 10s. Sampling cycle must not be lower than 1s for each datapoint Allowed maximum number of datapoints is 250. Allowed maximum MSU (MindSphere Units) limit is 10000 per asset Size limitations of files Allowed maximum file size to be download is 100 MB For each download request, a maximum of 2 MB of a range of a file can be requested. Allowed maximum file size to be uploaded is 100 MB Number of events Maximum 1000 events per day Formats The formats of the parameters must be correctly provided to the MCL functions. The formats of specific fields are described in the developer documentation ( Doxygen ). Format description for timeseries timestamps: YYYY-MM-DDThh:mm:ss.sssZ for Example: 2016-04-26T08:06:25.317Z Following datatypes are allowed: MindConnect LIB Standard Datamodel Parser Asset Management sint FLOAT sint uint FLOAT uint STRING STRING STRING REAL FLOAT REAL BOOL BOOL BOOL HTTPS & Authentication: For HTTPS communication you need to have the latest valid MindSphere s root certificate on client side. If root certificate expires (normally valid time is long enough) or System Manual, 07/2017 9
Limitations has been changed due to security issues you need to replace certificate on your custom agent side. Initial access token (IAT) for onboarding must be used (onboarding of agent) within 7 days after creation of virtual agent in MindSphere. If IAT expires a new agent has to be created. IAT can only be used one time. After successfully onboarding your custom agent needs to call within 7 days rotate key function of MindConnect LIB in order to update authentication credentials. If credentials are expired, your custom agent will not be able to communicate with MindSphere and you are forced to call rotate key. MindConnect LIB s default function for storing of authentication data can be replaced by your implementation in order to improve security level. 10 System Manual, 07/2017
Testing 4 Testing of a Custom Agent is very important to ensure the desired functionality and to guarantee security functions. A Custom Agents can only be tested on resources designated for development and testing purposes and not on productive environments. Before a Custom Agent can be used in a productive environment all necessary functions and security mechanisms have to be tested. Note: It is not allowed to connect any Custom Agent with a MindSphere productive system without prior testing. Requirements Testing must be conducted on developer space Developer space is only available with a MindAccess Developer Account Check if all formats are in line with the aforementioned criteria (see chapter 2.1 Limitations) Do not exceed the aforementioned limits for data uploads (see chapter 2.1. Limitations) Check the onboarding process with regard to functionality and security Test the datamodel upload (and confirm that all datapoints are available in the right format) Test upload cycles and other data exchange mechanisms Check all possible security vulnerabilities which may constitute a threat to your Custom Agent, or the data that shall be transmitted through the Custom Agent, or the MindSphere Platform System Manual, 07/2017 11
Branding 5 You must not use designations relating to Siemens, such as "Siemens", "Si", any similar reference to the designation "Siemens", including but not limited to SIMATIC, SINUMERIK, SINALYTICS, and any abbreviations thereof, logos relating to Siemens or any word or logo confusingly similar thereto. You must not use the name of your Custom Agent or any of your trademarks or trade names in direct or indirect combination with or adjacent to any Siemens product or otherwise refer thereto. You are only entitled to use trademarks or trade names of Siemens upon our prior separate written approval, which must be requested by you on a case by case basis. Trademarks and tradenames of Siemens include without limitation MindSphere, MindConnect, MindApp, MindGate and other designations beginning with Mind. System Manual, 07/2017 13