init capabilities

capabilities-data/doc/add-your-printer.md

@@ -0,0 +1,103 @@
+# How to get your printer included in the database
+
+We aim to list every ESC/POS printer in this database, and we need your help!
+
+## Why is it good to have my printer listed?
+
+Data from this project is used by multiple open source projects to improve
+printer compatibility.
+
+If your printer is listed with accurate information, then drivers which use
+this data will know how to safely use features like images, QR codes,
+barcodes, and non-ASCII text encoding.
+
+## Is my printer in the database already?
+
+Check [the browsable version of this database](https://mike42.me/escpos-printer-db/).
+
+Some printers are sold under several names, so look out for similar model numbers as well.
+
+## Is my printer eligible to be listed?
+
+Any ESC/POS devices can be listed, including:
+
+- ESC/POS thermal and impact printers
+- Printers with ESC/POS emulation mode
+- Non-printing ESC/POS devices like customer displays
+
+If your printer does not understand ESC/POS, then we wont list it.
+
+## Information to gather
+
+The minimum info that you need to make a printer profile is:
+
+- Vendor name and model number.
+- Link to a vendor programming guide that lists supported features if it is available online.
+- Paper width (58mm and 80mm are common).
+
+If you don't have documentation, then you need to print some things to try to find out what your printer supports:
+
+- Test page output listing supported character encodings.
+- Output of some ESC/POS commands to see what works.
+
+For testing out features, you can send [escpos-php test files](https://github.com/mike42/escpos-php/tree/master/test/integration/resources/output)
+to your printer and note the output for each file.
+
+Once you have this, file a [new issue](https://github.com/receipt-print-hq/escpos-printer-db/issues/new) with the information.
+
+## How to write a printer profile
+
+Profiles are written in `yml` syntax. Start by selecting a base profile, then override a
+small number of options.
+
+- The `default` profile is a good base for printers with a lot of features
+- The `simple` profile is a good base for printers which have very few features
+
+This example is the `TM-U220` profile, which is based on the `simple` profile but notes
+that the printer supports two colors, and does not support high-density images.
+
+```yaml
+---
+TM-U220:
+  name: TM-U220
+  vendor: Epson
+  inherits: simple
+  notes: Two-color impact printer with 80mm output
+  features:
+    bitImageRaster: false
+    bitImageColumn: true
+    highDensity: false
+  colors:
+    0: black
+    1: alternate
+  media:
+    width:
+      mm: 80
+      pixels: Unknown
+...
+```
+
+As another example, the `SP2000` profile is based on the `default` profile,
+but lists the different code pages used by Star printers.
+
+```yaml
+---
+SP2000:
+  name: SP2000 Series
+  vendor: Star Micronics
+  inherits: default
+  notes: Star SP2000 impact printer series with ESC/POS emulation enabled
+  features:
+    starCommands: true
+  codePages:
+    # "Normal"
+    0: CP437
+    1: CP437
+    2: CP932
+    3: CP437
+    # .. code page list continues ...
+```
+
+Once you have written a profile for your own printer, send us a pull request with the
+new file. The profile will need to pass `yamllint`, an automated build, and be reviewed
+by a project contributor.