OPC UA Protocol Stack

Transcription

1 Enhanced Universal Realtime Operating System OPC UA Protocol Stack Programming Guide and Reference Document version: 05/2018 EUROS Embedded Systems GmbH Campestraße 12 D Nuremberg Germany Phone: Fax: Web:

2 Rev. Changes Date -001 first issue

3 General remarks All rights of this product information are reserved. No part of this product information may be reproduced in any form (print, photocopy, microfilm or other media) or processed, copied and distributed to third parties using electronic systems. This product information describes the present status of development. Modifications therefore are reserved. This product information was prepared with utmost care. However, no guarantee or liability for the faultlessness and correctness of the contents can be taken upon. EUROS is a registered trademark of EUROS Embedded Systems GmbH. IBM is a registered trademark of the IBM Corporation. Windows 7/8/10 are registered trademarks of the Microsoft Corporation. All others brands and product names are trademarks or registered trademarks of the appropriate title holders. Copyright by EUROS Embedded Systems GmbH, Campestr. 12, D Nuremberg, Germany Printed in Germany

4

5 The EUROS documentation The Documentation of the operating system EUROS is devided in four manuals: EUROS Programmer s Guide, EUROS User s Guide, EUROS Reference Manual and the EUROS Installation Guide, which are part of the EUROS development licence. The four basic manuals of the operating system have the following goals: EUROS Programmer s Guide The Programmer s Guide gives an overview over the concepts, the components and the system services of the operating system EUROS. The EUROS components and system objects are introduced and their properties and use are described. EUROS Reference Manual The EUROS Reference Manual contains detailled and complete descriptions of the system calls implemented under EUROS. It is the basic tool in order to write succesfully applications under the operating system EUROS. The system services of the Microkernel, I/O System, Process Manager, C-Library and the POSIX Interface are described. EUROS Installation Guide The EUROS Installation Guide contains information for the system administrator concerning the configuration, installation and adaption of the operating system. It is included in the development package and describes, how the adapt a target board monitor, how to configure a timer, an UART and an interrupt controller used by the operating system and how to dimension the EUROS data areas. Further documentation Each EUROS software component comes with its own documentation. Of special interest for OPC UA users are the manual of the respective ethernet driver and the manual of the networking components of EUROS. OPC UA detailed documentation The OPC UA protocol stack uses the same API as Unified Automation ( there Unified automation can be used for a look up of detail information.

6

7 EUROS IrDA Component Contents Table of contents Chapter 1 Introduction 1.1 OPC UA OPC UA Profiles Chapter 2 OPCUA Programming Guide 2.1 Installation Files Library Versions Dependencies on other libraries EUROSmake OPCUA programming Preliminaries Configuration Sample Code i

8 Contents EUROS IrDA Component ii

9 Definitions The following notational conventions are used for this manual: Block print <CR> User input, examples, name of variables and functions are displayed in block print. Non-printable characters are displayed as their names in angle brackets. [ ] Options and optional parameters are displayed in square brackets. Options and parameters of which exactly one can be used are seperated by a vertical line. M Function may be called in main(). I N S A Function may be called in I state. Function may be called in N state. Function may be called in S state. Function may be called in A state.

10

11 Chapter 1 Introduction

12

13 OPC UA Protocol stack Introduction 1.1 OPC UA OPC UA (Unified Architecture) is a standard provided by the OPC Foundation for data exchange in industrial automation. Furthermore it provides a data model which can be extended by third partites. All data is organized as nodes in a hierarchical and object oriented address space. 1-3

14 Introduction OPC UA Protocol stack 1-4

15 OPC UA Protocol stack Introduction 1.2 OPC UA Profiles OPC UA profiles are used for scaling OPC UA applications in accordance with the capability of the used hardware ranging from low-end microcontrollers to high-end PCs. For OPC UA servers for profiles are defined Nano: This is the most basic profile. It includes the ability to establish communications with clients, create sessions, browse the address space and read and/or write to attributes of nodes. Micro: The micro profile contains all functionality of the nano profile and adds the capability to monitor nodes for changes of their value passed on a subscription model. Embedded (emb): The embedded profile takes the micro profile and adds cryptogrpahic routines for secure communications Standard (std): In addition to the capabilities of the embedded profile, it is now possible for a client to execue function calls on the server. Furthermore authentication and authorization mechanisms are added. Address space can be either sourced in from a file at startup time of the server or compiled in into the server at compile time. In the later case we will speak of a static address space and name the resulting profiles (informally) by adding a -static to the profile name, i. e. nano-static, micro-static, emb-static, std-static. 1-5

16 Introduction OPC UA Protocol stack 1-6

17 Chapter 2 OPCUA Programming Guide

18 OPCUA Programming Guide OPC UA Protocol stack 2-8

19 OPC UA Protocol stack OPCUA Programming Guide 2.1 Installation Files The following files are shipped with the OPC UA protocol stack where profile is one of the OPC UA profiles:: crashhandler_<profile>.lib encoder_proxy_<profile>.lib uaencoder_<profile>.lib ipc_<profile>.lib Routines for gathering and providing basic information on case of a crash of the application Routines for encoding and decoding transmitted data Routines for data exchange between diferent instances of the OPC UA server and/or external applications memory_<profile>.lib Memory management minimalprovider_<profile>.lib Basic routines for providing the address space network_<profile>.lib platform_<profile>.lib timer_<profile>.lib uaapplication_<profile>.lib uabase_<profile>.lib uaseconv_<profile>.lib Networking routines Abstraction layer for accessing OS services Timer routines uaseconv_proxy_<profile>.lib uaserver_<profile>.lib uaserverprovider_<profile>.lib uasession_proxy_<profile>.lib uatcp_<profile>.lib uatcpmsg_proxy_<profile>.lib util_<profile>.lib Configuration API Basic routines of the OPC UA protocol stack Routines for the secure channel communication between server and client OPC UA server generic routines OPC UA server OPC UA specific routines session management OPC UA s TCP protocol Miscellaneous helper function 2-9

20 OPCUA Programming Guide OPC UA Protocol stack uaconfig_<profile>.lib uafielformat_<profile>.lib trace_<profile>.lib pki_store_proxy_<profile>.lib uapki_<profile>.lib uapki_store_<profile>.lib uacrypto_<profile>.lib opcua2018/<profile> Parsing routines for configuration files (not in static profiles) Routines for file handling (not in static profiles) Trace library (Tracing versions only) where <profile> is one of the OPCUA profiles: nano, micro, emb, std Management of cryptographic certificates (emb and std profiles only) Cryptographic routines (emb and std profiles only) C header file for OPCUA function calls, macro definitions and data types where <profile> is one of the OPCUA profiles: nano, micro, emb, std Library Versions The OPCUA protocol stack library is shipped in a Debug version, a No-Debug version and in a Tracing version. The Debug and/or the Tracing version should be used when developing OPCUA applications. The No-Debug version should be used for production code Dependencies on other libraries When using the embedded or the standard profile the application must be linked against libcrypto.lib from OpenSSL project. Unless using static variants (i. e. with namespace compiled in) the application must be linked against the file system library fms2.lib. All profiles require process.lib, net.lib and clib.lib. 2-10

21 OPC UA Protocol stack OPCUA Programming Guide 2.2 EUROSmake When using EUROSmake just add the line OPCUA_PROFILE=<profile> to your project.inc file where profile is the OPCUA profile you want to use: nano, micro, emb, std. If you want to build-in the namespace add -static to the profile name, e. g. nano-static. EUROSmake will take care of including all neccessary headers and libraries so no further steps are required. 2-11

22 OPCUA Programming Guide OPC UA Protocol stack 2.3 OPCUA programming Preliminaries The OPCUA stacks needs network services and semaphore services. Before starting the OPCUA stack please ensure that those services are set up correctly (cf. the respective EUROS manuals). If you are using cryptographic code (i. e. embedded or standard profiles) you must ensure that the random number generator has at least 256 bytes of entropy available. Furthermore you are required to define a global variable: #include <appconfig.h> struct appconfig g_appconfig; Configuration Before starting the OPCUA stack, you are required to initialize the product info of the g_appconfig structure: /*! [product_info] */ g_appconfig.manufacturer_name = <your name>; g_appconfig.product_name = <your product>; g_appconfig.product_uri = <your URI>; g_appconfig.application_name = <your application name>; g_appconfig.application_uri = <your applciation URI>; g_appconfig.dns = <domain name of the device>; /*! [product_info] * If you are using the static variants you will have to initialize further members of g_appconfig. Next call: #include <uaapplication/application.h> int uaapplication_init(struct uaapplication *app, int trace_level, int facility_mask, const char *config_file); If you are using a static variant config_file is ignored (and can be set to NULL), otherwise it must be the filename of a configuarion file containing necessary configuration data. Next call #include <uaserver/init.h> int uaserver_init(struct uaserver_provider *provider, int num_provider); In case you are using a static namespace the provider list should contain {-1, uaprovider_server_init} and you should provide a function int ua_register_static_addressspace(void); which handles the creation of the namespace. If you are loading you name space from a file, set uaserver_init s provider list to {-1, custom_init} with some custom function #include <uaserver/provider/provider.h> 2-12

23 OPC UA Protocol stack OPCUA Programming Guide int provider_file_init(struct uaprovider *ctx); which must call #include <uaserver/addressspace/persistence.h> int ua_addressspace_load_file(const char *filename, void *store, struct ua_addressspace_config *add); or int ua_addressspace_load_fd(ua_file_t f, void *store, struct ua_addressspace_config *add); for each namespace provider file you want to load. If file system is not supported you must also load your certificates (if required) via #include <proxystub/pki_store.h> int pki_store_save_cert(uint32_t store, struct pki_store_credentials *credentials, enum pki_store_loc location, size_t cert_len, unsigned char *cert_data, int prio); credentials are ignored without file system and can be set to NULL. The OPCUA server can now be started via #include <uaserver/init.h> int uaserver_start(void); After a sucessful start the calling task must enter an infinite loop (for the runtime of the OPCUA server) which calls: #include <uaapplication/application.h> int uaapplication_timed_docom(struct uaapplication *app, int timeout_ms); indefinitely, where app must be the variable initialized by uaapplication_init. 2-13

24 OPCUA Programming Guide OPC UA Protocol stack 2-14

25 OPC UA Protocol stack OPCUA Programming Guide 2.4 Sample Code #include <stdio.h> #include <uaapplication/application.h> #include <uaserver/init.h> #include <trace/trace.h> #include <appconfig.h> #include <uaprovider/server/uaprovider_server.h>#include <platform/ hostname.h> #include <platform/shutdown.h> #include <crashhandler/crashhandler.h> #include <memory/memory_layout.h> #include <uaserver/addressspace/persistence.h> #if USE_PROVIDER_FILE # include <uaserver/provider/provider.h> #endif #if defined(have_pki) # include <pki_store/pki_store_types.h> #endif #include <uaprovider/minimal/uaprovider_minimal.h> #include <openssl/rand.h> int server_main_init(int trace_level, int facility_mask, const char *config_file) { int ret; unsigned int i; static char fqdn[64]; struct ua_string tmp; ua_get_fqdn(fqdn, sizeof(fqdn)); /*! [product_info] */ g_appconfig.manufacturer_name = "EUROS GmbH"; g_appconfig.product_name = "HP SDK UA Demo Server"; g_appconfig.product_uri = "urn:euros:uademoserverhp"; g_appconfig.application_name = "HP SDK UA Demo Server"; g_appconfig.application_uri = "urn:euros:hpc:example"; 2-15

26 OPCUA Programming Guide OPC UA Protocol stack g_appconfig.dns /*! [product_info] */ = fqdn; /*! [uaapplication_init] */ #if! USE_PROVIDER_FILE g_appconfig.num_timers = 10; /* 100 */ g_appconfig.ipc.ipc_size = 130 * 1024; /* 16 MB */ g_appconfig.ipc.num_queues = 10; g_appconfig.ipc.num_services = 50; g_appconfig.ipc.num_messages = 100; g_appconfig.ipc.outprocess_encoder = 0; g_appconfig.net.buffer_size = 8*1024; /* 64 kb */ g_appconfig.net.num_buffers = 10; /* 100 */ g_appconfig.net.num_buffers_per_connection = 5; /* 50 */ g_appconfig.net.max_connections_per_ip = 19; g_appconfig.encoder.max_call_depth = 10; g_appconfig.encoder.max_string_length = 1000; g_appconfig.encoder.max_bytestring_length = 8000; g_appconfig.encoder.max_array_length = 1000; g_appconfig.subscription.num_sessions_with_subscriptions = 4; g_appconfig.subscription.num_publishrequests_per_session = 4; g_appconfig.subscription.num_notificationmessages_per_session = 8; g_appconfig.subscription.num_subscriptions_per_session = 2; g_appconfig.subscription.num_subscriptions = 8; g_appconfig.subscription.num_monitoreditems = 80; g_appconfig.subscription.max_monitoreditem_queue_size = 100; g_appconfig.subscription.max_notifications_per_publish = 1000; g_appconfig.subscription.min_publishing_interval = 10; g_appconfig.subscription.max_publishing_interval = 10000; g_appconfig.subscription.min_sampling_interval = 10; g_appconfig.subscription.max_sampling_interval = 10000; g_appconfig.subscription.min_lifetime = 1000; g_appconfig.subscription.max_lifetime = ; g_appconfig.session.num_sessions = 5; 2-16

27 OPC UA Protocol stack OPCUA Programming Guide g_appconfig.session.num_calls = 50; g_appconfig.session.keep_spare_session = true; g_appconfig.session.authentication_num_users = 10; g_appconfig.session.lifetime_check_interval = 5000; g_appconfig.session.lifetime_min = 10000; g_appconfig.session.lifetime_max = ; # if defined(ua_authentication_support) && defined(support_file_io) g_appconfig.session.authentication_passwd_file = "passwd"; # endif /* UA_AUTHENTICATION && SUPPORT_FILE_IO */ g_appconfig.session.authorization_num_users = 10; # if defined(ua_authorization_support) && defined(support_file_io) g_appconfig.session.authorization_users_file = "users"; # endif /* UA_AUTHORIZATION_SUPPORT && SUPPORT_FILE_IO */ g_appconfig.session.authorization_num_groups = 10; # if defined(ua_authorization_support) && defined(support_file_io) g_appconfig.session.authorization_groups_file = "groups"; # endif /* UA_AUTHORIZATION_SUPPORT && SUPPORT_FILE_IO */ g_appconfig.uatcpmsg.num_conns = 5; g_appconfig.uatcpmsg.num_listeners = 2; g_appconfig.uatcpmsg.num_ctxts = 50; g_appconfig.uatcpmsg.num_chunks = 3; g_appconfig.seconv.num_channels = 10; g_appconfig.seconv.min_security_token_lifetime = ; g_appconfig.seconv.max_security_token_lifetime = ; g_appconfig.seconv.keep_spare_channel = true; # ifdef HAVE_PKI g_appconfig.pkistore.num_pkistores = 1; g_appconfig.pkistore.pkistores = &MyPkistores; MyPkistores.config = "pki_store_0;5;5;5;5"; # endif g_appconfig.endpoint.endpoints = &MyEndpoint; MyEndpoint.endpoint_url = "opc.tcp://[hostname]:4840"; MyEndpoint.bind_address = " "; MyEndpoint.bind_port = 4840; MyEndpoint.user_tokens.num = 1; 2-17

28 OPCUA Programming Guide OPC UA Protocol stack g_appconfig.endpoint.user_tokens = &MyUserToken; g_appconfig.endpoint.num_user_tokens = 1; MyUserToken.name = "MyUserToken"; MyUserToken.type = UA_USERTOKENTYPE_ANONYMOUS; MyUserToken.policy_id = UA_SECURITY_POLICY_NONE; g_appconfig.endpoint.num_endpoints = 1; g_appconfig.endpoint.sec_configs = MySechan; MySechan[0].policy_id = UA_SECURITY_POLICY_NONE; MySechan[0].mode_none = true; MySechan[0].certificate = -1; # ifdef HAVE_CRYPTO MyEndpoint.security_policies.num = 2; MyEndpoint.security_policies.indicies[0] = 0; MyEndpoint.security_policies.indicies[1] = 1; MySechan[1].policy_id = UA_SECURITY_POLICY_BASIC256SHA256; MySechan[1].mode_none = false; MySechan[1].mode_sign_and_encrypt = true; MySechan[1].certificate = 0; MySechan[1].max_chain_length = 3; MySechan[1].max_verify_results = 5; g_appconfig.endpoint.num_sec_config = 2; g_appconfig.endpoint.num_sechan_certs = 1; g_appconfig.endpoint.allow_deprecated_policies = true; g_appconfig.endpoint.sechan_certs = &MySechanCert; ua_bytestring_attach(&mysechancert.server_cert, (char*) g_cert1024_der, (int) sizeof(g_cert1024_der)); ret = crypto_key_from_pem(g_private1024_key, sizeof(g_private1024_key), 0, 0, crypto_key_type_rsa_private, &MySechanCert.server_priv_key); if (0!= ret) { TRACE_ERROR(TRACE_FAC_APPLICATION, "could not source private key\n"); goto out_init; } # else MyEndpoint.security_policies.num = 1; MyEndpoint.security_policies.indicies[0] = 0; g_appconfig.endpoint.num_sec_config = 1; 2-18

29 OPC UA Protocol stack OPCUA Programming Guide # endif #endif g_appconfig.client.num_clients = 10; g_appconfig.client.num_subscriptions = 10; g_appconfig.client.session_timeout = ; g_appconfig.client.call_timeout = 10000; g_appconfig.client.return_diagnostics = 0; g_appconfig.client.publish_timeout = 60000; g_appconfig.client.keep_request = false; #ifdef HAVE_CRYPTO i = 0; do { #endif unsigned int ent = rand(); RAND_seed(&ent, sizeof(ent)); i += sizeof(ent); } while(256 > i); ret = uaapplication_init(&g_app, trace_level, facility_mask, config_file); if (ret!= 0) { TRACE_ERROR(TRACE_FAC_APPLICATION, "uaapplication_init failed.\n"); goto out_init; } /*! [uaapplication_init] */ /* replace [hostname] place holder in endpoint urls with fqdn */ for (i = 0; i < g_appconfig.endpoint.num_endpoints; ++i) { ua_string_set(&tmp, g_appconfig.endpoint.endpoints[i].endpoint_url); if (ua_string_index_of(&tmp, "[hostname]")!= -1) { ua_string_replace(&tmp, "[hostname]", fqdn); /* free old endpoint url */ ua_free((void *)g_appconfig.endpoint.endpoints[i].endpoint_url); /* set new one */ g_appconfig.endpoint.endpoints[i].endpoint_url = ua_strdup(ua_string_const_data(&tmp)); 2-19

30 OPCUA Programming Guide OPC UA Protocol stack } } ua_string_clear(&tmp); /*! [init_sdk] */ TRACE_INFO(TRACE_FAC_APPLICATION, "Initializing providers...\n"); ret = uaserver_init(g_provider, countof(g_provider)); if (ret < 0) goto out_server_init; /*! [init_sdk] */ #ifdef HAVE_PKI ret = pki_store_save_cert(0, NULL, pki_store_loc_trstd, sizeof(g_client_cert), g_client_cert, 0); if (ret < 0) goto out_server_init; #endif /*! [start_server] */ TRACE_INFO(TRACE_FAC_APPLICATION, "Starting server...\n"); ret = uaserver_start(); if (ret < 0) goto out_server_start; /*! [start_server] */ return 0; out_server_start: uaserver_clear(g_provider, countof(g_provider)); out_server_init: uaapplication_cleanup(&g_app); out_init: return ret; } 2-20