Creating a gRPC Client

Table of Contents

• Introduction
• Creating a Python gRPC Client
• Creating a C# gRPC Client
• Troubleshooting

Introduction

Each supported driver API has a corresponding .proto file in a sub-folder containing the driver name. All driver sub-folders are located under the generated folder here. The .proto file describes the API used by clients to interact with the ni_grpc_device_server and the NI device(s) connected to the server. For example, the .proto file for NI-SCOPE can be found (here). There is an additional .proto file that describes the Session Utilities API.

The information in the remainder of this document applies to creating a gRPC client in Python but gRPC also supports writing clients in additional languages. In order to create a client in languages other than Python:

1. See the gRPC documentation for a full list of supported languages.
2. Refer to this section of the Protocol Buffers documentation to learn how to generate the code needed to work with the desired API's messages as defined in each .proto file.
3. Navigate to the client section of the relevant Basics Tutorial for more details on writing client code in a given language. An example in C++ can be found here

Creating a Python gRPC Client

Refer to this video or the below steps for creating gRPC application using python.

1. Install the grpcio-tools using your preferred Python package manager. Two options are outlined below:

   PIP

   > pip install grpcio-tools
   

   Anaconda

   > conda install grpcio-tools
   

2. (optional) Install mypy-protobuf, types-protobuf, and grpc-stubs to enable PEP 484 type hints for gRPC and Protocol Buffers. This enables text editors such as VS Code to more accurately auto-complete references to gRPC stub and message objects. Type hints are also a prerequisite for using static type checking tools such as mypy and pyright.

   > pip install mypy-protobuf types-protobuf grpc-stubs
   

3. Determine whether to use the standard proto compiler or the Better Protobuf compiler to generate the supporting files from each .proto file. The latter produces a more idiomatic version of the gRPC API. For more information refer to the Better Protobuf repository here. If using the Better Protobuf compiler then install the betterproto tools, otherwise skip to the next step:

   > pip install "betterproto[compiler]"
   

   Note: The Better Protobuf compiler has a bug generating helpers for gRPC messages with oneof types. The problem is that zero-value messages in a oneof group take priority based on order and overwrite other set values. Therefore, only the last field, the field that has '_raw` appended to the name, can be properly set without wrapper modification.

4. Generate the supporting files for each API required by the client:

   Example commands ran from directory containing example file as organized in the client release

   a. Standard compiler:

   > python -m grpc_tools.protoc -I="..\..\proto" --python_out=. --grpc_python_out=. session.proto nidevice.proto niscope.proto
   

   Output for NI-SCOPE will be session_pb2.py, session_pb2_grpc.py, nidevice_pb2.py, nidevice_pb2_grpc.py,niscope_pb2.py, and niscope_pb2_grpc.py.

   b. Standard compiler with type hints:

   > python -m grpc_tools.protoc -I="..\..\proto" --python_out=. --grpc_python_out=. --mypy_out=. --mypy_grpc_out=. session.proto nidevice.proto niscope.proto
   

   Output for NI-SCOPE will be session_pb2.py, session_pb2_grpc.py, nidevice_pb2.py, nidevice_pb2_grpc.py,niscope_pb2.py, and niscope_pb2_grpc.py, plus the corresponding .pyi files containing the type hints.

   c. Better Protobuf compiler:

   >  mkdir nidevice
   >  cd nidevice
   >  python -m grpc_tools.protoc -I="..\..\..\proto" --python_betterproto_out=. session.proto nidevice.proto niscope.proto
   

   Output for NI-SCOPE will be __init__.py, niscope_pb2_grpc.py, nidevice_pb2_grpc.py, session_pb2_grpc.py, and a grpc folder.

   The directory containing the proto file being used as well as path(s) to any imports must be specified using the -I flag. The examples above demonstrate generation on Windows but you can adjust the path delimiters as needed for the platform being used.

5. Copy the output files (and folder) from the Step 3 to the folder containing the python client.

6. Add module imports:

   a. Standard compiler:

   import grpc
   import niscope_pb2 as niscope_types
   import niscope_pb2_grpc as grpc_niscope

   b. Better Protobuf compiler:

   import asyncio
   from nidevice import niscope_grpc
   from grpclib.client import Channel

   Note Install and import other libraries like matplotlib as required.

7. Create a secure or insecure channel based on the server's security configuration. Refer to this wiki page for details.

8. Write API specific calls to get data from your device. Refer to examples here.

Creating a C# gRPC Client

Pre-requisites

• Windows: .NET Framework 4.5+, Visual Studio 2013 or higher

Steps

1. Open Visual Studio

   1. Create a new project/solution
   2. Select Class Library(.NET Framework) for the first project.
   3. In this example, we'll name the solution NIDCPower and the project NIDCPowerProto.

2. Add the Grpc and Google.Protobuf NuGet packages as dependencies of this NIDCPowerProto project

   1. Right click on project
   2. Manage NuGet Packages
   3. Install these packages using Browse option

3. Add the Grpc.Tools NuGet package (version should be >= 1.17) to your project. This package enables you to generate code from the Protocol Buffer (.proto) files as part of the build.

4. Add session.proto and nidcpower.proto files directly under the NIDCPowerProto project. Then Save All (Ctrl+ Shift + S) so that NIDCPowerProto.csproj gets updated.

   Note: Proto files must be directly under this project. Placing them in other locations in the project may result in build errors due to the use of relative paths by Grpc.Tools.

5. Open the NIDCPowerProto.csproj file in a plain text editor such as Notepad and mark the proto files Protobuf as shown below:

   <Protobuf Include="nidcpower.proto" />
   <Protobuf Include="session.proto" />
   

6. Reload the project. Go to the Properties panel of those proto files and confirm that Build Action is listed as Protobuf:

   

7. Build the NIDCPowerProto project.

   1. Build should create NIDCPowerProto.dll in the bin\Debug folder.

   2. Build should also create the following 4 highlighted files(shown in image below) in obj\Debug folder. These are the gRPC generated files by Grpc.Tools NuGet package.

      

8. Create a new Console App (.NET Framework) within the solution to set up the gRPC client. In this example, we'll name the app NIDCPowerClient.

9. Right-click on the NIDCPowerClient project in the solution explorer and select Add -> Reference -> NIDCPowerProto project -> OK.

   

10. Right-click on the NIDCPowerClient project again and select Manage NuGet Packages -> Install Using Browse to add the Grpc and Google.Protobuf NuGet packages as project dependencies.

11. Copy the client code below into Program.cs:

    using System;
    using Grpc.Core;
    using NationalInstruments.Grpc.DCPower;
    
    namespace NIDCPowerClient
    {
        class Program
        {
            public static void Main(string[] args)
            {
                var server_address = "localhost";
                var server_port = "31763";
                var session_name = "NI-DCPower-Session";
    
                // Resource name, channel name, and options for a simulated 4147 client.
                var resource = "SimulatedDCPower";
                var options = "Simulate=1,DriverSetup=Model:4147;BoardType:PXIe";
                var channels = "0";
    
                Channel channel = new Channel(server_address + ":" + server_port, ChannelCredentials.Insecure);
    
                var client = new NiDCPower.NiDCPowerClient(channel);
    
                var initialize_reply = client.InitializeWithChannels(new InitializeWithChannelsRequest
                {
                    SessionName = session_name,
                    ResourceName = resource,
                    Channels = channels,
                    Reset = false,
                    OptionString = options
                });
                var vi = initialize_reply.Vi;
                if (initialize_reply.Status == 0)
                {
                    Console.WriteLine("Initialization was successful.");
                }
                else
                {
                    Console.WriteLine($"Initialization was not successful. Status is {initialize_reply.Status}");
                }
    
                client.Close(new CloseRequest
                {
                    Vi = vi
                });
    
                channel.ShutdownAsync().Wait();
                Console.WriteLine("Press any key to exit...");
                Console.ReadKey();
            }
        }
    }

12. Build the NIDCPowerClient project. Check the bin\Debug folder to make sure the build generated the NIDCPowerClient.exe app.

    

13. Run the ni_grpc_device_server obtained from our release on the server machine in one terminal.

14. Run the NIDCPowerClient.exe obtained in step 12 in another terminal.

Reference links for using .NET Framework

• https://grpc.io/docs/languages/csharp/quickstart/
• https://github.com/grpc/grpc/tree/v1.38.0/examples/csharp/HelloworldLegacyCsproj
• https://github.com/grpc/grpc/blob/master/src/csharp/BUILD-INTEGRATION.md
• https://github.com/grpc/grpc/blob/v1.38.0/src/csharp/README.md#prerequisites
• https://codelabs.developers.google.com/codelabs/cloud-grpc-csharp#0

Reference links if you need to use .NET Core:

• https://grpc.io/docs/languages/csharp/quickstart/
• https://github.com/grpc/grpc/tree/v1.38.0/examples/csharp/Helloworld
• https://docs.microsoft.com/en-us/aspnet/core/tutorials/grpc/grpc-start?view=aspnetcore5.0&tabs=visual-studio#create-the-grpc-client-in-a-net-console-app
• https://www.youtube.com/watch?v=ru5x_hDZ9Qw

Converting C API Calls to gRPC

The gRPC API is based on the C APIs for each supported driver. See Driver Documentation for finding the right documentation for you. Applications developed against the C APIs can be converted to use the gRPC API taking into account the following considerations:

1. Each of the functions in the C header have a corresponding RPC service method in the .proto file.
   Example: the niScope_InitWithOptions function defined in niScope.h corresponds to the InitWithOptions method on the NiScope service in niscope.proto.

2. Each RPC method accepts a Request and Response protobuf message where the fields of the Request correspond to the input parameters of the C function and the fields of the Response message correspond to the return value and output parameters in the C function.

   • Input parameters related to the size of output arrays and strings may be omitted from the request message. For example, the bufSize parameter of niScope_GetAttributeViString is automatically calculated and is not included in the GetAttributeViStringRequest message in niscope.proto.
   • Initialization functions can accept an additional session name which can be used to enable multiple clients to share a single session to a device.

3. Many of the constants defined in the driver C header file are grouped into enums in the .proto file. It is recommended to use these enum values in Request/Response message fields.
   For example, if you want the fetch API to calculate timeout automatically, set maximum_time parameter to TIME_LIMIT_NIDMM_VAL_TIME_LIMIT_AUTO value since the enum exists.

   fetch_result = dmm_service.fetch(vi = vi, maximum_time = nidmm_grpc.TimeLimit.TIME_LIMIT_NIDMM_VAL_TIME_LIMIT_AUTO)

   • If enum is not available for the value that you want to pass as a function parameter, use corresponding <param_name>_raw parameter for assigning the value directly.
     For example, If you want to set the fetch API timeout to 10 milliseconds, since enum corresponding to 10 milliseconds does not exist, you should use maximum_time_raw parameter for passing the value.

     fetch_result = dmm_service.fetch(vi = vi, maximum_time_raw = 10)

     NOTE: Better Protobuf compiler does not support setting enum values in the message containing oneof types. Use raw parameters in this case.

   • For CheckAttribute and SetAttribute APIs, values for attributes of a particular datatype are available under enums associated with that datatype. For example:
     NiDMMInt32AttributeValues enum contains values for NI-DMM attributes of Int32 type.
     NiDCPowerReal64AttributeValues enum contains values for NI-DCPower attributes of Real64 type.

     NOTE: No enums are available for GetAttribute APIs.

Troubleshooting

"Received message larger than max (15999943 vs. 4194304)"

gRPC has a default limit on max message size. This size can be configured in the client.

For an insecure python client, with unlimited message size:

channel = grpc.insecure_channel(
    f"{server_address}:{server_port}",
    options=[
        ("grpc.max_send_message_length", -1),
        ("grpc.max_receive_message_length", -1),
    ],
)

For C# see MaxReceiveMessageSize.

Depending on your application/driver, it may be possible to acquire data in smaller chunks.