gRPC Interface

Starting in PLC Shift Version 2.0 (May 2025), the PLC Shift runtime implements a gRPC (Google Remote Procedure Call) interface. The gRPC interface allows users to read and write from the system in a secure way using a variety of clients, services or programs.

 

Specifically:

 

In short, the gRPC interface lets you extend the functionality of PLC Shift apps and the PLC Shift runtime itself. As apps execute, data can be collected, analyzed and sent back to the system in real time. Or, data can be collected as it is generated, analyzed offline, and set points can be sent back to the system when the analysis is complete.

 

Device level settings for the gRPC server are explained below. Note that the gRPC server is a licensed feature. Each app that you want to be able access via the gRPC interface must have the gRPC feature licensed.

 

 

Starting in version 2.06 (June 2025), configuration has been moved from parameters to a JSON blob. Moving to JSON allows for more flexibility and makes it easier to add features in the future.

 

Set this to 'true' to enable the gRPC server and to 'false' to disable the gRPC server. When the server is enabled it will attempt to start gRPC listeners on the configured ports. Both HTTP (unencrypted) and HTTPS (encrypted) listeners can be enabled at the same time.

 

 Sample configuration JSON is shown below. All fields must be included in the JSON, even if they are empty.

 

 

The configuration is split into two sections: Server Settings and Auth Settings.

 

Use the 'EnableHttp', 'HttpPort' and 'HttpLocalHostOnly' settings to configure the gRPC server when using unencrypted connections.

 

When 'HttpLocalHostOnly' is set to 'true', the gRPC server will only accept connections coming from the same computer. When this setting is false, the gRPC server will bind to all network adapters and accept connections from anywhere. When binding to all adapters, the firewall on the computer or container needs to be configured to allow inbound connections. Binding to all adapters with HTTP is insecure and is not recommended.

 

Certificate based client authentication is not possible when using unencrypted connections. Certificate based authentication occurs as a part of negotiating the TLS connection and this happens at a lower level than the gRPC service.

 

Use the 'EnableHttps', 'HttpsPort'  and 'HttpsLocalHostOnly' settings to configure the gRPC server when using encrypted (TLS) connections.

 

When 'HttpsLocalHostOnly' is set to 'true', the gRPC server will only accept connections coming from the same computer. When this setting is false, the gRPC server will bind to all network adapters and accept connections from anywhere. When binding to all adapters, the firewall on the computer or container needs to be configured to allow inbound connections.

 

Use the 'HttpsCert' and 'HttpsCertKey' settings to use PLC Shift Manager to supply a certificate to the gRPC server. Both the certificate and private key must be in PEM format and not contain any newline, carriage return, or other extraneous characters. The certificate can be self-signed or obtained from a third party certificate authority.

 

Installing a certificate using PLC Shift Manager is insecure. The certificate and private key will be stored in the local database in plain text. If an export is generated, the values will be included in the export file in plain text. To overcome this, the gRPC server will first try to read a certificate from the file system before using the values from in the device configuration. This is secure because the certificate can be installed on the computer or container completely outside of PLC Shift.

 

Copy the server certificate in PFX format directly to the '/var/plc-shift-app/cert-store' directory to bypass PLC Shift Manager. The certificate must be named 'grpc-server-cert.pfx'. A PFX file is a binary format that contains both the certificate and the private key in a single file. The private key must not be password protected.

 

See the Application Information section for instructions on how to generate and use a self-signed certificate.

 

Use the 'EnableRestApi', 'EnableRestApiHttp', 'RestApiHttpPort' and 'RestApiHttpLocalHostOnly' settings to configure the REST API.

 

Set 'EnableRestApi' to true to enable the REST API. If HTTPS is enabled for the gRPC interface, then the REST API will be served on same port at the HTTPS interface. However, it is not possible to serve both the gRPC interface and the REST interface on the same port when using HTTP. This is because gRPC uses HTTP/2 transport and REST uses HTTP/1.1 transport. When gRPC is enabled for HTTP, we force the configured port to use HTTP/2, which means that HTTP/1.1 requests will not be processed.

 

When only HTTP is enabled for the gRPC interface, then 'EnableRestApiHttp' must be set to true and the 'RestApiHttpPort' field must be populated. Use the 'RestApiHttpLocalHostOnly' setting to select whether to bind to localhost or all adapters. hen binding to all adapters, the firewall on the computer or container needs to be configured to allow inbound connections.

 

See the Application Information section for more information on how to use the REST API.

 

Use the 'RequireClientCert', 'ClientCertIsSelfSigned' and 'CaPublicKey' settings to implement authentication using client certificates. When this feature is enabled, during the TLS connection negotiation, the gRPC server verifies that the client certificate is valid and is signed by a trusted authority.

 

When validating the signature on the client certificate, the gRPC server will first look in to the trust store on the computer to see if it has the public key for the certificate authority (CA) that signed the client certificate. Generally speaking, this means that certificates that are signed by well known certificate authorities will just work. Examples of well known CAs include Verisgn, Digicert, Microsoft, Google, Apple and many others. These companies can issue certificates that are accepted by most computers and web browsers. When using a client certificate from a well known CA, the 'ClientCertIsSelfSigned' option should be set to 'false'.

 

When a certificate is self-signed, or issued from a CA that is not well-known, the 'ClientCertIsSelfSigned' option should be set to 'true'. The public key for the CA must be included in PEM format in the 'CaPublicKey' field. The value must not contain any newline, carriage return, or other extraneous characters. The public key will be sued to verify the signature on the certificate. The public key cannot be password protected.

 

In all cases the CN (Common Name) field of the client certificate should contain the user name of the client. The user name here will be shown in the app's configuration change log if configuration values are updated through the gRPC interface. 

 

See the Application Information section for instructions on how to generate and use a self-signed client certificate.

 

The system can be protected by unauthorized access by using an API key. To use an API key, set 'EnableApiKey' to true and enter a key in the 'ApiKey' field. To access the system, send the key 'x-api-key' in the request header with a value of the configured API key. The API key protects both the gRPC interface and the REST API.

 

Use settings in this group to configure single sign on using Microsft Azure Entra (formerly Azure Active Directory (AAD)). Using SSO requires configuration of settings in the cloud.

 

Please contact us at support@reverity.io if you want to use this feature.

 

At the application level, every parameter has a 'gRPC Read' and 'gRPC Write' option. Selecting the 'gRPC' read option makes the parameter available to read via the gRPC interface. Selecting the 'gRPC Write' option allows the parameter to be written via the gRPC interface. Selecting the 'gRPC Write' option requires the 'gRPC Read' option to be checked.

 

Writing a value through the gRPC interface is no different than writing it from the PLC or the Modbus Server. The value is still validated and configuration changes are logged.

 

 

 

 

Example files are available at the following links:

 

This folder contains the single .proto file used by the gRPC service. This proto can be used with gRPC tools to automatically generate client stubs that can be used to interact with the gRPC server. This file can also be loaded into tools like Postman to test the gRPC interface.

 

This folder was added in version 2 of the archive.

 

This folder contains an OpenAPI definition for the REST interface. This file can be loaded into tools like Postman to test the REST interface, or can be used with automated code generation tools to generate client stubs that can be used to interact with the REST interface. This file can also be loaded into tools like Power Automate to make is easy to use Power Automate to interact with the REST API.

 

This folder contains code samples showing how to interact with the gRPC server.

 

 

This folder contains a sample configuration that can be loaded into PLC Shift Manger. Each configuration has one device and one Gas Flow app. The device has gRPC enabled and is configured for HTTP and HTTPS listeners on their default ports.

 

To use this configuration:

You should now be able to connect to the runtime using the sample code. No PLC is required, but the input values to the flow computer will be null, so unless these values are set, the flow computer will not show any flow.