A receipt printer in a hotel or a restaurant sits behind a router, so your server cannot call it. A cloud receipt printer calls out instead. The older kind, which most of this post is about, has a small computer inside that makes ordinary web requests and starts every exchange itself: every few seconds it asks a private URL whether there is work, and prints what the server hands back. A newer kind keeps one connection open to a broker and is told when a job is waiting (see “Printers that wait for an event”). Star CloudPRNT in its HTTP mode and Epson Server Direct Print are two technologies of the asking kind, and the two Tillcast supports today. Tillcast is the server at the other end of the URL, and this post describes what the printer and the server say to each other.
Why the printer asks instead of being told
Polling means nothing has to be installed at the venue: no software, no VPN and no local server. Your software never talks to the printer: it talks to the API, the API queues the job, and the printer collects it when it next asks.
- The printer asks its private URL for work, as it does every few seconds (every 5 seconds by default on the Star printer we tested), and is told there is nothing.
- Your software creates a job with one HTTPS call to the API.
- The server renders the document for the printer's profile and queues the job. It waits in the printer's queue, which holds at most 50 waiting jobs.
- The printer asks again. A Star printer is told a job is ready and downloads it, and an Epson printer gets the page in the answer to its poll. The job is delivered.
- The printer prints.
- The printer reports the result, a confirmation from a Star and a result post from an Epson. The job is printed, or failed if the printer reports an error.
- Your software reads the job and sees its final status.
Star CloudPRNT, step by step
CloudPRNT is Star’s protocol, and it is ordinary HTTP requests (over HTTPS in production). A Star printer needs one field filled in for Tillcast, the server URL, with no user name and no password. These are the requests, as Star documents them and as the Star printer we tested sent them:
- The poll. The printer sends a
POSTwith a small JSON body, about 0.3 KB when idle: its status, its MAC address, a status code and a few fields about attached peripherals. The interval is a setting on the printer. The answer to a poll cannot change it. - The answer. With nothing waiting, the answer is just
{"jobReady":false}; about once a day it also asks the printer to report its poll interval, client type, version and encodings. With a job waiting, it saysjobReadyis true, lists themediaTypesthe job can be sent as, and gives ajobToken. - The download. The printer sends a
GETto the same address, with the job’s token and the media type it wants in the query. The answer is the job, in the printer’s own command language: StarPRNT for a Star. Tillcast renders your document into those commands when it accepts the job, not when the printer asks. - The confirmation. After printing, the printer sends a
DELETEwith a status code,200 OKfor success. A code that is not a success tells the server the printer could not handle the job, for example510for media it does not take. - The next poll comes at once. The printer polls again right after a download and right after a confirmation, whatever its interval. A second job in the queue therefore goes out straight after the first, and only the first job waits for the interval.
Epson Server Direct Print, step by step
Server Direct Print is Epson’s counterpart. The printer’s settings hold a server URL, an interval, and an ID and password. Tillcast needs no ID and no password: the address is the credential. As Epson’s manual describes it, and as Tillcast implements it, the exchange has two requests where Star’s has three:
- The poll. The printer sends a
POSTas a form:ConnectionType=GetRequest, an ID, which is empty here, and aName, the device’s own name (an Epson we tried sent it). - The answer. With nothing waiting, the answer is
200with an empty body. With a job waiting, the answer is an XML document with aprintjobidand, inside<epos-print><command>, the printer commands as hex. The page arrives in the answer to the poll, so there is no separate download. - The result. The printer sends a second
POST,ConnectionType=SetResponse, with an XML result:success, acode, astatusand theprintjobid. The server answers with an empty200.
With the printer’s spooler on, which Epson lists for some printers and firmware, an Epson reports a job as printed when it has accepted the page, so a cover opened or paper out after that is not reported. What the model we printed on reports for a cover opened or paper out has not been tried yet. An Epson printer needs a few more settings than a Star one (Server Direct Print switched on, the address, how often it asks for work), and it may need a certificate imported.
What a poll interval costs
A shorter interval gets paper out sooner and makes more requests. A job created at a random moment waits between zero and one full interval for the next poll. Each Star poll is one request (not yet measured for an Epson), because the printer’s address carries everything the server needs, so the number of requests an idle printer makes in a day is plain arithmetic:
Data table
A bar chart of requests per printer per day. A 2 second interval makes 43,200, 5 seconds makes 17,280, 10 seconds makes 8,640, 30 seconds makes 2,880 and 60 seconds makes 1,440.
| Label | Value (requests per day) |
|---|---|
| 2 s | 43,200 |
| 5 s | 17,280 |
| 10 s | 8,640 |
| 30 s | 2,880 |
| 60 s | 1,440 |
In our tests against the production server, a small run of ten jobs on one Star printer at a 5 second interval took 2 to 9 seconds from the API call to the confirmation (one more job, sent before the run, took 12). The mean was 6.2 and 5.2 seconds with the printer’s two TLS encryption levels (HIGH + MEDIUM and MEDIUM), and the two cannot be told apart. Most of the spread is the wait for the next poll. It is one printer and ten jobs, so treat it as an order of magnitude, not a promise. A poll shorter than 5 seconds is not in the standard plan (see pricing).
Printers that wait for an event
Asking is not the only way a printer can learn about a job. Some printers can keep one connection open to a message broker (the protocol is called MQTT) and are told when a job is waiting, so they do not have to ask. The printer stops asking on a timer: it is told when a job is waiting, so a job does not wait for the next poll. Star’s CloudPRNT has such a mode: the server publishes a message that either says “poll now”, after which the printer fetches the job as usual, or carries the job or its address. It needs a broker to hold the connections, and only newer printers can do it. The Star printer we tested announces HTTP,MQTT in the headers of its poll. If a printer has MQTT settings, leave them off for Tillcast: the Star setup page says so.
Tillcast does not offer this today. Every job reaches a printer because the printer asks for it. Push to printers is planned, with no date, and asking will stay as the fallback for printers that cannot be told.
Why the secret is in the path
A printer’s address looks like https://<customer code>.print.tillcast.com/<secret>. The host names the customer. The last part of the path is the printer’s secret, and the settings form has no user name and no password.
There were two reasons for that. First, a Star printer sends every request first without credentials, gets a 401, and sends it again with them. With a login, every poll would be two requests. With the secret in the address, the first request is already complete. Second, the only authentication the Epson manual we read describes is Digest, which needs a password, so Tillcast leaves the ID and password empty and treats the address as the credential. A side effect is that a printer is set up with one field.
The server stores only a hash of the secret. A request with a wrong or unknown secret gets a 403. The URL is shown once, when the printer is made, so treat it as a password: if it is lost, the secret is rotated and the old URL stops at once. The security page lists what is built.
A job can print twice, or end in doubt
WarningDelivery is not exactly once
On a Star, if the printer’s confirmation never reaches Tillcast, the job is offered again and can print twice. If no answer to the confirmation arrives, the printer sends it again, a few times (Star documents three or five repeats, by firmware), with the retry number in the request. Tillcast prefers a possible duplicate to a lost receipt. An Epson works the other way round: a job that was handed over is not offered again for 120 seconds, and after that it ends failed with the reason result_missing, although it may have printed. Either way, an Idempotency-Key protects your API call and not the paper: when a job ends in doubt, look at the paper before you print again.
A lost confirmation or a power cut can lead to a duplicate in the time between the download and the confirmation. In our test run above that was 1.8 to 2.6 seconds on average, including the printing. Design the receipt so a duplicate does no harm: a kitchen ticket can carry its number in large type, so the second copy is easy to spot.
The job lifecycle, seen from the printer
| Job status | What happened on the wire |
|---|---|
queued |
The job is in the printer’s queue, up to 50 waiting. A Star’s next poll is answered jobReady: true. |
delivered |
A Star downloaded the job, or an Epson was given it in the answer to a poll. |
printed |
A Star sent a success code in its confirmation, or an Epson posted a successful result. |
failed |
The printer reported an error code, or an Epson sent no result within 120 seconds. reason and result_code say which. |
expired |
No printer took the job before expires_at, 24 hours by default. A job that was taken and never confirmed can also end expired; when delivered_at is set, it may have printed. |
cancelled |
You cancelled a job that was still queued. |
What we have tested, and what we have not
In our tests with one Star printer we saw polling at 2, 5 and 60 second intervals, plain text and formatted printing, Polish letters in formatted printing, QR codes, the paper cut, and a full test page, every section of which came out. The printer polled the production address with no user name or password.
The full test page has also been printed on an Epson printer with Server Direct Print, and every section came out (see Printers). Other models have not been tried, and Tillcast says a printer works only after it has run on a device. Other makers are not supported yet; the Printers page shows each maker’s status. Star’s older Star Line printers are planned. A printer that has connected and has not polled for about 4 minutes has the status offline; last_seen_at shows when it last polled. Star, CloudPRNT, Epson and Server Direct Print are names of their makers, used here to say which printers work with Tillcast.
Next steps
- Print your first receipt with one API call sends a job to one of these printers.
- The docs explain jobs, the printer URL and supported printers.
- Pricing explains how production is billed.