artiq/doc/manual/installing.rst

210 lines
9.9 KiB
ReStructuredText
Raw Normal View History

.. _install-from-conda:
2014-09-28 23:25:32 +08:00
Installing ARTIQ
================
The preferred way of installing ARTIQ is through the use of the conda package manager.
The conda package contains pre-built binaries that you can directly flash to your board.
.. warning::
2016-04-09 23:57:43 +08:00
NIST users on Linux need to pay close attention to their ``umask``.
The sledgehammer called ``secureconfig`` leaves you (and root) with umask 027 and files created by root (for example through ``sudo make install``) inaccessible to you.
The usual umask is 022.
2016-04-09 23:57:43 +08:00
2016-02-11 06:37:21 +08:00
.. warning::
2017-09-29 23:14:21 +08:00
Conda packages are supported for Linux (64-bit) and Windows (64-bit).
Users of other operating systems (32-bit Linux or Windows, BSD, OSX ...) should and can :ref:`install from source <install-from-source>`.
2016-02-11 06:37:21 +08:00
.. _install-anaconda:
2016-02-11 06:37:21 +08:00
Installing Anaconda or Miniconda
--------------------------------
2016-04-09 23:57:43 +08:00
You can either install Anaconda (choose Python 3.5) from https://store.continuum.io/cshop/anaconda/ or install the more minimalistic Miniconda (choose Python 3.5) from http://conda.pydata.org/miniconda.html
2016-04-09 23:57:43 +08:00
After installing either Anaconda or Miniconda, open a new terminal (also known as command line, console, or shell and denoted here as lines starting with ``$``) and verify the following command works::
$ conda
2016-04-09 23:57:43 +08:00
Executing just ``conda`` should print the help of the ``conda`` command [1]_.
2016-03-01 00:19:50 +08:00
Installing the ARTIQ packages
-----------------------------
.. note::
On a system with a pre-existing conda installation, it is recommended to update conda to the latest version prior to installing ARTIQ.
First add the conda-forge repository containing ARTIQ dependencies to your conda configuration::
$ conda config --prepend channels http://conda.anaconda.org/conda-forge/label/main
Then add the M-Labs ``main`` Anaconda package repository containing stable releases and release candidates::
$ conda config --prepend channels http://conda.anaconda.org/m-labs/label/main
2016-03-01 00:19:50 +08:00
.. note::
2016-03-31 16:26:53 +08:00
To use the development versions of ARTIQ, also add the ``dev`` label (http://conda.anaconda.org/m-labs/label/dev).
2016-04-09 23:57:43 +08:00
Development versions are built for every change and contain more features, but are not as well-tested and are more likely to contain more bugs or inconsistencies than the releases in the ``main`` label.
2016-04-09 23:57:43 +08:00
Then prepare to create a new conda environment with the ARTIQ package and the matching binaries for your hardware:
choose a suitable name for the environment, for example ``artiq-main`` if you intend to track the main label, ``artiq-3`` for the 3.x release series, or ``artiq-2016-04-01`` if you consider the environment a snapshot of ARTIQ on 2016-04-01.
2016-04-09 23:57:43 +08:00
Choose the package containing the binaries for your hardware:
2016-04-09 23:57:43 +08:00
* ``artiq-kc705-nist_clock`` for the KC705 board with the NIST "clock" FMC backplane and AD9914 DDS chips.
2016-04-10 21:01:00 +08:00
* ``artiq-kc705-nist_qc2`` for the KC705 board with the NIST QC2 FMC backplane and AD9914 DDS chips.
2016-04-09 23:57:43 +08:00
2016-04-10 11:17:45 +08:00
Conda will create the environment, automatically resolve, download, and install the necessary dependencies and install the packages you select::
2015-10-30 09:18:42 +08:00
$ conda create -n artiq-main artiq-kc705-nist_clock
2015-10-30 09:18:42 +08:00
2016-04-09 23:57:43 +08:00
After the installation, activate the newly created environment by name.
On Unix::
2015-10-30 09:18:42 +08:00
2016-04-09 23:57:43 +08:00
$ source activate artiq-main
2016-04-09 23:57:43 +08:00
On Windows::
2016-03-01 00:19:50 +08:00
2016-04-09 23:57:43 +08:00
$ activate artiq-main
2016-03-01 00:19:50 +08:00
2016-04-09 23:57:43 +08:00
This activation has to be performed in every new shell you open to make the ARTIQ tools from that environment available.
.. note::
Some ARTIQ examples also require matplotlib and numba, and they must be installed manually for running those examples. They are available in conda.
2016-04-09 23:57:43 +08:00
Upgrading ARTIQ
---------------
2015-10-30 09:18:42 +08:00
2016-04-09 23:57:43 +08:00
When upgrading ARTIQ or when testing different versions it is recommended that new environments are created instead of upgrading the packages in existing environments.
Keep previous environments around until you are certain that they are not needed anymore and a new environment is known to work correctly.
2016-04-10 11:17:45 +08:00
You can create a new conda environment specifically to test a certain version of ARTIQ::
2015-10-30 09:18:42 +08:00
$ conda create -n artiq-test-1.0rc2 artiq-kc705-nist_clock=1.0rc2
2015-10-30 09:18:42 +08:00
2016-04-09 23:57:43 +08:00
Switching between conda environments using ``$ source deactivate artiq-1.0rc2`` and ``$ source activate artiq-1.0rc1`` is the recommended way to roll back to previous versions of ARTIQ.
You can list the environments you have created using::
2015-10-30 09:18:42 +08:00
$ conda env list
2016-04-09 23:57:43 +08:00
See also the `conda documentation <http://conda.pydata.org/docs/using/envs.html>`_ for managing environments.
2016-03-31 16:25:39 +08:00
2014-09-28 23:25:32 +08:00
Preparing the core device FPGA board
------------------------------------
2016-04-09 23:57:43 +08:00
You now need to write three binary images onto the FPGA board:
1. The FPGA gateware bitstream
2. The BIOS
3. The ARTIQ runtime
2016-04-09 23:57:43 +08:00
They are all shipped in the conda packages, along with the required flash proxy gateware bitstreams.
2016-03-01 00:19:50 +08:00
.. _install-openocd:
Installing OpenOCD
^^^^^^^^^^^^^^^^^^
OpenOCD can be used to write the binary images into the core device FPGA board's flash memory.
The ``artiq`` or ``artiq-dev`` conda packages install ``openocd`` automatically but it can also be installed explicitly using conda on both Linux and Windows::
$ conda install openocd
.. _setup-openocd:
Configuring OpenOCD
^^^^^^^^^^^^^^^^^^^
Some additional steps are necessary to ensure that OpenOCD can communicate with the FPGA board.
On Linux, first ensure that the current user belongs to the ``plugdev`` group (i.e. `plugdev` shown when you run `$ groups`). If it does not, run ``sudo adduser $USER plugdev`` and relogin. If you installed OpenOCD using conda and are using the conda environment ``artiq-main``, then execute the statements below. If you are using a different environment, you will have to replace ``artiq-main`` with the name of your environment::
$ sudo cp ~/.conda/envs/artiq-main/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
$ sudo udevadm trigger
if you installed it from source:: Assuming you installed OpenOCD in ``/usr/local``, otherwise please substitute the install directory::
$ sudo cp /usr/local/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
$ sudo udevadm trigger
On Windows, a third-party tool, `Zadig <http://zadig.akeo.ie/>`_, is necessary. Use it as follows:
1. Make sure the FPGA board's JTAG USB port is connected to your computer.
2. Activate Options → List All Devices.
3. Select the "Digilent Adept USB Device (Interface 0)" or "FTDI Quad-RS232 HS" (or similar)
device from the drop-down list.
4. Select WinUSB from the spinner list.
5. Click "Install Driver" or "Replace Driver".
You may need to repeat these steps every time you plug the FPGA board into a port where it has not been plugged into previously on the same system.
.. _flashing-core-device:
Flashing the core device
^^^^^^^^^^^^^^^^^^^^^^^^
Then, you can flash the board:
2016-04-09 23:57:43 +08:00
* For the KC705 board (selecting the appropriate hardware peripheral)::
$ artiq_flash -t kc705 -V [nist_clock/nist_qc2]
The SW13 switches also need to be set to 00001.
The next step is to flash the MAC and IP addresses to the board. See :ref:`those instructions <flash-mac-ip-addr>`.
phaser: add jesd204b rtio dds gateware: add jesd204b awg gateware: copy phaser (df3825a) dsp/tools: update satadd mixin phaser: no DDS stubs dsp: accu fix phaser: cleanup/reduce sawg: kernel support and docs sawg: coredevice api fixes sawg: example ddb/experiment phaser: add conda package examples/phaser: typo sawg: adapt tests, fix accu stb sawg: tweak dds parameters sawg: move/adapt/extend tests sawg: test phy, refactor phaser: non-rtio spi phaser: target cli update phaser: ad9154-fmc-ebz pins phaser: reorganize fmc signal naming phaser: add test mode stubs phaser: txen is LVTTL phaser: clk spi xfer test phaser: spi for ad9154 and ad9516 phaser: spi tweaks ad9154: add register map from ad9144.xml ad9516: add register map from ad9517.xml and manual adaptation ad9154_reg: just generate getter/setter macros as well ad9154: reg WIP ad9154: check and fix registers kc705: single ended rtio_external_clk use single ended user_sma_clk_n instead of p/n to free up one clock sma kc705: mirror clk200 at user_sma_clock_p ad9516_regs.h: fix B_COUNTER_MSB phase: wire up clocking differently needs patched misoc kc705: feed rtio_external_clock directly kc705: remove rtio_external_clk for phaser phaser: spi tweaks ad9516: some startup ad9516_reg fixes phaser: setup ad9516 for supposed 500 MHz operation ad9516: use full duplex spi ad9154_reg: add CONFIG_REG_2 ad9154_reg: fixes phaser: write some ad9154 config ad9154_reg: fixes ad9154: more init, and human readable setup ad9154/ad9516: merge spi support ad9154: status readout Revert "kc705: remove rtio_external_clk for phaser" This reverts commit d500288bb44f2bf2eeb0c2f237aa207b0a8b1366. Revert "kc705: feed rtio_external_clock directly" This reverts commit 8dc7825519e3e75b7d3d29c9abf10fc6e3a8b4c5. Revert "phase: wire up clocking differently" This reverts commit ad9cc450ffa35abb54b0842d56f6cf6c53c6fbcc. Revert "kc705: mirror clk200 at user_sma_clock_p" This reverts commit 7f0dffdcdd28e648af84725682f82ec6e5642eba. Revert "kc705: single ended rtio_external_clk" This reverts commit a9426d983fbf5c1cb768da8f1da26d9b7335e9cf. ad9516: 2000 MHz clock phaser: test clock dist phaser: test freqs ad9154: iostandards phaser: drop clock monitor phaser: no separate i2c phaser: drive rtio from refclk, wire up sysref phaser: ttl channel for sync ad9154: 4x interp, status, tweaks phaser: sync/sysref 33V banks phaser: sync/sysref LVDS_25 inputs are VCCO tolerant phaser: user input-only ttls phaser: rtio fully from refclk ad9154: reg name usage fix ad9154: check register modifications Revert "ad9154: check register modifications" This reverts commit 45121d90edf89f7bd8703503f9f317ad050f9564. ad9154: fix status code ad9154: addrinc, recal serdes pll phaser: coredevice, example tweaks sawg: missing import sawg: type fixes ad9514: move setup functions ad9154: msb first also decreasing addr phaser: use sys4x for rtio internal ref phaser: move init code to main phaser: naming cleanup phaser: cleanup pins phaser: move spi to kernel cpu phaser: kernel support for ad9154 spi ad9154: add r/w methods ad9154: need return annotations ad9154: r/w methods are kernels ad9154_reg: portable helpers phaser: cleanup startup kernel ad9154: status test ad9154: prbs test ad9154: move setup, document phaser: more documentation
2016-07-22 21:56:09 +08:00
.. _configuring-core-device:
Configuring the core device
---------------------------
This should be done after either installation method (conda or source).
* (optional) If you are using DRTIO and the default routing table (for a star topology) is not suitable to your needs, prepare the routing table and add it to the ``flash_storage.img`` created in the next step. The routing table can be easily changed later, so you can skip this step if you are just getting started and only want to test local channels. See :ref:`Using DRTIO <using-drtio>`.
.. _flash-mac-ip-addr:
* Set the MAC and IP address in the :ref:`core device configuration flash storage <core-device-flash-storage>` (see above for the ``-t`` and ``-V`` options to ``artiq_flash`` that may be required): ::
2017-01-25 06:25:21 +08:00
$ artiq_mkfs flash_storage.img -s mac xx:xx:xx:xx:xx:xx -s ip xx.xx.xx.xx
$ artiq_flash -t [board] -V [adapter] -f flash_storage.img storage start
* (optional) Flash the idle kernel
2017-01-25 06:25:21 +08:00
The idle kernel is the kernel (some piece of code running on the core device) which the core device runs whenever it is not connected to a PC via Ethernet.
This kernel is therefore stored in the :ref:`core device configuration flash storage <core-device-flash-storage>`.
To flash the idle kernel:
* Compile the idle experiment:
The idle experiment's ``run()`` method must be a kernel: it must be decorated with the ``@kernel`` decorator (see :ref:`next topic <connecting-to-the-core-device>` for more information about kernels).
Since the core device is not connected to the PC, RPCs (calling Python code running on the PC from the kernel) are forbidden in the idle experiment.
::
$ artiq_compile idle.py
* Write it into the core device configuration flash storage: ::
$ artiq_coremgmt config -f idle_kernel idle.elf
.. note:: You can find more information about how to use the ``artiq_coremgmt`` utility on the :ref:`Utilities <core-device-management-tool>` page.
* (optional) Flash the startup kernel
The startup kernel is executed once when the core device powers up. It should initialize DDSes, set up TTL directions, etc. Proceed as with the idle kernel, but using the ``startup_kernel`` key in the ``artiq_coremgmt`` command.
For DRTIO systems, the startup kernel should wait until the desired destinations (including local RTIO) are up, using :meth:`artiq.coredevice.Core.get_rtio_destination_status`.
* (optional) Select the RTIO clock source
Some core devices may use either an external clock signal or their internal clock. The clock is selected at power-up. Use one of these commands: ::
$ artiq_coremgmt config write -s rtio_clock i # internal clock (default)
$ artiq_coremgmt config write -s rtio_clock e # external clock
2016-04-09 23:57:43 +08:00
.. rubric:: Footnotes
.. [1] [Linux] If your shell does not find the ``conda`` command, make sure that the conda binaries are in your ``$PATH``:
If ``$ echo $PATH`` does not show the conda directories, add them: execute ``$ export PATH=$HOME/miniconda3/bin:$PATH`` if you installed conda into ``~/miniconda3``.