diff --git a/build/templates/grpc_session_options.rst.mako b/build/templates/grpc_session_options.rst.mako index 05cb46f5b..9b8f4a8f6 100644 --- a/build/templates/grpc_session_options.rst.mako +++ b/build/templates/grpc_session_options.rst.mako @@ -14,6 +14,53 @@ Support for using ${driver_name} over gRPC +Creating a gRPC channel +----------------------- + +Using ${driver_name} over gRPC requires the ``grpc`` extra:: + + $ python -m pip install ${module_name}[grpc] + +Every ${driver_name} gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`${module_name}.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the ${driver_name} runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import ${module_name} + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = ${module_name}.GrpcSessionOptions(channel, '') + with ${module_name}.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -62,17 +109,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -81,18 +128,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`${module_name}.SessionInitializationBehavior` diff --git a/docs/nidcpower/grpc_session_options.rst b/docs/nidcpower/grpc_session_options.rst index 00265cdfd..0af0b2579 100644 --- a/docs/nidcpower/grpc_session_options.rst +++ b/docs/nidcpower/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-DCPower over gRPC +Creating a gRPC channel +----------------------- + +Using NI-DCPower over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidcpower[grpc] + +Every NI-DCPower gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidcpower.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-DCPower runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidcpower + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidcpower.GrpcSessionOptions(channel, '') + with nidcpower.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidcpower.SessionInitializationBehavior` diff --git a/docs/nidigital/grpc_session_options.rst b/docs/nidigital/grpc_session_options.rst index f868c64d5..fbee6ae12 100644 --- a/docs/nidigital/grpc_session_options.rst +++ b/docs/nidigital/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-Digital Pattern Driver over gRPC +Creating a gRPC channel +----------------------- + +Using NI-Digital Pattern Driver over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidigital[grpc] + +Every NI-Digital Pattern Driver gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidigital.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-Digital Pattern Driver runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidigital + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidigital.GrpcSessionOptions(channel, '') + with nidigital.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidigital.SessionInitializationBehavior` diff --git a/docs/nidmm/grpc_session_options.rst b/docs/nidmm/grpc_session_options.rst index 9eaf91c83..258f7e41c 100644 --- a/docs/nidmm/grpc_session_options.rst +++ b/docs/nidmm/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-DMM over gRPC +Creating a gRPC channel +----------------------- + +Using NI-DMM over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidmm[grpc] + +Every NI-DMM gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidmm.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-DMM runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidmm + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidmm.GrpcSessionOptions(channel, '') + with nidmm.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidmm.SessionInitializationBehavior` diff --git a/docs/nifgen/grpc_session_options.rst b/docs/nifgen/grpc_session_options.rst index 2752e1d18..9fa2a095c 100644 --- a/docs/nifgen/grpc_session_options.rst +++ b/docs/nifgen/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-FGEN over gRPC +Creating a gRPC channel +----------------------- + +Using NI-FGEN over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nifgen[grpc] + +Every NI-FGEN gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nifgen.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-FGEN runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nifgen + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nifgen.GrpcSessionOptions(channel, '') + with nifgen.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nifgen.SessionInitializationBehavior` diff --git a/docs/nirfsa/grpc_session_options.rst b/docs/nirfsa/grpc_session_options.rst index 0c939dec8..dc993f54b 100644 --- a/docs/nirfsa/grpc_session_options.rst +++ b/docs/nirfsa/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-RFSA over gRPC +Creating a gRPC channel +----------------------- + +Using NI-RFSA over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nirfsa[grpc] + +Every NI-RFSA gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nirfsa.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-RFSA runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nirfsa + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nirfsa.GrpcSessionOptions(channel, '') + with nirfsa.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nirfsa.SessionInitializationBehavior` diff --git a/docs/nirfsg/grpc_session_options.rst b/docs/nirfsg/grpc_session_options.rst index 73d27acff..bffe8bc43 100644 --- a/docs/nirfsg/grpc_session_options.rst +++ b/docs/nirfsg/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-RFSG over gRPC +Creating a gRPC channel +----------------------- + +Using NI-RFSG over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nirfsg[grpc] + +Every NI-RFSG gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nirfsg.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-RFSG runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nirfsg + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nirfsg.GrpcSessionOptions(channel, '') + with nirfsg.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nirfsg.SessionInitializationBehavior` diff --git a/docs/niscope/grpc_session_options.rst b/docs/niscope/grpc_session_options.rst index a944c230a..62e8a40c2 100644 --- a/docs/niscope/grpc_session_options.rst +++ b/docs/niscope/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-SCOPE over gRPC +Creating a gRPC channel +----------------------- + +Using NI-SCOPE over gRPC requires the ``grpc`` extra:: + + $ python -m pip install niscope[grpc] + +Every NI-SCOPE gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`niscope.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-SCOPE runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import niscope + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = niscope.GrpcSessionOptions(channel, '') + with niscope.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`niscope.SessionInitializationBehavior` diff --git a/docs/niswitch/grpc_session_options.rst b/docs/niswitch/grpc_session_options.rst index e0271e078..1758ddd0a 100644 --- a/docs/niswitch/grpc_session_options.rst +++ b/docs/niswitch/grpc_session_options.rst @@ -7,6 +7,53 @@ Support for using NI-SWITCH over gRPC +Creating a gRPC channel +----------------------- + +Using NI-SWITCH over gRPC requires the ``grpc`` extra:: + + $ python -m pip install niswitch[grpc] + +Every NI-SWITCH gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`niswitch.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +``create_grpc_device_channel`` from the `nitlsconfig `_ package, +which the ``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed +with the NI-SWITCH runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import niswitch + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = niswitch.GrpcSessionOptions(channel, '') + with niswitch.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +102,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +121,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`niswitch.SessionInitializationBehavior`