This document describes the usage of RP Controller (RP-C) Web Service API. It is a general tutorial for users who want to consume it and obtain BACnet objects and properties.

Using the Web Service API, a Schneider Electric partner can remotely access BACnet objects and properties on the RP-C, which will return a list of object ids available and a list of property ids for a specific object.

• 3rd party client application can access BACnet objects and properties if the user credential is valid. The user will be authenticated based on User DB in RP-C.

• EcoStruxure System with multiple RP-Cs, users can be authenticated based on centralized User DB on the RP-C, AS-P or Enterprise Server by configuring Web Service Settings.

1. Update the RP-C with firmware which supports Web Service feature.

2. Configure Web Service Settings.

   • In WorkStation, in the System Tree pane, expand the RP-C.

   • Click and expand the System folder.

   • In the Web Service box, enter the address of the SpaceLogic Certificate configuration tool and enable the Web Service.

     • Ensure that the SpaceLogic Certificate Configuration Tool with configuration of the RP-C is running prior to enabling Web Service. This is required for the first setup only.

     • Run Restore optional properties. (Device -> Advanced -> Restore optional properties), if you don't see the Web Service box.

   • The Web Service State will be Running if Web Service starts successfully.

3. Update admin user name and password as soon as the Web Service is enabled for security.

4. Generate the mandatory Service certificate and key for each RP-C. You can deploy the Service Certificate and the key can be deployed using the SpaceLogic Certificate Configuration Tool (First time only) or APIs in web server settings.

• The number of calls to the API in the Sandbox is limited.

• The Sandbox application for this API document will return BACnet object data based on RP-33 FCU.A01.194_2c BMS application.

• Because there is a single instance of a database in the Sandbox application, you may get values updated by other users. The single instance of a database will be reset after a timeout without any incoming requests.

• To fully experience and extend the thresholds, enable the Web Service on the RP-C and use the environment.

There are two layers of authentication when creating secure connection between the server and a client. The first one is based on a Digital Certificate, and the other is based on a user database (Local or Central).

• Server Certificate Validation and Client Certificate Authentication

  • Server Certificate Validation

    To protect a HTTPS client, a server need to return the certificate to the client. The client should be able to validate identity and ownership of the certificate from the server using the CA Certificate.

    You can create self-signed certificates to set this up.

    First of all, generate root key. To protect your key, please set up a passphrase.

    openssl genrsa -des3 -out rootCA.key 2048

    Then, generate a root certificate. You need to enter a list of information.

    openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1825 -out rootCA.pem

    Now, you need to create the server key and certificate using this root certificate.

    Generate server key.

    openssl genrsa -out server.key 2048

    Or, generate ECC Server Key. (Available from the RP application software v5.0.x)

    openssl ecparam -genkey -name prime256v1 -out server.key

    Generate a CSR (Certificate Signing Request). You need to enter a list of information.

    openssl req -new -key server.key -out server.csr

    Generate a configuration file (server.ext). If you have a domain name server, you can add the address of your RP-C. Otherwise, you can add the IP address of your RP-C.

    authorityKeyIdentifier=keyid,issuer
    
    keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
    
    basicConstraints=CA:FALSE
    
    subjectAltName = @alt_names
    
    [alt_names]
    
    IP.1 = 192.168.0.100
    
    or
    
    DNS.1 = www.your-domain.com
    
    

    Generate a server Certificate.

    openssl x509 -req -in ./server.csr -CA ./rootCA.pem -CAkey ./rootCA.key -CAcreateserial -out ./server.crt -days 825 -sha256 -extfile ./server.ext

    Convert the server key and certificate to DER format to import to RP-C via web server settings API.

    openssl rsa -inform PEM -outform DER -in ./server.key -out ./server.key.der
    openssl x509 -inform PEM -outform DER -in ./server.crt -out ./server.crt.der

    In case of ECC Server Key,

    openssl ec -inform PEM -outform DER -in ./server.key -out ./server.key.der

    Convert the server key and certificate to .pfx format in order to import them to the RP-C via the SpaceLogic Certificate Configuration Tool. For more information about installing and using the tool, see the EcoStruxure Building Operation Technical Reference Guide.

    openssl pkcs12 -export -out ./server.pfx -inkey server.key -in server.crt

  • Client Authentication Certificate (Optional)

    The server can authenticate a client using the certificate. You can also create self-signed certificates to configure this.

    First of all, generate a root key. To protect your key, set up a passphrase.

    openssl genrsa -des3 -out rootCA.key 2048

    Then, generate a root certificate. You need to enter a list of information.

    openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1825 -out rootCA.pem

    Now, create a client key and a certificate using this root certificate.

    Generate a client key.

    openssl genrsa -out client.key 2048

    Generate a CSR (Certificate Signing Request). You need to enter a list of information.

    openssl req -new -key client.key -out client.csr

    Generate a configuration file (client.ext).

    authorityKeyIdentifier = keyid,issuer
    
    keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
    
    basicConstraints = CA:FALSE
    
    nsCertType = client, email
    
    nsComment = "Client Certificate"
    
    subjectKeyIdentifier = hash
    
    extendedKeyUsage = clientAuth, emailProtection
    
    

    Generate a client certificate.

    openssl x509 -req -in ./client.csr -CA ./rootCA.pem -CAkey ./rootCA.key -CAcreateserial -out ./client.crt -days 365 -sha256 -extfile ./client.ext

    Convert the root CA certificate to DER format in order to import to RP-C.

    openssl x509 -inform PEM -in rootCA.pem -outform DER -out rootCA.der

    If you are using SOAP UI for development, you need to merge the client key and certificate to pfx format.

    openssl pkcs12 -export -out client.pfx -inkey client.key -in client.crt -certfile rootCA.pem

• Token-based user authentication (Local and Centralized)

  Token-based authentication is a process where the client application first send a request to a server with a valid credencials. The server sends an access token back to the client as response. The client application then uses the token to acess the restricted resources in the next request until the token is valid.

  The RP-C returns an access token which contains enough data to identity a particular user. The token has an expiry time and if the token expires, the client application can request a new access token.

  

• Centralized user authentication

  • If you are using the EcoStruxure BMS System and want user authentication, enable the EWS Server.

  • In WorkStation, in the System Tree pane, expand the System of a server (Enterprise Server or Automation Server).

  • In the List View, click EcoStruxure Web Services and EWS Server Configuration.

  • In the Configuration Information box, enable EWS Server.

  • Create an Authentication Point for the RP-C Web Service

    • Create a folder in the EcoStruxure BMS server (Enterprise Server or Automation Server).

    • Create a Digital Value object.

    • Eg. ewsResourceId is 01/Server 1/RPC_WebAPI/WebAPI_Authentication_Point.

      

  • Enable EWS authentication on the RP-C using the web server settings API. Ensure the following:

    • ewsUserAuthEnabled is true.

    • ewsIPAddress and ewsPortNumber are from the EcoStruxure BMS server (Enterprise Server or Automation Server).

    • ewsResourceId is from an authentication point.

Note:

• If client certificate authentication is enabled, a client needs to have a vaild client certificate for authentication.
• Local user authentication or EWS (Centralized) user authentication is required based on the Web Service Settting.
• Token-based user authentication is available to protect a user password. Basic authentication is required to get a access token.

In case of proprietary properties, please refer to RP-C PICS Protocol document

You can use Notification APIs to efficiently monitor object value changes. First, the Web Service client needs to create COV(Change Of Value) subscriptions for the monitored objects.

When the property value (present value: 85) of a subscribed object is changed, a notification message is queued. The Web Service client can call an API to get the queued message periodically to monitor the value.

The default size of the notification message queue is 20. You can change the size of queue from 20 to 999 via Web Server settings API.

For efficient communications, the Web Service client needs to provide a query parameter "lastNotificationId" which is the Id of last message from the previous API request. Then the Web Service will return queued messages after the last notification message. If there is no messages after the last notification message, it will return an empty message with "outOfSync" as false.

"outOfSync" is true when requested lastNotificationId notification message doesn't exist in the queue. This means that the Web Service client missed several notification messages which would be popped out from the queue already. If so, the monitoring(or cached) values on the Web Service client application may be out of sync with the RP-C values.

In this case, RP-C returns the last 20 queued messages to synchronize the lastNotificationId between RP and the client application. If the client application has monitoring(or cached) values, it should obtain property values once more to refresh them.

The RP Series controller Web API follows the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.

Contact the SE Exchange support team at exchange.support@se.com and include:

• Endpoint URL
• Request/Response
• Any additional information like Screenshots , Postman collections.