W2000A Screenshot Utility
=========================
--- Version 0.96 ---

Useful websites:
 http://sourceforge.net/apps/trac/welecw2000a/
 http://www.mikrocontroller.net/topic/206819 (in German)

Changelog
---------

* v0.1 (Initial Release):

  Provides new RS232 command # (pound) to initiate b/w screendump with simple
  RLE compression.  Usually only around 10-15kB to be transferred.

* v0.2:

  Additional ' (tick) command to initiate full plane dump with same simple RLE
  compression as with the # command.  Around 60-65kB total to be transferred.

  Planes are coloured and combined into an PPM image file.  Individual planes
  are also available as numbered PGM image files for inspection or partial
  export.

  New -h and -f command line options.  More status and progress messages on
  stderr.

  Since multiple planes can be output, data is written to file(s) in v0.2, no
  longer to stdout.  Use -f option to specify target file prefix.

* v0.3:

  Native windows support.  New command line option -c to specify COM port.
  Third party ComTools from Anton Zechner are used for now, likely to be
  replaced in upcoming releases.  Precompiled EXE is bundled from now on.

  Alternative BMP output instead of PPM/PGM.

  Makefile is provided.  Please note that we changed from .c to .cpp just for
  the third party ComTools, actual C++ features are not used.

  Patch is now included in BF1.2-0.80-beta upwards, so diff is no longer
  provided.  ' and # RS232 commands were removed, instead screenshots may be
  triggered in the Quick Print of the DSO.

* v0.4

  Linux: -c </dev/ttyXX> is implemented.

  Different RLE algorithm used (better compression for up to 60000 identical
  bytes.

  The program will now trigger a screenshot download (with -s), a monochrome
  screenshot (-m) or a dump of raw data (-d).

  The programm now keeps listening for as many dumps as you want to make.  Old
  behavior may be turned on by using -o (One-Shot).

  Because of that, files have to named sequentially.  A 4-digit number is
  starting at 0000 is added.  You may set the start point manually via -n.
  Please note:  Files are truncated and overwritten.  So make sure you
  move away your precious previously obtained scope data before a new
  invocation _or_ carefully use -n / -f.

  Monochromatic screenshots are now black/white, no longer black/greyish.

  New -i flag, inverts colours.  Especially useful for monochromatic
  screenshots.

  New command line option -t to specify trace file format, currently
  supported:  csv (default) and ascii.

  Patch is in SVN firmware and firmware starting FW1.2-0.84-beta.

* v0.88

  From now on, any version X.YY will work with version X.YY of the open source firmware 

* v0.89

  Modified order of planes

* v0.90

  Switch "-r" requests a dump of unfiltered data

* v0.91

  Switch "-v" display version information

* v0.93

  Extended dump type recognition to be BF and OS firmware compatible.
  This version also works with older firmware revisions.

* v0.94:

  - unified OS screenshot utitilty and derived utility by BF/Hayo
  - recommended DSO firmware BF v2.13 or newer,
    older versions may work but are untested
  - a _whole lot_ of cleanup and refactoring
  - fixed and updated comments and documentation (i.e. this file)
  - new command line option -a
  - ouput of scope parameters on trace dump

* v0.95:

  - reworked trace dumps, both on this side as well as on the DSO side
  - traces may now be scaled via command line option -p
  - improved header format
  - needs BF Firmware v2.14 or newer

* v0.96:

  - able to trigger and receive measurements
  - needs BF Firmware v2.16 or newer
  - minor improvements/fixes

Known Issues
------------

  The BMP file format uses the somewhat uncommon storing order of
  "upside-down", in contrast to the usual raster scan order starting top-left
  (0, 0) and ending bottom-right (640, 480).

  Turns out that using the "normal" order is possible and specified by using a
  negative height value.  But after implementing this it further turns out
  that some programs and image libraries just don't expect that option to be
  used.

DSO Preparation
---------------

  * BF Firmware v2.16 or newer is required

  * Older firmware:
    Pleae update firmware :)

Building
--------

  $ make unix
  or
  $ make win

Making A Screenshot or Retrieving Traces
----------------------------------------

  Windows:

     Run w2000a-screenshot.exe or edit and use provided .bat file.

  Advanced Usage:

  (1a) Start w2000a-screenshot:
       $ ./w2000a-screenshot -c $device

       The program now waits for data dumps from the DSO.

       Use the Quick Print menu on the DSO.  Download starts automatically.

  (1b) Start w2000a-screenshot:
        $ ./w2000a-screenshot -c $device -s

       The program triggers a colour screenshot dump immediately, then exits.

       Use -m, -d for monochrome screenshot or traces respectively.
       (Note:  Use -i in combination with -m for printouts.)

  (2a) In the case of screenshots, the utility decompresses the RLE data from
       the DSO and writes a PPM or BMP image file.

       You might want to use ppmto*(1) of NetPBM or convert(1) of
       ImageMagick to make more handy files out of the PPM images, i.e.:
         $ convert screenshot-num.ppm screenshot-num.png

  (2b) For measurement data, the utility writes a .csv (Comma Seperated Values)
       file.  Use -t ascii to change to ASCII output (suitable for kst).