{
    "info": {
        "author": "Andreas Svela",
        "author_email": "asvela@ic.ac.uk",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# Keysight oscilloscope acquire package\n\n\nv2.0.1 // August 2019 // Andreas Svela\n\n## Overview\n\nThis package gives functionality for acquiring traces from Keysight oscilloscopes through a VISA interface, and exports traces as a chosen ASCII format file (default csv) and a png of the trace plot. The Python library `visa` is used for communication. The code has been tested on a Keysight DSO2024A model using a USB connection.\n\nThe code is structured as a module `keyoscacquire/oscacq.py` containing the engine doing `visa` interfacing in a class `Oscilloscope`, and support functions for data processing/saving. Programmes are located in `keyoscacquire/programmes.py`.  Default options are found in `keyoscacq/config.py`, the files in `/scripts` can be ran from the command line and are essentially the same running the installed executables.\n\n## Installation\n\nInstall the package with pip:\n\n```bash\n$ pip install keysightoscilloscopeacquire\n```\n\nor download locally and install with `$ python setup.py install` or by running `install.bat`.\n\n#### Default options\n\nThe package is installed with a set of default options found in `keyoscacq/config.py`:\n\n```python\n# Default options in config.py\n_visa_address = 'USB0::XXXX::XXXX::MYXXXXXXXX::INSTR' # address of instrument\n_waveform_format = 'WORD' # WORD formatted data is transferred as 16-bit uint.\n                          # BYTE formatted data is transferred as 8-bit uint.\n                          # ASCii formatted data converts the internal integer data values to real Y-axis values.\n                          #       Values are transferred as ASCii digits in floating point notation, separated by commas.\n_ch_nums = ['']           # list of chars, e.g. ['1', '3']. Use a list with an empty string [''] to capture all currently displayed channels\n_acq_type = \"HRESolution\" # {HRESolution, NORMal, AVER<m>} where <m> is the number of averages in range [1, 65536]\n_num_avg = 2              # default number of averages used if only AVER is given as acquisition type\n_filename = \"data\"        # default base filename of all traces and pngs exported, a number is appended to the base\n_file_delimiter = \" n\"    # delimiter used between _filename and filenumber (before _filetype)\n_filetype = \".csv\"        # filetype of exported data, can also be txt/dat etc.\n_export_png = True        # export png of plot of obtained trace\n_show_plot = False        # show each plot when generated (program pauses until it is closed)\n_timeout = 15000          # ms timeout for the instrument connection\n```\n\nFor changes to these defaults to take effect, the package must be reinstalled locally after doing the changes in `config.py`, simply by navigating to the directory containing `setup.py` and running `$ python setup.py install` or `install.bat`. **Note** that none of the functions access the global variables directly, but they are feed them as default arguments.\n\nThe `_waveform_format` dictates whether 16/8 bit raw values or comma separated ascii voltage values should be transferred when the waveform is queried for (the output file will be ascii anyway, this is simply a question of how the data is transferred to and processed on the computer). Raw values format is approx. 10x faster than ascii.\n\nThe command line programmes will save traces in the folder from where they are ran as`_filename+_file_delimiter+<n>+_filetype`, i.e. by default as `data n<n>.csv`and `data n<n>.png`.\n\n## Known issues/suggested improvements\n\n- Known issue: Sometimes `WORD` waveform does not give the correct trace data, just random noise (but switching to `ASCii` or `BYTE` gives correct traces). If this happens, open *KeySight BenchVue* and obtain one trace through the software. Now try to obtain a trace through this package -- it should now work again using `WORD`.\n- Add optional argument to supply visa address of instrument to command line executables and scripts\n\n## Usage\n\n**In order to connect to a VISA instrument, NI MAX or similar might need to be running on the computer.** The VISA address of the instrument can be found in NI MAX, and should be set as the `_visa_address` variable, see below, before installation.\n\nFour command line programmes `get_single_trace`, `get_num_traces`, `getTraces_connect_each_time` and `getTraces_single_connection` can be ran directly from the command line after installation (i.e. from whatever folder and no need for `$ python [...].py`).\n\nThe two first programmes will obtain one and a specified number of traces, respectively. The two latter programmes are loops for which every time `enter` is hit a trace will be obtained and exported as csv and png files with successive numbering. By default all active channels on the oscilloscope will be captured (this can be changed, see below). The difference between the two latter programmes is that the first programme is establishing a new connection to the instrument each time a trace is to be captured, whereas the second opens a connection to start with and does not close the connection until the program is quit. The second programme only checks which channels are active when it connects, i.e. the first programme will save only the currently active channels for each saved trace; the second will each time save the channels that were active at the time of starting the programme.\n\n\n### Optional command line argument sets base filename, acquiring mode or number of traces to obtain\n\nFurthermore, both programmes takes up to two optional arguments:\n`-f \"custom filename\"` set as the base filename to \"custom filename\"\n`-a AVER8`  sets acquiring type to average with eight traces\n`-n 10` sets number of traces to obtain (only for `get_num_traces`)\n\nFor example\n```bash\n$ getTraces_single_connection_loop -f measurement\n```\nwill give output files `measurement n<n>.csv` and `measurement n<n>.png`.  The programmes will check if the file `\"measurement\"+_file_delimiter+num+_filetype)` exists, and if it does, prompt the user for something to append to `measurement` until `\"measurement\"+appended+\"0\"+_filetype` is not an existing file. *The same checking procedure applies also when no base filename is supplied and `DEFAULT_FILENAME` is used.*\n\n### Obtaining single traces\n\nRunning the module with `$ python -m keyoscacquire` obtains and saves a trace with default options being used. Alternatively, the filename and acquisition type can be specified as per the paragraph above using the  executable, e.g. `$ get_single_trace -f \"fname\" -a \"AVER\"`.\n\n### Obtaining traces when the scope is running vs when stopped\n\nWhen the scope **is running** the `capture_and_read` functions will obtain a trace by running `:DIGitize`, causing the instrument to acquire a trace and then stop the oscilloscope. When the scope **is stopped** the current trace on the screen of the oscilloscope will be captured (*Warning:* This might mean the settings specified with `:ACQuire` are not used, i.e. acquiring mode and number of points to be captured).\n\nThe scope will always be set to running after a trace is captured.\n\n\n### Scripts in ./scripts\n\nThese can be ran as command line scripts from the folder with `$ python [script].py`. Optional arguments for filename and acquisition mode can be used, such as `$ python [script].py \"otherFileName\"`, or `$ python [script].py \"otherFileName\" \"AVER8\"`. Note, no flag specifiers are needed (or allowed) and the sequence of arguments is fixed.\n\n\n### Logging\n\nThe module gives output for debugging through `logging`. The output can be directed to the terminal by adding the following to the top level file using the keyoscacquire package\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\nor directed to a file `mylog.log` with\n```python\nimport logging\nlogging.basicConfig(filename='mylog.log', level=logging.DEBUG)\n```",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://microphotonics.net/",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "keysightoscilloscopeacquire",
        "package_url": "https://pypi.org/project/keysightoscilloscopeacquire/",
        "platform": "",
        "project_url": "https://pypi.org/project/keysightoscilloscopeacquire/",
        "project_urls": {
            "Homepage": "http://microphotonics.net/"
        },
        "release_url": "https://pypi.org/project/keysightoscilloscopeacquire/2.0.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Obtain traces, save to files and export raw plots from Keysight oscilloscopes using PyVISA.",
        "version": "2.0.1"
    },
    "last_serial": 5753626,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "040f6515c439b7cd03bab18fcc3c2826",
                    "sha256": "29aaf92a5d7249de1c2c5c9bcb7ce36506a556204ecf937f991742dcd846c445"
                },
                "downloads": -1,
                "filename": "keysightoscilloscopeacquire-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "040f6515c439b7cd03bab18fcc3c2826",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 15971,
                "upload_time": "2019-03-08T01:27:18",
                "url": "https://files.pythonhosted.org/packages/b5/a2/4e0853a227f78ce02a8d282e6cd33ecdbcf7052ba312b27b1ba64298875f/keysightoscilloscopeacquire-1.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "a7e5a908da910bcf10c4b554e8e5e11c",
                    "sha256": "297c568d2baaf7d91ca3f8b6836d5a33903e79f7d5b23c5ba1a68d50f11c4138"
                },
                "downloads": -1,
                "filename": "keysightoscilloscopeacquire-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "a7e5a908da910bcf10c4b554e8e5e11c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 14758,
                "upload_time": "2019-03-08T01:27:20",
                "url": "https://files.pythonhosted.org/packages/90/90/56d1ac682b3684b700324956801a9ae543f899531cd85c6f7c5a93f14b34/keysightoscilloscopeacquire-1.0.0.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c4763fc3083c31704c07bf25a7188458",
                    "sha256": "f967bc18a288a301de5ce700b48b75526ae5e73cccef402cdc3809f61962efbb"
                },
                "downloads": -1,
                "filename": "keysightoscilloscopeacquire-1.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "c4763fc3083c31704c07bf25a7188458",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15630,
                "upload_time": "2019-04-08T23:01:11",
                "url": "https://files.pythonhosted.org/packages/24/ab/03f8f7f4bc38cf71472d0cf6beca22e8b7c77b378a4a7ddc2ff42382ea01/keysightoscilloscopeacquire-1.1.0.tar.gz"
            }
        ],
        "2.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7685cc6a0b0223d7f01cef98d6f86587",
                    "sha256": "1bae77a8e918b963af811ed58e9400d1e905e55c2ecaffa9b7ea22acf626a4b9"
                },
                "downloads": -1,
                "filename": "keysightoscilloscopeacquire-2.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "7685cc6a0b0223d7f01cef98d6f86587",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15976,
                "upload_time": "2019-08-29T14:46:14",
                "url": "https://files.pythonhosted.org/packages/d8/33/d7481a98a9a1789397a7b1828b59e208db6c92c400db859e9039afa6d961/keysightoscilloscopeacquire-2.0.0.tar.gz"
            }
        ],
        "2.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "001fd0e4d0053553cd287612df2c6be6",
                    "sha256": "ff2dc6d4b05665da825e1400c523291089848c5d1921bf06c5348e050989e254"
                },
                "downloads": -1,
                "filename": "keysightoscilloscopeacquire-2.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "001fd0e4d0053553cd287612df2c6be6",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15965,
                "upload_time": "2019-08-29T15:00:51",
                "url": "https://files.pythonhosted.org/packages/2c/08/b4541770a35613cafd205614db0a03cf87ac1d55b53de6d10c592674d893/keysightoscilloscopeacquire-2.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "001fd0e4d0053553cd287612df2c6be6",
                "sha256": "ff2dc6d4b05665da825e1400c523291089848c5d1921bf06c5348e050989e254"
            },
            "downloads": -1,
            "filename": "keysightoscilloscopeacquire-2.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "001fd0e4d0053553cd287612df2c6be6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 15965,
            "upload_time": "2019-08-29T15:00:51",
            "url": "https://files.pythonhosted.org/packages/2c/08/b4541770a35613cafd205614db0a03cf87ac1d55b53de6d10c592674d893/keysightoscilloscopeacquire-2.0.1.tar.gz"
        }
    ]
}