DISK IMAGE MANAGER AND GUI FOR UPLOADING PATTERNS TO KNITTING MACHINES

This program will allow you to design patterns in any raster image
editor such as gimp, photoshop, paintbrush, picasa, corel painter, etc.
and upload them to your knitting machine.

You will need to build an interface cable. How to do this:
* http://www.ladyada.net/wiki/tutorials/knittingmachine/ftdicable.html

Supports WINDOWS and LINUX. Mac OSX support is stagnant, but
you can contribute by contacting [email protected]

Machine capabilities:
* Brother Electroknit KH-950
* Brother Electroknit KH-940
* Brother Electroknit KH-930 BETA
* ! Your machine here?
    Help out the project! :)

Emulation capabilities:
* PDD1 floppy drive FDC emulation mode (limited)

Picture read capabilities:
* Recommended: 24-bit RGB - GIF, TIFF, PNG
* Any format supported by FreeImage

Software using library:
* Alternative OpenFrameworks GUI
  See http://www.mcanet.info/patternUploader/ for information

Recognition:
* Thanks to Jonas Bengtsson for OSX support and binaries
* Thanks to Andrew Solomone for the full-color knitting style
* Thanks to Varvara Guljajeva and Mar Canet for inspiring the project
* Thanks to Steve Conklin for information provided at Antitronics
* GUI relies on SDL2 and FreeImage

== WINDOWS USERS =====================================================

Just download everything in the bin-win\ folder, put it anywhere you
like, then run gui.exe. This has everything you need to quickly get
patterns onto your machine.

== MAC USERS =========================================================

OSX binaries can be found in the bin-osx/ directory.
Jonas, would you like to put in a word here?

== LINUX USERS =======================================================

Linux binares can be found in the bin-linux/ directory.
This requires a modidifed SDL2 library to add xDnD support.
Tested under Ubuntu only.

Serial port detection is working, but is limited! HELP WANTED!
Should it fail, see bin-linux/ports.rc on how to manually add serial
devices to the list of detected ports.

The custom libSDL2.so file must be placed in the library search path.
Sorry for this odd procedure. HELP WANTED!

== FILES =============================================================

bin-X/            Binaries/executables for operating system X
lib/              Source files for the disk image manager/emulator
cli/              Source files for command line interface
gui/              Source files for graphical user interface
doc/              File/memory layout description
ptn/              Sample patterns as both original bmp and raw

win-###-make.bat  Build ###:cli/gui program (windows batch file)
linux-###.make.sh Build ###:cli/gui program (linux shell script)
osx-###.make.sh   Build ###:cli/gui program (osx shell script)

Want to help out by creating makefiles? Let me know!

== HOW TO USE GUI UTILITY ============================================

Sorry, no proper documentation available at this point. HELP WANTED!

It is however fairly straight forward!

1) Install the application (os dependant process) and launch it.
2) Click FORMAT and select your machine
3) Drag pictures (24-bit GIF, PNG or TIFF) into the window
   Make sure the pictures are of size STITCHESxROWS pixels.
   Pictures with two colors will import as single color.
   Pictures with different colors will import as multi or full color.
     Multi-color: pictures with only one contrast color per row
     Full-color: pictures with several colors on one or more rows
       Full-color requires special stitching procedure
4) Verify import by clicking pattern in list on the left, then EDIT.
5) Click EMULATE and select the correct serial port in the list
6) Use the knitting machine to load from disk (track #1 only)

== HOW TO USE CLI UTILITY ============================================

The CLI utility can be considered outdated, but is still useful when
you need to make patterns on a new machine and store them as a file
for analysis. The GUI does not provide this functionality.

Compile and launch knit executable.

Typing ? or help will give

  ?/help      show this
  r/read      read in data from file
  w/write     write out data to file
  m/machine   select knitting machine
  f/format    clear all tracks
  t/track     set working track
  a/add       add pattern to track
  s/show      display content of track
  i/info      additional track info
  e/emulate   emulate floppy
  q/quit      end program
  x/halt      halt on errors


read - Reads image on disk to memory
  The file can be either disk image or folder with emulator files.

  Entering the name of a file will read it as a disk image, ie:
    filename> sample/1.img

  Entering a folder name, ending with a (back)slash, will read
  Tandy FDD1 emulator file folder, ie:
    filename> fddemu/img/
    
    
write - Write memory to image on disk
  The file can be either disk image or folder with emulator files.
  See "read" command for more info.


machine - Select knitting machine
  This will show the currently selected machine as well as list
  the available/supported machines.
  
  After listing, you are prompted to select a new machine and
  this is selected by typing the short name of the machine
  you wish to use, ie:
    machine> kh940


format - Clear computer ram contents
  This will delete everything currently contained in memory and
  ready the program for input of a new file.


track - Set working track
  The machine can store patterns in two separate tracks and this
  is chosen when saving/loading from the machine.
  
  This will sets the current working track for add, show and
  info commands.
  
  Tracks are entered as a number between 1 and 2, ie:
    track> 1
  
  
add - Add a pattern to memory
  The pattern is read from a raw image file, ie:
    filename> patterns/903.raw

  See doc\raw_format.txt for a description of the format.
  
  
show - Show patterns contained in memory
  This will list all available patterns and to into pattern
  display mode. In this mode you get the following promt:
  
    pattern>
    
  instead of the regular one.
  
  To exit this mode enter d, done or simply enter a blank line.
  
  While in this mode, enter the pattern number of an available
  pattern to print out a graphical representation of the
  pattern as well as its binary data representation.


info - Shows additional non-pattern information
  This will display all important fields in the currently
  loaded file and run a verification suite against all of
  the know values.
  
  Verifications are done against the most common and verified
  to work values that have been downloaded from the machine.
  
  Therefore it MAY give FAIL on "write pointer" entries and/or
  the "loaded head" entry for some files because the machine
  sometimes inserts a 0x00 byte between patterns which causes
  a mismatch of 1 for these values. Exactly when/why this is
  done is uncertain, but it is not needed when writing patterns,
  so it may actually be a bug in the machine.
  
  Additionally, MOST parameters WILL give FAIL on a blank
  formatted file, regardless if done via device or this
  program.
  
  For a file generated using this program all parameters
  should give OK before attempting download.
  

emulate - Start floppy emulator
  
  This will ask for a serial device and the format is different
  depending on your system. For linux-flavors, it will usually
  look like:
  serial device> /dev/ttyS0
  
  For windows, it will look something like:
  serial device> COM1
  
  After entering a serial device, the program will go into 
  floppy emulation mode.
  
  You can exit this mode by sending a SIGINT, which is usually
  Ctrl+C on most systems.
  
  While in this mode, you can use the knitting machine to save
  or load data into program memory, which can first be build
  using add or read using read.
  
  After saving from the machine you can keep it with write.
  
  
quit - Self explanatory
  Go outside and enjoy the weather
  
halt - Enable/disable halt on errors
  Enabling halt on errors is good for command line execution
  
== CLI BATCH EXECUTION ===============================================

All commands can be executed from command line, for example:

knit x a ptn/tile.raw a ptn/inca.raw a ptn/text.raw w test.img q

Will do the following:

* Enable halt on error
* Add ptn/blocks.raw as #901
* Add ptn/inca.raw as #902
* Add ptn/text.raw as #903
* Write disk image to test.img
* Quit

In addition commands can also be piped in, or typed manually in
succession at any prompt within the program.

== LACE TOOL COMPILER ================================================

A lace tool compiler is included in the lace/ directory, this compiler
works with the brother lace tool, supporting normal and fine lace.
The purpose of the lace tool is to move or join stitches across neddles,
see the lace tool ASCII format defined in doc/lace_format.rst

You can use it from command line like this:

python lace/lace_compiler.py lace/examples/fox.lace out.raw && \
           ./bin-linux/cli a out.raw e /dev/ttyUSB0 q

There's no gui support for it yet.