logic_analyzer_sump/README

SUMP compatible logic analyzer for Arduino
==========================================

This Arduino sketch implements a SUMP protocol compatible with the standard
SUMP client as well as the alternative client from here:
	http://www.lxtreme.nl/ols/

The alternative client version is highly recommended.  Download version
"ols-0.9.7" or newer for built-in device profiles.
NOTE: The latest officially released version of ols (0.9.7.2) does not work
      with modern Java runtimes.  You will need to build it yourself.
      Follow the build instructions here: https://github.com/jawi/ols

This SUMP protocol compatible logic analyzer for the Arduino board supports
5 channels consisting of digital pins 8-12, which are the first 5 bits (0-4)
of PORTB. Arduino pin 13 / bit 5 is the Arduino LED, bits 6 & 7 are the
crystal oscillator pins.

Uncomment CHAN5 below if you want to use the LED pin as an input and have
6 channels.

On the Arduino Mega board 8 channels are supported and 7k of samples.
Pins 22-29 (Port A) are used by default.

To use this with the original or alternative SUMP clients,
use these settings:

Sampling rate: 4MHz (or lower) (no 2MHz on ATmega168)
Channel Groups: 0 (zero) only
Recording Size:
   ATmega168:  532 (or lower)
   ATmega328:  1024 (or lower)
   ATmega2560: 7168 (or lower)
Noise Filter: doesn't matter
RLE: disabled (unchecked)

Triggering is still a work in progress, but generally works for samples
below 1MHz.  1MHz works for a basic busy wait trigger that doesn't store
until after the trigger fires.
Please try it out and report back.

Debugging
=========

You can uncomment the '#define DEBUG_MENU' line to add some diagnostic menu
options for capturing or dumping the capture buffer.
You can uncomment the '#define DEBUG' and '#define DEBUG_MENU' for a couple
extra menu options and logging of the received commands.  The DEBUG option
is generally only useful for development, while the DEBUG_MENU option is
good for troubleshooting when the logic_analyzer sketch isn't working for you.
Both are disabled by default to conserve RAM for improved stability.

CLI compiling
=============

If you want to use the 'arduino-mk' package (on Debian for example ) to compile
this using the Makefile, you'll need to make a couple of changes since the
Makefile only supports a single .ino file.  Basically you just need to append
the other two files to the main .ino and then remove them.

$ cat logic_analyzer_inline_4mhz.ino >> logic_analyzer.ino
$ cat logic_analyzer_inline_2mhz.ino >> logic_analyzer.ino
$ rm logic_analyzer_inline_4mhz.ino logic_analyzer_inline_2mhz.ino
$ make

This will make GIT unhappy so if you need to revert it to run 'git pull' do
this:
$ git reset --hard origin/master


Older Notes
===========================================================================
NOTE: With v0.11 you can now sample at 4MHz & 2MHz rates in addition to the 
      previous 1MHz and lower rates.  This is done via unrolled loops which
      makes the source code huge and the binary takes much more of the flash.
      v0.11 is just slightly to big for an ATmega168's flash.  You can comment
      out either captureInline2mhz() or captureInline4mhz() and it will fit.
      [ The code automatically skips the 2MHz code now, this isn't needed. ]

NOTE: v0.09 switched the channels BACK to pins 8-13 for trigger reliability.
      Please report any issues.  Uncomment USE_PORTD for pins 2-7.

NOTE: The device profiles should be included with this code.  Copy them to the
      'plugins' directory of the client.  The location varies depending on the
      platform, but on the mac it is here by default:
      /Applications/LogicSniffer.app/Contents/Resources/Java/plugins
      [ These are included in ols-0.9.7 or newer so do not copy them. ]

NOTE: If you are using the original SUMP client, then you will get a
      "device not found" error.
      You must DISABLE the Arduino auto reset feature to use this logic analyzer
      code. There are various methods to do this, some boards have a jumper,
      others require you to cut a trace.  You may also install a *precisely*
      120 Ohm resistor between the reset & 5V piins.  Make sure it is really
      120 Ohm or you may damage your board.  It is much easier to use the
      alternative SUMP client referenced above.
      [ This is not needed with ols-0.9.7 or newer. ]
      [ DO NOT use this resistor unless absolutely necessary on old clients. ]

NOTE: This master branch now supports Arduino 1.0 only.
      Checkout branch logic_analyzer_v0_5 for Arduino 22 support.


Release: v0.15 December 21, 2021.