README: explain why, show --help of brother_ql_create & more

DEBUG.md

@@ -0,0 +1,35 @@
+
+#### Debug
+
+If your printer has problems printing the instructions file, it may blink its LED (green or red) depending on the model. This can have many reasons, eg.:
+
+* The selected label doesn't match.
+* End of paper.
+* Unsupported opcode (some printers require a mode switching opcode, others fail if such an instruction is sent; some do support data compression, others don't)
+
+To debug this situation and find out which command could be the culprit, connect your printer via USB. (You don't get any status information via network).
+You can use the supplied tool `brother_ql_debug` to send your problematic instructions file to the printer. It will be split into single instructions sent one after the other.
+After every instruction, the printer will be given a chance to send a status response containing error information. Here is an example:
+
+    philipp@lion ~> brother_ql_debug ./720x151_monochrome.bin /dev/usb/lp0
+    INFO: CMD preamble FOUND. Instruction: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 [...] 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
+    INFO: CMD init FOUND. Instruction: 1B 40 
+    INFO: CMD status request FOUND. Instruction: 1B 69 53 
+    INFO: Response from the device: 80 20 42 30 4F 30 00 00 00 00 3E 0A 00 00 15 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    INFO: Interpretation of the response: 'Reply to status request' (phase: Waiting to receive), 'Continuous length tape' 62x0 mm^2, errors: []
+    INFO: CMD media/quality FOUND. Instruction: 1B 69 7A CE 0A 3E 00 97 00 00 00 01 00 
+    INFO: CMD margins FOUND. Instruction: 1B 69 64 23 00 
+    INFO: CMD raster FOUND. Instruction: 67 00 5A 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 FF FF FF 1F FF FF FF FF FF F0 00 00 00 00 00 0F FF FF 03 FF FF FF FF E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 [...] 00 07 FF FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
+    INFO: Response from the device: 80 20 42 30 4F 30 00 00 00 00 3E 0A 00 00 15 00 00 00 06 01 00 00 00 00 00 00 00 00 00 00 00 00
+    INFO: Interpretation of the response: 'Phase change' (phase: Printing state), 'Continuous length tape' 62x0 mm^2, errors: []
+    INFO: CMD print FOUND. Instruction: 1A 
+    TIME 1.60
+    INFO: Interpretation of the response: 'Printing completed' (phase: Printing state), 'Continuous length tape' 62x0 mm^2, errors: []
+    TIME 1.60
+    INFO: Interpretation of the response: 'Phase change' (phase: Waiting to receive), 'Continuous length tape' 62x0 mm^2, errors: []
+
+Here, a command file was successfully printed. The last response should state the *Waiting to receive* phase.
+If you want to confirm the sending of every single command individually, you can add the `--interactive` argument to the command line call.
+
+If you're seeing any error there, open a new issue on Github containing the debugging output to get your device supported.
+

README.md

@@ -7,7 +7,7 @@ In more details, the following is possible with this package:
 * Create raster language files for the Brother label printers.  
   These binary files contain the instructions for the printer and can be created from image files or programmatically in your own Python script.
 * Analyze files containing raster instructions.  
-  A tool that interprets all the instructions, writes out information about all of them, and creates PNG images of the printouts to be expected.
+  A tool to dissect the binary files (interprets all the instructions, writes out information about all of them, and creates PNG images of the printouts to be expected).
 * Print raster instruction files with your Brother label printer via different backends:
   * pyusb (works cross-platform)
   * network (works cross-platform for WiFi/Ethernet-enabled printers)
@@ -17,6 +17,17 @@ The following printers are claimed to be supported (✓ means verified by the au
 
 * QL-500 (✓), QL-550, QL-560, QL-570, QL-580N, QL-650TD, QL-700 (✓), QL-710W (✓), QL-720NW (✓), QL-1050, and QL-1060N.
 
+### Why
+
+The special feature is that no printer driver is required from Brother for this to work.
+This software bypasses the whole printing system including printer drivers and directly
+talks to your label printer instead. This means that even though Brother doesn't offer
+a driver for the Raspberry Pi (running Linux on ARM) you can print nicely using this software.
+Even if there are drivers for your operating system, many programs have difficulties to set
+the page sizes and margins for the labels correctly. If you want to print with high precision
+(which is important for barcodes for example), you rather want to have control about every
+single pixel to be printed. That's possible with this software package.
+
 ### Installation
 
     pip install https://github.com/pklaus/brother_ql/archive/master.zip
@@ -31,8 +42,9 @@ This package was mainly created for use with Python 3. The essential functionali
 
 #### Create
 
-You can create a new instruction file to be sent to the printer with
+This is possibly the most important piece of software in this package:
-the `brother_ql_create` tool:
+
+It allows you to create a new instruction file in the label printers' raster language:
 
     brother_ql_create --model QL-500 ./720x300_monochrome.png > 720x300_monochrome.bin
 
@@ -40,21 +52,50 @@ If you want to find out about its options, just call the tool with `--help`:
 
     brother_ql_create --help
 
-Currently, the `brother_ql_create` tool is still lacking quite some important features like:
+giving:
 
-* setting the media to something different than 62mm endless labels
+    usage: brother_ql_create [-h] [--model MODEL] [--label-size LABEL_SIZE]
-* using the 600dpi mode
+                             [--threshold THRESHOLD] [--no-cut]
+                             [--loglevel LOGLEVEL]
+                             image [outfile]
+    
+    positional arguments:
+      image                 The image file to create a label from.
+      outfile               The file to write the instructions to. Defaults to
+                            stdout.
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      --model MODEL, -m MODEL
+                            The printer model to use. Check available ones with
+                            `brother_ql_info --list-models`.
+      --label-size LABEL_SIZE, -s LABEL_SIZE
+                            The label size (and kind) to use. Check available ones
+                            with `brother_ql_info --list-label-sizes`.
+      --threshold THRESHOLD, -t THRESHOLD
+                            The threshold value (in percent) to discriminate
+                            between black and white pixels.
+      --no-cut              Don't cut the tape after printing the label.
+      --loglevel LOGLEVEL   Set to DEBUG for verbose debugging output to stderr.
 
-Please open an issue on Github if you want the tool to support more use cases.
+The image argument should be a PNG/GIF/JPEG image file.
-State what you want to be supported and what the command call could look like.
+For the best results, provide it in the right pixel dimensions (suiting the chosen --label-size).
+
+Some notes:
+
+Currently, the `brother_ql_create` tool doesn't support the 600x300 dpi mode supported by some printers.
+The output will always use the 300dpix300dpi mode with the *high quality preference* set.
 
 #### Analyse
 
-To analyse a binary file containing Brother QL Raster instructions and
+To analyse a binary file containing Brother QL Raster instructions:
-create an image of what would be printed:
 
     brother_ql_analyse 720x300_monochrome.bin --loglevel DEBUG
 
+The tool will dissect your file and print the opcodes to stdout.
+In addition, it creats images of what the printer's output would look like.
+They are saved to page0001.png etc. (yes, one .bin file can contain more than one "page").
+
 This tool also has the `--help` option.
 
 (This specific tool doesn't work on Python 2.)
@@ -71,7 +112,7 @@ Or via network (if you have a LAN/WLAN enabled Brother QL):
 
     nc 192.168.0.23 9100 < my_label.bin
 
-You can also use the tool `brother_ql_print` to send the instructions to your printer.
+You can also use the tool `brother_ql_print` (Py3 only) to send the instructions to your printer:
 
     brother_ql_print 720x151_monochrome.bin /dev/usb/lp0
     # or
@@ -79,36 +120,10 @@ You can also use the tool `brother_ql_print` to send the instructions to your pr
     # or (requires PyUSB: `pip install pyusb`)
     brother_ql_print 720x151_monochrome.bin usb://0x04f9:0x2015
 
-#### Debug
-
 If your printer has problems printing the instructions file, it may blink its LED (green or red) depending on the model. This can have many reasons, eg.:
 
 * The selected label doesn't match.
 * End of paper.
-* Unsupported opcode (some printers require a mode switching opcode, others fail if such an instruction is sent; some do support data compression, others don't)
+* Unsupported opcode (wrong --model when using `brother_ql_create`?)
 
-To debug this situation and find out which command could be the culprit, connect your printer via USB. (You don't get any status information via network).
+More info on how to debug difficult situations to be found in the [DEBUG doc](DEBUG.md).
-You can use the supplied tool `brother_ql_debug` to send your problematic instructions file to the printer. It will be split into single instructions sent one after the other.
-After every instruction, the printer will be given a chance to send a status response containing error information. Here is an example:
-
-    philipp@lion ~> brother_ql_debug ./720x151_monochrome.bin /dev/usb/lp0
-    INFO: CMD preamble FOUND. Instruction: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 [...] 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
-    INFO: CMD init FOUND. Instruction: 1B 40 
-    INFO: CMD status request FOUND. Instruction: 1B 69 53 
-    INFO: Response from the device: 80 20 42 30 4F 30 00 00 00 00 3E 0A 00 00 15 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
-    INFO: Interpretation of the response: 'Reply to status request' (phase: Waiting to receive), 'Continuous length tape' 62x0 mm^2, errors: []
-    INFO: CMD media/quality FOUND. Instruction: 1B 69 7A CE 0A 3E 00 97 00 00 00 01 00 
-    INFO: CMD margins FOUND. Instruction: 1B 69 64 23 00 
-    INFO: CMD raster FOUND. Instruction: 67 00 5A 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 FF FF FF 1F FF FF FF FF FF F0 00 00 00 00 00 0F FF FF 03 FF FF FF FF E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 [...] 00 07 FF FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 
-    INFO: Response from the device: 80 20 42 30 4F 30 00 00 00 00 3E 0A 00 00 15 00 00 00 06 01 00 00 00 00 00 00 00 00 00 00 00 00
-    INFO: Interpretation of the response: 'Phase change' (phase: Printing state), 'Continuous length tape' 62x0 mm^2, errors: []
-    INFO: CMD print FOUND. Instruction: 1A 
-    TIME 1.60
-    INFO: Interpretation of the response: 'Printing completed' (phase: Printing state), 'Continuous length tape' 62x0 mm^2, errors: []
-    TIME 1.60
-    INFO: Interpretation of the response: 'Phase change' (phase: Waiting to receive), 'Continuous length tape' 62x0 mm^2, errors: []
-
-Here, a command file was successfully printed. The last response should state the *Waiting to receive* phase.
-If you want to confirm the sending of every single command individually, you can add the `--interactive` argument to the command line call.
-
-If you're seeing any error there, open a new issue on Github containing the debugging output to get your device supported.