VERSION = "0.1.0"
-DESTDIR ?= /usr/local/share/sigrok-dumps
+# TODO Ideally instructions would use autotools, cmake, or some other
+# higher level abstraction instead of DIY shell commands. Which would
+# improve portability and robustness (by picking the most appropriate
+# install tool that is available on the target), and would transparently
+# enable support for --prefix and DESTDIR et al, including out of source
+# builds when desired.
+PREFIX ?= /usr/local
+INSTALL_DIR = $(PREFIX)/share/sigrok-dumps
+
+# Be explicit about which files or subdirectories to install.
+# Update this list when adding a new top level subdirectory to the
+# set of example captures. It's assumed that this event is rare.
+# The list is phrased such that users can specify additional items
+# when they invoke the 'make install' command.
+FILES_DIRS += ac97 am230x arm_trace aud avr_isp avr_pdi
+FILES_DIRS += caliper can cec
+FILES_DIRS += dac dali dcc dcf77 display dmx512 dsi
+FILES_DIRS += flexray fsk
+FILES_DIRS += gpib graycode
+FILES_DIRS += i2c i2s ir
+FILES_DIRS += jtag
+FILES_DIRS += led lens_mounts lpc
+FILES_DIRS += maple_bus mcs48 mdio microwire miller misc morse mouse_sensors
+FILES_DIRS += nfc nonstandard_eeproms
+FILES_DIRS += onewire ook
+FILES_DIRS += pjon ps2 pwm
+FILES_DIRS += qi
+FILES_DIRS += rc rfid
+FILES_DIRS += sae-j1850 sdcard sdq sht7x signature sle44xx spdif spi
+FILES_DIRS += stepper_motor swd swim
+FILES_DIRS += tdm_audio
+FILES_DIRS += uart usb usb_power_delivery
+FILES_DIRS += vfd
+FILES_DIRS += wiegand
+FILES_DIRS += xy2-100
+FILES_DIRS += z80
all:
@echo "Run 'make dist' to create a tarball."
@rm -f ChangeLog
install:
- @mkdir -p $(DESTDIR)
- @cp -r * $(DESTDIR)
- @rm -f $(DESTDIR)/Makefile
-
+ @mkdir -p $(DESTDIR)$(INSTALL_DIR)
+ @cp -r $(FILES_DIRS) $(DESTDIR)$(INSTALL_DIR)
sigrok-dumps is in a usable state and has had official tarball releases.
+Installing
+----------
+
+Example captures need not get built or compiled, but can get installed.
+
+ $ git clone git://sigrok.org/sigrok-dumps
+ $ cd sigrok-dumps
+ $ make install
+
+Optional PREFIX or DESTDIR specs are supported as well.
+
+ $ make PREFIX=/usr install
+ $ make PREFIX=${HOME} install
+
+ $ make DESTDIR=$( pwd )/rootfs install
+
+
Contributing dumps
------------------
IRC
---
-You can find the sigrok developers in the #sigrok IRC channel on Freenode.
+You can find the sigrok developers in the #sigrok IRC channel on Libera.Chat.
Website
--- /dev/null
+-------------------------------------------------------------------------------
+AVR ISP / Atmel ATmega328/P
+-------------------------------------------------------------------------------
+
+This is an example capture of the AVR in-system programming (ISP) protocol.
+
+The device used for ISP was a Bus Pirate v3.5 with firmware v6.1.
+
+The target was an Arduino UNO board with an Atmel ATmega328/P chip.
+
+The PC software used for controlling the programmer was avrdude 7.1.
+
+
+Logic analyzer setup
+--------------------
+
+The logic analyzer used was a Saleae Logic Clone (at 4MHz):
+
+ Probe AVR ISP header
+ -------------------------
+ 1 MOSI
+ 2 MISO
+ 3 SCK
+ 4 RST
+
+
+Data
+----
+
+The following avrdude commands were captured:
+
+ avrdude -p atmega328p -c buspirate -P /dev/ttyUSB0 -v
----------------------
Cycles through the numbers 0 to F with alternating dot.
+
+
+test_7_segment_all_alphabet.sr
+------------------------------
+
+Covers more combinations of LED segments, including alphanumeric codes
+(letters, punctuation).
+
+
+mystery_message.sr
+------------------
+
+Contains LED segment combinations that are not known to the decoder.
--- /dev/null
+-------------------------------------------------------------------------------
+Maxim Integrated DS3231 RTC
+-------------------------------------------------------------------------------
+
+Details:
+ - DS3231 datasheet: https://datasheets.maximintegrated.com/en/ds/DS3231.pdf
+
+
+Logic analyzer setup
+--------------------
+
+The logic analyzer used was Geeetech Mini Board Cypress FX2(LP) eval board
+with fx2lafw firmware (at 4MHz):
+
+ Probe DS3231 pin
+ -------------------------
+ 0 SCL
+ 1 SDA
+
+
+ds3231_ex1.sr
+----------------------
+
+The file provides reading/writing of time keeping registers as well as
+control, control/status and temperature registers of the RTC chip, which
+was setup to 24-hours mode:
+
+- Read Control register
+- Write Control register - disable alarms
+- Read Control/Status register
+- Write Control/Status register - clear alarm's flags
+- Write Alarm 1 registers - set Alarm 1 at every 1st date
+- Write Alarm 2 registers - set Alarm 2 at every minute
+- Read date/time
+- Read temperature (MSB)
+
+
+ds3231_ex2.sr
+----------------------
+
+The file provides reading/writing of time keeping registers as well as
+control/status and temperature registers of the RTC chip, which was setup
+to 24-hours mode and after Alarm 2 occured:
+
+- Read Control/Status register
+- Write Control/Status register - clear alarm flag
+- Read date/time
+- Read temperature (MSB)
--- /dev/null
+-------------------------------------------------------------------------------
+Intel H55 LPC (low pin count) traffic
+-------------------------------------------------------------------------------
+
+This capture is an LPC (low pin count) I/O read transaction from an Intel H55
+chipset on a Foxconn H55MXV motherboard.
+
+Details:
+http://en.wikipedia.org/wiki/Low_Pin_Count
+
+
+Hardware setup
+--------------
+
+The capture was taken with an FPGA sampling at 200 MHz and imported into sigrok
+as 8bit binary data.
+
+ Probe LPC
+ ----------
+ 2 LCLK
+ 3 LFRAME#
+ 4 LAD0
+ 5 LAD1
+ 6 LAD2
+ 7 LAD3
+
+
+h55_lpc_io_write.sr
+---------------
+An I/O write to 0x2e (super IO index register) of 0x55.
--- /dev/null
+-------------------------------------------------------------------------------
+IBM POWER9 LPC (low pin count) traffic
+-------------------------------------------------------------------------------
+
+These captures are examples of various transaction types from an IBM POWER9 LPC
+(low pin count) interface.
+
+Details:
+http://en.wikipedia.org/wiki/Low_Pin_Count
+
+
+Hardware setup
+--------------
+
+The logic analyser used was a DreamSourceLab DSLogic U3Pro32. As support for
+this is not yet in sigrok, the traces were captured externally and imported.
+
+ Probe LPC
+ ----------
+ 0 LAD0
+ 1 LAD1
+ 2 LAD2
+ 3 LAD3
+ 4 LFRAME#
+ 5 LCLK
+
+
+power9_lpc_io_read.sr
+--------------
+An I/O read from 0x3fd (serial port) which returns 0x60.
+
+power9_lpc_io_write.sr
+---------------
+An I/O write to 0x3f8 (serial port) of 0x73.
+
+power9_lpc_firmware_read.sr
+--------------------
+A firmware read from 0xfff7000 which returns 0x54524150.
+
+power9_lpc_firmware_write.sr
+---------------------
+A firmware write to 0xc031360 of 0x0000.
+
+power9_lpc_io_write_abort.sr
+---------------------
+An I/O read that gets aborted because the peripheral never responded.
--- /dev/null
+------------------------------------------------------------------------
+SQI communication (multi-I/O SPI)
+------------------------------------------------------------------------
+
+This capture demonstrates SQI communication, which is a form of SPI data
+exchange where transmitters use multiple I/O data lines in parallel to
+communicate the same amount of data in fewer clock cycles.
+
+In contrast to e.g. QuadSPI flash memory chips which may change the data
+line count or clock scheme several times within a transaction, SQI keeps
+the clock and the number of data lines used by the transmitter consistent
+across the full length of the SPI transaction. Only the direction of data
+lines could change, when e.g. a master first transmits a request which
+the slave then responds to, while both use the same number of data lines.
+Full duplex communication as with the traditional MISO/MOSI scheme is
+not possible with SQI.
+
+
+Logic analyzer setup
+--------------------
+
+The capture was taken at a samplerate of 100MHz.
+
+ Probe SPI
+ ----------------------------
+ 2 SCK (clock)
+ 3 CS (select)
+ 4 IO0 (data, LSB)
+ 5 IO1
+ 6 IO2
+ 7 IO3 (data, MSB)
+
+
+sqi-four-data-lines-one-transfer.sr
+-----------------------------------
+
+This capture uses four I/O data lines. Data gets sampled at the rising
+clock edge (single data rate). Data is sent in MSB first order. The SPI
+transaction's data byte sequence is:
+
+ 80 00 00 10 22 42 4f 4f 54 00 80 00 00 a8 85 77 00 20 4e 00 00
+
+
+sqi-four-data-lines-three-transfers.sr
+--------------------------------------
+
+This capture was constructed from the above single-transfer example
+capture. The SPI transfer is repeated three times.