Searching...

No Matches

Introduction

The S2OPC OPC UA Toolkit provides a Client/Server C source code implementation including an OPC UA communication stack, B model and C source code implementation for a minimal set of services and a cryptographic library adaptation for OPC UA needs (using mbedtls). S2OPC also provides a PubSub C source code implementation, it shares some components with Client/Server part (cryptographic services, OPC UA types, etc.).

For further details on supported features see the README.md file content. Additional information on how to build, configure and use S2OPC is also available on the wiki.

The following sections only concern the C source documentation.

You will find documentation on the Python binding for S2OPC on following page: Go to PyS2OPC documentation

Client / Server API

The Client / Server API is composed of high-level (wrapper) API and low-level API. The prefered way to use S2OPC is to use only the high-level API. Note that the low-level API will be subject to important changes and refactoring in the future release since the high-level API is designed to address any application need.

High-level Common Client/Server API

The high-level common Client/Server API shall be used to initialize (or clear) the S2OPC toolkit prior to use (or after using) the high-level client/server API. Those functions are shared between high-level server/client API:

SOPC_CommonHelper_Initialize shall be called before any other high-level API function to initialize S2OPC client/server tooklit. The logger configuration might be provided as parameter, the default configuration might be retrieved using SOPC_Common_GetDefaultLogConfiguration and modified as needed.
SOPC_CommonHelper_Clear shall be called after any other high-level API function to clear S2OPC client/server tooklit.
SOPC_CommonHelper_GetBuildInfo provides S2OPC client/server toolkit build info.

High-level Server API

The high-level server API provides functions for configuration (endpoints and security, address space content, user management, etc.) and functions to manage server execution (start/stop, local service execution, etc.).

The main configuration functions are defined by libs2opc_server_config.h:

SOPC_ServerConfigHelper_Initialize shall be called before any other function of the server wrapper module (and after SOPC_CommonHelper_Initialize).
SOPC_ServerConfigHelper_Clear shall be called when server wrapper module is not used anymore.
SOPC_ServerConfigHelper_ConfigureFromXML loads configuration from XML configuration files (server endpoints and security, address space, users). See XML file examples.
SOPC_ServerConfigHelper_SetMethodCallManager sets a manager for callbacks to use for CallMethod service (available only if s2opc is NOT compiled with S2OPC_NANO_PROFILE=1).
SOPC_ServerConfigHelper_SetWriteNotifCallback sets a callback to receive notification on address space write operations from clients.
SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse sets a callback to use local services on server in an asynchronous way (see SOPC_ServerHelper_LocalServiceAsync).
SOPC_ServerConfigHelper_SetKeyPasswordCallback sets a callback to provide the password to decrypt the private key of the server (if encrypted).

In case the dedicated XML configuration files are not used to configure server, use the additional configuration functions located in libs2opc_server_config_custom.h.

The main functions for server execution are defined by libs2opc_server.h:

SOPC_ServerHelper_StartServer: starts the server asynchronously, it runs until requested to stop.
SOPC_ServerHelper_StopServer: stops the server.
SOPC_ServerHelper_Serve synchronous alternative to SOPC_ServerHelper_StartServer, it blocks until server stopped.
SOPC_ServerHelper_LocalServiceAsync: executes a local service (add nodes, read, write, etc.) on server asynchronously, service response is provided through callback defined with SOPC_ServerConfigHelper_SetLocalServiceAsyncResponse.
SOPC_ServerHelper_LocalServiceSync: executes a local service (add nodes, read, write, etc.) on server synchronously.
SOPC_ServerHelper_CreateEvent: creates an OPC UA event instance of the given known event type (available only if s2opc is compiled with S2OPC_EVENT_MANAGEMENT=1)
SOPC_ServerHelper_TriggerEvent: triggers the given OPC UA event instance from the given node as notifier (available only if s2opc is compiled with S2OPC_EVENT_MANAGEMENT=1)

See implementation examples toolkit_demo_server.c (XML configuration only), Command-Line interactive embedded demo (Server +PubSub) (static embedded configuration only), toolkit_test_server_local_service.c (local services), toolkit_test_server.c (both XML and non-XML configuration) or toolkit_test_server_client.c (both client and server).

See XML configuration schemas and examples:

Server endpoints and security XSD schema and XML example
Address space XSD schema and XML example
Users XSD schema and XML example

Also see the demonstration wiki section for explanation on how to run the server and configure it.

High-Level Client API

The high-level client API provides functions for configuration (endpoints and security, user type) and functions to manage client execution (start/stop, service execution, etc.).

The main configuration functions are defined by libs2opc_client_config.h:

SOPC_ClientConfigHelper_Initialize shall be called before any other function of the client wrapper module (and after SOPC_CommonHelper_Initialize).
SOPC_ClientConfigHelper_Clear shall be called when client wrapper module is not used anymore.
SOPC_ClientConfigHelper_ConfigureFromXML loads configuration from XML configuration files (client connection endpoint and security, user type) and returns the array of configured connections. See XML file examples.
SOPC_ClientConfigHelper_SetServiceAsyncResponse sets a callback to use services in an asynchronous way (see SOPC_ClientHelper_ServiceAsync).
SOPC_ClientConfigHelper_SetClientKeyPasswordCallback sets a callback to provide the password to decrypt the private key of the client (if encrypted).
SOPC_ClientConfigHelper_SetUserNamePasswordCallback sets a callback to retrieve user/password for connection using UserName type for session activation.
SOPC_ClientConfigHelper_SetUserKeyPasswordCallback sets a callback to retrieve user private key decryption password for connection using X509 user type (if encrypted).
SOPC_ClientConfigHelper_GetConfigFromId returns the configuration of a connection from the string id defined in XML configuration.

In case the dedicated XML configuration files are not used to configure client, use the additional configuration functions located in libs2opc_client_config_custom.h.

The main functions for client execution are defined by libs2opc_client.h:

SOPC_ClientHelper_DiscoveryServiceAsync: executes a discovery service asynchronously for a connection configuration.
SOPC_ClientHelper_DiscoveryServiceSync: executes a discovery service synchronously for a connection configuration.
SOPC_ClientHelper_Connect: establishes a connection and returns the connection instance.
SOPC_ClientHelper_Disconnect: disconnects a connection instance.
SOPC_ClientHelper_ServiceAsync: executes a service asynchronously on a connection instance.
SOPC_ClientHelper_ServiceSync: executes a service synchronously on a connection instance.

Additional functions are provided and dedicated to subscription related services, it provides management of 1 subscription per connection instance:

SOPC_ClientHelper_CreateSubscription: creates a subscription on a connection and returns the subscription instance.
SOPC_ClientHelper_DeleteSubscription: deletes a subscription instance.
SOPC_ClientHelper_Subscription_CreateMonitoredItems: creates monitored items on a subscription instance with associated context.
SOPC_ClientHelper_Subscription_DeleteMonitoredItems: deletes monitored items on a subscription instance.
SOPC_ClientHelper_Subscription_AsyncService: executes other subscription related services asynchronously on a subscription instance.
SOPC_ClientHelper_Subscription_SyncService: executes other subscription related services synchronously on a subscription instance.

See implementation examples <service>.c or Command Line Interface client, and toolkit_test_client.c.

See XML configuration schemas and examples: client connections endpoint and security XSD schema and XML example

Low-level client API (usage not recommended and API subject to changes)

Main configuration functions and types for client are provided by sopc_toolkit_config.h and sopc_user_app_itf.h. The functions with SOPC_ToolkitServer_ prefix shall be ignored.

(Optional) log configuration with SOPC_Common_Initialize
SOPC_Toolkit_Initialize initializes the toolkit and configures the SOPC_ComEvent_Fct application callback to manage received events from toolkit.
SOPC_ToolkitClient_AddSecureChannelConfig adds a new secure channel configuration (SOPC_SecureChannel_Config). In case security is used, the default PKI provider might be used (sopc_pki_stack.h) and certficates shall be loaded (sopc_key_manager.h).
SOPC_Toolkit_Clear shall be called when toolkit is not used anymore.

Once toolkit is intitialized and a secure channel configuration is added, the client is able to establish connection:

SOPC_ToolkitClient_AsyncActivateSession to establish a secure channel and activate a session with given user token.
SOPC_ToolkitClient_AsyncActivateSession_Anonymous simplified version of SOPC_ToolkitClient_AsyncActivateSession for anonymous user.
SOPC_ToolkitClient_AsyncActivateSession_UsernamePassword simplified version of SOPC_ToolkitClient_AsyncActivateSession for using UserName.

Session activation result is provided by event SE_ACTIVATED_SESSION through the configured SOPC_ComEvent_Fct callback, resulting session identifier is necessary to send requests through a session.

It is also possible to send discovery services requests to through a configured connection without session using:

SOPC_ToolkitClient_AsyncSendDiscoveryRequest establishes a secure channel without session and send the given request. Response received with event SE_RCV_DISCOVERY_RESPONSE through SOPC_ComEvent_Fct callback.

Once a session has been activated it will be possible to send all kind of requests using the session identifier to call:

SOPC_ToolkitClient_AsyncSendRequestOnSession. Response are received with event SE_RCV_SESSION_RESPONSE through SOPC_ComEvent_Fct callback.

Note: The client API provides raw OPC UA responses to the OPC UA requests sent. Only the secure channel and session services are automatically managed by toolkit. See High-Level Client API for automated subscription service support.

See implementation examples Command line tools s2opc_<service>.c for dedicated services (read, write, etc.).

Low-level server API (usage not recommended and API subject to changes)

Main configuration function and types for server are provided by sopc_toolkit_config.h and sopc_user_app_itf.h. The functions with SOPC_ToolkitClient_ prefix shall be ignored.

Some are shared with Low-level client API (usage not recommended and API subject to changes) configuration:

(Optional) log configuration with SOPC_Common_Initialize
SOPC_Toolkit_Initialize initializes the toolkit and configure the SOPC_ComEvent_Fct application callback to manage received events from toolkit.
SOPC_ToolkitServer_Configured shall be called once all the configuration steps are terminated.
SOPC_Toolkit_Clear shall be called when toolkit is not used anymore.

For main server configuration there are 2 possible options. The first is to use the XML configuration parser:

Configure with XML file (XSD schema, XML example) using SOPC_Config_Parse, it produces a pre-filled SOPC_S2OPC_Config.
In case security is used, the default PKI provider might be used (sopc_pki_stack.h) and certificates shall be loaded (sopc_key_manager.h) into SOPC_S2OPC_Config (SOPC_Server_Config::pki, SOPC_Server_Config::serverCertificate, SOPC_Server_Config::serverKey) using certificates paths from SOPC_Server_Config.

The second is to allocate a SOPC_S2OPC_Config structure and to initialize it using SOPC_S2OPC_Config_Initialize function, then initialize all SOPC_Server_Config fields manually.

In both cases the User authentication and user authorization managers shall be configured for each SOPC_Endpoint_Config in SOPC_Server_Config::endpoints and the Method call manager configuration shall be configured if CallMethod service shall be supported.

Finally for each endpoint of the server (SOPC_Server_Config::endpoints), SOPC_ToolkitServer_AddEndpointConfig shall be called to configure it in the server.

Configure initial address space

Address space configuration shall be done to define the initial data present in the address space. This configuration shall be defined using OPC UA standard schema. An example is provided for a nano server and a nano extended server.

All the reciprocal references between nodes shall be present in it. The script gen-reciprocal-refs-address-space.xslt might be used to generate reciprocal references missing (XSLT 2.0 processor required).

Once the XML address space is defined, the C structure to be used for toolkit configuration shall be generated. It could be done using the Python C code generator prior to compilation or using the dynamic XML loader.

Use the XML dynamic loader SOPC_UANodeSet_Parse to convert at runtime a UANodeSet XML file to expected C structure to be configured with SOPC_ToolkitServer_SetAddressSpaceConfig.
Or use the Python script generate-s2opc-address-space.py to convert a UANodeSet XML file into a C file that can be compiled in the binary, and retrieved with the embedded address space loader SOPC_Embedded_AddressSpace_Load.

Finally call SOPC_ToolkitServer_SetAddressSpaceConfig with the address space structure to configure the server address space content and set the client write notification callback with SOPC_ToolkitServer_SetAddressSpaceNotifCb to receive notification on client write operation.

Configure address space update

Once the initial address space is configured, you might want to configure behavior on address space update from client or to configure how to update address space locally.

The server application will be notified of address space changes, it only needs to configure the associated callback using SOPC_ToolkitServer_SetAddressSpaceNotifCb with the SOPC_AddressSpaceNotif_Fct application callback to manage received AS_WRITE_EVENT events from toolkit.

The server application is able to modify the address space on runtime using OPC UA services locally. It is allowed to treat OPC UA service requests (OpcUa_ReadRequest, OpcUa_WriteRequest, OpcUa_BrowseRequest and discovery service requests) using SOPC_ToolkitServer_AsyncLocalServiceRequest. Once the function is called, an asynchronous SE_LOCAL_SERVICE_RESPONSE event will be received by the SOPC_ComEvent_Fct application callback containing the response message (OpcUa_ReadResponse, etc.).

User authentication and user authorization managers

User authentication and user authorization managers shall be implemented for each endpoint (SOPC_Endpoint_Config::authenticationManager and SOPC_Endpoint_Config::authorizationManager).

Default implementations accepting any user for authentication (SOPC_UserAuthentication_CreateManager_AllowAll) and authorization (SOPC_UserAuthorization_CreateManager_AllowAll) are provided for development use. Otherwise either application implements its own functions (SOPC_UserAuthentication_ValidateUserIdentity_Func and SOPC_UserAuthorization_AuthorizeOperation_Func) depending on its needs (LDAP, etc.) or a simple implementation based on XML user management configuration file loading is provided.

In the latter case use the parser for XML user management configuration file (XSD schema, XML example) SOPC_UsersConfig_Parse and set result in SOPC_Endpoint_Config.

Note: The toolkit does not provide default implementation to encrypt/decrypt the user credentials which means a Secure Channel with SignAndEncrypt security mode and None user security policy shall be used.

Method call manager configuration

If the MethodCall service shall be supported, it is necessary to define a method call manager SOPC_MethodCallManager. A basic implementation is provided by SOPC_MethodCallManager_Create, this manager provides the function SOPC_MethodCallManager_AddMethod to define method implementation through SOPC_MethodCallFunc_Ptr callback.

PubSub API

Examples of Pub or Sub test applications can be found here publisher and subscriber, and a PubSub-Server sample is implemented here.

Moreover, the cli_pubsub_server sample provides an example of implementation with a static configuration for embedded targets.

Main interface is defined by sopc_pub_scheduler.h and sopc_sub_scheduler.h.

Common API (PubSub and Client/Server)

The common API shall be used to initialize (or clear) the S2OPC toolkit prior to use (or after using) the client/server API or pubsub API. For the client/server the initialization and clear functions are automatically called by low-level API functions or by high-level API functions. Those functions are shared between all API when including the S2OPC Common library:

SOPC_Common_Initialize shall be called before any other high-level API function to initialize S2OPC toolkit (constants and platfrom specific checks, logger initalization).
SOPC_Common_Clear shall be called after any other high-level API function to clear S2OPC toolkits.
SOPC_Common_GetDefaultLogConfiguration retrieve default log configuration.

Configuration API

The PubSub configuration API is provided through sopc_pubsub_conf.h and uses the concepts of OPC UA PubSub specification Common Configuration Model (see §9.1 in OPC UA part 14 v1.04) to define the following elements configuration: PubSubConnection, ReaderGroup, DataSetReader, SecurityMode, SecurityKeyServices, FieldTarget, FieldMetaData, PublishedDataSet, WriterGroup, WriterDataSet, PublishedDataSet, PublishedDataSetSource, PublishedVariable.

The protocol to use is automatically deduced from the PubSubConnection address prefix (only UDP, Ethernet and MQTT supported for now). The configuration might be generated by parsing an XML configuration file, with XSD schema format, using the function SOPC_PubSubConfig_ParseXML to dynamically parse XML file. Or statically using generate-s2opc_pubsub-static-config.py script which generate a C file. SOPC_PubSubConfig_GetStatic function is generated and return SOPC_PubSubConfiguration pointer. See Command-Line interactive embedded demo (Server +PubSub) for a static embedded configuration example.

Configure data source/target handlers

For a Publisher application, a data source handler shall be defined to retrieve the data from configured information in the PublishedDataSet. The handler shall be built using SOPC_PubSourceVariableConfig_Create, by providing a function with the signature SOPC_GetSourceVariables_Func, and shall then be provided on Publisher start.

For a Subscriber application, a data target handler shall be defined to set the data from configured information in the DataSetReader. The handler shall be built using SOPC_SubTargetVariableConfig_Create by providing a function with the signature SOPC_SetTargetVariables_Func, and shall then be provided on Subscriber start.

Configure SKS

For Publisher and Subscriber applications a Security Keys manager shall be defined using SOPC_PubSubSKS_SetSkManager to permit encrypted/signed communication.

Publisher and Subscriber schedulers will retrieve the keys directly from the Security Keys manager which is in charge of locally storing the keys. But in order to implement a complete SKS mechanism on Pub/Sub side, the following elements should also be configured to update the keys in the manager:

Security Keys Manager (see sopc_sk_manager.h): manages local storage of the keys retrieved from the Security Keys Provider, it should be created using SOPC_SKManager_Create.
Security Keys Provider (see sopc_sk_provider.h): source providing the Security Keys using Security Keys Services, it should implement a client connection calling the GetSecurityKeys method of the SKS server(s). Several providers might be defined using SOPC_SKProvider_TryList_Create to have alternative SKS sources.
Security Keys Builder (see sopc_sk_builder.h): provides update function to retrieve keys from the Security Keys Provider and fills the Security Keys Manager. SOPC_SKBuilder_Setter_Create should be used to create a builder replacing all keys on update.
Security Keys Scheduler (see sopc_sk_scheduler.h): schedules the periodic update of keys retrieved using the builder. SOPC_SKscheduler_Create should be used to create the scheduler, then SOPC_SKscheduler_AddTask should be called to configure the task with defined Security Keys Builder, Provider and Manager. And finally SOPC_SKscheduler_Start should be called to start the scheduler task updating the keys.

Note: Security Keys manager might be configured to stub connection to a real SKS server by using local keys files or data updated externally.

The samples/PubSub_ClientServer/pubsub_server/pubsub.c provides an example of implementation using Security Key Service with the described elements.

PubSub lifecycle

The Publisher lifecycle is managed through the functions SOPC_PubScheduler_Start and SOPC_PubScheduler_Stop. And the Subscriber lifecycle is managed through the functions SOPC_SubScheduler_Start and SOPC_SubScheduler_Stop. The Subscriber state changes might be received by providing a handler with the signature SOPC_SubscriberStateChanged_Func.

Note: The PubSub library part is only supported for POSIX platform for the moment.

OPC UA stack behavior configuration constants

Two sets of constants are defined to configure the OPC UA stack behavior. One of them is designed for the OPC UA common encoding layer (message size, string max length, etc.) and another for the OPC UA Client/Server services layer (maximum number of operatoins per call, etc.). Those variables might be changed for specific needs at library compile time and are defined in respectively in sopc_common_constants.h and sopc_toolkit_config_constants.h.