bfitDesigoExt

Overview

The BuildingFit Desigo Connector is designed to connect to the Siemens Desigo API to abstract and simplify the data gathering processing in SkySpark.

This connector implements only the read-only functionality of the Desigo WSI. This includes: Learn, SyncHis, SyncCur. It does not include or implement API endpoints that write data back to the Desigo WSI server.

The following limits apply when using the Web Service Interface:

• Number of concurrent sessions: 100
• Delay for notifications: <1 second
• 250,000 value updates / day
• 10,000 value subscriptions
• 50,000 event notifications / day
• 50,000 event-counter notifications / day
• 1,000,000 trends / min

Definitions

Desigo CC - The Desigo control center software. This software supports the Desigo Web Client/Remote Client as well as the Desigo Web Services Interface.

Desigo Web Client/Remote Client - This section of the Desigo CC software allows for visual interaction with the Desigo CC. It is often used for Controls management. The Desigo Connector cannot interface with the web client/remote client.

Desigo Web Services Interface (WSI) - This section of the Desigo CC software exposes the API (Application Programming Interface). It responds to programmatic requests through the Windows IIS Server. It is the critical portion of the Desigo CC which must be enabled and set up in order for the Desigo Connector to function.

Desigo Connector - The interface designed by BuildingFit to allow automatic interaction between the Desigo WSI and SkySpark.

Considerations for the Desigo WSI Server deployment

The connector can be severely limited by the Windows installation of the Desigo WSI server. In the worst case, this can limit the number of connections to 3. It is strongly recommended that the Desigo WSI be run from a Windows Server Edition installation.

The Siemens Desigo Web Services Interface listens for and responds to requests through the Windows IIS (Internet Information Services) Server. The Windows IIS Server is supplied as part of all Windows installations. However, the servers are feature-limited to the Windows version. For example, a Windows Home Edition installation will not respond to more than 10 requests at a time. While we have taken steps to provide quick performance using various approaches that limit the number of requests and optimize web packet response time, certain functionality can be severely hampered by this limitation. Standard learn functionality is one example, since the system must wait for the current node to be completely explored before exploring future nodes it it is not possible to package large volumes of data into a single connection. This can lead to slow discovery in the export process.

Deployment

What you will need to connect:

• The Web Services URI
• A sufficiently permissive login username and password. For example, write capabilities require an account with write permissions.

Setting up the connector is simple:

• Create a new connector in the Connectors app where the desigo URI terminates at the Web Services address. The address MUST end with a trailing /. For example: https://www.foo.net/WebServices/.
• Add username and password to the appropriate fields of the connector record. This can be done during the above step or after creation by using the edit function of the Connectors app.
• Points can be discovered and added using the Connectors aspect of the Builders app.

• If the connector returns an SSL error after creation it may be necessary to add the WSI URI to the trusted URIs list.
• Navigate to the desired SkySpark site -> Host app -> Crypto tab.
• Click the "Trust Uri" button.
• The URI field should be the Web Services URI as it was set up for the connector. The alias is any human readable name to describe the trusted uri record.

Login Limitations

The Desigo API operates on credentials that can be shared between the API and the Swagger Web Client. While a user can log in using the same credentials from both places there are some hitching points which should be noted.

• A user logged into Swagger will monopolize the login access until 30 minutes after their last input was detected in the system. No other access using the same credentials will be possible during this time.
• API access is controlled using tokens. If multiple applications using the same credentials attempt to access the API, the latest token requested is the only one that remains active. Since there is no way to detect that this has occurred, invalidated tokens will need to wait for their timeout period before they can request a new token. By default, this is a 10 minute lockout but it may be modified on your system.

Differences from common connectors

SyncCur - In an effort to work around the server limitations, the Desigo connector will attempt to group requests into a single connection. While most connectors will update points as responses are returned and partial sync updates can be seen, the batched Desigo requests will all return at the same time. As a result, it may appear that no work is being done for 10 to 30 seconds. In general, polled points in the same polling bucket will batch together. This can be strategically exploited to minimize server load by assigning polling tuning to points at staggered intervals.

Learn - The Desigo WSI only returns limited information on points with the initial query, therefore, it is necessary to perform additional requests to discover the most critical information. For example, the Kind of the point. However, useful but non-critical information such as the unit type of the point was not gathered as the number of additional requests would significantly slow the process and place additional load on the IIS server. This information can be exposed later with custom programming.

Points vs. Point Attributes - The common paradigm for exposed points functions where each point describes a single kind of data and the default attribute is simply the data value. For example, a VAV would have a zone air temperature point exposed that only returns temperature data. While the Desigo WSI supports this type of infrastructure and it is the format that we generally suggest, it also supports multiple attributes on a single point. In our experience, this is most common with VAVs where a single point is exposed and then all data is trended as unique attributes under this point. These attributes will not be discovered by the learn function as they are not nodes in the site structure and will require custom programming to expose the attributes as points in a manner that functions well with SkySpark.

Mapping histories

Unlike SkySpark, Desigo does not differentiate between trendlog points and history points. The information can still be merged with the live points record by calling the bfitDesigoTrendseriesInfo function and operating on the results. The following is an example axon function that might accomplish this:

() => do 
  points: readAll(point and bfitDesigoConnRef)
  trendlogs: read(bfitDesigoConn).bfitDesigoTrendseriesInfo(0)

  trendlogs.each(trendlog => do
    point: points.find(p => p["bfitDesigoCur"] == trendlog["objectId"])
    if (point != null) try point.diff({"bfitDesigoHis": trendlog["trendseriesId"]}).commit catch null
  end)
end

Known Issues

• Gathering histories and gathering current values require different permissions within the Desigo system. Certain functions required for mapping histories will not function properly without the correct permissions. For example, calling read(bfitDesigoConn).bfitDesigoTrendseriesInfo(0) will return Error 403 Forbidden when not sufficiently privileged even when it is possible to map to live points and pull their current values.