Sharing Driver Sessions Between Clients - ni/grpc-device GitHub Wiki

Overview

The NI gRPC Device Server allows sharing driver sessions between multiple gRPC clients. This enables test architects to build applications, services, and systems that share driver sessions between multiple OS processes, network hosts, and/or programming languages.

Session Naming

Session names are user-specified names that identify driver sessions on the NI gRPC Device Server. Specifying a name for a session enables sharing the session between multiple gRPC clients. To specify a session name, set the session_name field in the initialize request.

If you do not specify a session name, or you specify an empty string, the NI gRPC Device Server automatically chooses a unique name.

For example, niscope.proto defines InitWithOptionsRequest:

message InitWithOptionsRequest {
  string session_name = 1;
  string resource_name = 2;
  bool id_query = 3;
  bool reset_device = 4;
  string option_string = 5;
  nidevice_grpc.SessionInitializationBehavior initialization_behavior = 6;
}

This code from one of the Python example programs initializes an NI-SCOPE session, setting its session name to "demo":

init_result = niscope_client.InitWithOptions(
    niscope_types.InitWithOptionsRequest(
        session_name="demo",
        resource_name=RESOURCE,
        id_query=False,
        option_string=OPTIONS,
    )
)

When multiple clients execute this code:

• The first initialize call creates a session named "demo" on the server, with the specified resource name and option string.
• Subsequent initialize calls returns the same session as the first call, without creating a new session.

Note

The NI gRPC Device Server only uses the session name to identify sessions. If a session with the specified name already exists, the NI gRPC Device Server ignores the specified resource name, channel string, option string, etc.

Session Initialization Behavior

The initialization_behavior setting in the initialize request tells NI gRPC Device Server whether to create a new driver session or attach to an existing driver session.

The SessionInitializationBehavior enum is defined in session.proto:

enum SessionInitializationBehavior {
  SESSION_INITIALIZATION_BEHAVIOR_UNSPECIFIED = 0;
  SESSION_INITIALIZATION_BEHAVIOR_INITIALIZE_NEW = 1;
  SESSION_INITIALIZATION_BEHAVIOR_ATTACH_TO_EXISTING = 2;
}

Possible settings:

• UNSPECIFIED (default): The NI gRPC Device Server will attach to an existing session with the specified name if it exists, otherwise the server will initialize a new session.
• INITIALIZE_NEW: Require the NI gRPC Device Server to initialize a new session with the specified name. If a session with the specified name already exists, the initialize call fails with gRPC status code ALREADY_EXISTS.
• ATTACH_TO_EXISTING: Require the NI gRPC Device Server to attach to an existing session with the specified name. If a session with the specified name does not exist, the initialize call fails with gRPC status code FAILED_PRECONDITION.

Driver APIs

NI Modular Instruments

For documentation on gRPC session naming/initialization in NI Modular Instruments LabVIEW APIs, see the appropriate Initialize for gRPC Session, Attach gRPC Session, and Detach gRPC Session VIs for the API you are using.

For documentation on gRPC session naming/initialization in NI Modular Instruments Python APIs, see the gRPC Support page for the API you are using.

Comparison of LabVIEW and Python APIs

Operation	LabVIEW	Python
Automatically create or attach	not supported	Specify SessionInitializationBehavior.AUTO (default) in gRPC options
Automatically close or detach	not supported	Use context manager: with Session(...) as session:
Create a new session on the server	Call Initialize for gRPC Session VI	Specify SessionInitializationBehavior.INITIALIZE_SERVER_SESSION in gRPC options
Attach to an existing session on the server	Call Attach gRPC Session VI	Specify SessionInitializationBehavior.ATTACH_TO_SERVER_SESSION in gRPC options
Detach from the session on the server	Call Detach gRPC Session VI	Discard session object without calling session.close()
Close the session on the server	Call close VI	Call session.close()

Note

The SessionInitializationBehavior enum value names are different in Python vs. session.proto.

Note

MeasurementLink measurement services in LabVIEW should use the session exists field in the ReserveSessions response to decide whether to create/close or attach/detach.

NI-DAQmx

For NI gRPC Device Server, a NI-DAQmx task is considered to be a type of driver session. nidaqmx.proto's equivalent of the session initialize request is CreateTaskRequest:

message CreateTaskRequest {
  string session_name = 1;
  nidevice_grpc.SessionInitializationBehavior initialization_behavior = 2;
}

NI-DAQmx tasks have names (independent of NI gRPC Device Server), which are used to refer to saved tasks in NI MAX and LabVIEW projects. The NI gRPC Device Server uses the session name as the NI-DAQmx task name. If a saved task with the same name exists in NI MAX, CreateTaskRequest will return an error, but you can use LoadTaskRequest to load the saved task.

For documentation on gRPC session naming/initialization in the NI-DAQmx Python API, see the nidaqmx.grpc_session_options page.

NI-VISA

To enable gRPC remoting with NI-VISA 2024Q2 or later, pass grpc://{address}/{resource_name}?init_behavior={init_behavior}&session_name={session_name} as the VISA resource name. Example: grpc://localhost:31756/GPIB::2::INSTR?init_behavior=0&session_name=MySession.

Initialization Behavior	Close Behavior	init_behavior Value
Automatically create or attach	Automatically close or detach server session	0
Create a new session on the server	Close server session	1
Attach to an existing session on the server	Detach server session	2
Create a new session on the server	Detach server session	3
Attach to an existing session on the server	Close server session	4

In LabVIEW, you can use VISA Open for gRPC Session.vi or VISA Format gRPC URI.vi to build a grpc:// URI.