sigrok - User contributions [en]

Protocol decoder API

2019-11-03T22:51:16Z

Jsolla: /* Required functions */

This page describes how [[libsigrokdecode]] '''Protocol Decoders ([[Protocol decoders|PDs]])''' work.

See also [[Protocol decoder HOWTO]] for a quick introduction of how to write your own decoders.

See [[Protocol decoder API/Queries]] for changes to the decoder API in version 3. All decoders use this API now and the v2 API is no longer supported.

== Architecture ==

* All PDs are written in Python (>= 3.0).
* Every PD registers its name, description, capabilities, etc.
* PDs can be stacked, so the user can construct a decoding pipeline/stack. The control of communication to/from PDs is done by the backend code in libsigrokdecode.
* The sample data passed into the PDs will be streamed/chunked, so they can run in real time as the data comes in from the hardware (or from a file).
* In order to keep PDs simple, they don't have to deal with the intricacies of the datafeed packets.

The frontend passes sample data into libsigrokdecode and gets decoder output (of various types) from every PD in the stack. Which of these output types of which PDs are actually displayed to the user is a matter of configuration or selection by the user; it is possible, for example, to have [[sigrok-cli]] print only the top of the PD stack's annotation output on stdout.

== API ==

=== Backend library ===

A Python module called '''<tt>sigrokdecode</tt>''' is provided. Every protocol decoder must import this. It contains the following items:

* '''<tt>the Decoder object</tt>'''
<blockquote>
Every protocol decoder must subclass this object.
</blockquote>

* '''<tt>OUTPUT_ANN</tt>'''
<blockquote>
A constant used to register annotation output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. [[Sigrok-cli|sigrok-cli]] shows the annotation output of a decoder stack's topmost decoder (per default), [[PulseView]] shows annotation output as graphical boxes or as circles (if the duration of the annotation is zero).
</blockquote>
* '''<tt>OUTPUT_PYTHON</tt>'''
<blockquote>
A constant used to register Python output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. Python output is passed as input to a decoder that is stacked onto the current decoder. The format of the data that is given to the '''<tt>[[#put-function|put()]]</tt>''' function is specific to a certain PD and should be documented for the authors of the higher level decoders, for example with a comment at the top of the decoder's source file.
</blockquote>
* '''<tt>OUTPUT_BINARY</tt>'''
<blockquote>
A constant used to register binary output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. The format of the data that is outputted is not specified, it's up to the author of the decoder to choose one (or multiple) appropriate format(s). For example, the [[Protocol_decoder:Uart|UART]] decoder outputs the raw bytes that it decodes, the [[Protocol_decoder:I2s|I²S]] decoder outputs the audio in WAV format, but the output could also be an image (JPG, PNG, other) file for a decoder that decodes a display protocol, a PCAP file for network/USB decoders, or one of [[Protocol decoder output|many other]] formats. [[Sigrok-cli|sigrok-cli]] can be used to redirect the binary output of a decoder into a file (or to pipe it into other applications), see the documentation of its '''--protocol-decoder-binary''' ('''-B''') option.
</blockquote>
* '''<tt>OUTPUT_META</tt>'''
<blockquote>
A constant used to register metadata output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. An example for a PD that outputs metadata is the SPI decoder that uses it to output the detected bitrate. See [[Protocol decoder output]] for various other possible examples.
</blockquote>

* <div id="put-function">'''<tt>put(startsample, endsample, output_id, data)</tt>'''</div>
<blockquote>
This is used to provide the decoded data back into the backend. '''<tt>startsample</tt>''' and '''<tt>endsample</tt>''' specify the absolute sample numbers of where this item (e.g. an annotation) starts and ends. '''<tt>output_id</tt>''' is an output identifier returned by the '''<tt>[[#register-function|register()]]</tt>''' function.
The '''<tt>data</tt>''' parameter's contents depend on the output type ('''<tt>output_id</tt>'''):
* '''OUTPUT_ANN''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the annotation index (determined by the order of items in '''<tt>Decoder.annotations</tt>''', see [[#Decoder_registration|below]]), the second is a list of annotation strings. The strings should be longer and shorter versions of the same annotation text (sorted by length, longest first), which can be used by frontends to show different annotation texts depending on e.g. zoom level.
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['Start', 'St', 'S']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is "Start", "St", "S".
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['CRC']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is just "CRC" (the list containins only one item).
** Example: ''<tt>self.put(35, 9000, self.out_ann, [17, ['Registered Parameter Number', 'Reg Param Num', 'RPN', 'R']])</tt>'''
*** The emitted data spans samples 35 to 9000, is of type OUTPUT_ANN, the annotation index is 17, the list of annotations strings is "Registered Parameter Number", "Reg Param Num", "RPN", "R".
* '''OUTPUT_PYTHON''': The '''<tt>data</tt>''' parameter is any arbitrary Python object that will be passed to stacked decoders. The format and contents are entirely decoder-dependent. Typically a Python list with various contents is passed to the stacked PDs.
** Example: ''<tt>self.put(10, 20, self.out_python, ['PACKET', ['Foo', 19.7, [1, 2, 3], ('bar', 'baz')]])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_PYTHON, the data contents themselves are entirely dependent on the respective decoder and should be documented in its [[Protocol_decoder_HOWTO#pd.py|pd.py]] file.
* '''OUTPUT_BINARY''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the binary format's index (determined by the order of items in '''<tt>Decoder.binary</tt>''', see [[#Decoder_registration|below]]), the second is a Python [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''] object.
** Example: ''<tt>self.put(10, 20, self.out_binary, [4, b'\xfe\x55\xaa'])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_BINARY, the binary format's index is 4, the emitted bytes are 0xfe, 0x55, 0xaa.
* '''OUTPUT_META''': The '''<tt>data</tt>''' parameter is a Python object of a certain type, as defined in the respective '''<tt>[[#register-function|register()]]</tt>''' function.
** Example: ''<tt>self.put(10, 20, self.out_meta, 15.7)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is a floating point number in this case.
** Example: ''<tt>self.put(10, 20, self.out_meta, 42)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is an integer number in this case.
</blockquote>

=== Decoder class functions ===

==== Required functions ====

* '''<tt>start(self)</tt>'''
<blockquote>
This function is called before the beginning of the decoding. This is the place to '''<tt>[[#register-function|register()]]</tt>''' the output types, check the user-supplied PD options for validity, and so on.
</blockquote>

* <div id="decode-and-wait-function-">'''<tt>decode(self)</tt>'''</div>
<blockquote>
'''In logic decoders''', this function is called by the [[libsigrokdecode]] backend to start the decoding.

It takes no arguments, but instead will enter an infinite loop and gets samples by calling the more versatile '''<tt>[[Protocol_decoder_API/Queries#self.wait()|wait()]]</tt>''' method. This frees specific protocol decoders from tedious yet common tasks like detecting edges, or sampling signals at specific points in time relative to the current position.

'''Note:''' This '''<tt>[[Protocol_decoder_API/Queries#self.decode()|decode(self)]]</tt>''' method's signature has been introduced in version 3 of the protocol decoder API, in previous versions only '''<tt>decode(self, startsample, endsample, data)</tt>''' was available.

</blockquote>

* <div id="decode-function">'''<tt>decode(self, startsample, endsample, data)</tt>'''</div>
<blockquote>
'''In stacked decoders''', this is a function that is called by the [[libsigrokdecode]] backend whenever it has a chunk of data for the protocol decoder to handle.

{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Argument
!Description

|-
| '''<tt>startsample</tt>'''
| The absolute samplenumber of the first sample in this chunk of data.

|-
| '''<tt>endsample</tt>'''
| The absolute samplenumber of the last sample in this chunk of data.

|-
| '''<tt>data</tt>'''
| A list containing the data to decode. Depending on whether the decoder decodes raw samples or is stacked onto another decoder, this argument is:
* Raw samples ('''<tt>inputs = ['logic']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is a list of tuples containing the (absolute) sample number and the channels of that sample: '''<tt>[(samplenum, channels), (samplenum, channels), ...]</tt>'''.<br />
'''<tt>samplenum</tt>''' is the (absolute) number of the sample, an integer that takes the values from '''<tt>startsample</tt>''' to '''<tt>endsample</tt>''' - 1.<br />
The type of '''<tt>channels</tt>''' is [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''],
a sequence type whose length is the sum of the lengths of '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''
(in other words, '''<tt>channels</tt>''' contains a byte for every channel/optional channel).<br />
The order of the bytes is the same as the order of the channels in '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''.<br>
The individual bytes take the values '''<tt>0</tt>''' or '''<tt>1</tt>''', or some other value for optional channels that aren't supplied to the decoder.<br>
The [[Protocol_decoder_HOWTO#channels_.26_optional_channels|Protocol decoder HOWTO]] page contains an example how the data can be processed.
</blockquote>

* Stacked decoder ('''<tt>inputs = ['</tt>'''<id of some other decoder>'''<tt>']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is the '''<tt>OUTPUT_PYTHON</tt>''' output of the decoder this PD is stacked upon.
Its format depends on the implementation of the underlying decoder and should be documented there.
</blockquote>
|}

</blockquote>

==== Optional functions ====

* '''<tt>metadata(self, key, value)</tt>'''
<blockquote>
Used to pass the decoder metadata about the data stream. Currently the only value for '''<tt>key</tt>''' is '''<tt>sigrokdecode.SRD_CONF_SAMPLERATE</tt>''', '''<tt>value</tt>''' is then the sample rate of the data stream in Hz.
</blockquote>

=== Decoder registration ===

A PD's '''Decoder''' class must contain a few attributes specifying metadata about the PD. The following keys can be used:

<blockquote>
{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Key
!Description

|-
| '''<tt>api_version</tt>'''
| The libsigrokdecode API version which this module uses. This is currently either 2 or 3.

|-
| '''<tt>id</tt>'''
| A short unique identifier for this protocol decoder. It should be all-lowercase, and only contains a-z, 0-9 and underscores. This must match the PD's Python module name (subdirectory name in the '''decoders''' directory). The [[sigrok-cli]] tool uses this to specify PDs on the command-line. Examples: 'jtag', 'sdcard_spi', 'uart'.

|-
| '''<tt>name</tt>'''
| The name of the decoder. Used when listing available PDs. Examples: 'JTAG', 'SD card (SPI mode)', 'UART'.

|-
| '''<tt>longname</tt>'''
| The (long) name of the decoder. Used when listing available PDs. Example: 'Joint Test Action Group (IEEE 1149.1)', 'Secure Digital card (SPI mode)', 'Universal Asynchronous Receiver/Transmitter'.

|-
| '''<tt>desc</tt>'''
| A freeform one-line description of the decoder. Used when listing available PDs. Should end with a full stop. Example: 'Protocol for testing, debugging, and flashing ICs.', 'Secure Digital card (SPI mode) low-level protocol.', 'Asynchronous, serial bus.'.

|-
| '''<tt>license</tt>'''
| The license under which the module is provided. This must be either '''<tt>gplv2+</tt>''' (meaning the GNU General Public License 2 or later), or '''<tt>gplv3+</tt>''' (GNU General Public License 3 or later). No other licenses for modules are permitted in libsigrokdecode.

|-
| '''<tt>inputs</tt>'''
| The list of types of input this decoder needs. If the decoder takes input from a logic analyzer driver, this should be set to '''<tt>logic</tt>''', which maps to SR_DF_LOGIC, the datafeed type. If it takes input from another PD, it should be set to the value of the '''<tt>outputs</tt>''' key of that PD. It should conform to the same rules as the '''<tt>id</tt>''' key (lowercase, no spaces, and so on).

|-
| '''<tt>outputs</tt>'''
| The list of types of output this decoder produces. If this decoder can feed decoded data back into the datafeed stream, its outputs will be identified with this key's value. It should conform to the same rules as the '''<tt>id</tt>''' key.

|-
| '''<tt>channels</tt>'''
| This key contains information about the channels (pins) that '''must''' be provided to this PD; the PD will not be able to work without them. For example, the [[Protocol_decoder:Spi|SPI]] decoder has to know which channel has the clock signal. This key contains a tuple of channel entries, where each entry is a Python dict with the keys '''id''', '''name''', and '''desc'''. Example: '''<tt>{'id': 'rx', 'name': 'RX', 'desc': 'UART receive line'}</tt>'''.

|-
| '''<tt>optional_channels</tt>'''
| The channels the PD can make use of, but are not strictly required. The key has the same format as that of the <tt>channels</tt> key above (a tuple of dicts). This tuple is allowed to be empty if the respective protocol decoder has no optional channels.

|-
| '''<tt>options</tt>'''
| A tuple describing the options for this decoder. Each tuple entry is a Python dict with the keys '''id''', '''desc''', '''default''', and '''values'''. Example: '''<tt>{'id': 'bitorder', 'desc': 'Bit order', 'default': 'msb-first', 'values': ('msb-first', 'lsb-first')}</tt>'''. This tuple can be empty, if the PD has no options.

|-
| '''<tt>annotations</tt>'''
| A list of annotation classes this protocol decoder can output. Elements of this list are tuples consisting of an identifier string and a human readable description string. The identifier string can be used in the options of [[sigrok-cli]] to select the specific annotation type, and should therefore not contain whitespace or special characters.

|-
| '''<tt>annotation_rows</tt>'''
| Annotation rows are used to group multiple annotation types together. The elements of this list are three element tuples consisting of:
* An annotation row ID (same naming rules as for other IDs).
* A human readable name/description string for the annotation row.
* A tuple containing the indices of the the annotation classes in the '''<tt>annotations</tt>''' tuple.
See the [[Protocol_decoder_HOWTO#annotations_.26_annotation_rows|example on the Protocol decoder HOWTO page]] for more information on this attribute.

|-
| '''<tt>binary</tt>'''
| A list of binary output types this protocol decoder can output, same format as the '''<tt>annotations</tt>''' list.

|}

</blockquote>

* <div id="register-function">'''<tt>register(output_type)</tt>'''</div>
<blockquote>
This function is used to register the output that will be generated by the decoder, its argument should be one of the '''<tt>OUTPUT_...</tt>''' constants described above. The function returns an identifier that can then be used as the '''<tt>output_id</tt>''' argument of the '''<tt>[[#put-function|put()]]</tt>''' function.
</blockquote>

See [[Protocol decoder HOWTO#pd.py|pd.py]] for an example.

[[Category:APIs]]

Protocol decoder:Cec

2019-11-03T22:10:08Z

Jsolla: /* Current status */

{{Infobox protocol decoder
| id = cec
| name = cec
| description = HDMI Consumer Electronics Control (CEC) protocol.
| status = supported
| license = GPLv2+
| source_code_dir = cec
| image = [[File:Cec_hdmi_pinout.png|250px]]
| input = logic
| output = cec
| probes = cec
}}

Consumer Electronics Control (CEC) is a feature of HDMI designed to allow users to command and control devices connected through HDMI

== Hardware ==

CEC Bus can be found in PIN 13 of the HDMI connector:

[[File:Cec_hdmi_pinout.png]]

== Protocol ==

It is a one-wire bidirectional serial bus that is based on the [https://en.wikipedia.org/wiki/European_Committee_for_Electrotechnical_Standardization CENELEC] standard AV.link protocol to perform remote control functions.

CEC is a separate electrical signal from the other HDMI signals. This allows a device to disable its high-speed HDMI circuitry in sleep mode, but be woken up by CEC. It is a single shared bus, which is directly connected between all HDMI ports on a device, so it can flow through a device which is completely powered off (not just asleep).

The bus is electrically identical to the AV.link protocol, but CEC adds a detailed higher-level message protocol.

The bus is an open-collector line, somewhat like I²C, passively pulled up to +3.3 V, and driven low to transmit a bit.

== Pulseview screenshots ==

<gallery widths=800px>
File:Cec_pulseview_ping_frames.png|<small>Ping (poll) frames</small>
File:cec_pulseview_vendor_command_frame.png|<small>Vendor command frame</small>
</gallery>

== Usage examples ==

'''Print all annotations (very verbose)'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC'''

cec-1: ST
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0x30
cec-1: EOM=N
cec-1: ACK
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0x04
cec-1: EOM=Y
cec-1: ACK
cec-1: 30:04
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK

'''Print frames only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=frames'''

cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 3f:82:10:00
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 30:44:6d
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:0d
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04

'''Print sections only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=sections'''

cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, Broadcast | OPC: ACTIVE_SOURCE | OPS: 0x10, 0x00 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: USER_CONTROL_PRESSED | OPS: 0x6d | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: TEXT_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK

== Current status ==

The CEC protocol decoder is capable of the following:

* Decoding all low level parts: START, BITs, EOM, ACK / NACK
* Resolve names of all logical addresses
* Resolve names of all opcodes
* Detect (and warn) timing errors
* Detect (and warn) misplaced bits, etc

Not implemented:

* Operands of the opcodes are not parsed, only printed.

[[Category:Protocol decoder]]

Protocol decoder API

2019-11-03T21:15:45Z

Jsolla:

This page describes how [[libsigrokdecode]] '''Protocol Decoders ([[Protocol decoders|PDs]])''' work.

See also [[Protocol decoder HOWTO]] for a quick introduction of how to write your own decoders.

See [[Protocol decoder API/Queries]] for changes to the decoder API in version 3. All decoders use this API now and the v2 API is no longer supported.

== Architecture ==

* All PDs are written in Python (>= 3.0).
* Every PD registers its name, description, capabilities, etc.
* PDs can be stacked, so the user can construct a decoding pipeline/stack. The control of communication to/from PDs is done by the backend code in libsigrokdecode.
* The sample data passed into the PDs will be streamed/chunked, so they can run in real time as the data comes in from the hardware (or from a file).
* In order to keep PDs simple, they don't have to deal with the intricacies of the datafeed packets.

The frontend passes sample data into libsigrokdecode and gets decoder output (of various types) from every PD in the stack. Which of these output types of which PDs are actually displayed to the user is a matter of configuration or selection by the user; it is possible, for example, to have [[sigrok-cli]] print only the top of the PD stack's annotation output on stdout.

== API ==

=== Backend library ===

A Python module called '''<tt>sigrokdecode</tt>''' is provided. Every protocol decoder must import this. It contains the following items:

* '''<tt>the Decoder object</tt>'''
<blockquote>
Every protocol decoder must subclass this object.
</blockquote>

* '''<tt>OUTPUT_ANN</tt>'''
<blockquote>
A constant used to register annotation output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. [[Sigrok-cli|sigrok-cli]] shows the annotation output of a decoder stack's topmost decoder (per default), [[PulseView]] shows annotation output as graphical boxes or as circles (if the duration of the annotation is zero).
</blockquote>
* '''<tt>OUTPUT_PYTHON</tt>'''
<blockquote>
A constant used to register Python output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. Python output is passed as input to a decoder that is stacked onto the current decoder. The format of the data that is given to the '''<tt>[[#put-function|put()]]</tt>''' function is specific to a certain PD and should be documented for the authors of the higher level decoders, for example with a comment at the top of the decoder's source file.
</blockquote>
* '''<tt>OUTPUT_BINARY</tt>'''
<blockquote>
A constant used to register binary output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. The format of the data that is outputted is not specified, it's up to the author of the decoder to choose one (or multiple) appropriate format(s). For example, the [[Protocol_decoder:Uart|UART]] decoder outputs the raw bytes that it decodes, the [[Protocol_decoder:I2s|I²S]] decoder outputs the audio in WAV format, but the output could also be an image (JPG, PNG, other) file for a decoder that decodes a display protocol, a PCAP file for network/USB decoders, or one of [[Protocol decoder output|many other]] formats. [[Sigrok-cli|sigrok-cli]] can be used to redirect the binary output of a decoder into a file (or to pipe it into other applications), see the documentation of its '''--protocol-decoder-binary''' ('''-B''') option.
</blockquote>
* '''<tt>OUTPUT_META</tt>'''
<blockquote>
A constant used to register metadata output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. An example for a PD that outputs metadata is the SPI decoder that uses it to output the detected bitrate. See [[Protocol decoder output]] for various other possible examples.
</blockquote>

* <div id="put-function">'''<tt>put(startsample, endsample, output_id, data)</tt>'''</div>
<blockquote>
This is used to provide the decoded data back into the backend. '''<tt>startsample</tt>''' and '''<tt>endsample</tt>''' specify the absolute sample numbers of where this item (e.g. an annotation) starts and ends. '''<tt>output_id</tt>''' is an output identifier returned by the '''<tt>[[#register-function|register()]]</tt>''' function.
The '''<tt>data</tt>''' parameter's contents depend on the output type ('''<tt>output_id</tt>'''):
* '''OUTPUT_ANN''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the annotation index (determined by the order of items in '''<tt>Decoder.annotations</tt>''', see [[#Decoder_registration|below]]), the second is a list of annotation strings. The strings should be longer and shorter versions of the same annotation text (sorted by length, longest first), which can be used by frontends to show different annotation texts depending on e.g. zoom level.
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['Start', 'St', 'S']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is "Start", "St", "S".
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['CRC']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is just "CRC" (the list containins only one item).
** Example: ''<tt>self.put(35, 9000, self.out_ann, [17, ['Registered Parameter Number', 'Reg Param Num', 'RPN', 'R']])</tt>'''
*** The emitted data spans samples 35 to 9000, is of type OUTPUT_ANN, the annotation index is 17, the list of annotations strings is "Registered Parameter Number", "Reg Param Num", "RPN", "R".
* '''OUTPUT_PYTHON''': The '''<tt>data</tt>''' parameter is any arbitrary Python object that will be passed to stacked decoders. The format and contents are entirely decoder-dependent. Typically a Python list with various contents is passed to the stacked PDs.
** Example: ''<tt>self.put(10, 20, self.out_python, ['PACKET', ['Foo', 19.7, [1, 2, 3], ('bar', 'baz')]])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_PYTHON, the data contents themselves are entirely dependent on the respective decoder and should be documented in its [[Protocol_decoder_HOWTO#pd.py|pd.py]] file.
* '''OUTPUT_BINARY''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the binary format's index (determined by the order of items in '''<tt>Decoder.binary</tt>''', see [[#Decoder_registration|below]]), the second is a Python [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''] object.
** Example: ''<tt>self.put(10, 20, self.out_binary, [4, b'\xfe\x55\xaa'])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_BINARY, the binary format's index is 4, the emitted bytes are 0xfe, 0x55, 0xaa.
* '''OUTPUT_META''': The '''<tt>data</tt>''' parameter is a Python object of a certain type, as defined in the respective '''<tt>[[#register-function|register()]]</tt>''' function.
** Example: ''<tt>self.put(10, 20, self.out_meta, 15.7)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is a floating point number in this case.
** Example: ''<tt>self.put(10, 20, self.out_meta, 42)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is an integer number in this case.
</blockquote>

=== Decoder class functions ===

==== Required functions ====

* '''<tt>start(self)</tt>'''
<blockquote>
This function is called before the beginning of the decoding. This is the place to '''<tt>[[#register-function|register()]]</tt>''' the output types, check the user-supplied PD options for validity, and so on.
</blockquote>

* <div id="decode-and-wait-function-">'''<tt>decode(self)</tt>'''</div>
<blockquote>
'''In logic decoders''', this function is called by the [[libsigrokdecode]] backend to start the decoding.

It takes no arguments, but instead will enter an infinite loop and gets samples by calling the more versatile '''<tt>[[Protocol_decoder_API/Queries#self.wait()|wait()]]</tt>''' method. This frees specific protocol decoders from tedious yet common tasks like detecting edges, or sampling signals at specific points in time relative to the current position.

'''Note:''' This '''<tt>decode(self)</tt>''' method's signature has been introduced in version 3 of the protocol decoder API, in previous versions only '''<tt>decode(self, startsample, endsample, data)</tt>''' was available.

</blockquote>

* <div id="decode-function">'''<tt>decode(self, startsample, endsample, data)</tt>'''</div>
<blockquote>
'''In stacked decoders''', this is a function that is called by the [[libsigrokdecode]] backend whenever it has a chunk of data for the protocol decoder to handle.

{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Argument
!Description

|-
| '''<tt>startsample</tt>'''
| The absolute samplenumber of the first sample in this chunk of data.

|-
| '''<tt>endsample</tt>'''
| The absolute samplenumber of the last sample in this chunk of data.

|-
| '''<tt>data</tt>'''
| A list containing the data to decode. Depending on whether the decoder decodes raw samples or is stacked onto another decoder, this argument is:
* Raw samples ('''<tt>inputs = ['logic']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is a list of tuples containing the (absolute) sample number and the channels of that sample: '''<tt>[(samplenum, channels), (samplenum, channels), ...]</tt>'''.<br />
'''<tt>samplenum</tt>''' is the (absolute) number of the sample, an integer that takes the values from '''<tt>startsample</tt>''' to '''<tt>endsample</tt>''' - 1.<br />
The type of '''<tt>channels</tt>''' is [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''],
a sequence type whose length is the sum of the lengths of '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''
(in other words, '''<tt>channels</tt>''' contains a byte for every channel/optional channel).<br />
The order of the bytes is the same as the order of the channels in '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''.<br>
The individual bytes take the values '''<tt>0</tt>''' or '''<tt>1</tt>''', or some other value for optional channels that aren't supplied to the decoder.<br>
The [[Protocol_decoder_HOWTO#channels_.26_optional_channels|Protocol decoder HOWTO]] page contains an example how the data can be processed.
</blockquote>

* Stacked decoder ('''<tt>inputs = ['</tt>'''<id of some other decoder>'''<tt>']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is the '''<tt>OUTPUT_PYTHON</tt>''' output of the decoder this PD is stacked upon.
Its format depends on the implementation of the underlying decoder and should be documented there.
</blockquote>
|}

</blockquote>

==== Optional functions ====

* '''<tt>metadata(self, key, value)</tt>'''
<blockquote>
Used to pass the decoder metadata about the data stream. Currently the only value for '''<tt>key</tt>''' is '''<tt>sigrokdecode.SRD_CONF_SAMPLERATE</tt>''', '''<tt>value</tt>''' is then the sample rate of the data stream in Hz.
</blockquote>

=== Decoder registration ===

A PD's '''Decoder''' class must contain a few attributes specifying metadata about the PD. The following keys can be used:

<blockquote>
{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Key
!Description

|-
| '''<tt>api_version</tt>'''
| The libsigrokdecode API version which this module uses. This is currently either 2 or 3.

|-
| '''<tt>id</tt>'''
| A short unique identifier for this protocol decoder. It should be all-lowercase, and only contains a-z, 0-9 and underscores. This must match the PD's Python module name (subdirectory name in the '''decoders''' directory). The [[sigrok-cli]] tool uses this to specify PDs on the command-line. Examples: 'jtag', 'sdcard_spi', 'uart'.

|-
| '''<tt>name</tt>'''
| The name of the decoder. Used when listing available PDs. Examples: 'JTAG', 'SD card (SPI mode)', 'UART'.

|-
| '''<tt>longname</tt>'''
| The (long) name of the decoder. Used when listing available PDs. Example: 'Joint Test Action Group (IEEE 1149.1)', 'Secure Digital card (SPI mode)', 'Universal Asynchronous Receiver/Transmitter'.

|-
| '''<tt>desc</tt>'''
| A freeform one-line description of the decoder. Used when listing available PDs. Should end with a full stop. Example: 'Protocol for testing, debugging, and flashing ICs.', 'Secure Digital card (SPI mode) low-level protocol.', 'Asynchronous, serial bus.'.

|-
| '''<tt>license</tt>'''
| The license under which the module is provided. This must be either '''<tt>gplv2+</tt>''' (meaning the GNU General Public License 2 or later), or '''<tt>gplv3+</tt>''' (GNU General Public License 3 or later). No other licenses for modules are permitted in libsigrokdecode.

|-
| '''<tt>inputs</tt>'''
| The list of types of input this decoder needs. If the decoder takes input from a logic analyzer driver, this should be set to '''<tt>logic</tt>''', which maps to SR_DF_LOGIC, the datafeed type. If it takes input from another PD, it should be set to the value of the '''<tt>outputs</tt>''' key of that PD. It should conform to the same rules as the '''<tt>id</tt>''' key (lowercase, no spaces, and so on).

|-
| '''<tt>outputs</tt>'''
| The list of types of output this decoder produces. If this decoder can feed decoded data back into the datafeed stream, its outputs will be identified with this key's value. It should conform to the same rules as the '''<tt>id</tt>''' key.

|-
| '''<tt>channels</tt>'''
| This key contains information about the channels (pins) that '''must''' be provided to this PD; the PD will not be able to work without them. For example, the [[Protocol_decoder:Spi|SPI]] decoder has to know which channel has the clock signal. This key contains a tuple of channel entries, where each entry is a Python dict with the keys '''id''', '''name''', and '''desc'''. Example: '''<tt>{'id': 'rx', 'name': 'RX', 'desc': 'UART receive line'}</tt>'''.

|-
| '''<tt>optional_channels</tt>'''
| The channels the PD can make use of, but are not strictly required. The key has the same format as that of the <tt>channels</tt> key above (a tuple of dicts). This tuple is allowed to be empty if the respective protocol decoder has no optional channels.

|-
| '''<tt>options</tt>'''
| A tuple describing the options for this decoder. Each tuple entry is a Python dict with the keys '''id''', '''desc''', '''default''', and '''values'''. Example: '''<tt>{'id': 'bitorder', 'desc': 'Bit order', 'default': 'msb-first', 'values': ('msb-first', 'lsb-first')}</tt>'''. This tuple can be empty, if the PD has no options.

|-
| '''<tt>annotations</tt>'''
| A list of annotation classes this protocol decoder can output. Elements of this list are tuples consisting of an identifier string and a human readable description string. The identifier string can be used in the options of [[sigrok-cli]] to select the specific annotation type, and should therefore not contain whitespace or special characters.

|-
| '''<tt>annotation_rows</tt>'''
| Annotation rows are used to group multiple annotation types together. The elements of this list are three element tuples consisting of:
* An annotation row ID (same naming rules as for other IDs).
* A human readable name/description string for the annotation row.
* A tuple containing the indices of the the annotation classes in the '''<tt>annotations</tt>''' tuple.
See the [[Protocol_decoder_HOWTO#annotations_.26_annotation_rows|example on the Protocol decoder HOWTO page]] for more information on this attribute.

|-
| '''<tt>binary</tt>'''
| A list of binary output types this protocol decoder can output, same format as the '''<tt>annotations</tt>''' list.

|}

</blockquote>

* <div id="register-function">'''<tt>register(output_type)</tt>'''</div>
<blockquote>
This function is used to register the output that will be generated by the decoder, its argument should be one of the '''<tt>OUTPUT_...</tt>''' constants described above. The function returns an identifier that can then be used as the '''<tt>output_id</tt>''' argument of the '''<tt>[[#put-function|put()]]</tt>''' function.
</blockquote>

See [[Protocol decoder HOWTO#pd.py|pd.py]] for an example.

[[Category:APIs]]

Protocol decoder API

2019-11-03T20:57:56Z

Jsolla:

This page describes how [[libsigrokdecode]] '''Protocol Decoders ([[Protocol decoders|PDs]])''' work.

See also [[Protocol decoder HOWTO]] for a quick introduction of how to write your own decoders.

See [[Protocol decoder API/Queries]] for changes to the decoder API in version 3. All decoders use this API now and the v2 API is no longer supported.

== Architecture ==

* All PDs are written in Python (>= 3.0).
* Every PD registers its name, description, capabilities, etc.
* PDs can be stacked, so the user can construct a decoding pipeline/stack. The control of communication to/from PDs is done by the backend code in libsigrokdecode.
* The sample data passed into the PDs will be streamed/chunked, so they can run in real time as the data comes in from the hardware (or from a file).
* In order to keep PDs simple, they don't have to deal with the intricacies of the datafeed packets.

The frontend passes sample data into libsigrokdecode and gets decoder output (of various types) from every PD in the stack. Which of these output types of which PDs are actually displayed to the user is a matter of configuration or selection by the user; it is possible, for example, to have [[sigrok-cli]] print only the top of the PD stack's annotation output on stdout.

== API ==

=== Backend library ===

A Python module called '''<tt>sigrokdecode</tt>''' is provided. Every protocol decoder must import this. It contains the following items:

* '''<tt>the Decoder object</tt>'''
<blockquote>
Every protocol decoder must subclass this object.
</blockquote>

* '''<tt>OUTPUT_ANN</tt>'''
<blockquote>
A constant used to register annotation output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. [[Sigrok-cli|sigrok-cli]] shows the annotation output of a decoder stack's topmost decoder (per default), [[PulseView]] shows annotation output as graphical boxes or as circles (if the duration of the annotation is zero).
</blockquote>
* '''<tt>OUTPUT_PYTHON</tt>'''
<blockquote>
A constant used to register Python output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. Python output is passed as input to a decoder that is stacked onto the current decoder. The format of the data that is given to the '''<tt>[[#put-function|put()]]</tt>''' function is specific to a certain PD and should be documented for the authors of the higher level decoders, for example with a comment at the top of the decoder's source file.
</blockquote>
* '''<tt>OUTPUT_BINARY</tt>'''
<blockquote>
A constant used to register binary output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. The format of the data that is outputted is not specified, it's up to the author of the decoder to choose one (or multiple) appropriate format(s). For example, the [[Protocol_decoder:Uart|UART]] decoder outputs the raw bytes that it decodes, the [[Protocol_decoder:I2s|I²S]] decoder outputs the audio in WAV format, but the output could also be an image (JPG, PNG, other) file for a decoder that decodes a display protocol, a PCAP file for network/USB decoders, or one of [[Protocol decoder output|many other]] formats. [[Sigrok-cli|sigrok-cli]] can be used to redirect the binary output of a decoder into a file (or to pipe it into other applications), see the documentation of its '''--protocol-decoder-binary''' ('''-B''') option.
</blockquote>
* '''<tt>OUTPUT_META</tt>'''
<blockquote>
A constant used to register metadata output, used as argument to the '''<tt>[[#register-function|register()]]</tt>''' function. An example for a PD that outputs metadata is the SPI decoder that uses it to output the detected bitrate. See [[Protocol decoder output]] for various other possible examples.
</blockquote>

* <div id="put-function">'''<tt>put(startsample, endsample, output_id, data)</tt>'''</div>
<blockquote>
This is used to provide the decoded data back into the backend. '''<tt>startsample</tt>''' and '''<tt>endsample</tt>''' specify the absolute sample numbers of where this item (e.g. an annotation) starts and ends. '''<tt>output_id</tt>''' is an output identifier returned by the '''<tt>[[#register-function|register()]]</tt>''' function.
The '''<tt>data</tt>''' parameter's contents depend on the output type ('''<tt>output_id</tt>'''):
* '''OUTPUT_ANN''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the annotation index (determined by the order of items in '''<tt>Decoder.annotations</tt>''', see [[#Decoder_registration|below]]), the second is a list of annotation strings. The strings should be longer and shorter versions of the same annotation text (sorted by length, longest first), which can be used by frontends to show different annotation texts depending on e.g. zoom level.
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['Start', 'St', 'S']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is "Start", "St", "S".
** Example: ''<tt>self.put(10, 20, self.out_ann, [4, ['CRC']])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_ANN, the annotation index is 4, the list of annotations strings is just "CRC" (the list containins only one item).
** Example: ''<tt>self.put(35, 9000, self.out_ann, [17, ['Registered Parameter Number', 'Reg Param Num', 'RPN', 'R']])</tt>'''
*** The emitted data spans samples 35 to 9000, is of type OUTPUT_ANN, the annotation index is 17, the list of annotations strings is "Registered Parameter Number", "Reg Param Num", "RPN", "R".
* '''OUTPUT_PYTHON''': The '''<tt>data</tt>''' parameter is any arbitrary Python object that will be passed to stacked decoders. The format and contents are entirely decoder-dependent. Typically a Python list with various contents is passed to the stacked PDs.
** Example: ''<tt>self.put(10, 20, self.out_python, ['PACKET', ['Foo', 19.7, [1, 2, 3], ('bar', 'baz')]])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_PYTHON, the data contents themselves are entirely dependent on the respective decoder and should be documented in its [[Protocol_decoder_HOWTO#pd.py|pd.py]] file.
* '''OUTPUT_BINARY''': The '''<tt>data</tt>''' parameter is a Python list with two items. The first item is the binary format's index (determined by the order of items in '''<tt>Decoder.binary</tt>''', see [[#Decoder_registration|below]]), the second is a Python [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''] object.
** Example: ''<tt>self.put(10, 20, self.out_binary, [4, b'\xfe\x55\xaa'])</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_BINARY, the binary format's index is 4, the emitted bytes are 0xfe, 0x55, 0xaa.
* '''OUTPUT_META''': The '''<tt>data</tt>''' parameter is a Python object of a certain type, as defined in the respective '''<tt>[[#register-function|register()]]</tt>''' function.
** Example: ''<tt>self.put(10, 20, self.out_meta, 15.7)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is a floating point number in this case.
** Example: ''<tt>self.put(10, 20, self.out_meta, 42)</tt>'''
*** The emitted data spans samples 10 to 20, is of type OUTPUT_META, the data itself is an integer number in this case.
</blockquote>

=== Decoder class functions ===

==== Required functions ====

* '''<tt>start(self)</tt>'''
<blockquote>
This function is called before the beginning of the decoding. This is the place to '''<tt>[[#register-function|register()]]</tt>''' the output types, check the user-supplied PD options for validity, and so on.
</blockquote>

* <div id="decode-function">'''<tt>decode(self, startsample, endsample, data)</tt>'''</div>
<blockquote>
This is a function that is called by the [[libsigrokdecode]] backend whenever it has a chunk of data for the protocol decoder to handle.

{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Argument
!Description

|-
| '''<tt>startsample</tt>'''
| The absolute samplenumber of the first sample in this chunk of data.

|-
| '''<tt>endsample</tt>'''
| The absolute samplenumber of the last sample in this chunk of data.

|-
| '''<tt>data</tt>'''
| A list containing the data to decode. Depending on whether the decoder decodes raw samples or is stacked onto another decoder, this argument is:
* Raw samples ('''<tt>inputs = ['logic']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is a list of tuples containing the (absolute) sample number and the channels of that sample: '''<tt>[(samplenum, channels), (samplenum, channels), ...]</tt>'''.<br />
'''<tt>samplenum</tt>''' is the (absolute) number of the sample, an integer that takes the values from '''<tt>startsample</tt>''' to '''<tt>endsample</tt>''' - 1.<br />
The type of '''<tt>channels</tt>''' is [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''],
a sequence type whose length is the sum of the lengths of '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''
(in other words, '''<tt>channels</tt>''' contains a byte for every channel/optional channel).<br />
The order of the bytes is the same as the order of the channels in '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''.<br>
The individual bytes take the values '''<tt>0</tt>''' or '''<tt>1</tt>''', or some other value for optional channels that aren't supplied to the decoder.<br>
The [[Protocol_decoder_HOWTO#channels_.26_optional_channels|Protocol decoder HOWTO]] page contains an example how the data can be processed.
</blockquote>

* Stacked decoder ('''<tt>inputs = ['</tt>'''<id of some other decoder>'''<tt>']</tt>'''):
<blockquote>
'''<tt>data</tt>''' is the '''<tt>OUTPUT_PYTHON</tt>''' output of the decoder this PD is stacked upon.
Its format depends on the implementation of the underlying decoder and should be documented there.
</blockquote>
|}

</blockquote>

'''Note'''

When writing a logic decoder, please note the '''<tt>decode()</tt>''' method's signature has changed in version 3 of the protocol decoder API. It takes no arguments, but instead will enter an infinite loop and gets samples by calling the more versatile '''<tt>wait()</tt>''' method. This frees specific protocol decoders from tedious yet common tasks like detecting edges, or sampling signals at specific points in time relative to the current position.

When writing a stacked decoder, the '''<tt>decode(self, startsample, endsample, data)</tt>''' is still valid.

==== Optional functions ====

* '''<tt>metadata(self, key, value)</tt>'''
<blockquote>
Used to pass the decoder metadata about the data stream. Currently the only value for '''<tt>key</tt>''' is '''<tt>sigrokdecode.SRD_CONF_SAMPLERATE</tt>''', '''<tt>value</tt>''' is then the sample rate of the data stream in Hz.
</blockquote>

=== Decoder registration ===

A PD's '''Decoder''' class must contain a few attributes specifying metadata about the PD. The following keys can be used:

<blockquote>
{| border="0" style="font-size: smaller;" class="alternategrey sortable sigroktable"
|-
!style="width: 8em;" | Key
!Description

|-
| '''<tt>api_version</tt>'''
| The libsigrokdecode API version which this module uses. This is currently either 2 or 3.

|-
| '''<tt>id</tt>'''
| A short unique identifier for this protocol decoder. It should be all-lowercase, and only contains a-z, 0-9 and underscores. This must match the PD's Python module name (subdirectory name in the '''decoders''' directory). The [[sigrok-cli]] tool uses this to specify PDs on the command-line. Examples: 'jtag', 'sdcard_spi', 'uart'.

|-
| '''<tt>name</tt>'''
| The name of the decoder. Used when listing available PDs. Examples: 'JTAG', 'SD card (SPI mode)', 'UART'.

|-
| '''<tt>longname</tt>'''
| The (long) name of the decoder. Used when listing available PDs. Example: 'Joint Test Action Group (IEEE 1149.1)', 'Secure Digital card (SPI mode)', 'Universal Asynchronous Receiver/Transmitter'.

|-
| '''<tt>desc</tt>'''
| A freeform one-line description of the decoder. Used when listing available PDs. Should end with a full stop. Example: 'Protocol for testing, debugging, and flashing ICs.', 'Secure Digital card (SPI mode) low-level protocol.', 'Asynchronous, serial bus.'.

|-
| '''<tt>license</tt>'''
| The license under which the module is provided. This must be either '''<tt>gplv2+</tt>''' (meaning the GNU General Public License 2 or later), or '''<tt>gplv3+</tt>''' (GNU General Public License 3 or later). No other licenses for modules are permitted in libsigrokdecode.

|-
| '''<tt>inputs</tt>'''
| The list of types of input this decoder needs. If the decoder takes input from a logic analyzer driver, this should be set to '''<tt>logic</tt>''', which maps to SR_DF_LOGIC, the datafeed type. If it takes input from another PD, it should be set to the value of the '''<tt>outputs</tt>''' key of that PD. It should conform to the same rules as the '''<tt>id</tt>''' key (lowercase, no spaces, and so on).

|-
| '''<tt>outputs</tt>'''
| The list of types of output this decoder produces. If this decoder can feed decoded data back into the datafeed stream, its outputs will be identified with this key's value. It should conform to the same rules as the '''<tt>id</tt>''' key.

|-
| '''<tt>channels</tt>'''
| This key contains information about the channels (pins) that '''must''' be provided to this PD; the PD will not be able to work without them. For example, the [[Protocol_decoder:Spi|SPI]] decoder has to know which channel has the clock signal. This key contains a tuple of channel entries, where each entry is a Python dict with the keys '''id''', '''name''', and '''desc'''. Example: '''<tt>{'id': 'rx', 'name': 'RX', 'desc': 'UART receive line'}</tt>'''.

|-
| '''<tt>optional_channels</tt>'''
| The channels the PD can make use of, but are not strictly required. The key has the same format as that of the <tt>channels</tt> key above (a tuple of dicts). This tuple is allowed to be empty if the respective protocol decoder has no optional channels.

|-
| '''<tt>options</tt>'''
| A tuple describing the options for this decoder. Each tuple entry is a Python dict with the keys '''id''', '''desc''', '''default''', and '''values'''. Example: '''<tt>{'id': 'bitorder', 'desc': 'Bit order', 'default': 'msb-first', 'values': ('msb-first', 'lsb-first')}</tt>'''. This tuple can be empty, if the PD has no options.

|-
| '''<tt>annotations</tt>'''
| A list of annotation classes this protocol decoder can output. Elements of this list are tuples consisting of an identifier string and a human readable description string. The identifier string can be used in the options of [[sigrok-cli]] to select the specific annotation type, and should therefore not contain whitespace or special characters.

|-
| '''<tt>annotation_rows</tt>'''
| Annotation rows are used to group multiple annotation types together. The elements of this list are three element tuples consisting of:
* An annotation row ID (same naming rules as for other IDs).
* A human readable name/description string for the annotation row.
* A tuple containing the indices of the the annotation classes in the '''<tt>annotations</tt>''' tuple.
See the [[Protocol_decoder_HOWTO#annotations_.26_annotation_rows|example on the Protocol decoder HOWTO page]] for more information on this attribute.

|-
| '''<tt>binary</tt>'''
| A list of binary output types this protocol decoder can output, same format as the '''<tt>annotations</tt>''' list.

|}

</blockquote>

* <div id="register-function">'''<tt>register(output_type)</tt>'''</div>
<blockquote>
This function is used to register the output that will be generated by the decoder, its argument should be one of the '''<tt>OUTPUT_...</tt>''' constants described above. The function returns an identifier that can then be used as the '''<tt>output_id</tt>''' argument of the '''<tt>[[#put-function|put()]]</tt>''' function.
</blockquote>

See [[Protocol decoder HOWTO#pd.py|pd.py]] for an example.

[[Category:APIs]]

Protocol decoders

2019-11-03T20:22:49Z

Jsolla:

This is a list of '''supported protocol decoders (PDs)''' and '''decoders which we might want to write in the future''' (or users might want to contribute).

See [[Protocol decoder API]] for details on how the decoders work in sigrok, and [[Protocol decoder HOWTO]] for a quick introduction about how to write your own decoders.

== Supported protocol decoders ==



Number of currently supported protocol decoders: '''102'''.

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
!Protocol
!Tags
!Input IDs
!Output IDs
!Status
!Full name
!Description

{{pd|ac97|AC '97|Audio Codec '97|Audio and modem control for PC systems.|Audio, PC|logic|—|supported}}
{{pd|ade77xx|ADE77xx|Analog Devices ADE77xx|Poly phase multifunction energy metering IC protocol.|Analog/digital, IC, Sensor|spi|—|supported}}
{{pd|adf435x|ADF435x|Analog Devices ADF4350/1|Wideband synthesizer with integrated VCO.|Clock/timing, IC, Wireless/RF|spi|—|supported}}
{{pd|adns5020|ADNS-5020|Avago ADNS-5020|Bidirectional optical mouse sensor protocol.|IC, PC, Sensor|spi|—|supported}}
{{pd|am230x|AM230x|Aosong AM230x/DHTxx/RHTxx|Aosong AM230x/DHTxx/RHTxx humidity/temperature sensor.|IC, Sensor|logic|—|supported}}
{{pd|arm_etmv3|ARM ETMv3|ARM Embedded Trace Macroblock v3|ARM ETM v3 instruction trace protocol.|Debug/trace|uart|—|supported}}
{{pd|arm_itm|ARM ITM|ARM Instrumentation Trace Macroblock|ARM Cortex-M / ARMv7m ITM trace protocol.|Debug/trace|uart|—|supported}}
{{pd|arm_tpiu|ARM TPIU|ARM Trace Port Interface Unit|Filter TPIU formatted trace data into separate streams.|Debug/trace|uart|uart|supported}}
{{pd|atsha204a|ATSHA204A|Microchip ATSHA204A|Microchip ATSHA204A family crypto authentication protocol.|Security/crypto, IC, Memory|i2c|—|supported}}
{{pd|aud|AUD|Advanced User Debugger|Renesas/Hitachi Advanced User Debugger (AUD) protocol.|Debug/trace|logic|—|supported}}
{{pd|avr_isp|AVR ISP|AVR In-System Programming|Atmel AVR In-System Programming (ISP) protocol.|Debug/trace|spi|—|supported}}
{{pd|avr_pdi|AVR PDI|Atmel Program and Debug Interface|Atmel ATxmega Program and Debug Interface (PDI) protocol.|Debug/trace|logic|—|supported}}
{{pd|can|CAN|Controller Area Network|Field bus protocol for distributed realtime control.|Automotive|logic|—|supported}}
{{pd|cc1101|CC1101|Texas Instruments CC1101|Low-power sub-1GHz RF transceiver chip.|IC, Wireless/RF|spi|—|supported}}
{{pd|cec|CEC|HDMI-CEC|HDMI Consumer Electronics Control (CEC) protocol.|Display, PC|logic|—|supported}}
{{pd|cfp|CFP|100 Gigabit C form-factor pluggable|100 Gigabit C form-factor pluggable (CFP) protocol.|Networking|mdio|—|supported}}
{{pd|counter|Counter|Edge counter|Count the number of edges in a signal.|Util|logic|—|supported}}
{{pd|dali|DALI|Digital Addressable Lighting Interface|Digital Addressable Lighting Interface (DALI) protocol.|Embedded/industrial, Lighting|logic|—|supported}}
{{pd|dcf77|DCF77|DCF77 time protocol|European longwave time signal (77.5kHz carrier signal).|Clock/timing|logic|—|supported}}
{{pd|dmx512|DMX512|Digital MultipleX 512|Digital MultipleX 512 (DMX512) lighting protocol.|Embedded/industrial, Lighting|logic|—|supported}}
{{pd|ds1307|DS1307|Dallas DS1307|Dallas DS1307 realtime clock module protocol.|Clock/timing, IC|i2c|—|supported}}
{{pd|ds2408|DS2408|Maxim DS2408|1-Wire 8-channel addressable switch.|Embedded/industrial, IC|onewire_network|—|supported}}
{{pd|ds243x|DS243x|Maxim DS2432/3|Maxim DS243x series 1-Wire EEPROM protocol.|IC, Memory|onewire_network|—|supported}}
{{pd|ds28ea00|DS28EA00|Maxim DS28EA00 1-Wire digital thermometer|1-Wire digital thermometer with Sequence Detect and PIO.|IC, Sensor|onewire_network|—|supported}}
{{pd|dsi|DSI|Digital Serial Interface|Digital Serial Interface (DSI) lighting protocol.|Embedded/industrial, Lighting|logic|—|supported}}
{{pd|edid|EDID|Extended Display Identification Data|Data structure describing display device capabilities.|Display, Memory, PC|i2c|—|supported}}
{{pd|eeprom24xx|24xx EEPROM|24xx I²C EEPROM|24xx series I²C EEPROM protocol.|IC, Memory|i2c|—|supported}}
{{pd|eeprom93xx|93xx EEPROM|93xx Microwire EEPROM|93xx series Microwire EEPROM protocol.|IC, Memory|microwire|—|supported}}
{{pd|em4100|EM4100|RFID EM4100|EM4100 100-150kHz RFID protocol.|IC, RFID|logic|—|supported}}
{{pd|em4305|EM4305|RFID EM4205/EM4305|EM4205/EM4305 100-150kHz RFID protocol.|IC, RFID|logic|—|supported}}
{{pd|enc28j60|ENC28J60|Microchip ENC28J60|Microchip ENC28J60 10Base-T Ethernet controller protocol.|Embedded/industrial, Networking|spi|—|supported}}
{{pd|gpib|GPIB|General Purpose Interface Bus|IEEE-488 General Purpose Interface Bus (GPIB / HPIB).|PC|logic|—|supported}}
{{pd|graycode|Gray code|Gray code and rotary encoder|Accumulate rotary encoder increments, provide statistics.|Encoding|logic|—|supported}}
{{pd|guess_bitrate|Guess bitrate|Guess bitrate/baudrate|Guess the bitrate/baudrate of a UART (or other) protocol.|Clock/timing, Util|logic|—|supported}}
{{pd|i2c|I²C|Inter-Integrated Circuit|Two-wire, multi-master, serial bus.|Embedded/industrial|logic|i2c|supported}}
{{pd|i2cdemux|I²C demux|I²C demultiplexer|Demux I²C packets into per-slave-address streams.|Util|i2c|—|supported}}
{{pd|i2cfilter|I²C filter|I²C filter|Filter out addresses/directions in an I²C stream.|Util|i2c|i2c|supported}}
{{pd|i2s|I²S|Integrated Interchip Sound|Serial bus for connecting digital audio devices.|Audio, PC|logic|i2s|supported}}
{{pd|iec|IEC|Commodore IEC bus|Commodore serial IEEE-488 (IEC) bus protocol.|PC, Retro computing|logic|—|supported}}
{{pd|ir_nec|IR NEC|IR NEC|NEC infrared remote control protocol.|IR|logic|—|supported}}
{{pd|ir_rc5|IR RC-5|IR RC-5|RC-5 infrared remote control protocol.|IR|logic|—|supported}}
{{pd|jitter|Jitter|Timing jitter calculation|Retrieves the timing jitter between two digital signals.|Clock/timing, Util|logic|—|supported}}
{{pd|jtag|JTAG|Joint Test Action Group (IEEE 1149.1)|Protocol for testing, debugging, and flashing ICs.|Debug/trace|logic|jtag|supported}}
{{pd|jtag_ejtag|JTAG / EJTAG|Joint Test Action Group / EJTAG (MIPS)|MIPS EJTAG protocol.|Debug/trace|jtag|—|supported}}
{{pd|jtag_stm32|JTAG / STM32|Joint Test Action Group / ST STM32|ST STM32-specific JTAG protocol.|Debug/trace|jtag|—|supported}}
{{pd|lin|LIN|Local Interconnect Network|Local Interconnect Network (LIN) protocol.|Automotive|uart|—|supported}}
{{pd|lm75|LM75|National LM75|National LM75 (and compatibles) temperature sensor.|Sensor|i2c|—|supported}}
{{pd|lpc|LPC|Low Pin Count|Protocol for low-bandwidth devices on PC mainboards.|PC|logic|—|supported}}
{{pd|maple_bus|Maple bus|SEGA Maple bus|Maple bus peripheral protocol for SEGA Dreamcast.|Retro computing|logic|—|supported}}
{{pd|max7219|MAX7219|Maxim MAX7219/MAX7221|Maxim MAX72xx series 8-digit LED display driver.|Display|spi|—|supported}}
{{pd|mcs48|MCS-48|Intel MCS-48|Intel MCS-48 external memory access protocol.|Retro computing|logic|—|supported}}
{{pd|mdio|MDIO|Management Data Input/Output|MII management bus between MAC and PHY.|Networking|logic|mdio|supported}}
{{pd|microwire|Microwire|Microwire|3-wire, half-duplex, synchronous serial bus.|Embedded/industrial|logic|microwire|supported}}
{{pd|midi|MIDI|Musical Instrument Digital Interface|Musical Instrument Digital Interface (MIDI) protocol.|Audio, PC|uart|—|supported}}
{{pd|miller|Miller|Miller encoding|Miller encoding protocol.|Encoding|logic|—|supported}}
{{pd|mlx90614|MLX90614|Melexis MLX90614|Melexis MLX90614 infrared thermometer protocol.|IC, Sensor|i2c|—|supported}}
{{pd|modbus|Modbus|Modbus RTU over RS232/RS485|Modbus RTU protocol for industrial applications.|Embedded/industrial|uart|modbus|supported}}
{{pd|morse|Morse|Morse code|Demodulated morse code protocol.|Encoding|logic|—|supported}}
{{pd|mrf24j40|MRF24J40|Microchip MRF24J40|IEEE 802.15.4 2.4 GHz RF tranceiver chip.|IC, Wireless/RF|spi|—|supported}}
{{pd|mxc6225xu|MXC6225XU|MEMSIC MXC6225XU|Digital Thermal Orientation Sensor (DTOS) protocol.|IC, Sensor|i2c|—|supported}}
{{pd|nrf24l01|nRF24L01(+)|Nordic Semiconductor nRF24L01(+)|2.4GHz RF transceiver chip.|IC, Wireless/RF|spi|—|supported}}
{{pd|nunchuk|Nunchuk|Nintendo Wii Nunchuk|Nintendo Wii Nunchuk controller protocol.|Sensor|i2c|—|supported}}
{{pd|onewire_link|1-Wire link layer|1-Wire serial communication bus (link layer)|Bidirectional, half-duplex, asynchronous serial bus.|Embedded/industrial|logic|onewire_link|supported}}
{{pd|onewire_network|1-Wire network layer|1-Wire serial communication bus (network layer)|Bidirectional, half-duplex, asynchronous serial bus.|Embedded/industrial|onewire_link|onewire_network|supported}}
{{pd|ook|OOK|On-off keying|On-off keying protocol.|Encoding|logic|ook|supported}}
{{pd|ook_oregon|Oregon|Oregon Scientific|Oregon Scientific weather sensor protocol.|Sensor|ook|—|supported}}
{{pd|ook_vis|OOK visualisation|On-off keying visualisation|OOK visualisation in various formats.|Encoding|ook|ook|supported}}
{{pd|pan1321|PAN1321|Panasonic PAN1321|Bluetooth RF module with Serial Port Profile (SPP).|Wireless/RF|uart|—|supported}}
{{pd|parallel|Parallel|Parallel sync bus|Generic parallel synchronous bus.|Util|logic|parallel|supported}}
{{pd|pca9571|PCA9571|NXP PCA9571|NXP PCA9571 8-bit I²C output expander.|Embedded/industrial, IC|i2c|—|supported}}
{{pd|ps2|PS/2|PS/2|PS/2 keyboard/mouse interface.|PC|logic|—|supported}}
{{pd|pwm|PWM|Pulse-width modulation|Analog level encoded in duty cycle percentage.|Encoding|logic|—|supported}}
{{pd|qi|Qi|Qi charger protocol|Protocol used by Qi receiver.|Embedded/industrial, Wireless/RF|logic|—|supported}}
{{pd|rc_encode|RC encode|Remote control encoder|PT2262/HX2262/SC5262 remote control encoder protocol.|IC, IR|logic|—|supported}}
{{pd|rfm12|RFM12|HopeRF RFM12|HopeRF RFM12 wireless transceiver control protocol.|Wireless/RF|spi|—|supported}}
{{pd|rgb_led_spi|RGB LED (SPI)|RGB LED string decoder (SPI)|RGB LED string protocol (RGB values clocked over SPI).|Display|spi|—|supported}}
{{pd|rgb_led_ws281x|RGB LED (WS281x)|RGB LED string decoder (WS281x)|RGB LED string protocol (WS281x).|Display, IC|logic|—|supported}}
{{pd|rtc8564|RTC-8564|Epson RTC-8564 JE/NB|Realtime clock module protocol.|Clock/timing|i2c|—|supported}}
{{pd|sda2506|SDA2506|Siemens SDA 2506-5|Serial nonvolatile 1-Kbit EEPROM.|IC, Memory|logic|—|supported}}
{{pd|sdcard_sd|SD card (SD mode)|Secure Digital card (SD mode)|Secure Digital card (SD mode) low-level protocol.|Memory|logic|—|supported}}
{{pd|sdcard_spi|SD card (SPI mode)|Secure Digital card (SPI mode)|Secure Digital card (SPI mode) low-level protocol.|Memory|spi|—|supported}}
{{pd|spdif|S/PDIF|Sony/Philips Digital Interface Format|Serial bus for connecting digital audio devices.|Audio, PC|logic|—|supported}}
{{pd|spi|SPI|Serial Peripheral Interface|Full-duplex, synchronous, serial bus.|Embedded/industrial|logic|spi|supported}}
{{pd|spiflash|SPI flash|SPI flash chips|xx25 series SPI (NOR) flash chip protocol.|IC, Memory|spi|—|supported}}
{{pd|ssi32|SSI32|Synchronous Serial Interface (32bit)|Synchronous Serial Interface (32bit) protocol.|Embedded/industrial|spi|—|supported}}
{{pd|st7735|ST7735|Sitronix ST7735|Sitronix ST7735 TFT controller protocol.|Display, IC|logic|—|supported}}
{{pd|stepper_motor|Stepper motor|Stepper motor position / speed|Absolute position and movement speed from step/dir.|Embedded/industrial|logic|—|supported}}
{{pd|swd|SWD|Serial Wire Debug|Two-wire protocol for debug access to ARM CPUs.|Debug/trace|logic|swd|supported}}
{{pd|swim|SWIM|STM8 SWIM bus|STM8 Single Wire Interface Module (SWIM) protocol.|Debug/trace|logic|—|supported}}
{{pd|t55xx|T55xx|RFID T55xx|T55xx 100-150kHz RFID protocol.|IC, RFID|logic|—|supported}}
{{pd|tca6408a|TI TCA6408A|Texas Instruments TCA6408A|Texas Instruments TCA6408A 8-bit I²C I/O expander.|Embedded/industrial, IC|i2c|—|supported}}
{{pd|timing|Timing|Timing calculation with frequency and averaging|Calculate time between edges.|Clock/timing, Util|logic|—|supported}}
{{pd|tlc5620|TI TLC5620|Texas Instruments TLC5620|Texas Instruments TLC5620 8-bit quad DAC.|IC, Analog/digital|logic|—|supported}}
{{pd|uart|UART|Universal Asynchronous Receiver/Transmitter|Asynchronous, serial bus.|Embedded/industrial|logic|uart|supported}}
{{pd|usb_packet|USB packet|Universal Serial Bus (LS/FS) packet|USB (low-speed and full-speed) packet protocol.|PC|usb_signalling|usb_packet|supported}}
{{pd|usb_power_delivery|USB PD|USB Power Delivery|USB Power Delivery protocol.|PC|logic|usb_pd|supported}}
{{pd|usb_request|USB request|Universal Serial Bus (LS/FS) transaction/request|USB (low-speed/full-speed) transaction/request protocol.|PC|usb_packet|usb_request|supported}}
{{pd|usb_signalling|USB signalling|Universal Serial Bus (LS/FS) signalling|USB (low-speed/full-speed) signalling protocol.|PC|logic|usb_signalling|supported}}
{{pd|wiegand|Wiegand|Wiegand interface|Wiegand interface for electronic entry systems.|Embedded/industrial, RFID|logic|—|supported}}
{{pd|x2444m|X2444M/P|Xicor X2444M/P|Xicor X2444M/P nonvolatile static RAM protocol.|IC, Memory|spi|—|supported}}
{{pd|xfp|XFP|10 Gigabit Small Form Factor Pluggable Module (XFP)|XFP I²C management interface structures/protocol|Networking|i2c|—|supported}}
{{pd|z80|Z80|Zilog Z80 CPU|Zilog Z80 microprocessor disassembly.|Retro computing|logic|—|supported}}

|}

== Possible candidates for future protocol decoders ==

{| border="0" style="font-size: smaller" class="alternategrey sortable sigroktable"
|-
!Protocol
!Category
!Input ID(s)
!Output ID(s)
!Status
!Description
!Comments

|-
| SA8807A
| Displays
| spi
|
| bgcolor="red" | 0%
| SPI-attached LCD. Datasheet: [http://pdf1.alldatasheet.com/datasheet-pdf/view/36922/SAMES/SA8807A.html Sames SA8807A].
|

|-
| EA eDIPTFT43-A
| Displays
| i2c
|
| bgcolor="red" | 0%
| I2C-attached LCD. Datasheet: [http://www.lcd-module.de/pdf/grafik/ediptft43-a.pdf EA eDIPTFT43-A].
|

|-
| Analog Devices AD7291
| ADC
| i2c
|
| bgcolor="red" | 0%
| I2C-attached ADC. Datasheet: [http://pdf1.alldatasheet.com/datasheet-pdf/view/318172/AD/AD7291.html Analog Devices AD7291].
|

|-
| Analog Devices ADS1258
| ADC
| spi
| ads1258
| bgcolor="orange" | 0%
| SPI-attached ADC.
| Planned (Uwe Hermann).

|-
| Microchip MCP3901
| ADC
| spi
| mcp3901
| bgcolor="orange" | 0%
| Can be controlled via a parallel protocol, or SPI, or I2C.
| Planned (Uwe Hermann).

|-
| JTAG / TMPA9xx
| Flash/debug
| jtag
| jtag_tmpa9xx
| bgcolor="red" | 0%
| Toshiba TMPA9xx specific JTAG protocol details.
|

|-
| USB transfer
| USB
| usb_request
| usb_transfer
| bgcolor="red" | 0%
|
|

|-
| USB / HID
| USB
| usb_transfer
| usb_hid
| bgcolor="red" | 0%
|
|

|-
| USB / CDC
| USB
| usb_transfer
| usb_cdc
| bgcolor="red" | 0%
|
|

|-
| USB / USBTMC
| USB
| usb_transfer
| usb_usbtmc
| bgcolor="red" | 0%
|
|

|-
| Dallas DS1985
| Other
| onewire_network
|
| bgcolor="orange" | 0%
| Dallas DS1985 iButton (1-Wire) device.
| Planned (Uwe Hermann).

|-
| UNI/O
| Embedded
| —
|
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Synchronous_Serial_Interface SSI]
| Embedded
| —
|
| bgcolor="red" | 0%
| Synchronous Serial Interface
|

|-
| CompactFlash
| Memory
| —
|
| bgcolor="red" | 0%
|
|

|-
| MMC
| Memory
| —
|
| bgcolor="red" | 0%
|
|

|-
| Memory Stick
| Memory
| —
|
| bgcolor="red" | 0%
|
|

|-
| SmartMedia
| Memory
| —
|
| bgcolor="red" | 0%
|
|

|-
| xD-Picture Card
| Memory
| —
|
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/ISO/IEC_7816 ISO 7816]
| Smartcards
| —
|
| bgcolor="red" | 0%
|
|

|-
| FlexRay
| Automotive
| —
|
| bgcolor="yellow" | 99%
| [http://en.wikipedia.org/wiki/Flexray FlexRay] is an automotive network communications protocol.
| Work in progress ([[User:Stephan_Thiele|Stephan Thiele]]).

|-
| AVR TPI
| Flash/debug
| —
|
| bgcolor="red" | 0%
| Atmel Tiny Programming Interface (TPI) protocol.
|

|-
| FWH
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| ISA
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| PCI
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| SMBus
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| IDE
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| SCSI
| PC
| —
|
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Platform_Environment_Control_Interface PECI]
| PC
| —
|
| bgcolor="red" | 0%
| Platform Environment Control Interface
|

|-
| [https://en.wikipedia.org/wiki/SVID SVID]
| PC
| —
|
| bgcolor="red" | 0%
| Serial Voltage Identification
|

|-
| [[Protocol_decoder:mfm|MFM]]
| PC
| —
|
| bgcolor="yellow" | 90%
| Floppy disk FM and [https://en.wikipedia.org/wiki/Modified_Frequency_Modulation MFM].
| Work in progress (David Wiens).

|-
| HD Audio
| Audio
| —
|
| bgcolor="red" | 0%
|
|

|-
| Nokia NRC17
| IR
| —
|
| bgcolor="red" | 0%
|
|

|-
| Sony SIRC
| IR
| —
|
| bgcolor="red" | 0%
|
|

|-
| Philips RC-6
| IR
| —
|
| bgcolor="red" | 0%
|
|

|-
| Philips RC-MM
| IR
| —
|
| bgcolor="red" | 0%
|
|

|-
| Philips RECS80
| IR
| —
|
| bgcolor="red" | 0%
|
|

|-
| [http://en.wikipedia.org/wiki/Infrared_Data_Association IrDA]
| Misc
| —
|
| bgcolor="red" | 0%
|
|

|-
| HD44780
| Displays
| —
|
| bgcolor="red" | 0%
| [http://en.wikipedia.org/wiki/HD44780_Character_LCD HD44780 character LCD] protocol
|

|-
| 7-segment display
| Displays
| —
|
| bgcolor="red" | 0%
|
|

|-
| [[Protocol_decoder:Pcf8814|PCF8814]]
| Displays
| —
| pcf8814
| bgcolor="yellow" | 50%
| Philips PCF8814 65 x 96 pixels matrix LCD driver
| Work in progress (Uwe Hermann).

|-
| [[Protocol_decoder:Pcf8814_lcd|PCF8814 LCD]]
| Displays
| pcf8814
| pcf8814_lcd
| bgcolor="yellow" | 50%
| Philips PCF8814 65 x 96 pixels matrix LCD driver
| Work in progress (Uwe Hermann).

|-
| [https://en.wikipedia.org/wiki/RDM_%28lighting%29 RDM]
| Industrial Lighting
| —
| rdm
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/NMEA_0183 NMEA 0183]
| GPS
| uart
| nmea0183
| bgcolor="red" | 0%
|
|

|-
| [[Protocol_decoder:Nmea2000|NMEA2000]]
| Marine
| can
| nmea2000
| bgcolor="red" | 0%
| [https://en.wikipedia.org/wiki/NMEA_2000 NMEA 2000 Wikipedia page]
|

|-
| [https://en.wikipedia.org/wiki/Digital_Command_Control DCC]
| Trains
| —
| dcc
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Train_Communication_Network MVB]
| Trains
| —
| mvb
| bgcolor="red" | 0%
| Multifunction Vehicle Bus
|

|-
| [https://en.wikipedia.org/wiki/Train_Communication_Network WTB]
| Trains
| —
| wtb
| bgcolor="red" | 0%
| Wire Train Bus
|

|-
| [https://en.wikipedia.org/wiki/C-Bus_%28protocol%29 C-Bus]
| Home automation
| —
| cbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/X10_%28industry_standard%29 X10]
| Home automation
| —
| x10
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/LonWorks LonWorks]
| Home automation
| —
| lonworks
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/S-Bus S-Bus]
| Home automation
| —
| sbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Meter-Bus M-Bus]
| Automation
| —
| mbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Modbus Modbus ASCII]
| Automation
| uart
| modbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Modbus Modbus TCP]
| Automation
| ip
| modbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Highway_Addressable_Remote_Transducer_Protocol HART protocol]
| Automation
| —
| hart
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/INTERBUS INTERBUS]
| Automation
| —
| interbus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/DirectNET_Protocol DirectNET]
| Automation
| uart
| directnet
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/KNX_%28standard%29 KNX]
| Automation
| various
| knx
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Bacnet BACnet]
| Automation
|
| bacnet
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/OpenTherm OpenTherm]
| Automation
| —
| opentherm
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/EBUS_%28serial_buses%29 EBUS]
| Automation
| uart
| ebus
| bgcolor="red" | 0%
|
|

|-
| [https://en.wikipedia.org/wiki/Attachment_Unit_Interface AUI]
| Networking
| —
| aui
| bgcolor="red" | 0%
| Attachment Unit Interface
|

|-
| [https://en.wikipedia.org/wiki/Medium_Dependent_Interface MDI]
| Networking
| —
| mdi
| bgcolor="red" | 0%
| Medium Dependent Interface
|

|-
| [https://en.wikipedia.org/wiki/Media_Independent_Interface MII]
| Networking
| —
| mii
| bgcolor="red" | 0%
| Media Independent Interface
|

|-
| [https://en.wikipedia.org/wiki/Gigabit_Media_Independent_Interface#Gigabit_Media_Independent_Interface GMII]
| Networking
| —
| gmii
| bgcolor="red" | 0%
| Gigabit Media Independent Interface
|

|-
| [https://en.wikipedia.org/wiki/10_Gigabit_Media_Independent_Interface#10_Gigabit_Media_Independent_Interface XGMII]
| Networking
| —
| xgmii
| bgcolor="red" | 0%
| 10 Gigabit Media Independent Interface
|

|-
| [[Protocol_decoder:esp8266|ESP8266]]
| Wireless
| uart
| esp8266
| bgcolor="red" | 0%
| WiFi Serial Transceiver
|

|-
| [[Protocol Decoder:tmds|TMDS (HDMI / DVI Pixel Data)]]
| Display
| tmds
| —
| bgcolor="orange" | 1%
| https://github.com/mithro/tmds_encoding
| Work in progress ([[User:Mithro|mithro]])

|-
| [[Protocol Decoder:Easymatic|Easymatic]]
| Home automation
| uart
| easymatic
| bgcolor="red" | 10%
|
| Work in progress (Platypus)

|-
| [[Protocol Decoder:DDC/CI|DDC/CI]]
| PC
| i2c
| —
| bgcolor="red" | 0%
|
|

|-
| Kenwood VH
| Misc
| —
| —
| bgcolor="yellow" | 50%
| SYSTEM CONTROL protocol used by Kenwood's VH HiFi-system
| In progress: https://github.com/kripton/libsigrokdecode/compare/kenwood_vh

|-
| IEC 61131-9
| Industrial
| —
| —
| bgcolor="red" | 0%
| "Single-drop digital communication interface for small sensors and actuators (SDCI, marketed as IO-Link)" https://en.wikipedia.org/wiki/IEC_61131
|

|-
| NRZ encoding family
| —
| —
| —
| bgcolor="red" | 0%
| Non-Return-to-Zero and its [https://en.wikipedia.org/wiki/Non-return-to-zero#Variants variants]
| whoever wants it

|-
| Manchester encoding
| —
| —
| —
| bgcolor="red" | 0%
| [https://en.wikipedia.org/wiki/Manchester_code Manchester code]
| whoever wants it

|-
| Sony LANC
| —
| —
| —
| bgcolor="red" | 0%
| [http://www.boehmel.de/lanc.htm Sony LANC]
| whoever wants it, contact [[User:Alexdaniel|AlexDaniel]] for more info. You can already decode the raw data by using UART with 9600 baud and no parity, but it'd be better if pulseview displayed the meaning (as in what these commands do)

|-
| CAN-FD
| Automotive
| —
| can
| bgcolor="yellow" | 90%
| Controller Area Network with Flexible Data Rate
| Work in progress ([[User:Stephan_Thiele|Stephan Thiele]]).

|-
| nrf905
| IC, Wireless/RF
| spi
| nrf905
| bgcolor="yellow" | 90%
| 433/868/915 Mhz RF transceiver chip
| Work in progress ([[User:jsolla|Jorge Solla]]).
|}

__FORCETOC__

Protocol decoder:Cec

2019-11-03T17:30:27Z

Jsolla:

{{Infobox protocol decoder
| id = cec
| name = cec
| description = HDMI Consumer Electronics Control (CEC) protocol.
| status = supported
| license = GPLv2+
| source_code_dir = cec
| image = [[File:Cec_hdmi_pinout.png|250px]]
| input = logic
| output = cec
| probes = cec
}}

Consumer Electronics Control (CEC) is a feature of HDMI designed to allow users to command and control devices connected through HDMI

== Hardware ==

CEC Bus can be found in PIN 13 of the HDMI connector:

[[File:Cec_hdmi_pinout.png]]

== Protocol ==

It is a one-wire bidirectional serial bus that is based on the [https://en.wikipedia.org/wiki/European_Committee_for_Electrotechnical_Standardization CENELEC] standard AV.link protocol to perform remote control functions.

CEC is a separate electrical signal from the other HDMI signals. This allows a device to disable its high-speed HDMI circuitry in sleep mode, but be woken up by CEC. It is a single shared bus, which is directly connected between all HDMI ports on a device, so it can flow through a device which is completely powered off (not just asleep).

The bus is electrically identical to the AV.link protocol, but CEC adds a detailed higher-level message protocol.

The bus is an open-collector line, somewhat like I²C, passively pulled up to +3.3 V, and driven low to transmit a bit.

== Pulseview screenshots ==

<gallery widths=800px>
File:Cec_pulseview_ping_frames.png|<small>Ping (poll) frames</small>
File:cec_pulseview_vendor_command_frame.png|<small>Vendor command frame</small>
</gallery>

== Usage examples ==

'''Print all annotations (very verbose)'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC'''

cec-1: ST
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0x30
cec-1: EOM=N
cec-1: ACK
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0x04
cec-1: EOM=Y
cec-1: ACK
cec-1: 30:04
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK

'''Print frames only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=frames'''

cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 3f:82:10:00
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 30:44:6d
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:0d
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04

'''Print sections only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=sections'''

cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, Broadcast | OPC: ACTIVE_SOURCE | OPS: 0x10, 0x00 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: USER_CONTROL_PRESSED | OPS: 0x6d | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: TEXT_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK

== Current status ==

The CEC protocol decoder is capable of the following:

* Decoding all low level parts: START, BITs, EOM, ACK / NACK
* Resolve names of all logical addresses
* Resolve names of all opcodes
* Detect (and warn) timing errors
* Detect (and warn) misplaced bits, etc

Pending:

* Operands of the opcodes are not parsed, only printed.

[[Category:Protocol decoder]]

Protocol decoder:Cec

2019-11-03T17:26:13Z

Jsolla:

Protocol decoder:Cec

2019-11-03T17:25:50Z

Jsolla:

{{Infobox protocol decoder
| id = cec
| name = cec
| description = HDMI Consumer Electronics Control (CEC) protocol.
| status = supported
| license = GPLv2+
| source_code_dir = cec
| image = [[File:Cec_hdmi_pinout.png|250px]]
| input = logic
| output = cec
| probes = cec
}}

Consumer Electronics Control (CEC) is a feature of HDMI designed to allow users to command and control devices connected through HDMI

== Hardware ==

CEC Bus can be found in PIN 13 of the HDMI connector:

[[File:Cec_hdmi_pinout.png]]

== Protocol ==

It is a one-wire bidirectional serial bus that is based on the [https://en.wikipedia.org/wiki/European_Committee_for_Electrotechnical_Standardization CENELEC] standard AV.link protocol to perform remote control functions.

CEC is a separate electrical signal from the other HDMI signals. This allows a device to disable its high-speed HDMI circuitry in sleep mode, but be woken up by CEC. It is a single shared bus, which is directly connected between all HDMI ports on a device, so it can flow through a device which is completely powered off (not just asleep).

The bus is electrically identical to the AV.link protocol, but CEC adds a detailed higher-level message protocol.

The bus is an open-collector line, somewhat like I²C, passively pulled up to +3.3 V, and driven low to transmit a bit.

== Pulseview screenshots ==

<gallery widths=800px>
File:Cec_pulseview_ping_frames.png|<small>Ping (poll) frames</small>
File:cec_pulseview_vendor_command_frame.png|<small>Vendor command frame</small>
</gallery>

== Usage examples ==

'''Print all annotations (very verbose)'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC''

cec-1: ST
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0x30
cec-1: EOM=N
cec-1: ACK
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0x04
cec-1: EOM=Y
cec-1: ACK
cec-1: 30:04
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK

'''Print frames only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=frames'''

cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 3f:82:10:00
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 30:44:6d
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:0d
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04

'''Print sections only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=sections'''

cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, Broadcast | OPC: ACTIVE_SOURCE | OPS: 0x10, 0x00 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: USER_CONTROL_PRESSED | OPS: 0x6d | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: TEXT_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK

[[Category:Protocol decoder]]

Protocol decoder:Cec

2019-11-03T17:24:40Z

Jsolla:

{{Infobox protocol decoder
| id = cec
| name = cec
| description = HDMI Consumer Electronics Control (CEC) protocol.
| status = supported
| license = GPLv2+
| source_code_dir = cec
| image = [[File:Cec_hdmi_pinout.png|250px]]
| input = logic
| output = cec
| probes = cec
}}

Consumer Electronics Control (CEC) is a feature of HDMI designed to allow users to command and control devices connected through HDMI

== Hardware ==

CEC Bus can be found in PIN 13 of the HDMI connector:

[[File:Cec_hdmi_pinout.png]]

== Protocol ==

It is a one-wire bidirectional serial bus that is based on the [https://en.wikipedia.org/wiki/European_Committee_for_Electrotechnical_Standardization CENELEC] standard AV.link protocol to perform remote control functions.

CEC is a separate electrical signal from the other HDMI signals. This allows a device to disable its high-speed HDMI circuitry in sleep mode, but be woken up by CEC. It is a single shared bus, which is directly connected between all HDMI ports on a device, so it can flow through a device which is completely powered off (not just asleep).

The bus is electrically identical to the AV.link protocol, but CEC adds a detailed higher-level message protocol.

The bus is an open-collector line, somewhat like I²C, passively pulled up to +3.3 V, and driven low to transmit a bit.

== Pulseview screenshots ==

<gallery widths=800px>
File:Cec_pulseview_ping_frames.png|<small>Ping (poll) frames</small>
File:cec_pulseview_vendor_command_frame.png|<small>Vendor command frame</small>
</gallery>

== Usage examples ==

'''Print all annotations (very verbose)'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC'''

cec-1: ST
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0x30
cec-1: EOM=N
cec-1: ACK
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 0
cec-1: 1
cec-1: 0
cec-1: 0
cec-1: 0x04
cec-1: EOM=Y
cec-1: ACK
cec-1: 30:04
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK

'''Print frames only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=frames'''

cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 3f:82:10:00
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 30:44:6d
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:0d
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04
cec-1: 35
cec-1: 35
cec-1: 30:8f
cec-1: 03:90:01
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 35
cec-1: 30:04

'''Print sections only'''

'''sigrok-cli -i data.sr -P cec:CEC=CEC -A cec=sections'''

cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1 HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, Broadcast | OPC: ACTIVE_SOURCE | OPS: 0x10, 0x00 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, TV | OPC: USER_CONTROL_PRESSED | OPS: 0x6d | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: TEXT_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: IMAGE_VIEW_ON | R: ACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, AudioSystem | OPC: PING | R: NACK
cec-1: HDR: Tuner_1, TV | OPC: GIVE_DEVICE_POWER_STATUS | R: ACK
cec-1: HDR: TV, Tuner_1 | OPC: REPORT_POWER_STATUS | OPS: 0x01 | R: ACK

[[Category:Protocol decoder]]

File:Cec pulseview vendor command frame.png

2019-11-03T17:05:55Z

Jsolla: cec pulseview vendor command frame

== Summary ==
cec pulseview vendor command frame
== Licensing ==
{{PD}}

File:Cec pulseview ping frames.png

2019-11-03T17:05:23Z

Jsolla: cec protocol pulseview ping frames

== Summary ==
cec protocol pulseview ping frames
== Licensing ==
{{PD}}

Protocol decoder:Cec

2019-11-03T17:04:18Z

Jsolla: Created page with "{{Infobox protocol decoder | id = cec | name = cec | description = HDMI Consumer Electronics Control (CEC) protocol. | status = supported..."

{{Infobox protocol decoder
| id = cec
| name = cec
| description = HDMI Consumer Electronics Control (CEC) protocol.
| status = supported
| license = GPLv2+
| source_code_dir = cec
| image = [[File:|250px]]
| input = logic
| output = cec
| probes = cec
}}

== HDMI CEC protocol decoder ==

Sigrok protocol decoder for HDMI CEC (Consumer Electronics Control)

Consumer Electronics Control (CEC) is a feature of HDMI designed to allow users to command and control devices connected through HDMI

CEC Bus can be found in PIN 13 of the HDMI connector: