sigrok - User contributions [en]

Saleae Logic16

2023-05-23T21:03:13Z

Endolith: /* Firmware */ Got it working on all three OSes!

{{Infobox logic analyzer
| image = [[File:Saleae Logic16 bottom.png|180px]]
| name = Saleae Logic16
| status = supported
| source_code_dir = saleae-logic16
| channels = 3/6/9/16
| samplerate = 100/50/32/16MHz
| samplerate_state = —
| triggers = none (SW-only)
| voltages = -0.9V — 6V
| threshold = configurable: for 1.8V to 3.6V systems: VIH=1.4V, VIL=0.7V for 5V systems: VIH=3.6V, VIL=1.4V
| memory = none
| compression = yes
| website = [http://www.saleae.com/logic16/ saleae.com]
}}

The '''Saleae Logic16''' is a USB-based, 16-channel logic analyzer with 100/50/32/16MHz sampling rate (at 3/6/9/16 enabled channels).

The case requires a '''Torx T5''' screwdriver to open.

See [[Saleae Logic16/Info]] for more details (such as '''lsusb -v''' output) about the device.

See [[Saleae Logic]] for the predecessor product of the Saleae Logic16.

== Hardware ==

* '''FPGA''': [http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/silicon_devices/fpga/spartan-3a.html Xilinx Spartan-3A XC3S200A], 200K gates ([http://www.xilinx.com/support/documentation/data_sheets/ds529.pdf datasheeet])
* '''USB interface chip''': [http://www.cypress.com/?mpn=CY7C68013A-56PVXC Cypress CY7C68013A-56PVXC (FX2LP)] ([http://www.cypress.com/file/138911/download datasheet])
* '''Ultralow capacitance ESD protection''': 4x [http://www.st.com/web/catalog/sense_power/FM114/CL1137/SC1490/PF109008 ST DVIULC6-4SC6] ([http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00065974.pdf datasheet])
* '''2Kbit I2C EEPROM''': [http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010774 Microchip 24AA02] ([http://ww1.microchip.com/downloads/en/DeviceDoc/21709J.pdf datasheet]) (marking: "B2TH", starts with "B2" always, the last 2 characters are a "traceability code")
* '''2.5MHz, 1.5A synchronous step down switching regulator (1.2V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189C")
* '''2.5MHz, 1.5A synchronous step down switching regulator (3.3V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189Z")
* '''N-MOSFET''': 2x 2N7002 type MOSFET (marking: "72Y7"). Connected as "low-side" switch/LED driver and inverter.

'''Pinouts and connections:'''

'''JTAG header (FPGA):'''

The '''J3''' pin header is a JTAG connector wired to the FPGA. The pins are (from left to right, the right-most pin, pin number 1, is square):

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!5
!4
!3
!2
!1

|-
| GND
| TMS
| TCK
| TDO
| TDI

|}

'''Testpoints:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!T1
!T2
!T3

|-
| 1.2V
| 3.3V
| GND (FX2)

|}

'''Cypress FX2:'''


{{chip_56pin
| 1=(FPGA 15, IO_L05P_3) PD5
| 2=(FPGA 13, IO_L04N_3) PD6
| 3=(FPGA 10, IO_L03N_3) PD7
| 4=GND
| 5=(FPGA 90, IO_0) CLKOUT
| 6=VCC
| 7=GND
| 8=(FPGA 3, IO_L01P_3) RDY0/*SLRD
| 9=(FPGA 16, IO_L05N_3) RDY1/*SLWR
| 10=AVCC
| 11=(24MHz crystal) XTALOUT
| 12=(24MHz crystal) XTALIN
| 13=AGND
| 14=AVCC

| 15=(USB D+) DPLUS
| 16=(USB D-) DMINUS
| 17=AGND
| 18=VCC
| 19=GND
| 20=(FPGA 84, IO_L02N_0) *IFCLK
| 21=RESERVED
| 22=(EEPROM SCL) SCL
| 23=(EEPROM SDA) SDA
| 24=VCC
| 25=(FPGA 40, IO_L08P_2) PB0
| 26=(FPGA 78, IO_L01N_0) PB1
| 27=(FPGA 77, IO_L01P_0) PB2
| 28=(FPGA 49, IO_L10N_2) PB3

| 29=PB4 (FPGA 46, MOSI)
| 30=PB5 (FPGA 41, IO_L08N_2)
| 31=PB6 (FPGA 37, IO_L07N_2)
| 32=PB7 (FPGA 93, IO_L05P_0)
| 33=GND
| 34=VCC
| 35=GND
| 36=CTL0 (FPGA 94, IO_L05N_0)
| 37=CTL1 (FPGA 97, IP_0)
| 38=CTL2 (FPGA 100, PROG_B)
| 39=VCC
| 40=PA0 (FPGA 54, DONE)
| 41=PA1 (FPGA 48, INIT_B)
| 42=PA2 (FPGA 53, CCLK)

| 43=PA3 (FPGA 51, MISO)
| 44=PA4 (FPGA 98, IO_L06P_0)
| 45=PA5 (FPGA 85, IO_L03P_0)
| 46=PA6 (FPGA 30, IO_L04P_2)
| 47=PA7 (FPGA 9, IO_L03P_3)
| 48=GND
| 49=RESET# (3.3V via D2 (diode?))
| 50=VCC
| 51=*WAKEUP (3.3V)
| 52=PD0 (FPGA 6, IO_L02N_3)
| 53=PD1 (FPGA 4, IO_L01N_3)
| 54=PD2 (FPGA 5, IO_L02P_3)
| 55=PD3 (FPGA 44, IO_L09N_2)
| 56=PD4 (FPGA 12, IO_L04P_3)

}}


'''Other FPGA connections:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!28
|CH0
!52
|CH8
|-
!29
|CH1
!56
|CH9
|-
!32
|CH2
!57
|CH10
|-
!33
|CH3
!60
|CH11
|-
!34
|CH4
!61
|CH12
|-
!36
|CH5
!62
|CH13
|-
!43
|CH6
!64
|CH14
|-
!50
|CH7
!65
|CH15
|-
!73
|colspan="3"|LED (active low)
|}

== Photos ==

<gallery>
File:Saleae Logic16.jpg|Device, front
File:Saleae Logic16 bottom.jpg|Device, bottom
File:Saleae Logic16 PCB top.jpg|PCB, top
File:Saleae Logic16 PCB bottom.jpg|PCB, bottom
File:Saleae logic16 xilinx xc3s200a.jpg|Xilinx XC3S200A
File:Saleae logic16 cypress fx2lp.jpg|Cypress FX2LP
File:Saleae logic16 eeprom b2th.jpg|I2C EEPROM
File:Saleae logic16 dl46.jpg|ST DVIULC6-4SC6
File:Saleae logic16 189z 189c.jpg|Voltage regulators
File:Saleae logic16 72y7.jpg|N-MOSFETs

</gallery>

== Firmware ==

=== Firmware and FPGA bitstream usage ===

To use the Saleae Logic16 (or its clones) with sigrok, you must first use a Python script to extract the FX2 firmware and the FPGA bitstreams from version 1.2.10 of Saleae's ''Logic'' software.

First download the Saleae vendor software. This version has been tested to work, but more recent versions are not supported currently (see [https://sigrok.org/bugzilla/show_bug.cgi?id=989 bug #989]). Old Saleae vendor software versions can be downloaded from [https://support.saleae.com/logic-software/legacy-software/older-software-releases support.saleae.com]. (32-bit vs 64-bit download doesn't matter; both produce the same output.)

Then extract the <code>Logic</code> Linux binary from the zip file and use the [http://sigrok.org/gitweb/?p=sigrok-util.git;a=tree;f=firmware/saleae-logic16 sigrok-fwextract-saleae-logic16] tool to extract the files from it. On Windows, [https://github.com/anno73/Saleae-Logic16-Clone/wiki#extract-from-logic this Python script can be run from python.exe]. On Linux, it can be executed directly:

$ '''sigrok-fwextract-saleae-logic16 Logic'''
saved 5214 bytes to saleae-logic16-fx2.fw
saved 149516 bytes to saleae-logic16-fpga-18.bitstream
saved 149516 bytes to saleae-logic16-fpga-33.bitstream

Copy these files to the directory where your [[libsigrok]] installation expects them and they will be found and used automatically by the libsigrok '''saleae-logic16''' driver.

On Linux, [https://sigrok.org/bugzilla/show_bug.cgi?id=67 this is usually] <code>/usr/local/share/sigrok-firmware</code> or <code>/usr/share/sigrok-firmware</code>. The latter is correct on Ubuntu (and where files are created by the unrelated [https://packages.ubuntu.com/lunar/all/sigrok-firmware-fx2lafw/filelist <code>sigrok-firmware-fx2lafw</code> package]).

On Windows, they should be placed in <code>C:\Program Files\sigrok\PulseView\share\sigrok-firmware\</code>.

On macOS, they should be placed in <code>/[…]/PulseView.app/Contents/share/sigrok-firmware/</code>.

=== Technical firmware details ===

The firmware for the FX2LP is embedded in the vendor application as a set of Intel HEX lines. Each line is uploaded individually with a separate control transfer. The firmware currently occupies the address range [0x0000-0x145d], but is uploaded out of order.

See [[Saleae Logic16/Firmware]] for more details on the vendor firmware.

== Driver ==
In Windows, the [https://github.com/anno73/Saleae-Logic16-Clone/wiki#install-usb-driver USB driver must also be installed using Zadig], similar to other devices, or you will get <code>sr: saleae-logic16: Failed to init device.</code>

== Protocol ==

'''Sample format''':

The samples (as received via USB) for the enabled probes (3, 6, 9, or 16) are organized as follows:

'''0xLL 0xLL 0xMM 0xMM 0xNN 0xNN 0xPP 0xPP 0xQQ 0xQQ 0xRR 0xRR ...'''

In the above example, 3 probes are enabled. For each probe there are 2 bytes / 16 bits (e.g. 0xLL 0xLL for probe 0), then the next probe's data is received (0xMM 0xMM for probe 1), then 0xNN 0xNN for probe 2. When 2 bytes have been received for all enabled probes, the process restarts with probe 0 again.

The 16 bits of data per probe seem to contain the pin state of the respective probe (1: high, 0: low) at 16 different sampling points/times (which ones depends on the samplerate).

'''Configuration''':

Endpoint 1 is used for configuration of the analyzer. The transfers are "encrypted" using a simple series of additions and XORs. Two kinds of transfers are used; a 3 byte out transfer starting with 0x81 followed by a 1 byte in transfer, and a 4 byte out transfer starting with 0x80. It's quite plausible that these provide raw read/write access to memory locations.

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Channel number configuration
|-
| 3 channels
| <tt>0x80 0x01 0x02 '''0x07''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 6 channels
| <tt>0x80 0x01 0x02 '''0x3f''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 9 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0x01'''</tt>
|-
| 16 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0xff'''</tt>
|}

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Sampling frequency
|-
| 500kHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0xc7'''</tt>
|-
| 1MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x63'''</tt>
|-
| 2MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x31'''</tt>
|-
| 4MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x18'''</tt>
|-
| 5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 8MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 10MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 12.5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x07'''</tt>
|-
| 16MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 25MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 32MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x04'''</tt>
|-
| 40MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 50MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 80MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 100MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x00'''</tt>
|}

== Resources ==

* [http://downloads.saleae.com/Logic+Guide.pdf Manual]
* [http://www.saleae.com/downloads Vendor software (current release)]
** [https://support.saleae.com/logic-software/latest-beta-release Vendor software (beta releases)]
** [https://support.saleae.com/logic-software/legacy-software/older-software-releases Vendor software (older releases)]
* [https://support.saleae.com/saleae-api-and-sdk/what-apis-are-available SDKs]

[[Category:Device]]
[[Category:Logic analyzer]]
[[Category:Supported]]

Saleae Logic16

2023-05-23T20:37:31Z

Endolith: /* Protocol */ Finally got it working

{{Infobox logic analyzer
| image = [[File:Saleae Logic16 bottom.png|180px]]
| name = Saleae Logic16
| status = supported
| source_code_dir = saleae-logic16
| channels = 3/6/9/16
| samplerate = 100/50/32/16MHz
| samplerate_state = —
| triggers = none (SW-only)
| voltages = -0.9V — 6V
| threshold = configurable: for 1.8V to 3.6V systems: VIH=1.4V, VIL=0.7V for 5V systems: VIH=3.6V, VIL=1.4V
| memory = none
| compression = yes
| website = [http://www.saleae.com/logic16/ saleae.com]
}}

The '''Saleae Logic16''' is a USB-based, 16-channel logic analyzer with 100/50/32/16MHz sampling rate (at 3/6/9/16 enabled channels).

The case requires a '''Torx T5''' screwdriver to open.

See [[Saleae Logic16/Info]] for more details (such as '''lsusb -v''' output) about the device.

See [[Saleae Logic]] for the predecessor product of the Saleae Logic16.

== Hardware ==

* '''FPGA''': [http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/silicon_devices/fpga/spartan-3a.html Xilinx Spartan-3A XC3S200A], 200K gates ([http://www.xilinx.com/support/documentation/data_sheets/ds529.pdf datasheeet])
* '''USB interface chip''': [http://www.cypress.com/?mpn=CY7C68013A-56PVXC Cypress CY7C68013A-56PVXC (FX2LP)] ([http://www.cypress.com/file/138911/download datasheet])
* '''Ultralow capacitance ESD protection''': 4x [http://www.st.com/web/catalog/sense_power/FM114/CL1137/SC1490/PF109008 ST DVIULC6-4SC6] ([http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00065974.pdf datasheet])
* '''2Kbit I2C EEPROM''': [http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010774 Microchip 24AA02] ([http://ww1.microchip.com/downloads/en/DeviceDoc/21709J.pdf datasheet]) (marking: "B2TH", starts with "B2" always, the last 2 characters are a "traceability code")
* '''2.5MHz, 1.5A synchronous step down switching regulator (1.2V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189C")
* '''2.5MHz, 1.5A synchronous step down switching regulator (3.3V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189Z")
* '''N-MOSFET''': 2x 2N7002 type MOSFET (marking: "72Y7"). Connected as "low-side" switch/LED driver and inverter.

'''Pinouts and connections:'''

'''JTAG header (FPGA):'''

The '''J3''' pin header is a JTAG connector wired to the FPGA. The pins are (from left to right, the right-most pin, pin number 1, is square):

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!5
!4
!3
!2
!1

|-
| GND
| TMS
| TCK
| TDO
| TDI

|}

'''Testpoints:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!T1
!T2
!T3

|-
| 1.2V
| 3.3V
| GND (FX2)

|}

'''Cypress FX2:'''


{{chip_56pin
| 1=(FPGA 15, IO_L05P_3) PD5
| 2=(FPGA 13, IO_L04N_3) PD6
| 3=(FPGA 10, IO_L03N_3) PD7
| 4=GND
| 5=(FPGA 90, IO_0) CLKOUT
| 6=VCC
| 7=GND
| 8=(FPGA 3, IO_L01P_3) RDY0/*SLRD
| 9=(FPGA 16, IO_L05N_3) RDY1/*SLWR
| 10=AVCC
| 11=(24MHz crystal) XTALOUT
| 12=(24MHz crystal) XTALIN
| 13=AGND
| 14=AVCC

| 15=(USB D+) DPLUS
| 16=(USB D-) DMINUS
| 17=AGND
| 18=VCC
| 19=GND
| 20=(FPGA 84, IO_L02N_0) *IFCLK
| 21=RESERVED
| 22=(EEPROM SCL) SCL
| 23=(EEPROM SDA) SDA
| 24=VCC
| 25=(FPGA 40, IO_L08P_2) PB0
| 26=(FPGA 78, IO_L01N_0) PB1
| 27=(FPGA 77, IO_L01P_0) PB2
| 28=(FPGA 49, IO_L10N_2) PB3

| 29=PB4 (FPGA 46, MOSI)
| 30=PB5 (FPGA 41, IO_L08N_2)
| 31=PB6 (FPGA 37, IO_L07N_2)
| 32=PB7 (FPGA 93, IO_L05P_0)
| 33=GND
| 34=VCC
| 35=GND
| 36=CTL0 (FPGA 94, IO_L05N_0)
| 37=CTL1 (FPGA 97, IP_0)
| 38=CTL2 (FPGA 100, PROG_B)
| 39=VCC
| 40=PA0 (FPGA 54, DONE)
| 41=PA1 (FPGA 48, INIT_B)
| 42=PA2 (FPGA 53, CCLK)

| 43=PA3 (FPGA 51, MISO)
| 44=PA4 (FPGA 98, IO_L06P_0)
| 45=PA5 (FPGA 85, IO_L03P_0)
| 46=PA6 (FPGA 30, IO_L04P_2)
| 47=PA7 (FPGA 9, IO_L03P_3)
| 48=GND
| 49=RESET# (3.3V via D2 (diode?))
| 50=VCC
| 51=*WAKEUP (3.3V)
| 52=PD0 (FPGA 6, IO_L02N_3)
| 53=PD1 (FPGA 4, IO_L01N_3)
| 54=PD2 (FPGA 5, IO_L02P_3)
| 55=PD3 (FPGA 44, IO_L09N_2)
| 56=PD4 (FPGA 12, IO_L04P_3)

}}


'''Other FPGA connections:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!28
|CH0
!52
|CH8
|-
!29
|CH1
!56
|CH9
|-
!32
|CH2
!57
|CH10
|-
!33
|CH3
!60
|CH11
|-
!34
|CH4
!61
|CH12
|-
!36
|CH5
!62
|CH13
|-
!43
|CH6
!64
|CH14
|-
!50
|CH7
!65
|CH15
|-
!73
|colspan="3"|LED (active low)
|}

== Photos ==

<gallery>
File:Saleae Logic16.jpg|Device, front
File:Saleae Logic16 bottom.jpg|Device, bottom
File:Saleae Logic16 PCB top.jpg|PCB, top
File:Saleae Logic16 PCB bottom.jpg|PCB, bottom
File:Saleae logic16 xilinx xc3s200a.jpg|Xilinx XC3S200A
File:Saleae logic16 cypress fx2lp.jpg|Cypress FX2LP
File:Saleae logic16 eeprom b2th.jpg|I2C EEPROM
File:Saleae logic16 dl46.jpg|ST DVIULC6-4SC6
File:Saleae logic16 189z 189c.jpg|Voltage regulators
File:Saleae logic16 72y7.jpg|N-MOSFETs

</gallery>

== Firmware ==

=== Firmware and FPGA bitstream usage ===

To use the Saleae Logic16 (or its clones) with sigrok, you must first use a Python script to extract the FX2 firmware and the FPGA bitstreams from version 1.2.10 of Saleae's ''Logic'' software.

First download the Saleae vendor software. This version has been tested to work, but more recent versions are not supported currently (see [https://sigrok.org/bugzilla/show_bug.cgi?id=989 bug #989]). Old Saleae vendor software versions can be downloaded from [https://support.saleae.com/logic-software/legacy-software/older-software-releases support.saleae.com]. (32-bit vs 64-bit download doesn't matter; both produce the same output.)

Then extract the <code>Logic</code> Linux binary from the zip file and use the [http://sigrok.org/gitweb/?p=sigrok-util.git;a=tree;f=firmware/saleae-logic16 sigrok-fwextract-saleae-logic16] tool to extract the files from it. On Windows, [https://github.com/anno73/Saleae-Logic16-Clone/wiki#extract-from-logic this Python script can be run from python.exe]. On Linux, it can be executed directly:

$ '''sigrok-fwextract-saleae-logic16 Logic'''
saved 5214 bytes to saleae-logic16-fx2.fw
saved 149516 bytes to saleae-logic16-fpga-18.bitstream
saved 149516 bytes to saleae-logic16-fpga-33.bitstream

Copy these files to the directory where your [[libsigrok]] installation expects them and they will be found and used automatically by the libsigrok '''saleae-logic16''' driver. [https://sigrok.org/bugzilla/show_bug.cgi?id=67 This is usually] <code>/usr/local/share/sigrok-firmware</code> or <code>/usr/share/sigrok-firmware</code>. The latter is correct on Ubuntu (and where files are created by the unrelated [https://packages.ubuntu.com/lunar/all/sigrok-firmware-fx2lafw/filelist <code>sigrok-firmware-fx2lafw</code> package]). On Windows, they should be placed in <code>C:\Program Files\sigrok\PulseView\share\sigrok-firmware\</code>.

=== Technical firmware details ===

The firmware for the FX2LP is embedded in the vendor application as a set of Intel HEX lines. Each line is uploaded individually with a separate control transfer. The firmware currently occupies the address range [0x0000-0x145d], but is uploaded out of order.

See [[Saleae Logic16/Firmware]] for more details on the vendor firmware.

== Driver ==
In Windows, the [https://github.com/anno73/Saleae-Logic16-Clone/wiki#install-usb-driver USB driver must also be installed using Zadig], similar to other devices, or you will get <code>sr: saleae-logic16: Failed to init device.</code>

== Protocol ==

'''Sample format''':

The samples (as received via USB) for the enabled probes (3, 6, 9, or 16) are organized as follows:

'''0xLL 0xLL 0xMM 0xMM 0xNN 0xNN 0xPP 0xPP 0xQQ 0xQQ 0xRR 0xRR ...'''

In the above example, 3 probes are enabled. For each probe there are 2 bytes / 16 bits (e.g. 0xLL 0xLL for probe 0), then the next probe's data is received (0xMM 0xMM for probe 1), then 0xNN 0xNN for probe 2. When 2 bytes have been received for all enabled probes, the process restarts with probe 0 again.

The 16 bits of data per probe seem to contain the pin state of the respective probe (1: high, 0: low) at 16 different sampling points/times (which ones depends on the samplerate).

'''Configuration''':

Endpoint 1 is used for configuration of the analyzer. The transfers are "encrypted" using a simple series of additions and XORs. Two kinds of transfers are used; a 3 byte out transfer starting with 0x81 followed by a 1 byte in transfer, and a 4 byte out transfer starting with 0x80. It's quite plausible that these provide raw read/write access to memory locations.

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Channel number configuration
|-
| 3 channels
| <tt>0x80 0x01 0x02 '''0x07''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 6 channels
| <tt>0x80 0x01 0x02 '''0x3f''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 9 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0x01'''</tt>
|-
| 16 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0xff'''</tt>
|}

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Sampling frequency
|-
| 500kHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0xc7'''</tt>
|-
| 1MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x63'''</tt>
|-
| 2MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x31'''</tt>
|-
| 4MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x18'''</tt>
|-
| 5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 8MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 10MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 12.5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x07'''</tt>
|-
| 16MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 25MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 32MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x04'''</tt>
|-
| 40MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 50MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 80MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 100MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x00'''</tt>
|}

== Resources ==

* [http://downloads.saleae.com/Logic+Guide.pdf Manual]
* [http://www.saleae.com/downloads Vendor software (current release)]
** [https://support.saleae.com/logic-software/latest-beta-release Vendor software (beta releases)]
** [https://support.saleae.com/logic-software/legacy-software/older-software-releases Vendor software (older releases)]
* [https://support.saleae.com/saleae-api-and-sdk/what-apis-are-available SDKs]

[[Category:Device]]
[[Category:Logic analyzer]]
[[Category:Supported]]

Saleae Logic16

2023-05-23T20:34:26Z

Endolith: /* Firmware */ Oh it's Python without .py extension, so actually cross-platform.

{{Infobox logic analyzer
| image = [[File:Saleae Logic16 bottom.png|180px]]
| name = Saleae Logic16
| status = supported
| source_code_dir = saleae-logic16
| channels = 3/6/9/16
| samplerate = 100/50/32/16MHz
| samplerate_state = —
| triggers = none (SW-only)
| voltages = -0.9V — 6V
| threshold = configurable: for 1.8V to 3.6V systems: VIH=1.4V, VIL=0.7V for 5V systems: VIH=3.6V, VIL=1.4V
| memory = none
| compression = yes
| website = [http://www.saleae.com/logic16/ saleae.com]
}}

The '''Saleae Logic16''' is a USB-based, 16-channel logic analyzer with 100/50/32/16MHz sampling rate (at 3/6/9/16 enabled channels).

The case requires a '''Torx T5''' screwdriver to open.

See [[Saleae Logic16/Info]] for more details (such as '''lsusb -v''' output) about the device.

See [[Saleae Logic]] for the predecessor product of the Saleae Logic16.

== Hardware ==

* '''FPGA''': [http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/silicon_devices/fpga/spartan-3a.html Xilinx Spartan-3A XC3S200A], 200K gates ([http://www.xilinx.com/support/documentation/data_sheets/ds529.pdf datasheeet])
* '''USB interface chip''': [http://www.cypress.com/?mpn=CY7C68013A-56PVXC Cypress CY7C68013A-56PVXC (FX2LP)] ([http://www.cypress.com/file/138911/download datasheet])
* '''Ultralow capacitance ESD protection''': 4x [http://www.st.com/web/catalog/sense_power/FM114/CL1137/SC1490/PF109008 ST DVIULC6-4SC6] ([http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00065974.pdf datasheet])
* '''2Kbit I2C EEPROM''': [http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010774 Microchip 24AA02] ([http://ww1.microchip.com/downloads/en/DeviceDoc/21709J.pdf datasheet]) (marking: "B2TH", starts with "B2" always, the last 2 characters are a "traceability code")
* '''2.5MHz, 1.5A synchronous step down switching regulator (1.2V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189C")
* '''2.5MHz, 1.5A synchronous step down switching regulator (3.3V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189Z")
* '''N-MOSFET''': 2x 2N7002 type MOSFET (marking: "72Y7"). Connected as "low-side" switch/LED driver and inverter.

'''Pinouts and connections:'''

'''JTAG header (FPGA):'''

The '''J3''' pin header is a JTAG connector wired to the FPGA. The pins are (from left to right, the right-most pin, pin number 1, is square):

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!5
!4
!3
!2
!1

|-
| GND
| TMS
| TCK
| TDO
| TDI

|}

'''Testpoints:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!T1
!T2
!T3

|-
| 1.2V
| 3.3V
| GND (FX2)

|}

'''Cypress FX2:'''


{{chip_56pin
| 1=(FPGA 15, IO_L05P_3) PD5
| 2=(FPGA 13, IO_L04N_3) PD6
| 3=(FPGA 10, IO_L03N_3) PD7
| 4=GND
| 5=(FPGA 90, IO_0) CLKOUT
| 6=VCC
| 7=GND
| 8=(FPGA 3, IO_L01P_3) RDY0/*SLRD
| 9=(FPGA 16, IO_L05N_3) RDY1/*SLWR
| 10=AVCC
| 11=(24MHz crystal) XTALOUT
| 12=(24MHz crystal) XTALIN
| 13=AGND
| 14=AVCC

| 15=(USB D+) DPLUS
| 16=(USB D-) DMINUS
| 17=AGND
| 18=VCC
| 19=GND
| 20=(FPGA 84, IO_L02N_0) *IFCLK
| 21=RESERVED
| 22=(EEPROM SCL) SCL
| 23=(EEPROM SDA) SDA
| 24=VCC
| 25=(FPGA 40, IO_L08P_2) PB0
| 26=(FPGA 78, IO_L01N_0) PB1
| 27=(FPGA 77, IO_L01P_0) PB2
| 28=(FPGA 49, IO_L10N_2) PB3

| 29=PB4 (FPGA 46, MOSI)
| 30=PB5 (FPGA 41, IO_L08N_2)
| 31=PB6 (FPGA 37, IO_L07N_2)
| 32=PB7 (FPGA 93, IO_L05P_0)
| 33=GND
| 34=VCC
| 35=GND
| 36=CTL0 (FPGA 94, IO_L05N_0)
| 37=CTL1 (FPGA 97, IP_0)
| 38=CTL2 (FPGA 100, PROG_B)
| 39=VCC
| 40=PA0 (FPGA 54, DONE)
| 41=PA1 (FPGA 48, INIT_B)
| 42=PA2 (FPGA 53, CCLK)

| 43=PA3 (FPGA 51, MISO)
| 44=PA4 (FPGA 98, IO_L06P_0)
| 45=PA5 (FPGA 85, IO_L03P_0)
| 46=PA6 (FPGA 30, IO_L04P_2)
| 47=PA7 (FPGA 9, IO_L03P_3)
| 48=GND
| 49=RESET# (3.3V via D2 (diode?))
| 50=VCC
| 51=*WAKEUP (3.3V)
| 52=PD0 (FPGA 6, IO_L02N_3)
| 53=PD1 (FPGA 4, IO_L01N_3)
| 54=PD2 (FPGA 5, IO_L02P_3)
| 55=PD3 (FPGA 44, IO_L09N_2)
| 56=PD4 (FPGA 12, IO_L04P_3)

}}


'''Other FPGA connections:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!28
|CH0
!52
|CH8
|-
!29
|CH1
!56
|CH9
|-
!32
|CH2
!57
|CH10
|-
!33
|CH3
!60
|CH11
|-
!34
|CH4
!61
|CH12
|-
!36
|CH5
!62
|CH13
|-
!43
|CH6
!64
|CH14
|-
!50
|CH7
!65
|CH15
|-
!73
|colspan="3"|LED (active low)
|}

== Photos ==

<gallery>
File:Saleae Logic16.jpg|Device, front
File:Saleae Logic16 bottom.jpg|Device, bottom
File:Saleae Logic16 PCB top.jpg|PCB, top
File:Saleae Logic16 PCB bottom.jpg|PCB, bottom
File:Saleae logic16 xilinx xc3s200a.jpg|Xilinx XC3S200A
File:Saleae logic16 cypress fx2lp.jpg|Cypress FX2LP
File:Saleae logic16 eeprom b2th.jpg|I2C EEPROM
File:Saleae logic16 dl46.jpg|ST DVIULC6-4SC6
File:Saleae logic16 189z 189c.jpg|Voltage regulators
File:Saleae logic16 72y7.jpg|N-MOSFETs

</gallery>

== Firmware ==

=== Firmware and FPGA bitstream usage ===

To use the Saleae Logic16 (or its clones) with sigrok, you must first use a Python script to extract the FX2 firmware and the FPGA bitstreams from version 1.2.10 of Saleae's ''Logic'' software.

First download the Saleae vendor software. This version has been tested to work, but more recent versions are not supported currently (see [https://sigrok.org/bugzilla/show_bug.cgi?id=989 bug #989]). Old Saleae vendor software versions can be downloaded from [https://support.saleae.com/logic-software/legacy-software/older-software-releases support.saleae.com]. (32-bit vs 64-bit download doesn't matter; both produce the same output.)

Then extract the <code>Logic</code> Linux binary from the zip file and use the [http://sigrok.org/gitweb/?p=sigrok-util.git;a=tree;f=firmware/saleae-logic16 sigrok-fwextract-saleae-logic16] tool to extract the files from it. On Windows, [https://github.com/anno73/Saleae-Logic16-Clone/wiki#extract-from-logic this Python script can be run from python.exe]. On Linux, it can be executed directly:

$ '''sigrok-fwextract-saleae-logic16 Logic'''
saved 5214 bytes to saleae-logic16-fx2.fw
saved 149516 bytes to saleae-logic16-fpga-18.bitstream
saved 149516 bytes to saleae-logic16-fpga-33.bitstream

Copy these files to the directory where your [[libsigrok]] installation expects them and they will be found and used automatically by the libsigrok '''saleae-logic16''' driver. [https://sigrok.org/bugzilla/show_bug.cgi?id=67 This is usually] <code>/usr/local/share/sigrok-firmware</code> or <code>/usr/share/sigrok-firmware</code>. The latter is correct on Ubuntu (and where files are created by the unrelated [https://packages.ubuntu.com/lunar/all/sigrok-firmware-fx2lafw/filelist <code>sigrok-firmware-fx2lafw</code> package]). On Windows, they should be placed in <code>C:\Program Files\sigrok\PulseView\share\sigrok-firmware\</code>.

=== Technical firmware details ===

The firmware for the FX2LP is embedded in the vendor application as a set of Intel HEX lines. Each line is uploaded individually with a separate control transfer. The firmware currently occupies the address range [0x0000-0x145d], but is uploaded out of order.

See [[Saleae Logic16/Firmware]] for more details on the vendor firmware.

== Protocol ==

'''Sample format''':

The samples (as received via USB) for the enabled probes (3, 6, 9, or 16) are organized as follows:

'''0xLL 0xLL 0xMM 0xMM 0xNN 0xNN 0xPP 0xPP 0xQQ 0xQQ 0xRR 0xRR ...'''

In the above example, 3 probes are enabled. For each probe there are 2 bytes / 16 bits (e.g. 0xLL 0xLL for probe 0), then the next probe's data is received (0xMM 0xMM for probe 1), then 0xNN 0xNN for probe 2. When 2 bytes have been received for all enabled probes, the process restarts with probe 0 again.

The 16 bits of data per probe seem to contain the pin state of the respective probe (1: high, 0: low) at 16 different sampling points/times (which ones depends on the samplerate).

'''Configuration''':

Endpoint 1 is used for configuration of the analyzer. The transfers are "encrypted" using a simple series of additions and XORs. Two kinds of transfers are used; a 3 byte out transfer starting with 0x81 followed by a 1 byte in transfer, and a 4 byte out transfer starting with 0x80. It's quite plausible that these provide raw read/write access to memory locations.

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Channel number configuration
|-
| 3 channels
| <tt>0x80 0x01 0x02 '''0x07''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 6 channels
| <tt>0x80 0x01 0x02 '''0x3f''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 9 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0x01'''</tt>
|-
| 16 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0xff'''</tt>
|}

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Sampling frequency
|-
| 500kHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0xc7'''</tt>
|-
| 1MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x63'''</tt>
|-
| 2MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x31'''</tt>
|-
| 4MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x18'''</tt>
|-
| 5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 8MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 10MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 12.5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x07'''</tt>
|-
| 16MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 25MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 32MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x04'''</tt>
|-
| 40MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 50MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 80MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 100MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x00'''</tt>
|}

== Resources ==

* [http://downloads.saleae.com/Logic+Guide.pdf Manual]
* [http://www.saleae.com/downloads Vendor software (current release)]
** [https://support.saleae.com/logic-software/latest-beta-release Vendor software (beta releases)]
** [https://support.saleae.com/logic-software/legacy-software/older-software-releases Vendor software (older releases)]
* [https://support.saleae.com/saleae-api-and-sdk/what-apis-are-available SDKs]

[[Category:Device]]
[[Category:Logic analyzer]]
[[Category:Supported]]

Saleae Logic16

2023-05-23T19:42:08Z

Endolith: /* Firmware */ Trying to make instructions more less confusing, putting information in order, adding details

{{Infobox logic analyzer
| image = [[File:Saleae Logic16 bottom.png|180px]]
| name = Saleae Logic16
| status = supported
| source_code_dir = saleae-logic16
| channels = 3/6/9/16
| samplerate = 100/50/32/16MHz
| samplerate_state = —
| triggers = none (SW-only)
| voltages = -0.9V — 6V
| threshold = configurable: for 1.8V to 3.6V systems: VIH=1.4V, VIL=0.7V for 5V systems: VIH=3.6V, VIL=1.4V
| memory = none
| compression = yes
| website = [http://www.saleae.com/logic16/ saleae.com]
}}

The '''Saleae Logic16''' is a USB-based, 16-channel logic analyzer with 100/50/32/16MHz sampling rate (at 3/6/9/16 enabled channels).

The case requires a '''Torx T5''' screwdriver to open.

See [[Saleae Logic16/Info]] for more details (such as '''lsusb -v''' output) about the device.

See [[Saleae Logic]] for the predecessor product of the Saleae Logic16.

== Hardware ==

* '''FPGA''': [http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/silicon_devices/fpga/spartan-3a.html Xilinx Spartan-3A XC3S200A], 200K gates ([http://www.xilinx.com/support/documentation/data_sheets/ds529.pdf datasheeet])
* '''USB interface chip''': [http://www.cypress.com/?mpn=CY7C68013A-56PVXC Cypress CY7C68013A-56PVXC (FX2LP)] ([http://www.cypress.com/file/138911/download datasheet])
* '''Ultralow capacitance ESD protection''': 4x [http://www.st.com/web/catalog/sense_power/FM114/CL1137/SC1490/PF109008 ST DVIULC6-4SC6] ([http://www.st.com/st-web-ui/static/active/en/resource/technical/document/datasheet/CD00065974.pdf datasheet])
* '''2Kbit I2C EEPROM''': [http://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010774 Microchip 24AA02] ([http://ww1.microchip.com/downloads/en/DeviceDoc/21709J.pdf datasheet]) (marking: "B2TH", starts with "B2" always, the last 2 characters are a "traceability code")
* '''2.5MHz, 1.5A synchronous step down switching regulator (1.2V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189C")
* '''2.5MHz, 1.5A synchronous step down switching regulator (3.3V)''': [http://www.semtech.com/power-management/switching-regulators/sc189 Semtech SC189] ([http://www.semtech.com/images/datasheet/sc189.pdf datasheet]) (marking: "189Z")
* '''N-MOSFET''': 2x 2N7002 type MOSFET (marking: "72Y7"). Connected as "low-side" switch/LED driver and inverter.

'''Pinouts and connections:'''

'''JTAG header (FPGA):'''

The '''J3''' pin header is a JTAG connector wired to the FPGA. The pins are (from left to right, the right-most pin, pin number 1, is square):

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!5
!4
!3
!2
!1

|-
| GND
| TMS
| TCK
| TDO
| TDI

|}

'''Testpoints:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!T1
!T2
!T3

|-
| 1.2V
| 3.3V
| GND (FX2)

|}

'''Cypress FX2:'''


{{chip_56pin
| 1=(FPGA 15, IO_L05P_3) PD5
| 2=(FPGA 13, IO_L04N_3) PD6
| 3=(FPGA 10, IO_L03N_3) PD7
| 4=GND
| 5=(FPGA 90, IO_0) CLKOUT
| 6=VCC
| 7=GND
| 8=(FPGA 3, IO_L01P_3) RDY0/*SLRD
| 9=(FPGA 16, IO_L05N_3) RDY1/*SLWR
| 10=AVCC
| 11=(24MHz crystal) XTALOUT
| 12=(24MHz crystal) XTALIN
| 13=AGND
| 14=AVCC

| 15=(USB D+) DPLUS
| 16=(USB D-) DMINUS
| 17=AGND
| 18=VCC
| 19=GND
| 20=(FPGA 84, IO_L02N_0) *IFCLK
| 21=RESERVED
| 22=(EEPROM SCL) SCL
| 23=(EEPROM SDA) SDA
| 24=VCC
| 25=(FPGA 40, IO_L08P_2) PB0
| 26=(FPGA 78, IO_L01N_0) PB1
| 27=(FPGA 77, IO_L01P_0) PB2
| 28=(FPGA 49, IO_L10N_2) PB3

| 29=PB4 (FPGA 46, MOSI)
| 30=PB5 (FPGA 41, IO_L08N_2)
| 31=PB6 (FPGA 37, IO_L07N_2)
| 32=PB7 (FPGA 93, IO_L05P_0)
| 33=GND
| 34=VCC
| 35=GND
| 36=CTL0 (FPGA 94, IO_L05N_0)
| 37=CTL1 (FPGA 97, IP_0)
| 38=CTL2 (FPGA 100, PROG_B)
| 39=VCC
| 40=PA0 (FPGA 54, DONE)
| 41=PA1 (FPGA 48, INIT_B)
| 42=PA2 (FPGA 53, CCLK)

| 43=PA3 (FPGA 51, MISO)
| 44=PA4 (FPGA 98, IO_L06P_0)
| 45=PA5 (FPGA 85, IO_L03P_0)
| 46=PA6 (FPGA 30, IO_L04P_2)
| 47=PA7 (FPGA 9, IO_L03P_3)
| 48=GND
| 49=RESET# (3.3V via D2 (diode?))
| 50=VCC
| 51=*WAKEUP (3.3V)
| 52=PD0 (FPGA 6, IO_L02N_3)
| 53=PD1 (FPGA 4, IO_L01N_3)
| 54=PD2 (FPGA 5, IO_L02P_3)
| 55=PD3 (FPGA 44, IO_L09N_2)
| 56=PD4 (FPGA 12, IO_L04P_3)

}}


'''Other FPGA connections:'''

{| border="0" style="font-size: smaller" class="sigroktable"
|-
!28
|CH0
!52
|CH8
|-
!29
|CH1
!56
|CH9
|-
!32
|CH2
!57
|CH10
|-
!33
|CH3
!60
|CH11
|-
!34
|CH4
!61
|CH12
|-
!36
|CH5
!62
|CH13
|-
!43
|CH6
!64
|CH14
|-
!50
|CH7
!65
|CH15
|-
!73
|colspan="3"|LED (active low)
|}

== Photos ==

<gallery>
File:Saleae Logic16.jpg|Device, front
File:Saleae Logic16 bottom.jpg|Device, bottom
File:Saleae Logic16 PCB top.jpg|PCB, top
File:Saleae Logic16 PCB bottom.jpg|PCB, bottom
File:Saleae logic16 xilinx xc3s200a.jpg|Xilinx XC3S200A
File:Saleae logic16 cypress fx2lp.jpg|Cypress FX2LP
File:Saleae logic16 eeprom b2th.jpg|I2C EEPROM
File:Saleae logic16 dl46.jpg|ST DVIULC6-4SC6
File:Saleae logic16 189z 189c.jpg|Voltage regulators
File:Saleae logic16 72y7.jpg|N-MOSFETs

</gallery>

== Firmware ==

=== Firmware and FPGA bitstream usage ===

To use the Saleae Logic16 (or its clones) with sigrok, you must first use a Linux machine to extract the FX2 firmware and the FPGA bitstreams from version 1.2.10 of Saleae's ''Logic'' software.

First download the Saleae vendor software. This version has been tested to work, but more recent versions are not supported currently (see [https://sigrok.org/bugzilla/show_bug.cgi?id=989 bug #989]). Old Saleae vendor software versions can be downloaded from [https://support.saleae.com/logic-software/legacy-software/older-software-releases support.saleae.com]. (32-bit vs 64-bit download doesn't matter; both produce the same output.)

Then extract the <code>Logic</code> Linux binary from the zip file and use the [http://sigrok.org/gitweb/?p=sigrok-util.git;a=tree;f=firmware/saleae-logic16 sigrok-fwextract-saleae-logic16] tool to extract the files from it:

$ '''sigrok-fwextract-saleae-logic16 Logic'''
saved 5214 bytes to saleae-logic16-fx2.fw
saved 149516 bytes to saleae-logic16-fpga-18.bitstream
saved 149516 bytes to saleae-logic16-fpga-33.bitstream

Copy these files to the directory where your [[libsigrok]] installation expects them and they will be found and used automatically by the libsigrok '''saleae-logic16''' driver. [https://sigrok.org/bugzilla/show_bug.cgi?id=67 This is usually] <code>/usr/local/share/sigrok-firmware</code> or <code>/usr/share/sigrok-firmware</code>. The latter is correct on Ubuntu (and where files are created by the unrelated [https://packages.ubuntu.com/lunar/all/sigrok-firmware-fx2lafw/filelist <code>sigrok-firmware-fx2lafw</code> package]).

=== Technical firmware details ===

The firmware for the FX2LP is embedded in the vendor application as a set of Intel HEX lines. Each line is uploaded individually with a separate control transfer. The firmware currently occupies the address range [0x0000-0x145d], but is uploaded out of order.

See [[Saleae Logic16/Firmware]] for more details on the vendor firmware.

== Protocol ==

'''Sample format''':

The samples (as received via USB) for the enabled probes (3, 6, 9, or 16) are organized as follows:

'''0xLL 0xLL 0xMM 0xMM 0xNN 0xNN 0xPP 0xPP 0xQQ 0xQQ 0xRR 0xRR ...'''

In the above example, 3 probes are enabled. For each probe there are 2 bytes / 16 bits (e.g. 0xLL 0xLL for probe 0), then the next probe's data is received (0xMM 0xMM for probe 1), then 0xNN 0xNN for probe 2. When 2 bytes have been received for all enabled probes, the process restarts with probe 0 again.

The 16 bits of data per probe seem to contain the pin state of the respective probe (1: high, 0: low) at 16 different sampling points/times (which ones depends on the samplerate).

'''Configuration''':

Endpoint 1 is used for configuration of the analyzer. The transfers are "encrypted" using a simple series of additions and XORs. Two kinds of transfers are used; a 3 byte out transfer starting with 0x81 followed by a 1 byte in transfer, and a 4 byte out transfer starting with 0x80. It's quite plausible that these provide raw read/write access to memory locations.

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Channel number configuration
|-
| 3 channels
| <tt>0x80 0x01 0x02 '''0x07''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 6 channels
| <tt>0x80 0x01 0x02 '''0x3f''' 0x80 0x01 0x03 '''0x00'''</tt>
|-
| 9 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0x01'''</tt>
|-
| 16 channels
| <tt>0x80 0x01 0x02 '''0xff''' 0x80 0x01 0x03 '''0xff'''</tt>
|}

{| border="0" style="font-size: smaller; white-space: nowrap;" class="alternategrey sigroktable"
!colspan="2"|Sampling frequency
|-
| 500kHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0xc7'''</tt>
|-
| 1MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x63'''</tt>
|-
| 2MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x31'''</tt>
|-
| 4MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x18'''</tt>
|-
| 5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 8MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x13'''</tt>
|-
| 10MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 12.5MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x07'''</tt>
|-
| 16MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x09'''</tt>
|-
| 25MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 32MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x04'''</tt>
|-
| 40MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x03'''</tt>
|-
| 50MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 80MHz
| <tt>0x80 0x01 0x0a '''0x01''' 0x80 0x01 0x04 '''0x01'''</tt>
|-
| 100MHz
| <tt>0x80 0x01 0x0a '''0x00''' 0x80 0x01 0x04 '''0x00'''</tt>
|}

== Resources ==

* [http://downloads.saleae.com/Logic+Guide.pdf Manual]
* [http://www.saleae.com/downloads Vendor software (current release)]
** [https://support.saleae.com/logic-software/latest-beta-release Vendor software (beta releases)]
** [https://support.saleae.com/logic-software/legacy-software/older-software-releases Vendor software (older releases)]
* [https://support.saleae.com/saleae-api-and-sdk/what-apis-are-available SDKs]

[[Category:Device]]
[[Category:Logic analyzer]]
[[Category:Supported]]

Talk:Protocol decoder output

2022-04-06T19:02:20Z

Endolith: Where does the report show up?

Where does the report show up? I have never seen one. [[User:Endolith|Endolith]] ([[User talk:Endolith|talk]]) 21:02, 6 April 2022 (CEST)

Libsigrokdecode

2022-01-18T22:35:31Z

Endolith: Python version is old, so no underscores in literals, f-strings, etc.

{{DISPLAYTITLE:libsigrokdecode}}
'''libsigrokdecode''' (sometimes abbreviated as "srd") is a shared library written in C, which provides (streaming) protocol decoding functionality.

It is licensed under the terms of the '''GNU GPL, version 3 or later'''.

The [[protocol decoders]] are written in Python 3 (>=3.2, <3.6).

== Getting the code ==

$ '''git clone git://sigrok.org/libsigrokdecode'''

You can also [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree browse the source code] via gitweb.

== Distribution packages ==

See [[Downloads#Binaries_and_distribution_packages|Downloads]].

== Building from source ==

See [[Building]].

== Supported protocol decoders ==

The libsigrokdecode library ships with a collection of various protocol decoders out of the box (but you can write your own too, of course; see [[Protocol decoder HOWTO]] and [[Protocol decoder API]] for details).

See [[Protocol decoders]] for the list of currently supported ones (and others we might support in the future).

== Resources ==

* [http://sigrok.org/api/libsigrokdecode/unstable/index.html API documentation]

__NOTOC__

Protocol decoder HOWTO

2021-07-19T14:05:12Z

Endolith: /* Random notes, tips and tricks */ Mention srdhelper, which maybe makes some of this obsolete?

This page serves as a quick-start guide for people who want to write their own [[libsigrokdecode]] protocol decoders ([[Protocol decoders|PDs]]).

It is '''not''' intended to replace the [[Protocol decoder API]] page, but rather to give a short overview/tutorial and some tips.

== Introduction ==

Protocol decoders are written entirely in Python (>= 3.0).

== Files ==

Every protocol decoder is a Python module and has its own subdirectory in libsigrokdecode's '''[http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders decoders]''' directory.

This is a minimalistic example of how a protocol decoder looks like, in this case the '''[[Protocol_decoder:I2c|i2c]]''' decoder (license header, comments, and some other parts omitted).

'''Note''': Do not start new protocol decoders by copying code from here. Instead, it's recommended to select an already existing decoder in the source code which is similar to the one you plan to write, and copy that as a starting point.

=== __init__.py ===


<source lang="python">
'''
I²C (Inter-Integrated Circuit) is a bidirectional, multi-master
bus using two signals (SCL = serial clock line, SDA = serial data line).

<Insert notes and hints for the user here>
'''

from .pd import Decoder
</source>


This is a standard Python file, required in every Python module. It contains a module-level docstring, which is accessible by frontends via the [http://sigrok.org/api/libsigrokdecode/unstable/index.html libsigrokdecode API]. It should contain a (very) short description of what the protocol (in this case [[Protocol_decoder:I2c|I²C]]) is about, and some notes and hints for the user of this protocol decoder (which can be shown in GUIs when the user selects/browses different PDs).

This docstring should '''not''' contain the full, extensive protocol description. Instead, the per-PD wiki page should be used for protocol description, photos of devices or photos of example acquisition setups, and so on. Each decoder has one unique wiki page at the URL '''<nowiki>http://sigrok.org/wiki/Protocol_decoder:<pd></nowiki>''', where '''<pd>''' is the Python module name of the decoder ('''i2c''' in this case). Some examples for such per-PD wiki pages: [[Protocol_decoder:Uart|UART]], [[Protocol_decoder:Pan1321|PAN1321]], [[Protocol_decoder:Mx25lxx05d|MX25Lxx05D]], [[Protocol_decoder:Dcf77|DCF77]].

The "'''from .pd import Decoder'''" line will make sure the code from '''pd.py''' gets properly imported when this module is used.

=== pd.py ===


<source lang="python">
import sigrokdecode as srd

class Decoder(srd.Decoder):
api_version = 2
id = 'i2c'
name = 'I²C'
longname = 'Inter-Integrated Circuit'
desc = 'Two-wire, multi-master, serial bus.'
license = 'gplv2+'
inputs = ['logic']
outputs = ['i2c']
channels = (
{'id': 'scl', 'name': 'SCL', 'desc': 'Serial clock line'},
{'id': 'sda', 'name': 'SDA', 'desc': 'Serial data line'},
)
optional_channels = ()
options = (
{'id': 'address_format', 'desc': 'Displayed slave address format',
'default': 'shifted', 'values': ('shifted', 'unshifted')},
)
annotations = (
('start', 'Start condition'),
('repeat-start', 'Repeat start condition'),
('stop', 'Stop condition'),
('ack', 'ACK'),
('nack', 'NACK'),
('bit', 'Data/address bit'),
('address-read', 'Address read'),
('address-write', 'Address write'),
('data-read', 'Data read'),
('data-write', 'Data write'),
('warnings', 'Human-readable warnings'),
)
annotation_rows = (
('bits', 'Bits', (5,)),
('addr-data', 'Address/Data', (0, 1, 2, 3, 4, 6, 7, 8, 9)),
('warnings', 'Warnings', (10,)),
)

def __init__(self, **kwargs):
self.state = 'FIND START'
# And various other variable initializations...

def metadata(self, key, value):
if key == srd.SRD_CONF_SAMPLERATE:
self.samplerate = value

def start(self):
self.out_ann = self.register(srd.OUTPUT_ANN)

def decode(self, ss, es, data):
for self.samplenum, (scl, sda) in data:
# Decode the samples.
</source>


The recommended name for the actual decoder file is '''pd.py'''. This file contains some meta information about the decoder, and the actual code itself, mostly in the '''decode()''' method.

If needed, large unwieldy lists or similar things can also be factored out into another *.py file (examples: [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders/midi midi], [http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=tree;f=decoders/z80 z80]).

== Copyright and license ==

Every protocol decoder '''must''' come with source code in the form of '''*.py''' files. No pre-compiled code should be present, Python or otherwise. The PD must not use any helpers that are not provided as source code under the same license as the PD itself.

The '''<tt>Decoder</tt>''' class must have a license declaration (see above), stating the license under which all the contents in the decoder's directory are provided. This is usually <tt>'gplv2+'</tt> or <tt>'gplv3+'</tt>, whichever you prefer. In either case, the decoder license must be compatible with the [[libsigrokdecode]] license (which is "GPL, version 3 or later").

== <tt>channels</tt> & <tt>optional_channels</tt> ==

The following excerpt from the [[Protocol_decoder:spi|SPI]] PD shows how to use '''<tt>channels</tt>''' and '''<tt>optional_channels</tt>'''. To decode SPI, the clock signal is always needed, the chip-select signal is optional and only used when provided. To give the user the flexibility to provide only one of the MOSI/MISO signals, they are both also defined as optional:


<source lang="python">
class Decoder(srd.Decoder):
...
id = 'spi'
...
channels = (
{'id': 'clk', 'name': 'CLK', 'desc': 'Clock'},
)
optional_channels = (
{'id': 'miso', 'name': 'MISO', 'desc': 'Master in, slave out'},
{'id': 'mosi', 'name': 'MOSI', 'desc': 'Master out, slave in'},
{'id': 'cs', 'name': 'CS#', 'desc': 'Chip-select'},
)
</source>


'''<tt>data</tt>''', the argument of the decoder's [[Protocol decoder API#decode-function|'''<tt>decode()</tt>''']] function that contains the data to decode, is a list of tuples. These tuples contain the (absolute) number of the sample and the data at that sample. To process all samples, the SPI decoder loops over '''<tt>data</tt>''' like this:


<source lang="python">
def decode(self, ss, es, data):
...
for (self.samplenum, pins) in data:
</source>


'''<tt>channels</tt>''' and '''<tt>optional_channels</tt>''' contain in total four channels, therefore the second member of the tuple is an object of Python's [https://docs.python.org/3/library/stdtypes.html#typebytes '''<tt>bytes</tt>'''] class containing 4 bytes, one for each channel. The decoder unpacks the bytes into the variables '''<tt>clk</tt>''', '''<tt>miso</tt>''', '''<tt>mosi</tt>''', and '''<tt>cs</tt>''' as shown below.

Then, it checks for the optional channels, if their value is either 0 or 1. If it is not, that optional channel is not provided to the decoder. In the case that neither of them is supplied, an exception is raised:


<source lang="python">
(clk, miso, mosi, cs) = pins
self.have_miso = (miso in (0, 1))
self.have_mosi = (mosi in (0, 1))
self.have_cs = (cs in (0, 1))

# Either MISO or MOSI (but not both) can be omitted.
if not (self.have_miso or self.have_mosi):
raise ChannelError('Either MISO or MOSI (or both) pins required.')
</source>


== <tt>annotations</tt> & <tt>annotation_rows</tt> ==

To make the relation between the '''<tt>annotations</tt>''' and the '''<tt>annotation_rows</tt>''' members of a decoder object more clear, take a look at how the [[Protocol_decoder:Ir_nec|ir_nec]] PD uses them:


<source lang="python">
class Decoder(srd.Decoder):
...
id = 'ir_nec'
...
annotations = ( # Implicitly assigned annotation type ID
('bit', 'Bit'), # 0
('agc-pulse', 'AGC pulse'), # 1
('longpause', 'Long pause'), # 2
('shortpause', 'Short pause'), # 3
('stop-bit', 'Stop bit'), # 4
('leader-code', 'Leader code'), # 5
('addr', 'Address'), # 6
('addr-inv', 'Address#'), # 7
('cmd', 'Command'), # 8
('cmd-inv', 'Command#'), # 9
('repeat-code', 'Repeat code'), # 10
('remote', 'Remote'), # 11
('warnings', 'Warnings'), # 12
)
annotation_rows = (
('bits', 'Bits', (0, 1, 2, 3, 4)),
('fields', 'Fields', (5, 6, 7, 8, 9, 10)),
('remote', 'Remote', (11,)),
('warnings', 'Warnings', (12,)),
)
</source>


It groups the first five annotation types together into the '''<tt>bits</tt>''' row and the next six into the '''<tt>fields</tt>''' row. The rows '''<tt>remote</tt>''' and '''<tt>warnings</tt>''' both only contain one annotation type.

Without '''<tt>annotation_rows</tt>''', [[PulseView]] would have to put each annotation type in its own row (which is unhandy if the decoder has many annotations) or it would have to put them all on the same row (which would result in unreadable output due to overlaps). But because of the '''<tt>annotation_rows</tt>''', the output of the [[Protocol_decoder:Ir_nec|ir_nec]] decoder is grouped together as shown in the following picture (note how different annotation types, distinguishable by their different colors, share the same row):

[[File:Pv example ir nec cropped.png]]

However, as you can imagine, handling numeric IDs is quite bothersome - especially if they change and all affected IDs have to be changed throughout the PD. To avoid this, you can use a pseudo-enum:


<source lang="python">
ann_bit, ann_agc_pulse, ann_long_pause, ann_short_pause, ann_stop_bit, ann_leader_code, ann_addr, ann_addr_inv, ann_cmd, ann_cmd_inv, ann_repeat_code, ann_remote, ann_warning = range(13)

class Decoder(srd.Decoder):
...
id = 'ir_nec'
...
annotations = ( # Implicitly assigned annotation type ID
('bit', 'Bit'), # 0 = ann_bit
('agc-pulse', 'AGC pulse'), # 1 = ann_agc_pulse
('longpause', 'Long pause'), # 2 = ann_long_pause
('shortpause', 'Short pause'), # 3 = ann_short_pause
('stop-bit', 'Stop bit'), # 4 = ann_stop_bit
('leader-code', 'Leader code'), # 5 = ann_leader_code
('addr', 'Address'), # 6 = ann_addr
('addr-inv', 'Address#'), # 7 = ann_addr_inv
('cmd', 'Command'), # 8 = ann_cmd
('cmd-inv', 'Command#'), # 9 = ann_cmd_inv
('repeat-code', 'Repeat code'), # 10 = ann_repeat_code
('remote', 'Remote'), # 11 = ann_remote
('warnings', 'Warnings'), # 12 = ann_warning
)
annotation_rows = (
('bits', 'Bits', (ann_bit, ann_agc_pulse, ann_long_pause, ann_short_pause, ann_stop_bit)),
('fields', 'Fields', (ann_leader_code, ann_addr, ann_addr_inv, ann_cmd, ann_cmd_inv, ann_repeat_code)),
('remote', 'Remote', (ann_remote,)),
('warnings', 'Warnings', (ann_warning,)),
)
</source>


This way, all you need to ensure is that the order of the enum entries is the same as in the annotations array and you're set. There is one downside, though, as always: pseudo-enums are pitifully slow in python, so if you use them and you use them in a lot of places, your protocol decoder may be significantly slower (up to 4x has been observed), so choose wisely. You can use the PD test facility to compare, using e.g. 'time ./pdtest -r $YOUR_PD'

== Random notes, tips and tricks ==

* You should usually only use '''raise''' in a protocol decoder to raise exceptions in cases which are a clear bug in how the protocol decoder is invoked (e.g. if no samplerate was provided for a PD which needs the samplerate, or if some of the required channels were not provided by the user, and so on).
* Use the <code>has_channel()</code> method to check whether an optional channel has been provided or not.
* A simple and fast way to calculate a parity (i.e., count the number of 1 bits) over a number (0x55 in this example) is:<source lang="python">
ones = bin(0x55).count('1')
</source>
* A simple function to convert a BCD number (max. 8 bits) to an integer is:<source lang="python">
def bcd2int(b):
return (b & 0x0f) + ((b >> 4) * 10)
</source> This is available as <code>from common.srdhelper import bcd2int</code>
* An elegant way to convert a sequence of bus pins to a numeric value:<source lang="python">
from functools import reduce

def reduce_bus(bus):
if 0xFF in bus:
return None # unassigned bus channels
else:
return reduce(lambda a, b: (a << 1) | b, reversed(bus))
</source>
* A nice way to construct method names according to e.g. protocol commands is (assuming '''cmd''' is 8, this would call the function '''self.handle_cmd_0x08'''):<source lang="python">
fn = getattr(self, 'handle_cmd_0x%02x' % cmd);
fn(arg1, arg2, ...)
</source>
* A cheap way to deal with Python's lack of enumerations (useful for states, pin indices, annotation indices, etc.):<source lang="python">
class Cycle:
NONE, MEMRD, MEMWR, IORD, IOWR, FETCH, INTACK = range(7)
</source>Please be aware, though, that using this mechanism may slow down your decoder significantly. It may make sense to perform some basic profiling to see if this affects you, e.g. using <code>time ./pdtest -r $YOUR_PD</code>.
** A class <code>SrdIntEnum</code> is now available from <code>common.srdhelper</code> based on Python's native [https://docs.python.org/3/library/enum.html#enum.IntEnum <code>IntEnum</code>]
* <div id="SIGROKDECODE_DIR"></div>You don't need to reinstall the whole [[libsigrokdecode]] project every time you make a change on your decoder. Instead, you can use the environment variable '''<tt>SIGROKDECODE_DIR</tt>''' to point the software to your development directory: <source lang="bash">$ SIGROKDECODE_DIR=/path/to/libsigrokdecode/decoders/ sigrok-cli … -P <decodername></source>Because this environment variable is evaluated by the [[libsigrokdecode]] code itself, it can be used for any program that uses the library, for example when calling [[PulseView]] or the '''<tt>pdtest</tt>''' unit test utility from the [http://sigrok.org/gitweb/?p=sigrok-test.git;a=summary sigrok-test] repository. If you compiled a recent [[libsigrokdecode]] by yourself ([http://sigrok.org/gitweb/?p=libsigrokdecode.git;a=commit;h=40c6ac1d3fbded276dcbff23e8bc099896ab2fb5 newer than this commit]), you can also put decoders into your home directory, without the need for an additional environment variable. On Linux systems, this name follows the [http://standards.freedesktop.org/basedir-spec/latest/ar01s03.html XDG base directory specification], which by default resolves to <tt>~/.local/share/libsigrokdecode/decoders</tt>. If that folder does not exist, you can simply create it and drop your decoders there, in their own subdirectory, like you would do in the libsigrokdecode source tree. On Windows systems additional decoders are read from <tt>%ProgramData%\libsigrokdecode\decoders</tt>.

* To debug the Python implementation of a decoder during development, maintenance or research either add <code>print()</code> statements at appropriate locations. Or get WinPDB and use the remote debugging feature as outlined below (add this hook somewhere in pd.py, then "File -> Attach" to the running process). Decoders cannot be used in "regular" debuggers since they expect a rather specific environment to execute in, for all of receiving their input as well as having their output saved or presented as well as processing samples (data types, runtime routines). Remote debugging works in both the sigrok-cli and pulseview context. Adding another <code>print()</code> statement before starting the embedded debugger can help identify the moment in time when to attach.<source lang="python">
def __init__():
import rpdb2
rpdb2.start_embedded_debugger("pd")
...
</source>

For Windows you might want to use the following code, adapting it to your Python and WinPDB-reborn version:<source lang="python">
def __init__():
import sys
sys.path.insert(0, 'c:/Program Files (x86)/Python38-32/Lib/site-packages/winpdb_reborn-2.0.0.1-py3.8.egg')
import rpdb2
rpdb2.start_embedded_debugger("pd", fAllowRemote=True)
...
</source>

== Unit tests ==

In order to keep protocol decoders in a running state even when we make changes to a decoder or libsigrokdecode itself, we use unit tests for as many decoders as we can. These are stored in the [http://sigrok.org/gitweb/?p=sigrok-test.git sigrok-test repository]. If you want to add, modify or run one of them, clone that repository and [https://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=README check the README] for documentation.
We greatly appreciate it when you submit unit tests for your decoder so we can keep it in good health!

== Submitting your decoder ==

When you've finished your decoder and everything is working nicely, please contribute the decoder to the sigrok project so that other people can benefit from it (and test it, improve upon it, and so on).

* Check the decoder's operation in the most recent version of the software. You expect the decoder to get accepted in the project's mainline codebase. So it should work in that environment. Either build from up-to-date sources, or download nightly builds.
* Tell us about the location of your public git repo on the '''#sigrok''' IRC channel on libera.chat. As an alternative send the decoder to the [https://lists.sourceforge.net/lists/listinfo/sigrok-devel sigrok-devel] mailing list (preferrably against current master and as a full commit instead of a mere diff). Remember that pushing to a public git repo is preferred over email attachments.
* Please also make example data files (*.sr) including a small README available. Developers need these in order to properly review and test your decoder. Users need these to learn what the captures are about in the first place. Preferrably these files should also come as patches against the latest git master of the [http://sigrok.org/gitweb/?p=sigrok-dumps.git;a=tree sigrok-dumps] repository. See [[Example dumps]] for details. Submitting captures before any decoder materializes or work on a decoder even starts is very useful.
* Finally, please also consider adding a few "unit tests" for your decoder in the [http://sigrok.org/gitweb/?p=sigrok-test.git;a=tree sigrok-test] repository. These test will automatically run the decoder against various input files specified in '''test.conf''' and check whether the expected output is produced (examples: [http://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=decoder/test/rfm12/test.conf rfm12], [http://sigrok.org/gitweb/?p=sigrok-test.git;a=blob;f=decoder/test/nrf24l01/test.conf nrf24l01]). This allows us to notice and fix any regressions in the decoder and/or the [[libsigrokdecode]] backend that may arise over time.

Thanks a lot!

[[Category:APIs]]

User:Endolith

2021-07-19T13:24:12Z

Endolith: Created page with "https://github.com/endolith/libsigrokdecode"

https://github.com/endolith/libsigrokdecode