README.devices 15.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
-------------------------------------------------------------------------------
README.devices
-------------------------------------------------------------------------------

This README contains various notes for users of libsigrok (or frontends
that are based on libsigrok) about device- and/or driver-specific issues.


Firmware
--------

Some devices supported by libsigrok need a firmware to be uploaded every time
13
the device is connected to the PC (usually via USB), before it can be used.
14

15
The default locations where libsigrok expects the firmware files are:
16

17
  $SIGROK_FIRMWARE_DIR (environment variable)
18
  $HOME/.local/share/sigrok-firmware
19
  $prefix/share/sigrok-firmware
20 21
  /usr/local/share/sigrok-firmware
  /usr/share/sigrok-firmware
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

($prefix is usually /usr/local or /usr, depending on your ./configure options)

For further information see the section below and also:

  http://sigrok.org/wiki/Firmware


Per-driver firmware requirements
--------------------------------

The following drivers/devices require a firmware upload upon connection:

 - asix-sigma: The ASIX SIGMA and SIGMA2 require various firmware files,
   depending on the settings used. These files are available from our
   'sigrok-firmware' repository/project under a license which allows us
   to redistribute them.

 - fx2lafw: Logic analyzers based on the Cypress FX2(LP) chip need the
   firmware files from the 'sigrok-firmware-fx2lafw' repository/project.
42
   The firmware is written from scratch and licensed under the GNU GPLv2+.
43

44 45
 - hantek-6xxx: Certain oscilloscopes based on the Cypress FX2(LP) chip, such
   as the Hantek 6022BE/6022BL, SainSmart DDS120, and Rocktech BM102, need the
46 47 48
   firmware files from the 'sigrok-firmware-fx2lafw' repository/project.
   The firmware is written from scratch and licensed under the GNU GPLv2+.

49 50 51 52 53
 - hantek-dso: The Hantek DSO-2090 (and other supported models of the same
   series of Hantek PC oscilloscopes) need firmware files.
   These can be extracted from the vendor's Windows drivers using a tool
   from our 'sigrok-util' repository/project.

54 55 56 57 58 59 60 61
 - lecroy-logicstudio: The LeCroy LogicStudio requires FPGA bitstream files.
   These can be extracted from the vendor's Windows software using a tool
   from our 'sigrok-util' repository/project.
   Additionally, it requires a Cypress FX2 firmware. This can be extracted
   from the vendor's Windows software using another tool. Details:

     http://sigrok.org/wiki/LeCroy_LogicStudio#Firmware

62 63 64 65 66
 - saleae-logic16: The Saleae Logic16 needs a firmware file for the
   Cypress FX2 chip in the device, as well as two FPGA bitstream files.
   These can be extracted from the vendor's Linux application using a tool
   from our 'sigrok-util' repository/project.

67 68 69 70 71 72 73 74 75
 - sysclk-lwla:

    - The Sysclk LWLA1034 requires various bitstream files.
      These files are available from our 'sigrok-firmware' repository/project
      under a license which allows us to redistribute them.

    - The Sysclk LWLA1016 requires various bitstream files.
      These can be extracted from the vendor's Windows drivers using a tool
      from our 'sigrok-util' repository/project.
76

77 78 79
The following drivers/devices do not need any firmware upload:

 - agilent-dmm
80
 - appa-55ii
81
 - arachnid-labs-re-load-pro
82
 - atten-pps3xxx
83 84
 - baylibre-acme
 - beaglelogic
85
 - brymen-bm86x
86
 - brymen-dmm
87
 - cem-dt-885x
88
 - center-3xx (including all subdrivers)
89
 - chronovu-la
90
 - colead-slm
91
 - conrad-digi-35-cpu
92 93
 - demo
 - fluke-dmm
94
 - ftdi-la
95
 - gmc-mh-1x-2x (including all subdrivers)
96
 - gwinstek-gds-800
97
 - hameg-hmo
98 99
 - hp-3457a
 - hung-chang-dso-2100
100
 - ikalogic-scanalogic2
101 102
 - ikalogic-scanaplus
 - kecheng-kc-330b
103
 - kern-scale
104
 - lascar-el-usb
105
 - link-mso19
106 107
 - manson-hcs-3xxx
 - maynuo-m97
108
 - mic-985xx (including all subdrivers)
109
 - motech-lps-30x
Uwe Hermann's avatar
Uwe Hermann committed
110
 - norma-dmm
111
 - openbench-logic-sniffer
112
 - pce-322a
magnuskarlsson's avatar
magnuskarlsson committed
113
 - pipistrello-ols
114
 - rigol-ds
115
 - scpi-pps
116
 - serial-dmm (including all subdrivers)
117
 - serial-lcr (including all subdrivers)
Uwe Hermann's avatar
Uwe Hermann committed
118
 - teleinfo
119
 - testo
120
 - tondaj-sl-814
121
 - uni-t-dmm (including all subdrivers)
122
 - uni-t-ut32x
123
 - victor-dmm
124
 - yokogawa-dlm
125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
 - zeroplus-logic-cube


Specifying serial ports
-----------------------

Many devices supported by libsigrok use serial port based cables (real RS232
or USB-to-serial ones) to connect to a PC.

For all these devices, you need to specify the serial port they are connected
to (e.g. using the 'conn' option in sigrok-cli). It is not possible to scan
for such devices without specifying a serial port.

Example:

 $ sigrok-cli --driver <somedriver>:conn=/dev/ttyUSB0 ...

The following drivers/devices require a serial port specification:

 - agilent-dmm
145
 - appa-55ii
146
 - atten-pps3xxx
147
 - brymen-dmm
148
 - cem-dt-885x
149
 - center-3xx (including all subdrivers)
150
 - colead-slm
151
 - conrad-digi-35-cpu
152
 - fluke-dmm
153
 - gmc-mh-1x-2x (including all subdrivers)
154
 - hameg-hmo
155
 - link-mso19
156
 - mic-985xx (including all subdrivers)
Uwe Hermann's avatar
Uwe Hermann committed
157
 - norma-dmm
158
 - openbench-logic-sniffer
159 160
 - rigol-ds (for RS232; not required for USBTMC or TCP)
 - serial-dmm (including all subdrivers)
161
 - serial-lcr (including all subdrivers)
Uwe Hermann's avatar
Uwe Hermann committed
162
 - teleinfo
163 164 165 166 167
 - tondaj-sl-814

The following drivers/devices do not require a serial port specification:

 - asix-sigma
168
 - brymen-bm86x
169
 - chronovu-la
170 171 172
 - demo
 - fx2lafw
 - hantek-dso
173
 - ikalogic-scanalogic2
174 175
 - ikalogic-scanaplus
 - kecheng-kc-330b
176
 - lascar-el-usb
magnuskarlsson's avatar
magnuskarlsson committed
177
 - pipistrello-ols
178
 - rigol-ds (USBTMC or TCP)
179
 - saleae-logic16
180
 - sysclk-lwla
181
 - uni-t-dmm (including all subdrivers)
182
 - uni-t-ut32x
183
 - victor-dmm
184
 - yokogawa-dlm (USBTMC or TCP)
185 186 187
 - zeroplus-logic-cube


Uwe Hermann's avatar
Uwe Hermann committed
188 189
Specifying serial port parameters
---------------------------------
190 191 192 193

Every serial device's driver has default serial port parameters like baud
rate, number of data bits, stop bits and handshake status. If a device requires
different parameters, pass them as option "serialcomm" with the driver name.
194
See libsigrok docs for the function serial_set_paramstr() for complete specs.
195 196 197 198 199 200

Example:

 $ sigrok-cli --driver <somedriver>:conn=<someconn>:serialcomm=9600/7n1/dtr=1


201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
Permissions of serial port based devices
----------------------------------------

When using devices supported by libsigrok that use serial port based cables
(real RS232 or USB-to-serial ones) to connect to a PC, you need to ensure
that the user running the libsigrok frontend has (read/write) permissions to
access the serial port device (e.g. /dev/ttyS0, /dev/ttyUSB0, and so on).

You can use 'chmod' to apply permissions as you see fit, and/or 'chown' to
change the owner of the serial port device to a certain user or group.

For USB-to-serial based devices, we recommended using our udev rules file
(see below for details).


216 217
Permissions for USB devices (udev rules files)
----------------------------------------------
218 219 220 221 222

When using USB-based devices supported by libsigrok, the user running the
libsigrok frontend (e.g. sigrok-cli) has to have (read/write) permissions
for the respective USB device.

223 224 225 226
On Linux, this is accomplished using udev rules. libsigrok ships a rules
file containing all supported devices which can be detected reliably
(generic USB-to-serial converters are omitted, as these are used for a wide
range of devices, e.g. GPS receivers, which are not handled by libsigrok).
227

228 229 230 231 232
The file is available in contrib/60-libsigrok.rules. This file just contains
the list of devices and flags these devices with ID_SIGROK="1". Access is
granted by the 61-libsigrok-plugdev.rules or 61-libsigrok-uaccess.rules files,
allowing access to members of the plugdev group or to currently logged in
users, respectively.
233 234

When using a libsigrok package from your favorite Linux distribution, the
235 236 237 238 239 240 241
files should already be installed in /usr/lib/udev/rules.d/, i.e.
60-libsigrok.rules and one of the access granting rules files. Use of
61-libsigrok-uaccess.rules is encouraged on systemd distributions.

The access policy can be locally overridden by placing appropriate rules in
/etc/udev/rules.d/, disabling or ammending the default policy. See the
udev documentation, e.g. man 7 udev, for details.
242 243

If you're building from source, you need to copy the file to the place
244 245 246
where udev will read these rules. Local rules should go to /etc/udev/rules.d.
Keep the file naming, otherwise interaction between the libsigrok rules and
rules shipped by the system will be broken.
247

248
Please consult the udev docs for details.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298


Cypress FX2 based devices
-------------------------

Devices using the Cypress FX2(LP) chip without any specific USB VID/PID will
be enumerated with VID/PID 04b4:8613 (the default for "unconfigured FX2").
These are usually "FX2 eval boards" (that can also be used as LAs, though).

On Linux, the 'usbtest' driver will usually grab such devices, and they will
thus not be usable by libsigrok (and frontends).

You can fix this by running 'rmmod usbtest' as root before using the device.


UNI-T DMM (and rebranded models) cables
---------------------------------------

UNI-T multimeters (and rebranded devices, e.g. some Voltcraft models) can
ship with different PC connectivity cables:

 - UT-D04 (USB/HID cable with Hoitek HE2325U chip, USB VID/PID 04fa:2490)
 - UT-D04 (USB/HID cable with WCH CH9325 chip, USB VID/PID 1a86:e008)
 - UT-D02 (RS232 cable)

The above cables are all physically compatible (same IR connector shape)
with all/most currently known UNI-T multimeters. For example, you can
use either of the UT-D04 USB/HID cables or the UT-D02 RS232 cable with
the UNI-T UT61D multimeter.

When using the UT-D02 RS232 cable with any of the supported UNI-T DMMs,
you have to use the respective driver with a '-ser' drivername suffix
(internally all of these models are handled by the 'serial-dmm' driver).

You also need to specify the serial port via the 'conn' option, e.g.
/dev/ttyUSB0 (attached via a USB-to-serial cable) or /dev/ttyS0 (actual
RS232 port) on Linux (see above).

Finally, the user running the frontend (e.g. sigrok-cli) also needs
permissions to access the respective serial port (see above).

Examples (sigrok-cli):

 $ sigrok-cli --driver uni-t-ut61e-ser:conn=/dev/ttyUSB0 ...
 $ sigrok-cli --driver voltcraft-vc820-ser:conn=/dev/ttyS0 ...

When using any of the UT-D04 USB/HID cables you have to use the respective
driver _without_ the '-ser' drivername suffix (internally all of these models
are handled by the 'uni-t-dmm' driver).

299 300 301 302
You also need to specify the USB vendor/device IDs of the cable.
Autodetection is not possible here, since various other products use the
USB VID/PID of those cables too, and there is no way to distinguish them.

303 304 305 306 307 308 309
Since the UT-D04 cables are USB based (but don't use a USB-to-serial chip)
there is no need to specify a serial port via 'conn', of course.
However, the user running the frontend does also need to have permissions
to access the respective USB device (see above).

Examples (sigrok-cli):

310 311
 $ sigrok-cli --driver uni-t-ut61e:conn=1a86.e008 ...
 $ sigrok-cli --driver voltcraft-vc820:conn=04fa.2490 ...
312 313 314 315 316 317


UNI-T UT-D04 cable issue on Linux
---------------------------------

The UNI-T UT-D04 cable with Hoitek HE2325U (or WCH CH9325) chip seems to have
Uwe Hermann's avatar
Uwe Hermann committed
318
a very specific problem on Linux. Apparently it requires to be put into
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
suspend (and woken up again) before it is usable. This seems to be a
Linux-only issue, Windows is not affected by this since apparently the
Windows kernel does this for every USB device, always.

Thus, if you want to use any of the UNI-T DMMs with this specific cable,
you'll have to run the following script (as root) once, every time you attach
the cable via USB. The script was written by Ralf Burger.

See also: http://erste.de/UT61/index.html

  #!/bin/bash
  for dat in /sys/bus/usb/devices/*; do
    if test -e $dat/manufacturer; then
      grep "WCH.CN" $dat/manufacturer > /dev/null && echo auto > ${dat}/power/level && echo 0 > ${dat}/power/autosuspend
    fi
  done


337 338 339 340 341 342 343 344
Enabling multimeter / data logger measurement output
----------------------------------------------------

Some multimeters or data loggers will not start outputting measurement data
unless a certain action has been performed by the user beforehand. This is
usually mentioned in the vendor manual of the respective device, but here's
a short list for convenience:

345 346
 - BBC Goertz Metrawatt M2110: Briefly press the "Start/Reset" button on the
   interface panel on top.
347
 - Digitek DT4000ZC: Briefly press the "RS232" button.
348
 - Gossen Metrawatt Metrahit 1x/2x devices, driver gmc-mh-1x-2x-rs232:
349 350
   - Power on the device with the "DATA" button pressed.
   - Metrahit 2x devices must be configured for the respective interface type.
351
 - Gossen Metrawatt Metrahit 2x devices, driver gmc-mh-2x-bd232:
352 353 354 355 356 357 358
   - 'BD232' interface:
      The multimeter must be configured for the respective interface type.
   - 'SI232-II' interface ("PC Mode"):
      The multimeter must be configured for interface type 'BD232' (all),
      'SI232 online' (28-29S) or 'SI232 store' (22-26x). The interface must
      be configured to the same baud rate as the host (default 9600).
      Multimeter and interface must be configured to the same address.
359 360
 - Norma DM950: If the interface doesn't work (e.g. USB-RS232 converter), power
   on the device with "FUNC" pressed (to power the interface from the DMM).
361 362 363
 - PCE PCE-DM32: Briefly press the "RS232" button.
 - RadioShack 22-812: Press and hold "SELECT" and "RANGE" together.
 - TekPower TP4000ZC: Briefly press the "RS232" button.
364
 - Tenma 72-7750: Briefly press the "RS232C" button.
365
 - UNI-T UT60G: Briefly press the "RS232C" button.
366
 - UNI-T UT61B/C/D: Press the "REL/RS232/USB" button for roughly 1 second.
367 368
 - UNI-T UT71x: Press the "SEND/-/MAXMIN" button for roughly 1 second.
   Briefly pressing the "EXIT" button leaves this mode again.
369 370 371
 - UNI-T UT325: Briefly press the "SEND" button (as per manual). However, it
   appears that in practice you don't have to press the button (at least on
   some versions of the device), simply connect the device via USB.
372 373
 - V&A VA18B/VA40B: Keep the "Hz/DUTY" key pressed while powering on the DMM.
 - Victor 70C/86C: Press the "REL/RS232" button for roughly 1 second.
374
 - Voltcraft VC-830: Press the "REL/PC" button for roughly 2 seconds.
375
 - Voltcraft VC-870: Press the "REL/PC" button for roughly 1 second.
376 377


378 379
ChronoVu LA8/LA16 USB VID/PIDs
------------------------------
380

381 382
The ChronoVu LA8/LA16 logic analyzer is available in two revisions. Previously,
the device shipped with a USB VID/PID of 0403:6001, which is the standard ID
383 384
for FTDI FT232 USB chips.

385
Since this made it hard to distinguish the LA8/LA16 from any other device
386
with this FTDI chip connected to the PC, the vendor later shipped the
387
device with a USB VID/PID of 0403:8867.
388

389 390
The 'chronovu-la' driver in libsigrok supports both VID/PID pairs and
automatically finds devices with either VID/PID pair.
391 392 393 394 395


OLS
---

396 397 398 399
The Dangerous Prototypes Openbench Logic Sniffer (OLS) logic analyzer
driver in libsigrok assumes a somewhat recent firmware has been flashed onto
the OLS (it doesn't need a firmware upload every time it's attached via USB,
since the firmware is stored in the device permanently).
400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416

The most recent firmware version that is tested is 3.07.

If you use any older firmware and your OLS is not found or is not working
properly, please upgrade to at least this firmware version. Check the
Dangerous Prototypes wiki for firmware upgrade instructions:

 http://dangerousprototypes.com/docs/Logic_Sniffer_upgrade_procedure

Also, you need to specify a serial port for the OLS in the frontends, e.g.
using the 'conn' option in sigrok-cli, and you also need to have the
permissions to access the serial port (see above).

Example:

 $ sigrok-cli --driver ols:conn=/dev/ttyACM0 ...