Settings
Printer settings
Command language, roll or label stock, and the two sharing switches.
A printer's settings dialog has five groups. Identity and Hardware are the same for every device type; Output, Media and Sharing are the printer's own. Two of them are worth understanding properly: Media, because it is what a printer loaded with labels is configured through, and Sharing, because both of its switches change who else can talk to the hardware.
Output and Media are the same question asked of two different papers, so you never fill in both. A printer on a continuous roll has Output (character set, paper width) and nothing else; set its stock to labels and Output disappears, because neither setting describes a page whose size you state in millimetres.
Kitchen
Virtual printer · Le Comptoir
Identity
Hardware
What Raven identified the hardware as. Override it if the printer disagrees.
Output
Sharing
Raven frees the port between jobs and polls status instead of staying connected.
Opens a port on the venue LAN that a POS can print to.
192.168.1.24:9100Identity and hardware
| Setting | What it does |
|---|---|
| Name | Name it by its job ("Kitchen", "Counter 2"), not by its model. The model changes when the hardware is replaced; the job does not. |
| Physical device | Which discovered hardware this printer is bound to. This is the field you change when a printer is replaced, and the reason your stored device id survives the swap. See The four nouns. |
| Command language (emulation) | Which dialect Raven speaks to the printer. Raven identifies this during discovery and the control shows what it found; you can override it. It sits directly under the hardware picker because it is a claim about the hardware selected above. |
A wrong command language is the cause of the alarming failures: garbage characters, a cash drawer firing by itself, or nothing at all. If a printer misbehaves from the first job, set the language explicitly rather than re-sending.
Some dialects have no text mode at all. The printer is a bitmap engine, so Raven renders the whole ticket to an image before it leaves the platform and sends pixels. Label printers are all in this group, and so is one family of receipt printers. Two things follow. Raven cannot identify these printers safely on its own, so it asks you to confirm the language rather than adopting what it found; and the character set setting disappears, because there is no character in the stream for it to change. Nothing changes in how you author a ticket: you send the same Ticket XML and Raven decides how it has to arrive.
Output
| Setting | What it does | Getting it wrong looks like |
|---|---|---|
| Paper width | The roll width, which decides how many characters fit on a line and therefore how tables and rules lay out. | Wrapped table columns, rules running past the paper edge, or a receipt using half the roll. |
| Character set | The printer's code page: which byte means which accented or non-Latin character. | Accents printing as different letters or as noise. Nearly always the cause when "é" comes out wrong. |
Media
Stock is the one setting here that every printer has, and it decides whether the rest of the group exists. A continuous roll is the default and is what every printer was before Raven supported labels, so a printer you never touch keeps behaving exactly as it did.
Choose Label stock and four measurements appear, plus the printer's model. The stock and the command language have to agree, and Raven checks both directions: a receipt dialect cannot drive labels, and a label dialect cannot drive a roll. If they disagree the dialog says so when you save, on the field that is wrong.
Allergen labels
Virtual printer · Le Comptoir
Hardware
Raster only. Raven prepares the whole ticket as an image for this printer.
Media
Raven needs the model to know the head's resolution and printable width. Neither is printed on the stock.
The widths this model can print. Picked, not typed.
How far each label advances. Blank for continuous stock with no fixed length.
closed| Setting | What it does | Getting it wrong looks like |
|---|---|---|
| Stock | Whether this printer prints onto a continuous roll or onto pages. Everything below appears only for label stock. | A job refused at the printer, because the page Raven measured is not the paper in the machine. |
| Printer model | Which supported print head this is. It carries the head's resolution and its printable width, neither of which can be measured from the stock or asked of the printer reliably. Pick it before you type the measurements: it is what bounds them. | Labels printed at the wrong size, or shifted sideways, because a head's printable area does not sit where the arithmetic on the stock width suggests. |
| Across the print head | The label's edge-to-edge measurement as it passes under the head. Required, and chosen from a list: Raven carries a measured printable area per stock width for each model, so the widths it can print are the widths it has been characterised for. A printer may physically accept stock Raven has no measurement for; that stock cannot be printed on, and is refused when you save rather than at the printer. | Nothing, now. The list is what the model can print, so the old failure (a plausible size accepted everywhere and then refused by every job) is no longer expressible. |
| Along the feed direction | How far the stock advances per label. Leave it blank for continuous tape, which has no fixed length. | A ticket that overruns the label. Raven refuses the job at submission rather than printing a fragment onto one label and the rest onto the next. |
| Unprintable edges | Behind a disclosure, because the answer is almost always 0. These are margins your stock has, on top of what the printer itself cannot reach, which Raven already accounts for. Both are totals: both edges together, both ends together. Do not copy the margin figures from your printer's own configuration tool here: those are the ones already accounted for, and entering them takes them off twice. | A page smaller than the label, so the ticket is laid out into less room than it has. |
The two measurement fields name a direction, not a dimension, and that is deliberate. At least one supported printer shows those two figures on its own front panel in the opposite order from every field it reports over the network. An operator copying them into boxes labelled "width" and "height" enters them the wrong way round, and a transposed label prints off the edge of the stock. Which way the stock travels is unambiguous on the physical machine, so that is what the fields ask for. Read them off the label, not off the panel, if the two disagree.
Most of this fills itself in. Printers that have a network management channel report the stock they are loaded with, and Raven asks while it is already checking their status. Assign such a printer and the measurements arrive already filled; if they disagree with what is set, the dialog says so and offers the printer's figures. A field you have filled in yourself is never overwritten.
That reading is a diagnostic, not the authority: it is absent whenever the connector is offline, and a value becomes the one Raven prints against by being saved by a person. Raven always renders from the values in these fields.
One thing about label stock is never yours to set: whether it is die-cut labels or continuous tape. The printer detects that itself and does not let anyone assert it, so Raven asks the printer at print time over its network management service. A printer that cannot be asked does not print, and says so: the alternative would be to assume the more common kind, and printing continuous output onto die-cut labels breaks at the gap and finishes on the next label with nothing to report it. If label jobs fail saying Raven could not read what stock is loaded, the printer's management service (IPP) is off or unreachable from the connector.
What this means for the tickets you send is on Printing: the page is one label, not a roll that ends when the content does.
Sharing
Two independent switches. Either, both, or neither is valid, and neither ever disables the other. They answer different questions:
- Shared printer changes how Raven holds the real printer's port.
- Print server makes Raven answer as a printer on the venue LAN.
| Shared printer | Print server | Shape | Use it when |
|---|---|---|---|
| Default | Raven is the only thing talking to this printer, and your software calls the API. | ||
| Shared | Something else prints to the same hardware directly, and must keep working. | ||
| Front end | A POS you cannot change prints to Raven, and nothing else touches the printer. | ||
| Migration | One till prints through Raven while another still prints straight to the printer. |
Shared printer (passive mode)
Most receipt printers accept exactly one connection at a time. Normally Raven holds it, which gives live status but locks everything else out. With this on, Raven frees the port between jobs and checks status on a timer instead.
Turn it on when something else must keep talking to the same printer: a till printing directly, or a system you are migrating away from one register at a time. Printing stays just as reliable; the status you see becomes polled rather than live.
How often Raven checks the printer's status while sharing the port is set by Raven, not per printer: it is traffic on a venue LAN and on hardware that may be shared with another integrator. Ask us if a site genuinely needs a different one.
Print server
Raven opens a port on the venue LAN and behaves like a printer. You re-point the POS at that address and it prints through Raven with no code change on the POS at all. This is the answer for software you cannot modify.
Port is the only thing you choose. Once the connector reports the port open, the printer's card shows the POS address to type into the till. That address follows the connector's own network address, so reserve the connector's IP on the router if you can.
Know what you give up. A ticket that arrives from a till is not an interaction: there is no interaction id, no status to poll, no idempotency key, and nothing in History. The connector reports print-server activity separately, and the printer's card in the dashboard is where you see it. That is the whole of the observability, because a POS speaks a printer protocol and a printer protocol has no room for any of the rest.
So: use print server mode for the software you cannot change, and the API for the software you can. If both feed one printer, only the API half is traceable.