Add generic "Create marker here" context menu entry
[pulseview.git] / manual / acquisition.txt
1 == Data Acquisition
2
3 Working with PulseView follows a pattern:
4
5 image::pv_nodevice.png[]
6 <1> Open a new session
7 <2> Select the device you want to work with:
8 <3> Click "Run" to acquire signal data (waiting for a trigger first if you set one)
9
10 When you start PulseView and no sessions are restored from the last time you used it, it will
11 come up with a session that has the demo device selected. That way, you can get to know the
12 program even when you don't have any hardware to use it with.
13
14 === Device Selection
15
16 The device selector offers two methods to choose the device to use. If you click on the small
17 arrow on the side, you see a list of devices PulseView has recognized. If the device you want
18 to use it listed, you can just select it here to use it.
19
20 image::device_selector_dropdown.png[]
21
22 If it's not listed, you'll need to scan for it first. Since most serial port and Ethernet
23 devices can't be auto-detected, this is usually required for those.
24 To do so, either choose the "Connect to Device" option from the list or click on the button
25 itself. You will see the following dialog:
26
27 image::device_selector_scan.png[]
28
29 First, you'll need to pick a driver that you want to use. In order to do this, you'll need
30 to know which driver is used to talk to the device. If you're unsure, you can either try the
31 driver which you think may fit best or you can check the wiki. For every supported device there's
32 a wiki page, showing you which driver is used.
33
34 Once the driver has been chosen, you need to select the interface. Please be aware that USB
35 is only usable for devices that directly communicate over USB. Devices that use USB to emulate
36 a serial port (like the OpenBench Logic Sniffer) will have their serial port listed in the
37 serial port drop-down.
38
39 In case your device connects via Ethernet, you must supply the IP address and port. You are
40 also given the option to choose between raw TCP access and using the VXI protocol. VXI is an
41 industry standard which is mainly used in professional equipment and the device will most
42 likely let you know that it supports VXI. If your device however is more of a hobbyist grade
43 device, it's more likely that using raw TCP will be the correct choice.
44
45 After you selected the appropriate options, clicking the scan button will make PulseView try
46 to connect to the device with the given settings. If successful, any device(s) found will be
47 shown in the list box.
48
49 [NOTE]
50 When a session uses a USB device and you close Pulseview, a session with that same device
51 is re-opened when you start Pulseview again. Currently, this is however not the case for non-USB
52 devices, such as ones that connect via serial port or Ethernet.
53
54 [NOTE]
55 To avoid having to manually enter the device configuration for a serial port or Ethernet
56 device every time you want to use it and then having to scan for it, you can also use the
57 command line parameter -d to have PulseView scan for it on startup.
58
59 You may then change the device configuration and/or start the data acquisition by clicking
60 the "Run" button on the top left.
61
62 When you run the acquisition, you'll notice that the newly captured data goes off-screen.
63 This is to improve performance and let PulseView acquire the data without bogging down your
64 CPU too much. If you find this inconvenient because you'd like to see what kind of data is
65 coming in, you have three options:
66
67 * Enable "always perform zoom-to-fit" temporarily (see chapter "Data Analysis")
68 * Enable "constantly perform zoom-to-fit during acquisition" in the options
69 * Enable "always keep newest samples at the right edge during capture" in the options
70
71 Which method suits you best is up for you to decide.
72
73 === Device Configuration
74
75 In PulseView, the device configuration is done using these buttons:
76
77 image::pv_device_config.png[]
78 <1> Device-specific settings
79 <2> Channel-specific settings
80 <3> Number of samples to capture
81 <4> Sample rate at which to capture the samples
82 <5> Per-channel trigger setting (see below)
83
84 The values offered for those four elements depend on your device. Which settings you should choose
85 depends on several factors: the needs of your measurement, the device you use to capture the data
86 and the capabilities of your computer.
87
88 The sample rate you choose must at least be twice that of the highest frequency you want to
89 capture - ideally 3 to 5 times as much so that you have some margin. That way, a jittering signal
90 won't ruin your measurements.
91
92 [NOTE]
93 If you're using a device with a Cypress FX2 (most 8 channel / 24 MHz logic analyzers do) then you should
94 be aware that the 24 MHz sampling rate (12 MHz for 16 channels) can only be sustained under perfect
95 conditions. Usually, those devices are shipped with low-quality USB cables, impairing USB transfers as
96 USB traffic increases. Therefore, you can try a different USB cable if you're facing issues at higher
97 sample rates. If they persist, it's worth trying a different USB port as well.
98
99 === Triggers
100
101 The signal labels on the left side of the view (D0, D1 and so on in the picture above) allow you to
102 configure certain aspects of these signals. If the device supports it then the trigger that will be
103 used for this signal will be among them.
104
105 As of now, the trigger system is awaiting extension for advanced and complex trigger types, meaning
106 that the only triggers available to you are:
107
108 * Trigger when the signal has a "low" level
109 * Trigger when the signal has a "high" level
110 * Trigger when the signal switches from "low" to "high" level (rising edge)
111 * Trigger when the signal switches from "hig" to "low" level (falling edge)
112 * Trigger when the signal changes level in any way (any edge)
113
114 Once you choose a trigger, the icon for the type you chose becomes visible on the right side of the
115 trace view.
116
117 When you click "Run" with a trigger configured, PulseView will wait for the device to trigger and
118 send data before it can show anything. There is currently no frame limit, so if the device driver
119 supports it, PulseView will continue arming the trigger and collecting data until you either click
120 "Stop" or it runs out of memory.
121
122 === Channel Groups
123
124 Some devices share certain settings between a group of channels, which is why PulseView may show
125 the channels your device offers in groups. You can see which channels are grouped by looking at the
126 dark gray bar on the left. If there is none, no channels are grouped.
127
128 Currently, the grouping is only done for your convenience and there's no direct functional impact.
129 This means that you're free to ungroup and group channels as you please. To do so, right-click
130 on the dark gray bar and select "Ungroup".
131 If you want to create a new group, select the signals you want to group by holding down CTRL
132 and clicking on the signal labels. Once you have selected the ones you want to be grouped,
133 right-click on one of the labels you selected and choose "Group".
134