Microlab Instruments Documentation

Transcription

1 Microlab Instruments Documentation Release Kristofer Monisit May 19, 2016

2

3 Contents 1 Quick start 1 2 Contents Microlab Instruments Features Installation Usage and Tutorial Basics Types of Instruments Reference Manual base_classes module microlab_instruments module Contributing Types of Contributions Get Started! Pull Request Guidelines Tips Credits Development Lead Contributors History ( ) Indices and tables 17 Python Module Index 19 i

4 ii

5 CHAPTER 1 Quick start $ pip install git+ $ python import microlab_instruments as mi giratina = mi.giratina() giratina.write('*idn?') print giratina.read_ascii() 1

6 2 Chapter 1. Quick start

7 CHAPTER 2 Contents 2.1 Microlab Instruments Microlab Instruments is an abstraction layer for all the GPIB/Ethernet/USB/Serial instruments in the Microlab. All you have to do is instantiate an instrument class. With the help of each instrument s SCPI command reference, just ask(), write(), or read() commands. No need to worry about hardware and protocol settings. Free software: BSD license Documentation: Features TODO 2.2 Installation To install: $ pip install git+ To uninstall: $ pip uninstall microlab-instruments To upgrade, you need to uninstall then reinstall the package. No provisions have yet been made for pip install --upgrade Usage and Tutorial Basics 1. Start using microlab-instruments import microlab_instruments as mi 2. Turn on the instrument nicknamed Giratina. 3

8 3. Initialize Giratina in the software environment giratina = mi.giratina() 4. Query Giratina for its identification string. giratina.write('*idn?') 5. Read Giratina s ASCII response print giratina.read_ascii() 6. Putting them all together, you can write a script that asks Giratina for its identification string: import microlab_instruments as mi giratina = mi.giratina() giratina.write('*idn?') print giratina.read_ascii() Types of Instruments Two types of instruments are modeled in this Python package. 1. SCPI instruments communicate via GPIB or TCP/IP. They can receive string commands and respond in either ASCII, binary, or IEEE-754 floating point formats. 2. I2C instruments communicate via the Aardvark adapter. They are more limited in terms of commands and response formats. SCPI Instruments The most important commands for SCPI instruments are: write() read_ascii() read_binary() read_ieee754() The read... commands return the following data types: read_ascii returns human-readable str. read_binary technically returns str but it is not guaranteed to be human-readable. Printing the output of this function will only result in gibberish in your terminal. read_ieee754 returns a list of numbers which are the result of a measurement SCPI query. WARNING If you consecutively send write several commands that for which you expect a response without reading their respective responses in turn, you may no longer be able to segregate the data in the response buffer. For example: import microlab_instruments as mi giratina = mi.giratina() giratina.write('*idn?') giratina.write(':fetch:arr:volt?') # The following line of code reads too much. The response to '*IDN?' is 4 Chapter 2. Contents

9 # not necessarily 4096 bytes long. The beginning of the response to # ':fetch:arr:volt' is read prematurely and this library does not provide # functions to reconstruct the data when it is read this way. giratina.read_ascii(bufsize=4096) Convenience functions are provided such that write and read commands are done consecutively. ask_ascii() ask_binary() ask_ieee754() SCPI Instruments Example The following code takes a screenshot of the present display on Giratina and saves it in screenshot.jpg in the current directory. giratina.write(':disp:enab ON') giratina.write(':disp:view GRAPH') giratina.write(':hcop:sdum:form JPG') giratina.write('*opc') giratina.write(':hcop:sdum:data?') d = giratina.read_binary() fd = open('screenshot.jpg', 'wb') fd.write(d) fd.close() For the following code, connect a 1kΩ resistor between the positive and negative probes. We will sweep the voltage from 0 to 5 and measure the current. Voltage sweep values and the corresponding current values are retrieved. import microlab_instruments as mi import numpy as np giratina = mi.giratina() giratina.write('*idn?') giratina.write(':source:function:mode voltage') giratina.write(':source:sweep:direction up') giratina.write(':source:sweep:stair double') giratina.write(':source:sweep:spacing linear') giratina.write(':source:voltage:mode sweep') giratina.write(':source:voltage:start 0') giratina.write(':source:voltage:stop 5') giratina.write(':source:voltage:points 201') giratina.write(':sens:curr:prot 0.120') giratina.write(':trigger:source aint') giratina.write(':trigger:count 201') giratina.write(':format:data real,64') giratina.write(':outp on') giratina.write(':init (@1)') giratina.ask_ascii('*opc?') giratina.write(':output off') giratina.write(':fetch:arr:volt? (@1)') volt = np.array(giratina.read_ieee754()) giratina.write(':fetch:arr:curr? (@1)') curr = np.array(giratina.read_ieee754()) 2.3. Usage and Tutorial 5

10 res = volt / curr for m, n, o in zip(volt, curr, res): a = '{0:>20.3e}'.format(m) b = '{0:>17.1f}mA'.format(n*1e3) c = '{0:>20.3e}'.format(o) print ''.join([a, b, c]) I2C Instruments The I2C instruments are more specialized and thus we will discuss them here. The four I2C instruments are listed below, but you will actively use only the first three. 1. Kerrigan, an FPGA 2. Traxex, a temperature sensor 3. Xin, another temperature sensor identical to Traxex 4. Chen, an I2C multiplexer used to coordinate the Traxex and Xin These I2C instruments communicate via the Aardvark adapter, which must be initialized first. I2C Instruments Example Kerrigan has only two commands, write() and read() import microlab_instruments as mi aa = mi.aardvark() kerrigan = mi.kerrigan() REGISTER = 0x11 PAYLOAD = 0xAA kerrigan.write(register, PAYLOAD) print kerrigan.read(register) # This should output 0xAA print kerrigan.read(0x12) # This should output 0x00 To use Traxex and Xin, we also need to initialize Chen. The temperature sensors have only one command, read_temp(), which returns the temperature in Celsius degrees. import microlab_instruments as mi aa = mi.aardvark() chen = mi.chen(aa) traxex = mi.traxex(aa, chen) xin = mi.xin(aa, chen) print traxex.read_temp() print xin.read_temp() 2.4 Reference Manual base_classes module class microlab_instruments.base_classes.aardvarkinstrument Bases: object 6 Chapter 2. Contents

11 Initialize an Aardvark. Raises Exception Upon instantiation, SPI communication is tested. A 25-long array of bytes is sent twice to the Aardvark (and subsequently to the FPGA). After the second attempt, a response identical to the array must be received. If not, an Exception is raised. In this case, it may be likely that the FPGA did not respond properly. I2C_STATUS_CODES = {1: AA_I2C_STATUS_BUS_ERROR, 2: AA_I2C_STATUS_SLA_ACK, 3: AA_I2C_STATUS These are the status codes used by i2c_write(), i2c_read(), and i2c_write_read() when raising Exceptions. i2c_read(address, bufsize) Read bufsize number of bytes from the I2C slave with address. Parameters address (int) Slave address from which to receive response. bufsize (int) Size in bytes of expected response from slave. Returns out Response from slave. A bufsize-length list of ints. Return type list Raises Exception if the status response is not 0. See I2C_STATUS_CODES. i2c_write(address, bytecode) Write bytecode to the Aardvark output to be received by I2C slave with address. Parameters address (int) Slave address to receive bytecode. Limited to 8 bits. bytecode (int) Raw bytecode to send. Limited to 8 bits. Returns out Number of bytes sent. Return type int Raises Exception if the status response is not 0. See I2C_STATUS_CODES. i2c_write_read(address, bytecode, bufsize) Write bytecode to, and read bufsize bytes from, I2C slave with address in one fell swoop! Parameters address (int) Slave address to receive bytecode. Limited to 8 bits. bytecode (int) Raw bytecode to send. Limited to 8 bits. bufsize (int) Size in bytes of expected response from slave. Returns out Response from slave. A bufsize-length list of ints. Return type list Raises Exception if the status response is not 0. See I2C_STATUS_CODES. spi_write(bytecode) Write bytecode to, and read 25 bytes from, the SPI channel in one fell swoop! Parameters bytecode (list) Raw bytecodes to send. Must be exactly 25-long list of bytes. Returns out Response bytes. A 25-length list of ints. Return type list Raises Exception if bytecode does not have exactly 25 8-bit elements Reference Manual 7

12 class microlab_instruments.base_classes.fpgainstrument(aardvark) Bases: object An abstraction layer for the FPGA. read(register) Read the contents of register. Parameters register (int) The register address to read. Limited to 1 byte long. write(register, payload) Write a 1-byte-long payload to a register address. Parameters payload (int) The data to write. Limited to 1 byte long. register (int) The register address to write to. Limited to 1 byte long. class microlab_instruments.base_classes.gpibinstrument(nickname, reset=true) Bases: microlab_instruments.base_classes.scpiinstrument Initialize a GPIB instrument Parameters nickname (str) A nickname associated with a GPIB primary address and defined in /etc/gpib.conf. read(bufsize=4096) Read bufsize bytes from instrument. Using this low-level function, there is no way to ensure that all the response data has been retrieved, or to make sense of binary data. It is strongly recommended to use read_ascii(), read_binary(), or read_ieee754(). Parameters bufsize (int) Defaults to 4096 bytes. Expected size in bytes of the response from the instrument. Returns out Response from the instrument. Return type str reset() Reset the GPIB instrument. write(scpi_string) Write SCPI command to the instrument. The end-of-string character (for example, \n) is automatically appended. Parameters scpi_string (str) A valid SCPI command. See the instrument s SCPI command reference. class microlab_instruments.base_classes.i2cmuxinstrument(aardvark) Bases: object An abstraction layer for the I2C multiplexer chip. switch_to(mux_slave_address) Setup the multiplexer to relay I2C commands to the device having mux_slave_address Parameters slave_address (int) The device to which the multiplexer will relay I2C commands. class microlab_instruments.base_classes.scpiinstrument Bases: object 8 Chapter 2. Contents

13 ask_ascii(scpi_string) A convenience function for calling write() and read_ascii() consecutively. Up to 4096 bytes are read from the ASCII response buffer. Parameters scpi_string (str) A valid SCPI query command. See the instrument s SCPI command reference. Raises Exception If the SCPI command does not end with a? (i.e. not a query command) ask_binary(scpi_string) A convenience function for calling write() and read_binary() consecutively. Parameters scpi_string (str) A valid SCPI query command. See the instrument s SCPI command reference. Raises Exception If the SCPI command does not end with a? (i.e. not a query command) ask_ieee754(scpi_string) A convenience function for calling write() and read_ieee754() consecutively. Parameters scpi_string (str) A valid SCPI query command. See the instrument s SCPI command reference. Raises Exception If the SCPI command does not end with a? (i.e. not a query command) configure(config_file) Reads from a text file containing valid SCPI commands separated by newlines to configure the instrument. Only program commands are allowed. Configures the instrument by sending those commands consecutively. Automatically sends an *OPC? command to await pending operations. Prints out those commands to standard output. Text written after a # character are considered comments. Commands in the configuration file are assumed to be valid for the instrument. Parameters config_file (str) The filename of the configuration file. Raises Exception If any of the SCPI commands contain a? (i.e. are query commands) read_ascii(bufsize=4096) Read ASCII response from instrument in chunks of bufsize bytes until a \n is encountered. Parameters bufsize (int) Defaults to 4096 bytes. Size of consecutive chunks of data to be read. Returns out Response from the instrument. Return type str read_binary() Read raw binary data from instrument. It is the developer s responsiblity to make sense of it. Returns out Response from the instrument. This is just a string of binary code. Return type str A typical use case is obtaining a screenshot of the instrument panel. The following code is for the Agilent B2902A Precision Source Measure Unit, nicknamed Yveltal. import microlab_instruments as mi yveltal = mi.yveltal() yveltal.write(':disp:enab ON') yveltal.write(':disp:view GRAP') yveltal.write(':hcop:sdum:form JPG') 2.4. Reference Manual 9

14 yveltal.ask_ascii('*opc?') yveltal.write(':hcop:sdum:data?') image_data = yveltal.read_binary() file_handle = open('screendump.jpg', 'wb') file_handle.write(image_data) file_handle.close() read_ieee754() A convenience function to read binary data known to be formatted in IEEE-754 floating-point. Internally calls read_binary() and automatically determines half-, single-, or double-precision based on the instrument s settings. Returns out A list of floating-point numbers. Return type list class microlab_instruments.base_classes.serialinstrument(device_port) Bases: object Initialize an RS-232 instrument. class microlab_instruments.base_classes.tcpipinstrument(socket_pair, reset=true) Bases: microlab_instruments.base_classes.scpiinstrument Initialize TCP/IP instrument. Parameters socket_pair (tuple) A 2-tuple of the form ( , 5025). read(bufsize=4096) Read bufsize bytes from instrument. Using this low-level function, there is no way to ensure that all the response data has been retrieved, or to make sense of binary data. It is strongly recommended to use read_ascii(), read_binary(), or read_ieee754(). Parameters bufsize (int) Defaults to 4096 bytes. Expected size in bytes of the response from the instrument. Returns out Response from the instrument. Return type str reset() Reset the instrument. write(scpi_string) Write SCPI command to the instrument. The end-of-string character (for example, \n) is automatically appended. Parameters scpi_string (str) A valid SCPI command. See the instrument s SCPI command reference. class microlab_instruments.base_classes.tempsensorinstrument(aardvark, mux) Bases: object An abstraction layer for the Sensirion STS21 temperature sensor with an I2C communication interface. Initialize a Sensirion STS21 temperature sensor. Parameters aardvark (Aardvark) An Aardvark object through which I2C commands are relayed. mux (I2CMuxInstrument) The I2C multiplexer through which I2C commands are relayed. 10 Chapter 2. Contents

15 read_temp() Read measured temperature data. Returns out Temperature in degress Celsius Return type float microlab_instruments module class microlab_instruments.microlab_instruments.arceus Bases: microlab_instruments.base_classes.gpibinstrument class microlab_instruments.microlab_instruments.chen(aardvark) Bases: microlab_instruments.base_classes.i2cmuxinstrument Initialize the I2C multiplexer. Parameters aardvark (Aardvark) An Aardvark object through which I2C commands are relayed. import microlab_instruments as mi aa = mi.aardvark() chen = mi.chen(aa) class microlab_instruments.microlab_instruments.darkrai Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.deoxys Bases: microlab_instruments.base_classes.tcpipinstrument ask_waveform_data() A convenience function to query the waveform preamble and waveform data in one call. Additionally, it also composes the (x,y) data list. Returns out A 2-column list. The first column holds the x values and the second column holds the y values. Return type list compose_waveform_xy(waveform_y, waveform_preamble) Compose the (x,y) data list according to the y data and preamble obtained from the instrument. Returns out A 2-column list. The first column holds the x values and the second column holds the y values. Return type list read_preamble() Read the waveform preamble from Deoxys. It contains the following metadata about the waveform data: Returns out Return type dict class microlab_instruments.microlab_instruments.genesect Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.giratina Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.heatran Bases: microlab_instruments.base_classes.tcpipinstrument 2.4. Reference Manual 11

16 class microlab_instruments.microlab_instruments.ho_oh Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.kerrigan(aardvark) Bases: microlab_instruments.base_classes.fpgainstrument Initialize the FPGA. Parameters aardvark (Aardvark) An Aardvark object through which I2C commands are relayed. import microlab_instruments as mi aa = mi.aardvark() kerrigan = mi.kerrigan(aa) class microlab_instruments.microlab_instruments.kyurem Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.meloetta Bases: microlab_instruments.base_classes.gpibinstrument class microlab_instruments.microlab_instruments.rayquaza Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.traxex(aardvark, mux) Bases: microlab_instruments.base_classes.tempsensorinstrument Initialize a Sensirion STS21 temperature sensor. Parameters aardvark (Aardvark) An Aardvark object through which I2C commands are relayed. import microlab_instruments as mi aa = mi.aardvark() traxex = mi.traxex(aa) print traxex.read_temp() class microlab_instruments.microlab_instruments.xerneas Bases: microlab_instruments.base_classes.gpibinstrument class microlab_instruments.microlab_instruments.xin(aardvark, mux) Bases: microlab_instruments.base_classes.tempsensorinstrument Initialize a Sensirion STS21 temperature sensor. Parameters aardvark (Aardvark) An Aardvark object through which I2C commands are relayed. import microlab_instruments as mi aa = mi.aardvark() xin = mi.xin(aa) print xin.read_temp() class microlab_instruments.microlab_instruments.yveltal Bases: microlab_instruments.base_classes.tcpipinstrument class microlab_instruments.microlab_instruments.zygarde Bases: microlab_instruments.base_classes.tcpipinstrument 12 Chapter 2. Contents

17 2.5 Contributing Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: Types of Contributions Report Bugs Report bugs at If you are reporting a bug, please include: Your operating system name and version. Any details about your local setup that might be helpful in troubleshooting. Detailed steps to reproduce the bug. Fix Bugs Look through the GitHub issues for bugs. Anything tagged with bug is open to whoever wants to implement it. Implement Features Look through the GitHub issues for features. Anything tagged with feature is open to whoever wants to implement it. Write Documentation Microlab Instruments could always use more documentation, whether as part of the official Microlab Instruments docs, in docstrings, or even on the web in blog posts, articles, and such. Submit Feedback The best way to send feedback is to file an issue at If you are proposing a feature: Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Remember that this is a volunteer-driven project, and that contributions are welcome :) Get Started! Ready to contribute? Here s how to set up microlab-instruments for local development. 1. Fork the microlab-instruments repo on GitHub. 2. Clone your fork locally: 2.5. Contributing 13

18 $ git clone 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development: $ mkvirtualenv microlab-instruments $ cd microlab-instruments/ $ python setup.py develop 4. Create a branch for local development: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox: $ flake8 microlab-instruments tests $ python setup.py test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub: $ git add. $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check and make sure that the tests pass for all supported Python versions Tips To run a subset of tests: $ python -m unittest tests.test_microlab-instruments 2.6 Credits Development Lead Kristofer Monisit <kmonisit@gmail.com> 14 Chapter 2. Contents

19 2.6.2 Contributors None yet. Why not be the first? 2.7 History ( ) First release on PyPI History 15

20 16 Chapter 2. Contents

21 CHAPTER 3 Indices and tables genindex modindex search 17

22 18 Chapter 3. Indices and tables

23 Python Module Index b base_classes, 6 m microlab_instruments.base_classes, 6 microlab_instruments.microlab_instruments, 11 19

24 20 Python Module Index

25 Index A Giratina (class in microlab_instruments.microlab_instruments), 11 AardvarkInstrument (class in microlab_instruments.base_classes), 6 GPIBInstrument (class in microlab_instruments.base_classes), 8 Arceus (class in microlab_instruments.microlab_instruments), 11 H ask_ascii() (microlab_instruments.base_classes.scpiinstrument method), 8 Heatran (class in microlab_instruments.microlab_instruments), 11 ask_binary() (microlab_instruments.base_classes.scpiinstrument method), 9 Ho_oh (class in microlab_instruments.microlab_instruments), ask_ieee754() (microlab_instruments.base_classes.scpiinstrument 11 method), 9 ask_waveform_data() (microlab_instruments.microlab_instruments.deoxys method), 11 B base_classes (module), 6 C Chen (class in microlab_instruments.microlab_instruments), 11 compose_waveform_xy() (microlab_instruments.microlab_instruments.deoxys method), 11 configure() (microlab_instruments.base_classes.scpiinstrument method), 9 D Darkrai (class in microlab_instruments.microlab_instruments), 11 Deoxys (class in microlab_instruments.microlab_instruments), 11 F FPGAInstrument (class in microlab_instruments.base_classes), 7 G Genesect (class in microlab_instruments.microlab_instruments), 11 I i2c_read() (microlab_instruments.base_classes.aardvarkinstrument method), 7 I2C_STATUS_CODES (microlab_instruments.base_classes.aardvarkinstrument attribute), 7 i2c_write() (microlab_instruments.base_classes.aardvarkinstrument method), 7 i2c_write_read() (microlab_instruments.base_classes.aardvarkinstrument method), 7 I2CMuxInstrument (class in microlab_instruments.base_classes), 8 K Kerrigan (class in microlab_instruments.microlab_instruments), 12 Kyurem (class in microlab_instruments.microlab_instruments), 12 M Meloetta (class in microlab_instruments.microlab_instruments), 12 microlab_instruments.base_classes (module), 6 microlab_instruments.microlab_instruments (module), 11 R Rayquaza (class in microlab_instruments.microlab_instruments), 12 21

26 read() (microlab_instruments.base_classes.fpgainstrument method), 8 Yveltal (class in microlab_instruments.microlab_instruments), 12 read() (microlab_instruments.base_classes.gpibinstrument method), 8 read() (microlab_instruments.base_classes.tcpipinstrumentz method), 10 Zygarde (class in microlab_instruments.microlab_instruments), 12 read_ascii() (microlab_instruments.base_classes.scpiinstrument method), 9 read_binary() (microlab_instruments.base_classes.scpiinstrument method), 9 read_ieee754() (microlab_instruments.base_classes.scpiinstrument method), 10 read_preamble() (microlab_instruments.microlab_instruments.deoxys method), 11 read_temp() (microlab_instruments.base_classes.tempsensorinstrument method), 10 reset() (microlab_instruments.base_classes.gpibinstrument method), 8 reset() (microlab_instruments.base_classes.tcpipinstrument method), 10 S SCPIInstrument (class in microlab_instruments.base_classes), 8 SerialInstrument (class in microlab_instruments.base_classes), 10 spi_write() (microlab_instruments.base_classes.aardvarkinstrument method), 7 switch_to() (microlab_instruments.base_classes.i2cmuxinstrument method), 8 T TCPIPInstrument (class in microlab_instruments.base_classes), 10 TempSensorInstrument (class in microlab_instruments.base_classes), 10 Traxex (class in microlab_instruments.microlab_instruments), 12 W write() (microlab_instruments.base_classes.fpgainstrument method), 8 write() (microlab_instruments.base_classes.gpibinstrument method), 8 write() (microlab_instruments.base_classes.tcpipinstrument method), 10 X Xerneas (class in microlab_instruments.microlab_instruments), 12 Xin (class in microlab_instruments.microlab_instruments), 12 Y 22 Index