deploy: d86b62d

main/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a30f5b232d9fb3e8970f66bc7d3afb1f
+config: bda5522d97de56817f861757d7785f80
 tags: 645f666f9bcd5a90fca523b33c5a78b7

main/_downloads/479ab8342eb97d88724b54dbc5bb6ff8/tutorial2_position_capture-2.py

@@ -0,0 +1,2 @@
+from common.python.timing_plot import make_timing_plot
+make_timing_plot('/home/runner/work/PandABlocks.github.io/PandABlocks.github.io/docs/user/tutorials/tutorial2.timing.ini', 'Trigger Counter 5x faster', 'Milliseconds')

main/_downloads/f4b28c8d0cd34cd9868dfca21e485b81/tutorial2_position_capture-1.py

@@ -0,0 +1,2 @@
+from common.python.timing_plot import make_timing_plot
+make_timing_plot('/home/runner/work/PandABlocks.github.io/PandABlocks.github.io/docs/user/tutorials/tutorial2.timing.ini', 'Trigger Only', 'Milliseconds')

main/_sources/user/index.rst.txt

@@ -13,6 +13,9 @@ side-bar.
             :caption: Tutorials
             :maxdepth: 1
 
+            tutorials/tutorial1_blinking_leds.rst
+            tutorials/tutorial2_position_capture.rst
+
         +++
 
         Tutorials for installation and typical usage. New users start here.

main/_sources/user/tutorials/tutorial1_blinking_leds.rst.txt

@@ -0,0 +1,94 @@
+.. _blinking_leds_tutorial:
+
+Blinking LEDs Tutorial
+======================
+
+This tutorial will introduce you to the basics of PandABlocks, how to wire
+Blocks together to make different LEDs flash at different rates
+
+
+Opening the GUI
+---------------
+
+Point your web browser at the ip address or hostname of the PandA and you will
+be greeted with a welcome page. At the bottom of this page will be links for
+Docs, Control and Admin. You can use the Control link to open the Web Control
+page that we will use in these tutorials. For more information on the Web
+Control, see its entry in the Docs section.
+
+
+Loading the tutorial design
+---------------------------
+
+The Design dropdown box allows you to select from saved designs stored on the
+PandA. Selecting an item from this list will load the saved design over the
+current Block settings. You can use the Save method to save your current
+design if you wish to keep it.
+
+Select "template_tutorial1_leds" from the box and the settings and wiring of
+the Blocks in the PandA will be changed to the following:
+
+.. image:: ../../images/tutorial1_layout.png
+
+If you now look at the front panel of the PandA you should see the first 4
+TTL output LEDs turn on sequentially, then turn off in the opposite order.
+
+
+How the design works
+--------------------
+
+The CLOCKS Block is creating a 50% duty cycle pulse train with a period of 1s.
+PULSE1..4 are taking this as an input trigger, and producing a different width
+pulse with a different delay for each PULSE Block. These PULSE Blocks work as a
+delay line, queuing a series of pulses up to be sent out when the delay expires.
+
+If you click on one of them you can see its settings:
+
+.. image:: ../../images/tutorial1_pulse.png
+
+If you increase the delay beyond the 1s period you will notice that the
+``Queued`` field will increase, but the PULSE Block will still continue
+outputting pulses after the desired delay. However if you increase the width
+beyond the pulse period the Block will drop the pulse, reporting it via the
+``Dropped`` field. This is so it avoids merging them together.
+
+You can also try clicking on the CLOCKS Block to modify the period of the input
+pulse train.
+
+You can also try wiring these outputs to different TTLOUT Blocks by clicking
+the Palette icon, dragging a TTLOUT Block onto the canvas, and connecting it
+up by dragging the PULSE out port to the TTLOUT val port.
+
+
+The Bit Bus
+-----------
+
+All ports on the visible Blocks are blue. They represent bits, single boolean
+values that can propagate through the system by connecting Blocks together.
+These outputs can be viewed on their respective Blocks by clicking them on the
+design, or all together by clicking the Bits field in the left hand pane:
+
+.. image:: ../../images/tutorial1_bits.png
+
+If you scroll down to the section with the Pulse blocks you will see the
+same pattern of flashing lights as on the front of the PandA
+
+.. note::
+
+    The web GUI polls the PandA at 10Hz, receiving the current value of each bit
+    and whether it has changed. The web GUI uses this information to reflect the
+    current value of each bit if pulsing at less than 5Hz, and displaying a 5Hz
+    pulsing value if faster than 5Hz. This means that you will see even short
+    pulses reflected on the web GUI. The front panel LEDs have a similar
+    behaviour but with a maximum rate of 10Hz.
+
+
+Conclusion
+----------
+
+This tutorial has shown how to load a saved design and modify some parameters.
+It has also introduced the PULSE delay block that is useful for delaying and
+stretching trigger signals. It has introduced bit outputs and shown how they
+can be connected to the outside world using the TTLOUT Blocks. In the next
+tutorial we will read about position outputs, how they can be set and how they
+can be captured.

main/_sources/user/tutorials/tutorial2_position_capture.rst.txt

@@ -0,0 +1,208 @@
+.. _position_capture_tutorial:
+
+Position Capture Tutorial
+=========================
+
+This tutorial will introduce you to the Position Capture interface of
+PandABlocks, how to provide trigger signals to control when these capture points
+are taken and visualize the data.
+
+
+Loading the tutorial design
+---------------------------
+
+Select "template_tutorial2_pcap" from the Design dropdown box and the settings
+and wiring of the Blocks in the PandA will be changed to the following:
+
+.. image:: ../../images/tutorial2_layout.png
+
+
+How the design works
+--------------------
+
+This design has two CLOCK Blocks, which are enabled as soon as the PCAP Block
+becomes active:
+
+- The first CLOCK is wired to PCAP trigger and gate. The gate is a level driven
+  signal that provides the window of time that a capture should be active over.
+  The trigger is an edge driven signal that actually captures data. In this
+  example, PCAP.TRIG_EDGE="Falling" so capture will be triggered on a falling
+  edge of the trigger.
+- The second CLOCK is wired to a COUNTER, triggering the increment of the
+  counter value.
+
+We start off with both CLOCK Blocks set to a period of 1s, so each second the
+COUNTER will increment by one, followed by a PCAP trigger half a second later.
+This is best viewed as a timing diagram:
+
+.. timing_plot::
+   :path: docs/user/tutorials/tutorial2.timing.ini
+   :section: Trigger Only
+   :xlabel: Milliseconds
+
+What PCAP does on that trigger is determined by the PCAP Block settings, and
+the contents of the Bits and Positions tables. For Bits you can turn capture
+(instantaneous at the time of trigger) on and off. For Positions, you have a
+choice of:
+
+============== =======================
+Capture        Description
+-------------- -----------------------
+No             Don't capture
+Value          Instantaneous capture at time of trigger
+Diff           The difference in the value while gate was high
+Sum            The sum of all the samples while gate was high
+Min            The smallest value seen while gate was high
+Max            The largest value seen while gate was high
+Mean           The average value seen while gate was high
+Min Max        Capture both Min and Max
+Min Max Mean   Capture Min Max and Mean
+============== =======================
+
+There are also a handful of other fields like the start of frame, end of frame
+and trigger time that can be captured by setting fields on the PCAP Block. If
+you click on the PCAP Block you will see them in the Outputs section:
+
+.. image:: ../../images/tutorial2_pcap.png
+
+In the inputs section of the PCAP Block we can see that we have set a delay of
+1 for both the Trig and Gate. Delays on bit inputs are in FPGA clock ticks, and
+are there to compensate for different length data paths that need to be aligned.
+Each Block and each wire in PandA take 1 clock tick each. In this example, both
+COUNTER1 and PCAP are being triggered by a CLOCK in the same clock tick, but
+we want to delay the input to PCAP by one clock tick so that it sees the updated
+COUNTER1 value *after* the corresponding CLOCK rising edge.
+
+.. note::
+
+   The delay fields of the PCAP Block are also shown as small badges on the
+   input ports of the Block
+
+We can set COUNTER1.OUT to capture the Value at trigger by modifying the
+Positions table and pressing Submit:
+
+.. image:: ../../images/tutorial2_positions.png
+
+Now we can get a client ready to receive data. We can capture data in ASCII or
+Binary format as detailed in the TCP server documentation, and TANGO and EPICS
+have clients to do this. For this tutorial we will just use the ASCII format on
+the commandline to check::
+
+   $ nc <panda-ip> 8889
+
+Here we could specify binary output and header format, but we'll just stick
+with the default ASCII output (the default). Press Return again, and we will
+see::
+
+   OK
+
+Now go back to the PandA layout and select the PCAP Block, pressing the ARM
+button. The Active light will go on and data will start streaming in the
+terminal window until Disarm is pressed::
+
+   missed: 0
+   process: Scaled
+   format: ASCII
+   fields:
+    COUNTER1.OUT double Value scale: 1 offset: 0 units:
+
+    1
+    2
+    3
+    4
+   END 4 Disarmed
+
+This tallies with the timing diagram we saw above, the captured value matches
+the instantaneous value of COUNTER1.OUT when PCAP.TRIG went high.
+
+We will now make the COUNTER1.OUT increment 5 times faster. Set CLOCK2.PERIOD
+to 0.2s, and click PCAP.ARM and you will see the captured value change::
+
+   missed: 0
+   process: Scaled
+   format: ASCII
+   fields:
+    COUNTER1.OUT double Value scale: 1 offset: 0 units:
+
+    3
+    8
+    13
+    18
+   END 4 Disarmed
+
+If we look at the timing plot, we can see this also matched what we expect, the
+value is captured mid way through each increment of 5:
+
+.. timing_plot::
+   :path: docs/user/tutorials/tutorial2.timing.ini
+   :section: Trigger Counter 5x faster
+   :xlabel: Milliseconds
+
+Now let's investigate the other options. If we change the Positions table
+so COUNTER1.OUT captures the Diff instead of Value then we will see it captures
+the difference between the value at the rising edge of the gate, and the
+falling edge::
+
+   missed: 0
+   process: Scaled
+   format: ASCII
+   fields:
+    COUNTER1.OUT double Diff scale: 1 offset: 0 units:
+
+    2
+    2
+    2
+    2
+   END 4 Disarmed
+
+This again matches the timing plot, GATE rises when COUNTER was at 1, and falls
+at 3, then rises at 6 and falls at 8.
+
+.. note::
+
+   If we hadn't put in the 1 clock tick delays for Gate and Trig then we would
+   see 3 rather than 2, as GATE would rise at 0 and fall at 3, then rise at 5
+   and fall at 8
+
+This capture output is generally used with COUNTER Blocks connected to an input
+fed from a V2F_ to capture the total counts produced in a given time window.
+
+If we change COUNTER1.OUT to capture Min Max and Mean, we will see the other
+options::
+
+   missed: 0
+   process: Scaled
+   format: ASCII
+   fields:
+    COUNTER1.OUT double Min scale: 1 offset: 0 units:
+    COUNTER1.OUT double Max scale: 1 offset: 0 units:
+    COUNTER1.OUT double Mean scale: 1 offset: 0 units:
+
+    1 3 1.8
+    6 8 6.8
+    11 13 11.8
+    16 18 16.8
+   END 4 Disarmed
+
+Here we can see our min and max values as we expected, and also the Mean of
+the COUNTER value during the total gate::
+
+   # (sum of counter_value * time_at_value) / gate_time = mean
+   (1 * 0.2 + 2 * 0.2 + 3 * 0.1) / 0.5 = 1.8
+   (6 * 0.2 + 7 * 0.2 + 8 * 0.1) / 0.5 = 6.8
+
+This capture output is generally used with encoders, to give the min, max and
+mean value of the encoder over a detector frame.
+
+Conclusion
+----------
+
+This tutorial has shown how to use the Position Capture interface of a PandA
+to capture entries on the position bus, and introduced the different capture
+types. It has also introduced the COUNTER block that is useful connecting to
+the pulse train produced by a V2F_. In the next tutorial we will read about
+how to use position compare to generate triggers from position outputs, and
+how to configure position capture to work with it.
+
+
+.. _V2F: https://hal.archives-ouvertes.fr/hal-01573024/document

main/_static/documentation_options.js

@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '3.1.dev1+g7c4ec5e',
+    VERSION: '3.1.dev2+gd86b62d',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

main/_static/plot_directive.css

@@ -0,0 +1,16 @@
+/*
+ * plot_directive.css
+ * ~~~~~~~~~~~~
+ *
+ * Stylesheet controlling images created using the `plot` directive within
+ * Sphinx.
+ *
+ * :copyright: Copyright 2020-* by the Matplotlib development team.
+ * :license: Matplotlib, see LICENSE for details.
+ *
+ */
+
+img.plot-directive {
+    border: 0;
+    max-width: 100%;
+}