diff --git a/README b/README deleted file mode 100644 index ca222d7..0000000 --- a/README +++ /dev/null @@ -1,105 +0,0 @@ -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. - diff --git a/README.md b/README.md new file mode 100644 index 0000000..b5f7cc4 --- /dev/null +++ b/README.md @@ -0,0 +1,106 @@ +SUMP compatible logic analyzer for Arduino +========================================== + +This Arduino sketch implements a SUMP protocol compatible logic analyzer. +This implementation is compatible with the standard SUMP client as well as +an alternative OLS client. More recently support has been added to Sigrok. + +This logic analyzer for Arduino supports 6 channels consisting of digital +pins 8-13, which are the first 6 bits (0-5) of PORTB. +Arduino pin 13 / bit 5 is the Arduino LED, bits 6 & 7 are the crystal +oscillator pins. Comment out CHAN5 if you don't want to use the +LED pin for an input. + +On the Arduino Mega board 8 channels are supported and 7k of samples. +Pins 22-29 (Port A) are used by default. + +Client Software +=============== + +The OLS alternative client hasn't had an official release recently so you will +need to compile it yourself. + +Follow the build instructions here: https://github.com/jawi/ols + + +Older details on the OLS client is available at the project page: +https://lxtreme.nl/projects/ols/ + +Direct link to older releases of the OLS alternative client: +http://www.lxtreme.nl/ols/ + +The alternative client version is highly recommended. You can tried the older +release ols-0.9.7.2 but most likely need to build it yourself. Use "ols-0.9.7" +or newer for built-in device profiles. + +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) +``` + +Using the Logic Analyzer +======================== +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. Please provide a detailed bug report +if you file an issue. + +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-cli` tool to compile this using the Makefile, +you'll need to install the tool first following instructions here: +https://arduino.github.io/arduino-cli/ + +Once installed you can simple type `make` and you should get some simple help: +```bash +$ make +---> run 'make build' to compile for Arduino Duemilanove +---> run 'make upload' to upload to /dev/ttyUSB* +``` + + +Other Notes +=========================================================================== +``` +NOTE: Starting with v0.11 you can 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 too big for an ATmega168's flash. The code + automatically skips the 2MHz code on ATmega168 + +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: 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. ] +```