Creating a gRPC Client

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

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. 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.

3. 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
   > python -m grpc_tools.protoc -I="..\..\proto" --python_out=. --grpc_python_out=. niscope.proto
   

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

   b. Better Protobuf compiler:

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

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

   In the example above each command is executed from the folder containing the referenced .proto file. 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. The driver .proto files reference the session.proto file and therefore the path to that file must also be specified, if in separate directory.

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

5. 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.

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

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

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 constants defined in the C header are grouped into enums in the .proto file. Request message fields to which those values apply can be set using corresponding enums.
   • The request messages that use enum types will also have a _raw field that can be used to set the raw numeric or string value. This allows a client to specify values other than those included in the enum. For example, while performing single point fetch for NI-DMM, you can specify maximum_time parameter using TimeLimit enum or specify it as an integer value.

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

   • Constants that can used to set value field in request messages for SetAttribute and CheckAttribute functions are grouped into an enum that corresponds to the required field value type. For example, constants in the NiDMMInt32AttributeValues enum provide values for value field of niDMM_SetAttributeViInt32 function in the NI-DMM API.
   • The .proto file only supports use of 32-bit numeric values as constants within enums. To support other value types, we have created unique 32-bit numeric values to map to constants such as a string or other type of numeric value, and use them in corresponding enums in the .proto file. These values should only be used for assigning to fields with _mapped suffix in the request message.
   • Response messages from API calls to GetAttribute functions do not use enum types in the value fields.