X-Git-Url: https://sigrok.org/gitweb/?p=sigrok-cli.git;a=blobdiff_plain;f=doc%2Fsigrok-cli.1;h=4258009bd7a507b282911d78a2bdf6d2e50a82c5;hp=cc137221a9a213bc4cd3bacc3140f9aea50ec8fc;hb=HEAD;hpb=2d4077a71b069d1b535128c2449cfdda447c6ba1 diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1 index cc13722..33174cd 100644 --- a/doc/sigrok-cli.1 +++ b/doc/sigrok-cli.1 @@ -1,82 +1,148 @@ -.TH SIGROK\-CLI 1 "May 29, 2012" +.TH SIGROK\-CLI 1 "April 07, 2023" .SH "NAME" -sigrok\-cli \- Command-line client for the sigrok logic analyzer software +sigrok\-cli \- Command-line client for the sigrok software .SH "SYNOPSIS" -.B sigrok\-cli \fR[\fB\-hVlDdiIoOptwasA\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-l\fR|\fB\-\-loglevel\fR level] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-trigger\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR decoderlist] [\fB\-s\fR|\fB\-\-protocol\-decoder\-stack\fR stack] [\fB\-A\fR|\fB\-\-protocol\-decoder\-annotations\fR annlist] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR] +.B sigrok\-cli [OPTIONS] [COMMAND] .SH "DESCRIPTION" -.B sigrok\-cli -is a cross-platform command line utility for the -.B sigrok -logic analyzer software. +\fBsigrok\-cli\fP is a cross-platform command line utility for the +\fBsigrok\fP software. .PP -The command-line frontend for sigrok cannot display graphical output, but is -still sufficient to run through the whole process of hardware initialization, -acquisition, protocol decoding and saving the session. +It cannot display graphical output, but is still sufficient to run through +the whole process of hardware initialization, acquisition, protocol decoding +and saving the session. .PP It is useful for running on remote or embedded systems, netbooks, PDAs, and for various other use-cases. It can display samples on standard output or save them in various file formats. -.SH "OPTIONS" +.SH OPTIONS .TP .B "\-h, \-\-help" Show a help text and exit. .TP .B "\-V, \-\-version" Show -.B sigrok-cli -version, and information about supported hardware drivers, input file +.B sigrok\-cli +version and the versions of libraries used. +.TP +.B "\-L, \-\-list\-supported" +Show information about supported hardware drivers, input file formats, output file formats, and protocol decoders. .TP -.BR "\-l, \-\-loglevel " -Set the libsigrok and libsigrokdecode loglevel. At the moment -.B sigrok-cli -doesn't support setting the two loglevels independently. The higher the -number, the more debug output will be printed. Valid loglevels are -.BR 0 " (NONE)," -.BR 1 " (ERR)," -.BR 2 " (WARN)," -.BR 3 " (INFO)," -.BR 4 " (DBG), and" -.BR 5 " (SPEW)." -.TP -.B "\-D, \-\-list\-devices" -List all logic analyzer devices found on the system. This actively scans for -devices (USB, serial port, and others). -.TP -.BR "\-d, \-\-device " -The device to use for acquisition. It can be specified by ID as reported by -.BR "\-\-list\-devices" , -or by the name of the driver as reported by -.BR \-\-version . -.sp -A device can optionally be followed by a colon-separated list of device -options, where each option takes the form -.BR key=value . -For example, to set the samplerate on the first device you might specify +.B "\-\-list\-supported\-wiki" +Show information about supported protocol decoders in MediaWiki syntax. +This is generally only used by developers to easily update the list of +supported protocol decoders in the sigrok wiki. +.TP +\fB\-d, \-\-driver\fP +Unless doing a global scan, users typically select one of the available +drivers. This can speedup program start, and can avoid false matches for +ambiguous configurations. Selecting a driver also allows to pass more +driver specific options. Use the +.BR "\-L " ( "\-\-list\-supported" ")" +option to get a list of available drivers. +.sp +Drivers can take options, in the form \fBkey=value\fP +separated by colons. +.sp +Drivers communicating with hardware via a serial port always need the port +specified as the \fBconn\fP option. For example, to use the +Openbench Logic Sniffer: .sp -.RB " $ " "sigrok\-cli \-d 0:samplerate=1m" +.RB " $ " "sigrok\-cli \-\-driver=ols:conn=/dev/ttyACM0" " [...]" .sp -Samplerate is an option common to most devices. The argument specifies the -samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. +Some USB devices don't use a unique VendorID/ProductID combination, and thus +need that specified as well. Notice that colons are used to separate the +driver name from the \fBconn\fP option, thus colons cannot be used within the +\fBconn\fP option's argument. To select a specific USB device, use either +\fBVendorID.ProductID\fP or \fBbus.address\fP: +.sp +USB \fBVendorID.ProductID\fP example: +.sp +.RB " $ " "sigrok\-cli \-\-driver=uni\-t\-ut61e:conn=1a86.e008" " [...]" +.sp +USB \fBbus.address\fP example: +.sp +.RB " $ " "sigrok\-cli \-\-driver=uni\-t\-ut61e:conn=4.6" " [...]" +.TP +.B "\-D, \-\-dont\-scan" +Do not automatically scan for device drivers in the absence of a +.BR "\-d " ( "\-\-driver" ) +specification. +.TP +.BR "\-c, \-\-config " +A colon-separated list of device options, where each option takes the form +.BR key=value . +Multiple occurances of the +.B \-\-config +option are supported. +The first item in the list of options can take the form +.B channel_group= +which would override the +.B \-\-channel\-group +specification for this list of options. Other option lists in other +.B \-\-config +occurances are not affected by this list's channel group name. +.sp +For example, to set the samplerate to 1MHz on a device supported by the +fx2lafw driver, you might specify +.sp +.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config samplerate=1m" " [...]" +.sp +Samplerate is an option common to most logic analyzers. The argument specifies +the samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz. The following are all equivalent: .sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1000000" +.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config samplerate=1000000" " [...]" +.sp +.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config samplerate=1m" " [...]" +.sp +.RB " $ " "sigrok\-cli \-d fx2lafw \-\-config \(dqsamplerate=1 MHz\(dq" " [...]" .sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d 0:samplerate=1m" +These examples specify options within a channel group. +The first two are equivalent. .sp -.RB " $ " "sigrok\-cli \-\-samples 100 \-d ""0:samplerate=1 MHz"" +.RB " $ " "sigrok\-cli \-d demo \-\-channel\-group Logic \-\-config pattern=random [...]" +.sp +.RB " $ " "sigrok\-cli \-d demo \-\-config channel_group=Logic:pattern=random [...]" +.sp +.RB " $ " "sigrok\-cli \-d demo \-\-config samplerate=1m \-\-config channel_group=Logic:pattern=random [...]" .TP .BR "\-i, \-\-input\-file " -Load input from a file instead of a hardware device. If the +Load input from a file instead of a hardware device. You can specify +"-" to use stdin as input. If the .B \-\-input\-format -option is not supplied, sigrok-cli attempts to autodetect the file format of +option is not supplied, sigrok\-cli attempts to autodetect the file format of the input file. +.sp +Example for loading a sigrok session file: +.sp +.RB " $ " "sigrok\-cli \-i example.sr" " [...]" +.sp +Example for loading a WAV file (autodetection of input format): +.sp +.RB " $ " "sigrok\-cli \-i example.wav" " [...] +.sp +Example for loading a VCD file from stdin (autodetection of input format): +.sp +.RB " $ " "cat example.vcd | sigrok\-cli \-i \-" " [...] .TP .BR "\-I, \-\-input\-format " When loading an input file, assume it's in the specified format. If this option is not supplied (in addition to .BR \-\-input\-file ), -sigrok-cli attempts to autodetect the file format of the input file. +sigrok-cli attempts to autodetect the file format of the input file. Use the +.BR "\-L " ( "\-\-list\-supported" ")" +option to see a list of available input formats. +.sp +The format name may optionally be followed by a colon-separated list of +options, where each option takes the form +.BR "key=value" . +.sp +Example for loading a binary file with options: +.sp +.RB " $ " "sigrok\-cli \-i example.bin" +.br +.BR " \-I binary:numchannels=4:samplerate=1mhz" " [...]" .TP .BR "\-o, \-\-output\-file " Save output to a file instead of writing it to stdout. The default format @@ -84,57 +150,64 @@ used when saving is the sigrok session file format. This can be changed with the .B \-\-output\-format option. +.sp +Example for saving data in the sigrok session format: +.sp +.RB " $ " "sigrok\-cli " "[...] " "\-o example.sr" .TP -.BR "\-O, \-\-output\-format " +.BR "\-O, \-\-output\-format " Set the output format to use. Use the -.B \-V -option to see a list of available output formats. The format name may -optionally be followed by a colon-separated list of options, where each -option takes the form -.BR "key=value" . +.BR "\-L " ( "\-\-list\-supported" ")" +option to see a list of available output formats. .sp -Supported formats currently include -.BR bits , -.BR hex , -.BR ascii , -.BR binary , -.BR vcd , -.BR ols , -.BR gnuplot , -.BR chronovu-la8 ", and" -.BR csv . +The format name may optionally be followed by a colon-separated list of +options, where each option takes the form +.BR "key=value" . .sp -The +For example, the .B bits or .B hex formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" option, specifying the number of samples (in bits) to display per line. Thus -.B hex:width=128 +.B "\-O hex:width=128" will display 128 bits per line, in hexadecimal: .sp - 1:ffff ffff ffff ffff ffff ffff ffff ffff - 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 + 0:ffff ffff ffff ffff ffff ffff ffff ffff + 1:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00 .sp -The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to +The lines always start with the channel number (or name, if defined), followed by a colon. If no format is specified, it defaults to .BR bits:width=64 , like this: .sp - 1:11111111 11111111 11111111 11111111 [...] - 2:11111111 00000000 11111111 00000000 [...] + 0:11111111 11111111 11111111 11111111 [...] + 1:11111111 00000000 11111111 00000000 [...] +.sp +Example for saving data in the CSV format with options: +.sp +.RB " $ " "sigrok\-cli " "[...] " "\-o example.csv \-O csv:dedup:header=false" +.sp +Notice that boolean options are \fBtrue\fP when no value gets specified. .TP -.BR "\-p, \-\-probes " -A comma-separated list of probes to be used in the session. +.BR "\-C, \-\-channels " +A comma-separated list of channels to be used in the session. +.sp +Note that sigrok always names the channels according to how they're shown on +the enclosure of the hardware. If your logic analyzer numbers the channels 0\-15, +that's how you must specify them with this option. An oscilloscope's channels +would generally be referred to as "CH1", "CH2", and so on. +Use the \fB\-\-show\fP option to see a list of channel names for your device. .sp -The default is to use all the probes available on a device. You can name -a probe like this: +The default is to use all the channels available on a device. You can name +a channel like this: .BR "1=CLK" . -A range of probes can also be given, in the form +A range of channels can also be given, in the form .BR "1\-5" . .sp Example: .sp - $ -.B "sigrok\-cli \-\-samples 100 \-\-probes 1=CLK,2\-4,7" +.RB " $ " "sigrok\-cli \-\-driver fx2lafw \-\-samples 100" +.br +.B " \-\-channels 1=CLK,2\-4,7" .br CLK:11111111 11111111 11111111 11111111 [...] 2:11111111 11111111 11111111 11111111 [...] @@ -144,24 +217,36 @@ Example: .sp The comma-separated list is processed from left to right, i.e. items farther to the right override previous items. For example -.B "1=CS,1=MISO" -will set the name of probe 1 to +.B "1=CS,CS=MISO" +will set the name of channel 1 to .BR "MISO" . +.TP +.BR "\-g, \-\-channel\-group " +Specify the channel group to operate on. Some devices organize channels into +groups, the settings of which can only be changed as a group. The list of +channel groups, if any, is displayed with the \fB\-\-show\fP command. +.sp +Examples: +.sp +.RB " $ " "sigrok\-cli \-g CH1" " [...]" .sp -Also, while -.B "5=MOSI,6=MISO" -will only select probes 5 and 6, and set their names to MISO and MOSI, the -command line -.B "5=MOSI,6=MISO,1\-8" -will select probes 1\-8 (including 5 and 6, of course), but the names specified -for probes 5 and 6 will be reset to the defaults by the -.B "1\-8" -probe selection. +.RB " $ " "sigrok\-cli \-d demo \-g Logic \-c pattern=graycode" " [...]" +.sp +Channel group specifications in +.B \-\-get +or +.B \-\-config +options take precedence over channel group names in +.B \-\-channel\-group +so that a single +.B sigrok\-cli +invocation can support the query or manipulation of multiple device options +which reside in different channel groups. .TP .BR "\-t, \-\-triggers " A comma-separated list of triggers to use, of the form -.BR "=" . -You can use the name or number of the probe, and the trigger itself is a +.BR "=" . +You can use the name or number of the channel, and the trigger itself is a series of characters: .sp .BR "0 or 1" : @@ -173,31 +258,30 @@ A rising or falling value on the pin. An effectively corresponds to .BR 01 . .br -.BR "c" : +.BR "e" : Any kind of change on a pin (either a rising or a falling edge). .sp -Not every device supports all of these trigger types. Use the -.B "\-d " -argument (with no other arguments) to see which triggers your device supports. +Not every device supports all of these trigger types. Use the \fB\-\-show\fP +command to see which triggers your device supports. .TP -.BR "\-w, \-\-wait-trigger" -Don't output any sample data (even if it's actually received from the logic -analyzer) before the trigger condition is met. In other words, do not output +.BR "\-w, \-\-wait\-trigger" +Don't output any sample data (even if it's actually received from the +hardware) before the trigger condition is met. In other words, do not output any pre-trigger data. This option is useful if you don't care about the data -that came before the trigger (but the logic analyzer hardware delivers this -data to sigrok nonetheless). +that came before the trigger (but the hardware delivers this data to sigrok +nonetheless). .TP -.BR "\-a, \-\-protocol\-decoders " +.BR "\-P, \-\-protocol\-decoders " This option allows the user to specify a comma-separated list of protocol decoders to be used in this session. The decoders are specified by their ID, as shown in the -.B \-\-version +.BR "\-L " ( "\-\-list\-supported" ")" output. .sp Example: .sp $ -.B "sigrok\-cli \-i \-a i2c" +.B "sigrok\-cli \-i \-P i2c" .sp Each protocol decoder can optionally be followed by a colon-separated list of options, where each option takes the form @@ -206,101 +290,241 @@ of options, where each option takes the form Example: .sp $ -.B "sigrok\-cli \-i \-a uart:baudrate=115200:parity=odd" +.B "sigrok\-cli \-i " +.br +.B " \-P uart:baudrate=115200:parity=odd" .sp The list of supported options depends entirely on the protocol decoder. Every protocol decoder has different options it supports. .sp Any "options" specified for a protocol decoder which are not actually -supported options, will be interpreted as being probe name/number assignments. +supported options, will be interpreted as being channel name/number assignments. .sp Example: .sp $ .B "sigrok\-cli \-i " .br -.B " \-a spi:wordsize=9:miso=1:mosi=5:sck=3:cs=0" +.B " \-P spi:wordsize=9:miso=1:mosi=5:clk=3:cs=0" .sp In this example, .B wordsize is an option supported by the .B spi -protocol decoder. Additionally, the user tells sigrok to decode the SPI -protocol using probe 1 as MISO signal for SPI, probe 5 as MOSI, probe 3 -as SCK, and probe 0 as CS# signal. -.TP -.BR "\-s, \-\-protocol\-decoder\-stack " -This option allows the user to specify a protocol decoder stack, i.e. -the way in which one protocol decoder's output gets piped into another -protocol decoder. If not specified, the stack will be set up in the same -order in which the protocol decoders were given with the -.B \-\-protocol-decoders -option. +protocol decoder. Additionally, the user requests sigrok to decode the SPI +protocol using channel 1 as MISO signal for SPI, channel 5 as MOSI, channel 3 +as CLK, and channel 0 as CS# signal. +.sp +The +.B sigrok\-cli +application can automatically assign logic channels to decoder inputs +in their strict channel index order (by means of the +.B auto_index +keyword), or can automatically assign logic channels to decoder inputs +when their names match (case insensitive match, +.B auto_names +keyword). Users need to explicitly request this assignment, the default +behaviour is to not automatically assign any signals. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-i " +.br +.B " \-P ieee488:assign_channels=auto_names" +.br .sp -The decoders are specified by their ID, as shown in the -.B \-\-version -output. In addition to the -.B \-s -option, all protocol decoders that are used in a stack, must also be specified -(together with their options, if any) using the -.B \-a -parameter. +When multiple decoders are specified in the same +.BR -P +option, they will be stacked on top of each other in the specified order. .sp Example: .sp $ -.B "sigrok\-cli \-i \-a i2c:sda=4:scl=7,rtc8564" +.B "sigrok\-cli \-i \-P i2c,eeprom24xx" .br -.B " \-s i2c,rtc8564" -.sp -In this example, the -.B \-s -option specifies that the output of the -.BR i2c " decoder" -is piped into the -.BR rtc8564 " decoder," -i.e., the -.BR rtc8564 " decoder" -is stacked on top of the -.BR i2c " decoder." -.sp -The respective protocol decoder options and probe name/number assignments -must be given using the -.B \-a -option (you cannot specify them in the -.B \-s -option). + $ +.B "sigrok\-cli \-i \-P uart:baudrate=31250,midi" +.sp +When multiple +.BR -P +options are specified, each of them creates one decoder stack, which +executes in parallel to other decoder stacks. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-i \-P uart:tx=D0:rx=D1 \-P timing:data=D2" +.sp .TP .BR "\-A, \-\-protocol\-decoder\-annotations " -By default, only the stack's topmost protocol decoder's annotation output is -shown. With this option another decoder's annotation can be selected for -display, by specifying its ID: +By default, all annotation output of all protocol decoders is +shown. With this option a specific decoder's annotations can be selected for +display, by specifying the decoder ID: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid \-A i2c" +.sp +If a protocol decoder has multiple annotation classes, you can also specify +which one of them to show by specifying its short description like this: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" +.br +.B " \-A i2c=data\-read" +.sp +Select multiple annotation classes by separating them with a colon: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" +.br +.B " \-A i2c=data\-read:data\-write" +.sp +Annotation row names will resolve to their respective list of classes. +Row and class names can be used in combination. When names are ambiguous +then class names take precedence. +.sp + $ +.B "sigrok\-cli \-i \-P i2c" +.br +.B " \-A i2c=addr\-data:warnings" +.sp +You can also select multiple protocol decoders, with optionally selected +annotation classes each, by separating them with commas: +.sp + $ +.B "sigrok\-cli \-i \-P i2c,i2cfilter,edid" +.br +.B " \-A i2c=data\-read:data\-write,edid" +.TP +.BR "\-M, \-\-protocol\-decoder\-meta " +When given, show protocol decoder meta output instead of annotations. +The argument is the name of the decoder whose meta output to show. +.sp + $ +.B "sigrok\-cli \-i \-M i2c" +.sp +Not every decoder generates meta output. +.TP +.BR "\-B, \-\-protocol\-decoder\-binary " +When given, decoder "raw" data of various kinds is written to stdout instead +of annotations (this could be raw binary UART/SPI bytes, or WAV files, PCAP +files, PNG files, or anything else; this is entirely dependent on the +decoder and what kinds of binary output make sense for that decoder). +.sp +No other information is printed to stdout, so this is +suitable for piping into other programs or saving to a file. +.sp +Protocol decoders that support binary output publish a list of binary +classes, for example the UART decoder might have "TX" and "RX". To +select TX for output, the argument to this option would be: +.sp + $ +.B "sigrok\-cli \-i \-B uart=tx" +.br +.sp +If only the protocol decoder is specified, without binary class, all classes +are written to stdout: +.sp + $ +.B "sigrok\-cli \-i \-B uart" +.sp +(this is only useful in rare cases, generally you would specify a certain +binary class you're interested in) +.sp +Not every decoder generates binary output. +.TP +.BR "\-\-protocol\-decoder\-samplenum +When given, decoder annotations will include sample numbers, too. +This allows consumers to receive machine readable timing information. +.TP +.BR "\-\-protocol\-decoder\-ann\-class +When given, decoder annotations will include annotation class names. +.TP +.BR "\-\-protocol\-decoder\-jsontrace +When given, decoder output uses the Google Trace Event format (JSON). +Which can be inspected in web browsers or other viewers. +.TP +.BR "\-l, \-\-loglevel " +Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok\-cli\fP +doesn't support setting the two loglevels independently. The higher the +number, the more debug output will be printed. Valid loglevels are: +.sp +\fB0\fP None +.br +\fB1\fP Error +.br +\fB2\fP Warnings +.br +\fB3\fP Informational +.br +\fB4\fP Debug +.br +\fB5\fP Spew +.TP +.B "\-\-show" +.br +Show information about the selected option. For example, to see options for a +connected fx2lafw device: +.sp + $ +.B "sigrok\-cli \-\-driver fx2lafw \-\-show +.sp +In order to properly get device options for your hardware, some drivers might +need a serial port specified: .sp $ -.B "sigrok\-cli \-i \-a i2c,i2cfilter,edid -A i2c" +.B "sigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-show .sp -If a protocol decoder has multiple annotation formats, you can also specify -which of them to show by specifying its short description like this: +This also works for protocol decoders, input modules and output modules: .sp $ -.B "sigrok\-cli \-i \-a i2c,i2cfilter,edid" +.B "sigrok\-cli \-\-protocol\-decoders i2c \-\-show + $ +.B "sigrok\-cli \-\-input\-format csv \-\-show + $ +.B "sigrok\-cli \-\-output\-format bits \-\-show +.sp +This also works for input files, including optional input format specifications: +.sp + $ +.B "sigrok\-cli \-\-input\-file \-\-show + $ +.B "sigrok\-cli \-\-input\-file \-\-input\-format vcd \-\-show +.TP +.B "\-\-scan" +Scan for devices that can be detected automatically. +.sp +Example: +.sp + $ +.B "sigrok\-cli \-\-scan +.br + The following devices were found: +.br + demo \- Demo device with 12 channels: D0 D1 D2 D3 D4 D5 D6 D7 A0 A1 A2 A3 .br -.B " \-A i2c=rawhex" + fx2lafw:conn=3.26 \- CWAV USBee SX with 8 channels: 0 1 2 3 4 5 6 7 .sp -You can also select multiple protocol decoders, with an optional selected -annotation format each, by separating them with commas: +However, not all devices are auto-detectable (e.g. serial port based ones). +For those you'll have to provide a \fBconn\fP option, see above. .sp $ -.B "sigrok\-cli \-i \-a i2c,i2cfilter,edid" +.B "sigrok\-cli \-\-driver digitek\-dt4000zc:conn=/dev/ttyUSB0 \-\-scan .br -.B " \-A i2c=rawhex,edid" + The following devices were found: +.br + Digitek DT4000ZC with 1 channel: P1 .TP .BR "\-\-time " Sample for .B -milliseconds, then quit. You can optionally follow the number by -.B s -to state the number of seconds to sample instead. For example, +milliseconds, then quit. +.sp +You can optionally follow the number by \fBs\fP to specify the time to +sample in seconds. +.sp +For example, .B "\-\-time 2s" will sample for two seconds. .TP @@ -308,35 +532,99 @@ will sample for two seconds. Acquire .B samples, then quit. +.sp +You can optionally follow the number by \fBk\fP, \fBm\fP, or \fBg\fP to +specify the number of samples in kilosamples, megasamples, or gigasamples, +respectively. +.sp +For example, +.B "\-\-samples 3m" +will acquire 3000000 samples. +.TP +.BR "\-\-frames " +Acquire +.B +frames, then quit. .TP .BR "\-\-continuous" Sample continuously until stopped. Not all devices support this. -.SH "EXAMPLES" -In order to get exactly 100 samples from the (only) detected logic analyzer -hardware, run the following command: .TP -.B " sigrok\-cli \-\-samples 100" +.BR "\-\-get " +Get the value of +.B +from the specified device and print it. +Multiple variable names can be specified and get separated by colon. +The list of variable names optionally can be preceeded by +.B "channel_group=" +which would override the +.B \-\-channel\-group +specification. +Multiple +.B \-\-get +occurances are supported in a single +.B sigrok\-cli +invocation. +.sp + $ +.B sigrok\-cli \-d demo \-\-get samplerate:averaging \-\-get channel_group=Logic:pattern .TP -If you want to sample data for 3 seconds, use: +.BR "\-\-set" +Set one or more variables specified with the \fB\-\-config\fP option, without +doing any acquisition. +.SH EXAMPLES +In order to get exactly 100 samples from the connected fx2lafw-supported logic +analyzer hardware, run the following command: .TP -.B " sigrok\-cli \-\-time 3000" +.B " sigrok\-cli \-\-driver fx2lafw \-\-samples 100" +.TP +If you want to sample data for 3 seconds (3000 ms), use: +.TP +.B " sigrok\-cli \-\-driver fx2lafw \-\-time 3000" .TP Alternatively, you can also use: .TP -.B " sigrok\-cli \-\-time 3s" +.B " sigrok\-cli \-\-driver fx2lafw \-\-time 3s" +.TP +To capture data from the first 4 channels using the Openbench Logic Sniffer lasting 100ms at 10 MHz starting at the trigger condition +0:high, 1:rising, 2:low, 3:high, use: .TP -To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use: +.nf +\fBsigrok\-cli \-\-driver ols:conn=/dev/ttyACM0 \-\-config samplerate=10m \\\fP +\fB\-\-output\-format bits \-\-channels 0\-3 \-\-wait\-trigger \\\fP +\fB\-\-triggers 0=1,1=r,2=0,3=1 \-\-time 100\fP .TP -.B " sigrok\-cli -d 0:samplerate=10m \-O bits \-p 1\-4 \-\-time 100 \\\\" -.B " \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 " +To turn on internal logging on a Lascar EL-USB series device: +.TP +\fBsigrok\-cli \-\-driver lascar\-el\-usb:conn=10c4.0002 \\\fP +\fB\-\-config datalog=on \-\-set\fP .SH "EXIT STATUS" .B sigrok\-cli exits with 0 on success, 1 on most failures. +.SH "ENVIRONMENT" +.TP +.B SIGROK_FIRMWARE_DIR +A single path where to search for firmware images, in addition to a +builtin list of locations. +.TP +.B SIGROK_FIRMWARE_PATH +Multiple path entries where to search for firmware images, in addition +to builtin locations. +.TP +When decoder support was enabled in the application's configuration: +.TP +.B SIGROKDECODE_DIR +A single path where to search for protocol decoders, in addition to +a builtin list of locations. +.TP +.B SIGROKDECODE_PATH +Multiple path entries where to search for protocol decoders, in addition +to builtin locations. .SH "SEE ALSO" -\fBsigrok\-qt\fP(1), -\fBsigrok\-gtk\fP(1) +\fBpulseview\fP(1) .SH "BUGS" -Please report any bugs on the sigrok\-devel mailing list +Please report any bugs via Bugzilla +.RB "(" http://sigrok.org/bugzilla ")" +or on the sigrok\-devel mailing list .RB "(" sigrok\-devel@lists.souceforge.net ")." .SH "LICENSE" .B sigrok\-cli