doc: Management expansion, suggested edits

doc/manual/getting_started_core.rst

@@ -213,7 +213,7 @@ When using :mod:`~artiq.frontend.artiq_run`, the recorded buffer data can be ext
 .. note::
     The first time this command is run, it will retrieve the entire contents of the analyzer buffer, which may include every experiment you have run so far. For a more manageable introduction, run the analyzer once to clear the buffer, run the experiment, and then run the analyzer a second time, so that only the data from this single experiment is displayed.
 
-This will produce a list of the exact output events submitted to RTIO, printed in chronological order, along with the state of both ``now_mu`` and ``rtio_counter_mu``. While useful in diagnosing some specific gateware errors (in particular, :ref:`sequencing issues <sequence-errors>`), it isn't the most readable of formats. An alternate is to export to VCD, which can be viewed using third-party tools such as GtkWave. Run the experiment again, and use a command in the form of: ::
+This will produce a list of the exact output events submitted to RTIO, printed in chronological order, along with the state of both ``now_mu`` and ``rtio_counter_mu``. While useful in diagnosing some specific gateware errors (in particular, :ref:`sequencing issues <sequence-errors>`), it isn't the most readable of formats. An alternate is to export to VCD, which can be viewed using third-party tools such as GTKWave. Run the experiment again, and use a command in the form of: ::
 
     $ artiq_coreanalyzer -w <file_name>.vcd
 
@@ -221,7 +221,9 @@ The ``<file_name>.vcd`` file should be immediately created and written. Check th
 
 .. tip::
 
-    To view e.g. RTIO slack in GtkWave, drag the ``rtio_slack`` signal into the 'Signals' dock, under ``Time``. By default, the data will be presented in a raw form which you will probably not find particularly useful. For RTIO slack in particular, left-click, select ``Data Format > BitsToReal``, then ``Data Format > Analog``, to see a stepped waveform like that which the dashboard displays. Note also that the 'Waves' dock timescale is probably zoomed in very far; you may need to zoom out by some distance to see the effects of your experiment.
+    Tutorials on GTKWave options (or other third-party tools) and how best to view VCD files can be found online. By default, the data in a trace like ``rtio_slack`` will probably be presented in a raw form. To see a stepped wave as in the ARTIQ dashboard, look for options to interpret the data as a real number, then as an analog signal.
+
+    Pay attention to the timescale of the waveform dock in your chosen viewer; if you have set your signals to display but nothing is visible, it may be zoomed in or out much too far.
 
 The easiest way to view recorded analyzer data, however, is directly in the ARTIQ dashboard, a feature which will be presented later in :ref:`interactivity-waveform`.
 

doc/manual/main_frontend_tools.rst

@@ -62,7 +62,7 @@ These are the top-level commands used to run and manage ARTIQ experiments. Not a
 
 .. automodule:: artiq.frontend.artiq_session
 
-ARTIQ session manager. Automatically runs the master, dashboard and local controller manager on the current machine. The latter requires the ``artiq-comtools`` package to be installed. Requires access to device database, for the sake of the master.
+ARTIQ session manager. Automatically runs the master, dashboard and local controller manager on the current machine. The latter requires the ``artiq-comtools`` package to be installed.
 
 When supplying arguments to individual front-end tools, use ``=`` to avoid ambiguity in argument parsing, e.g.: ::
 
@@ -81,7 +81,7 @@ and so on.
 
 .. automodule:: artiq_comtools.artiq_ctlmgr
 
-ARTIQ controller manager. Supplied in the separate package ``artiq-comtools``, which is included with a standard ARTIQ installation but can also be `installed standalone <https://github.com/m-labs/artiq-comtools>`_, with the intention of making it easier to run controllers and controller managers on machines where a full ARTIQ installation may not be necessary or convenient. Requires the master to be running.
+ARTIQ controller manager. Supplied in the separate package ``artiq-comtools``, which is included with a standard ARTIQ installation but can also be `installed standalone <https://github.com/m-labs/artiq-comtools>`_, with the intention of making it easier to run controllers and controller managers on machines where a full ARTIQ installation may not be necessary or convenient.
 
 .. argparse::
    :ref: artiq_comtools.artiq_ctlmgr.get_argparser

doc/manual/using_data_interfaces.rst

@@ -5,7 +5,7 @@ Beyond running single experiments, or basic use of master, client, and dashboard
 
 .. note::
 
-    This page follows up directly on :doc:`getting_started_mgmt`, but discusses a broader range of features, most of which continue to rest on the foundation of the management system. Some sections (datasets, the browser) are still possible to try out using your PC alone; others (MonInj, the RTIO analyzer) are only meaningful in relation to some kind of real-time hardware.
+    This page follows up directly on :doc:`getting_started_mgmt`, but discusses a broader range of features, most of which continue to rest on the foundation of the management system. Some sections (datasets, the browser) are still possible to try out using your PC alone; others (MonInj, the RTIO analyzer) are only meaningful in relation to real-time hardware.
 
 .. _mgmt-datasets:
 
@@ -83,7 +83,7 @@ Notably, the browser does not merely act as an HD5 viewer, but also allows the u
 Non-RTIO devices and the controller manager
 -------------------------------------------
 
-As described in :doc:`rtio`, there are two classes of equipment a laboratory typically finds itself needing to operate. So far, we have largely discussed ARTIQ in terms of one only: the kind of specialized hardware that requires the very high-resolution timing control ARTIQ provides. The other class comprises the broad range of regular, "slow" laboratory devices, which do *not* require nanosecond precision and can generally be operated perfectly well from a regular PC over a non-realtime channel such as USB.
+As described in :doc:`rtio`, there are two classes of equipment a laboratory typically finds itself needing to operate. So far, we have largely discussed ARTIQ in terms of one only: specialized hardware which requires the very high-resolution timing control ARTIQ provides. The other class comprises the broad range of regular, "slow" laboratory devices, which do *not* require nanosecond precision and can generally be operated perfectly well from a regular PC over a non-realtime channel such as USB.
 
 To handle these "slow" devices, ARTIQ uses *controllers*, intermediate pieces of software which are responsible for the direct I/O to these devices and offer RPC interfaces to the network. By convention, ARTIQ controllers are named with the prefix ``aqctl_``. Controllers can be started and run standalone, but are generally handled through the *controller manager*, :mod:`~artiq_comtools.artiq_ctlmgr`. The controller manager in turn communicates with the ARTIQ master, and through it with clients or the GUI.
 
@@ -137,7 +137,8 @@ Command-line monitor
 
 For those peripherals which support monitoring, the command-line :mod:`~artiq.frontend.artiq_rtiomon` utility can be used to see monitor output directly in the terminal. The command-line monitor does not require or interact with the management system or even the device database. Instead, it takes the core device IP address and a channel number as parameters and communicates with the core device directly.
 
-This tool is very simple, and there is rarely any reason to prefer its use over the dashboard monitor. Nonetheless, it can be helpful for certain kinds of debugging.
+.. tip::
+    To remember which channel numbers were assigned to which peripherals, check your device database, specifically the ``channel`` field in local entries.
 
 .. _interactivity-waveform:
 
@@ -168,7 +169,7 @@ Eventually, you should be able to see the up-and-down 'square wave' pattern of t
 
 .. tip::
 
-    File options in the top left allow for saving and exporting RTIO traces and channel lists, as well as opening them from saved files.
+    File options in the top left allow for saving and exporting RTIO traces and channel lists (including to VCD), as well as opening them from saved files.
 
 RTIO logging
 ^^^^^^^^^^^^