From a0dc993f2f305127e7f1b7790216151be9d4ff4d Mon Sep 17 00:00:00 2001
From: Patrick Kanzler <patrick.kanzler@fablab.fau.de>
Date: Sun, 1 May 2016 15:27:15 +0200
Subject: [PATCH] DOC add example on printing commands from binary files

---
 doc/download/barcode.bin | Bin 0 -> 2667 bytes
 doc/user/usage.rst       |  27 +++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 doc/download/barcode.bin

diff --git a/doc/download/barcode.bin b/doc/download/barcode.bin
new file mode 100644
index 0000000000000000000000000000000000000000..ae4070d70a02f0b74946bbc6011ef46379dac870
GIT binary patch
literal 2667
zcmbVOT~FIc6osV))@`MI*(Vg~B6X`k$%hjPp)b3R2}||?Rf2Z+bz)DGQ5=tDPcVo-
zzh`X6$+$_sgcQctGw0rO?#KAxuY<$(H5cQFA{P2IVlkz{R}<^taO;wPX7fN%Am!Am
zO$R$p-?fU(wpE*KS8N^FeyP|_VS84w^<dkt*z7YHf2$a~8j%*pe|200$7$&}H(^&=
z`pr#Un0CyAh$Jl|$#=bj>AATJVWhjJ=^Um#(*y=-$)Gl=!#{Mq;}41=nFu9hs0F-{
zq+qjZ*ITuz`?76!x~K2X&U+Va+j2(op5qO;RNnM?AXB^nrRp1r#MG`qtnvbz;s4_Y
zx8Z2NSK@*Djev(^2o}y~JQf~BvGnJj(kb?&&y%KQ9SpYZ4tWzKeX&b~UNHAXIHr0U
z%W!;z*W8<uFUCSOabnArq2i%>PX?XZ)G_%1`<A1kY&&z1kdnlFe-)0{T*(<z!ec@3
zxDgzs=e$^P28J2c!A7c{oJ9;&*Hb<-88@;pjJV#=&8=&2%`=Bc`n$yv{La4xWIz-Q
zG{)Xy4UnDzvhD=xZ`$8q2!I{ig{EcFzND}g2X&{ROf7$~1U3PqEvNlT1st~jac=Bx
zYoLEOChP0<`2Ey$1eLbXQgsb|>8tg<ksKz>)P1!`f$raqu0qi3X?DHuB=@rgbGf--
zeu5CVT&|SUVcW$x=w4_JpI9u|DBx7g4i-ccwipd*ixN5GltkPUEXZ^%rih+=C%PO*
zJWfuqgLynL)Wp@H2L^l(_7-cT=XM1P9gEY(sn>tJZ8Tf@&~CBBnZbjKS)SGU@ezGY
zxKAvhM6p=45+x%8;`nax-`#NrQ7n<T;oa3bx=W_~o`(e=lArVGmz-E|qbB^3Sj>rs
zdW`x=07Xp1g%UUUv~AE@1S7I#IU%|$YvmCUA}0);QAEkaN>a)w1*UtJ5sXin>bzOV
zL!nKsW|JWHWs8kGpJwv})1T8k7tC4;mWi1kpt=k>F{OFtlAaJOR$;+JKhl%j7m30p
zF&D`MkSgVnt7v44MNxo}t}j7T6hZ|#_**(|lA(x`Yv4eSzxT_BGUX-Bm3Y56|5{hf
z`wZfRhFCo3n(~Wm5LN0NLneGA=hht#NhHMXnFumDfxfM4+wcNVttW!K)_s|+3v|1a
zje;M6*Ud)>SI}i1MLhOc!s!hqkF${s%x-wnd~`nHdid+|2|<=9eH!zS$7s*&%VYJv
ze(D#;i|B{1Ov@^aON%?SXlje}ZLYryyh&W|*!sI5u6H~6|I_Y~A<>ijC%x5CK7Vq5
J*Q-y?&i{#g_R0VN

literal 0
HcmV?d00001

diff --git a/doc/user/usage.rst b/doc/user/usage.rst
index 23f38e7..1d848a1 100644
--- a/doc/user/usage.rst
+++ b/doc/user/usage.rst
@@ -177,6 +177,33 @@ And for a network printer::
                 host: 127.0.0.1
                 port: 9000
 
+Advanced Usage: Print from binary blob
+--------------------------------------
+
+Imagine you have a file with ESC/POS-commands in binary form. This could be useful for testing capabilities of your
+printer with a known working combination of commands.
+You can print this data with the following code, using the standard methods of python-escpos. (This is an
+advantage of the fact that `_raw()` accepts binary strings.)
+
+::
+
+    from escpos import printer
+    p = printer.Serial()  # adapt this to your printer model
+
+    file = open("binary-blob.bin", "rb")  # read in the file containing your commands in binary-mode
+    data = file.read()
+    file.close()
+
+    p._raw(data)
+
+That's all, the printer should then print your data. You can also use this technique to let others reproduce an issue
+that you have found. (Just "print" your commands to a File-printer on your local filesystem.)
+However, please keep in mind, that often it is easier and better to just supply the code that you are using.
+
+Here you can download an example, that will print a set of common barcodes:
+
+    * :download:`barcode.bin </download/barcode.bin>` by `@mike42 <https://github.com/mike42>`_
+
 How to update your code for USB printers
 ----------------------------------------