One of the new features in Workers 5.1 is the new gRPC Worker templates, which are available from the Workers for LabVIEW Community GitHub repository and can be downloaded directly through the Workers 5.1 Worker User Library tool.
This guide will walk you through how to change the data types used by the gRPC Worker templates by customizing their Public API payloads. This allows you to adapt the templates for your own applications whenever you need to communicate between a Workers application and an application written in another language over gRPC.
Good to know before you start:
The gRPC Worker templates use a bidirectional streaming RPC. This choice maps cleanly onto a Worker's bidirectional Public API of Requests and Responses, allowing messages to flow asynchronously in both directions between a Workers application and an application written in another language.
The gRPC service and message types used by the gRPC Worker templates are defined in a .proto file. This file acts as a contract, allowing the messages and their payloads to be clearly defined for both the gRPC Server and Client. This provides a clearly defined Public API for the gRPC Worker templates, while the same .proto contract can also be implemented by applications written in any other language supported by gRPC.
The NI gRPC Code Generator, available here:
https://github.com/ni/grpc-labview/releases/download/v1.7.0.1/grpc-labview.zip
is used to generate the LabVIEW gRPC libraries and the LabVIEW data types required for the message payloads. For the supported data types used by these templates, this means that no manual work is required to translate the text-based .proto definitions into the LabVIEW typedefs required by the gRPC Workers.
The .proto file used by the gRPC Worker templates is called template.proto. It defines 18 predefined messages: nine sent from the client to the server, and nine sent from the server to the client.
Each message has its own payload definition. When you change a message payload in template.proto and regenerate the LabVIEW gRPC libraries, the NI gRPC Code Generator automatically regenerates the corresponding LabVIEW datatype (i.e. typedef).
Mapping between Worker Public APIs and template.proto
As mentioned above, template.proto defines 18 message types across the gRPC bidirectional stream: 9 in each direction.
template.proto message definitions
These are the messages provided in the gRPC Worker Templates:
Messages from Client to Server (template.proto)
message Msg_ToServer_1 { string placeholder = 1; }
message Msg_ToServer_2 { string placeholder = 1; }
message Msg_ToServer_3 { string placeholder = 1; }
message Msg_ToServer_4 { string placeholder = 1; }
message Msg_ToServer_5 { string placeholder = 1; }
message Msg_ToServer_6 { string placeholder = 1; }
message Msg_ToServer_7 { string placeholder = 1; }
message Msg_ToServer_8 { string placeholder = 1; }
message Msg_ToServer_9 { string placeholder = 1; }Messages from Server to Client (template.proto)
message Msg_ToClient_1 { string placeholder = 1; }
message Msg_ToClient_2 { string placeholder = 1; }
message Msg_ToClient_3 { string placeholder = 1; }
message Msg_ToClient_4 { string placeholder = 1; }
message Msg_ToClient_5 { string placeholder = 1; }
message Msg_ToClient_6 { string placeholder = 1; }
message Msg_ToClient_7 { string placeholder = 1; }
message Msg_ToClient_8 { string placeholder = 1; }
message Msg_ToClient_9 { string placeholder = 1; }gRPC Worker Public APIs
Shown below are the Public APIs of the gRPC Server (left) and gRPC Client (right) Workers respectively. You will notice that the message names of each Public Request and Response correspond directly to the gRPC message names defined in template.proto above, allowing you to keep track of the mapping between the template.proto contract and your gRPC Server and Client Workers.
Note that the mapping reverses depending on which Worker is being used:
In the gRPC Client Worker, Msg_toServer messages are Public Requests and Msg_ToClient messages are Public Responses.
In the gRPC Server Worker, Msg_ToClient messages are Public Requests and Msg_ToServer messages are Public Responses.
Worker Public API payloads (data types)
Now that the message mapping is defined, the next step is to understand how the payloads — the data sent with each message — are defined.
The payload for each message is defined between the curly brackets following the message name. For example, in template.proto we have the following message:
message Msg_ToServer_1 { string placeholder = 1; }This message is sent from a gRPC Client to a gRPC Server. Its payload contains a string called placeholder.
For example, if we wanted to change the message payload to contain a boolean and a 32-bit integer, we would change the message definition in template.proto to:
message Msg_ToServer_1 { bool led = 1; int32 number = 2; }Here, led and number are user-defined field names that describe the purpose of the data being sent. You can name these fields appropriately for your own application. The values 1 and 2 are the protobuf field numbers used to identify each field within the message.
The NI gRPC Code Generator reads template.proto and generates the corresponding LabVIEW gRPC Server and Client libraries, including the LabVIEW datatypes used for each message payload.
After regenerating these libraries, the payload datatype for Msg_ToServer_1 now contains a Boolean and a 32-bit integer instead of the original string.
This change is reflected in both the gRPC Client Worker's Public Request VI (rqp_Msg_ToServer_1.vi) and in the gRPC Server Worker's Public Response VI (rsp_Msg_ToServer_1.vi), as shown in the screenshots below.
Thus, by changing the payload definitions of the predefined messages in template.proto and regenerating the LabVIEW gRPC libraries, the corresponding payload typedefs used by the Public API VIs of the gRPC Server and Client Workers are updated automatically.
This allows you to easily change the type of data sent in each of the 18 predefined gRPC messages to suit the requirements of your application.
In Part 2, I’ll walk you through how to modify the message payloads in template.proto, regenerate the corresponding LabVIEW gRPC libraries with the NI gRPC Code Generator, and test the gRPC Server and Client Worker templates with the newly generated payload typedefs..