SORIS
SORIS (Southbound Open RESTful Integration Service) represents an architecture style for designing networked applications. It relies on a stateless, client-server, cacheable communications protocol—in this case, HTTP(S). The SORIS architecture provides interoperability between computer systems on the internet, while the SORIS adapter allows vendors to integrate their proprietary subsystems with Desigo CC.
For procedures or workflows, see the step-by-step section. For adapter deployment or configuration, see the SORIS Adapter SDK Developer API Document, available when you installed your SDK.
The following graphic shows the five-step workflow required for integrating a SORIS adapter with Desigo CC. The dashed-line box represents Desigo CC, and all the components inside are provided by the SORISDriver extension module. The SORIS adapter represents the framework where you build your adapter. You will also need to develop the logical adapter, the object model, and the communications driver for the subsystem or device you are integrating. The descriptions that follow provide a more detailed explanation of the process.
- An Object Model in Desigo CC is basically a named object with a list of properties. For example, a Light Object might have properties like color, power, brightness, and name. You create one or more Object Models in Desigo CC that correspond to the data structures of the subsystem objects you want to integrate. There might even be some domain libraries—for example, Fire or Security—that already contain Object Models matching the objects you are integrating, and you can re-use those.
- An extraction tool exports the Object Models into several output types. You can select the properties from each Object Model you want to export. The tool exports information as RDF classes. Additionally, it exports specific programming language abstract types (C# and Java) corresponding to the Object Model. To enable frameworks that can generate RESTful services, the extraction tool also produces a Swagger document. This document describes the Object Model as data-definition aspects, along with endpoints representing the property (read and update).
- The generated object-oriented classes from step 2 are ready to use in programming the adapter. In this step, you create your logical adapter using the SDK for either C# or Java. Your logical adapter needs to implement 3 methods in the framework. The first one is Initialize(), and this is where you enumerate all the objects in your subsystem and add them to a container. The next two methods are Read() and Write(). This is where you provide the code to read and write each property, possibly doing some data type conversions in the process. You will also provide a communication driver to the system you are integrating. That system needs to be able to provide a list of all the instances, and it needs the ability to read and write properties.
- The HTTP(S) endpoint of the SORIS adapter provides the description of the instances (Things) hosted in the adapter. These Thing Descriptions are RDF documents serialized in JSON.
- The SORIS adapter contains the Thing Descriptions, which contain the Object Models. The SORIS driver communicates with the SORIS adapter to get the Thing Descriptions, and then an auto-discovery component in Desigo CC makes the instances of the Object Model(s) and addresses the properties with resource URLs. Then, the SORIS driver starts to read and update the resources.
The following properties and commands display in the Extended Operation tab.
Property | Description | Commands |
AggregatedSummaryStatus | Highest priority status that is currently active for an object. | — |
Alarm Suppression | When this feature is enabled for specific system objects, any alarms coming from those objects are suppressed in the management platform. You can enable suppression for one alarm class or all alarm classes. |
|
Online | Possible values:
| — |
Subsystem Status | Shows default values that can be changed by the adapter developer:
| — |
URL | Adapter address and port number. If the auto discover feature has not been programmed into the adapter, the Discover command can be used to manually add one or more thingAdapter objects to the adapter. |
|
Auto Discover | Possible values:
| — |
Discovery Status | Current status of discovery. Normally, the status displays | — |
Consistency | Possible values:
| — |
Database Revision | Revision number corresponding to a change in the adapter such as adding or removing a thingAdapter object, changing a date, and so on. | — |
Last Discovery Revision | Revision for the last manual discovery. | — |
Adapter Revision | Current revision number for the selected adapter. | — |
Has Web Configuration | Possible values:
| — |
With WSI authentication configured in the adapter, you can automatically access an adapter web interface, which allows you to view adapter status and modify basic settings. You can also modify settings for the adapter network.
If WSI authentication is not configured, you can still access the page by entering a password and logging in. The feature is available by clicking the Adapter Configuration tab that displays once a SORIS adapter is selected.
Alarms are a type of WOT (Web of Things) event that are sent through the SORIS adapter WebSocket connection to all registered clients. The adapter provides an alarm library and APIs to help generate, remove, send, and backup alarms. The alarm library also allows automatic and custom handling of alarm actions, such as Acknowledging an alarm.
SORIS supports alarming through the use of categories, which are handled in the management station alarm table or in the adapter. There are two types of alarming—workstation-based, and driver-based. Workstation-based alarming is defined in the management station, while driver-based alarming is defined in the adapter.
The SORIS alarm table is created when the SORISDriver feature is installed. If you create a new adapter and object model for third-party IoT devices, you must use the alarm table format that follows (same column names, same number of columns):
SORIS supports subscribing to and unsubscribing from COVs and alarms.
A COV (Change of Value) is a type of WOT communication object that is used to notify all connected clients that the value of a specific property has changed. This method helps reduce web traffic by eliminating the need for clients to periodically send pull requests to obtain property values. When a COV is send to the SORIS Adapter, the adapter handles sending it out through a WebSocket connection only to the clients that are registered to receive COVs for the given property. The adapter provides a COV library and APIs to help create and send COVs.
Subscriptions allow clients to register for specific data over the WebSocket connection. Each client can create, update, and delete subscriptions by sending HTTP(S) requests. Subscriptions currently handle subscribing to alarms and COVs only. When setting up a subscription for alarms, the registered clients will either receive all alarms or no alarms. When setting up a subscription for COVs, the client will send a list of Things to subscribe to. The management station configures the subscription details required for communication through the WebSocket.
A hierarchy uses views and nodes to arrange Smart Devices into logical groups. For example, smart light bulbs may be grouped by the floor and room where they are located. SORIS supports the creation of hierarchies, with two conditions. If you want to create a logical view, you must map it to Discovery. Additionally, some user-defined views may require mapping to Discovery. In that case, check with the adapter developer for instructions.
The driver and adapter are multi-threaded and can handle a large volume of polling. The driver will have no trouble processing 100,000 polls per minute. The maximum amount of traffic the driver can process depends on 4 things:
- The number of threads in the driver. The default is 75, but you can increase the number if needed. These are concurrent HTTP(S) requests into the adapter.
- The latency in communication with your devices. The longer it takes to read or write a property on your end device, the fewer requests per minute per thread you can have.
- The CPU—the raw power of your hardware for Desigo CC and the adapter. With a high-end, quad-core i7 machine and very low latency (2 ms), the driver can process 500,000 polls a minute.
- The latency between the driver and adapter. If they are on the same computer, this is the best-case scenario. If the adapter is running on an embedded Linux computer somewhere else on the network, then each request takes longer to service.
You can program the SORIS Adapter to enable automatic discovery of thingAdapter objects. If you enable automatic discovery and then add an object to the adapter, Desigo CC recognizes the object and automatically displays it in System Browser.
If you do not program automatic discovery into the adapter and then add a thingAdapter object to it, the system detects an inconsistency between the objects in the adapter and Desigo CC. The management station then generates an alarm.
At this point, you need to rediscover the object to re-synchronize the adapter and the management station. Once the thingAdapter object is discovered, the Consistency property in Extended Operations reads Up to date, the system removes the alarm from the Event List, and the Activity Log records the transaction.
When deciding how to deploy the adapter you develop, you need to consider the security and privacy needs for the data you are exchanging between the adapter and the Desigo CC driver. Since the adapter acts as a web server, any client can connect to it and access its data. For example, from anywhere on the intranet, you can point a browser or Postman at your adapter URL and use those tools to read and write the data you expose. This may not be desirable or acceptable on a customer site. You have two deployment options for addressing these security concerns.
Recommended Option
The recommended deployment option is to allow the adapter to be accessed only by the local computer it is running on. In this scenario, you deploy the adapter on the same computer as Desigo CC.
VPN Option
The other option is to use a VPN between Desigo CC and the computer you deploy the adapter on. This will also secure the data from the intranet and only allow access to computers on the VPN. This method may require IT support and is more costly than using the recommended option. However, this option may be required when you must deploy on a separate computer or on an embedded device.
HTTP vs HTTPS
The following information also applies to WS and WSS for WebSockets.
The SORIS driver and the adapters support both HTTP and HTTPS. HTTPS adds encryption for more secure communication, but this marginally decreases performance. It also requires some extra configuration and management of certificates. Here are some additional guidelines:
- If you are running the adapter on the same machine as the driver, you only need to use HTTP.
- If the adapter and the driver are on the same intranet, and security is not a major concern for the type of data being exchanged, you can still use HTTP.
- If communication occurs on the internet or less secure intranets, you should use HTTPS.
- The decrease in performance for HTTPS can be significant if you are using an inexpensive embedded device for the adapter.
Certificates
You may want to create optional, self-signed certificates for both C# and Java adapters, or you might want to configure a C# Adapter to accept client certificates if the adapter is running on a remote client. If the adapter is not deployed in a secure environment (intranet), you must configure authentication for it.
For step-by-step instructions on these scenarios, see the following topics:
Configure a C# Adapter with HTTPS and WSS
Configure a Java Adapter with HTTPS and WSS
Configure a C# Adapter to Accept Client Certificates
The SORIS adapter has several command line parameters that you can use to change the settings and behavior of the adapter. Run the adapter with the following help flag to display the list: <SORISAdapter>.exe -?
Description | |
The adapter is a program that allows communication between Desigo CC and a Smart Device service. The adapter can run as either a command line program or as a service when installed. | |
Usage | |
NOTE: All commands and options must begin with a hyphen—for example, | |
Commands | |
| Installs and starts adapter as a service. If the adapter is already installed as a service, this command updates the service command line arguments. |
| Stops and uninstalls the service. |
| Opens the TCP connection with HTTPS security. |
| Allows connections from remote clients. For security reasons, the adapter allows only local HTTP client connections by default. |
| Registers the adapter with mDNS. This option is required if the adapter needs to be discovered through a gateway. |
| Turns on client certificate authentication. Only clients with accepted client certificates can connect with the adapter. |
Options | |
| Manually sets the IP address or Computer Name to be used for communication with the adapter. The primary, active IP address is used by default. |
| Manually sets the port number used for communication with the adapter. If multiple adapters are running on the same computer, each adapter needs a different port number. The default port is 8080. |
| Manually sets the Port number used for WebSocket communication with the adapter. If multiple adapters are running on the same computer, each adapter needs a different port number. The default port is 8005. |
| Defines an authorization method to enable the Graphical Web Interface. authTypes Options: |
| Sets the URL path to the WSI web application. |
| Manually changes the directory path used to discover the RDF (OWL) files. |
| Manually sets the Name of the service. The default name is the adapter executable name. |
| Turns on the option to log all adapter output to file. FileSize is an Optional parameter used to define the maximum file size of the log file in MegaBytes. |
| The Adapter endpoint is a unique string used to differentiate between multiple instances of the same adapter. The endpoint can be set either through command line arg or in the code. |
Example | |
This example installs the adapter as a service with the entered IP and port as command line arguments. | |
- SORIS Drivers: maximum of 10 per Desigo CC server; maximum of 10 per Desigo CC FEP
- SORIS Networks: no limit
- SORIS Adapters: no limit
- Objects: 25,000 per adapter
