From 53db026cbff117b52a3fdfb9c2f78e94af144767 Mon Sep 17 00:00:00 2001 From: Zach Hindes Date: Thu, 8 Aug 2024 13:49:12 -0500 Subject: [PATCH] README improvements for upcoming public announcements (#622) * readme improvements for upcoming public announcements --- README.rst | 149 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 91 insertions(+), 58 deletions(-) diff --git a/README.rst b/README.rst index 9d213dd9..38a87c67 100644 --- a/README.rst +++ b/README.rst @@ -1,25 +1,51 @@ -=========== ================================================================================================================================= -Info Contains a Python API for interacting with NI-DAQmx. See `GitHub `_ for the latest source. -Author National Instruments -=========== ================================================================================================================================= ++------------+-----------------------------------------------------------+ +| **Info** | Contains a Python API for interacting with NI-DAQmx. See | +| | `GitHub `_ for the | +| | latest source. | ++------------+-----------------------------------------------------------+ +| **Author** | National Instruments | ++------------+-----------------------------------------------------------+ + +.. contents:: Table of Contents + :depth: 1 + :backlinks: none About ===== -The **nidaqmx** package contains an API (Application Programming Interface) -for interacting with the NI-DAQmx driver. The package is implemented in Python. -The package is implemented as a complex, -highly object-oriented wrapper around the NI-DAQmx C API using the -`ctypes `_ Python library. +The **nidaqmx** package allows you to develop instrumentation, acquisition, and +control applications with NI data acquisition (DAQ) devices in Python. -**nidaqmx** supports all versions of the NI-DAQmx driver that ships with the C -API. The C API is included in any version of the driver that supports it. The -**nidaqmx** package does not require installation of the C header files. +Documentation +------------- + +You can find the latest API documentation for the **nidaqmx** package on +`Read the Docs `_. + +Refer to the +`NI-DAQmx User Manual `_ for +an overview of NI-DAQmx, key concepts, and measurement fundamentals. The +NI-DAQmx Help also installs locally with the full version of NI-DAQmx. Refer to +`this Knowledge Base (KB) `_ +for more information. + +Implementation +-------------- -Some functions in the **nidaqmx** package may be unavailable with earlier -versions of the NI-DAQmx driver. Visit the -`ni.com/downloads `_ to upgrade your version of -NI-DAQmx. +The package is implemented in Python as an object-oriented wrapper around the +NI-DAQmx C API using the +`ctypes `_ Python library. + +Supported NI-DAQmx Driver Versions +---------------------------------- + +**nidaqmx** supports all versions of NI-DAQmx. Some functions in the **nidaqmx** +package may be unavailable with earlier versions of the NI-DAQmx driver. Refer +to the Installation section for details on how to install the latest version of +the NI-DAQmx driver. + +Operating System Support +------------------------ **nidaqmx** supports Windows and Linux operating systems where the NI-DAQmx driver is supported. Refer to @@ -27,43 +53,50 @@ driver is supported. Refer to for which versions of the driver support your hardware on a given operating system. +Python Version Support +---------------------- + **nidaqmx** supports CPython 3.8+ and PyPy3. Installation ============ -Running **nidaqmx** requires NI-DAQmx to be installed. Visit -`ni.com/downloads `_ to download the latest -version of NI-DAQmx. None of the recommended **Additional items** are required -for **nidaqmx** to function, and they can be removed to minimize installation -size. It is recommended you continue to install the **NI Certificates** package -to allow your Operating System to trust NI built binaries, improving your -software and hardware installation experience. - -**nidaqmx** can be installed with `pip `_:: +You can use `pip `_ to download **nidaqmx** from +`PyPI `_ and install it:: $ python -m pip install nidaqmx -Similar Packages -================ +Automatic Driver Installation +----------------------------- + +Running **nidaqmx** requires NI-DAQmx to be installed. The **nidaqmx** module +ships with a command-line interface (CLI) to streamline the installation +experience. You can install the NI-DAQmx driver using the following command:: + + $ python -m nidaqmx installdriver -There are similar packages available that also provide NI-DAQmx functionality in -Python: +On Windows, this command will download and launch an online streaming installer +from ni.com. On Linux, this will download the repository registration package +for your Linux distribution and install the driver using your package manager. -- `daqmx `_ - (`slightlynybbled/daqmx on GitHub `_) - provides an abstraction of NI-DAQmx in the ``ni`` module. +Manual Driver Installation +-------------------------- -- PyLibNIDAQmx (`pearu/pylibnidaqmx on GitHub `_) - provides an abstraction of NI-DAQmx in the ``nidaqmx`` module, which collides - with this package's module name. +Visit `ni.com/downloads `_ to download the latest +version of NI-DAQmx. None of the recommended **Additional items** are required +for **nidaqmx** to function, and they can be removed to minimize installation +size. It is recommended you continue to install the **NI Certificates** package +to allow your Operating System to trust NI built binaries, improving your +software and hardware installation experience. Getting Started =============== -In order to use the **nidaqmx** package, you must have at least one DAQ (`Data Acquisition `_) -device installed on your system. Both physical and simulated devices are supported. The examples below use an X Series DAQ device -(e.g.: PXIe-6363, PCIe-6363, or USB-6363). -You can use **NI MAX** or **NI Hardware Configuration Utility** to verify and configure your devices. +In order to use the **nidaqmx** package, you must have at least one DAQ +(`Data Acquisition `_) device +installed on your system. Both physical and simulated devices are supported. The +examples below use an X Series DAQ device (e.g.: PXIe-6363, PCIe-6363, or +USB-6363). You can use **NI MAX** or **NI Hardware Configuration Utility** to +verify and configure your devices. Finding and configuring device name in **NI MAX**: @@ -79,8 +112,23 @@ Finding and configuring device name in **NI Hardware Configuration Utility**: :align: center :width: 800px -Tasks in NI-DAQmx ------------------ +Python Examples +=============== + +You can find a variety of examples in the GitHub repository in the +`nidaqmx-python examples `_ +directory. For best results, use the examples corresponding to the version of +**nidaqmx** that you are using. For example, if you are using version 1.0.0, +check out the +`examples directory in the 1.0.0 tag `_. +Newer examples may demonstrate features that are not available in older versions +of **nidaqmx**. + +Key Concepts in NI-DAQmx +========================= + +Tasks +----- A task is a collection of one or more virtual channels with timing, triggering, and other properties. Refer to `NI-DAQmx Task `_ for more information. @@ -92,8 +140,8 @@ Example code to create a task: >>> with nidaqmx.Task() as task: ... pass -Virtual Channels in NI-DAQmx ----------------------------- +Virtual Channels +---------------- Virtual channels, or sometimes referred to generically as channels, are software entities that encapsulate the physical channel along with other channel specific information (e.g.: range, terminal configuration, and custom scaling) that formats the data. A physical channel is a terminal or pin at which you can measure or generate an analog or digital signal. A single physical channel @@ -307,8 +355,6 @@ Following is an example of using an **nidaqmx.system.System** object. >>> isinstance(phys_chan.ai_term_cfgs[0], Enum) True -You can find more examples in `nidaqmx-python examples `_. - Bugs / Feature Requests ======================= @@ -335,19 +381,6 @@ Please include **all** of the following information when opening an issue: to determine the version of NI-DAQmx you have installed. - The operating system and version, for example Windows 7, CentOS 7.2, ... -Documentation -============= - -Documentation is available `here `_. - -Additional Documentation -======================== - -Refer to the `NI-DAQmx Help `_ -for API-agnostic information about NI-DAQmx or measurement concepts. - -NI-DAQmx Help installs only with the full version of NI-DAQmx. - License =======