Skip to navigation

First connection

The welcome receipt a Star printer prints when it connects to Tillcast for the first time, and the test print.
View as Markdown

What the welcome receipt is

When a Star printer connects with a new URL for the first time, it prints a short welcome receipt. The installer sees on the spot that the URL was typed correctly and belongs to the right location. The values below are made up.

------------------------------------------------
Printer connected
------------------------------------------------
Location: Hotel Example
Printer: Reception left
Organization: Example Software
Model: Star mC-Print3
Firmware: 5.2
Time (UTC): 2026-10-09 12:05
This printer is ready.

An Epson prints no welcome receipt. An Epson added with its maker named is added with the receipt off, and its welcome_print reads false. A printer added by its paper width reads welcome_print true until it first connects, unless it was added with the receipt off, and if it turns out to be an Epson, that first connection switches the receipt off. Use the test print below to see that an Epson works.

What the welcome receipt shows

  • The location name and the printer name. They show at once whether the printer got the URL of the right location.
  • The organization’s name.
  • The printer model and firmware, when the printer has reported them.
  • The time of the first connection, in UTC. It is not the local time of the location.

The receipt never shows the printer URL, the secret or anything else that would let someone poll as this printer. The labels are in English. Names print as given: Tillcast escapes them, so a name cannot change the layout of the receipt.

A few lines of the organization’s own text, such as a support phone number, are designed to print under “This printer is ready”. Setting that text is not built yet, so the receipt has none today.

When the welcome receipt prints

  • On the first connection of a Star printer.
  • After every new URL: when the printer is added, when its secret is rotated, and when it moves to another customer.
  • Not after a move inside a customer, because the URL does not change.
  • Not when a job is already waiting at the first connection. Printing that job confirms the connection anyway, and a test print queued before the first connection takes the place of the welcome receipt.
  • Not when a new device connects behind the same URL. A replaced printer prints no new welcome receipt.
  • A Star added by its paper width is asked about its paper first, so its receipt follows its answer: a little later than for a Star added with its maker named.

It is on by default. A printer can turn it off for itself: send "welcome_print": false when you add the printer or with PATCH /v1/printers/{printer}, or clear the checkbox under Advanced in the Add printer dialog of the dashboard. A switch for all the printers of an organization is not built yet.

The welcome job expires after 1 hour, so a printer that was out of paper does not print “connected” the next day. See Jobs.

Test print

A test print queues one test page for a printer, to see that the address, the printer and the paper work. It works for a Star and for an Epson.

  • In the dashboard, press Test print on the printer’s page: it queues the short page that the rest of this section describes. The second button, Full test page, queues the full test page, a long page (about 80 cm of paper) that shows what the printer can print. An owner or a developer sees the buttons.
  • With the API, call POST /v1/printers/{printer}/test-print with a key that has the jobs:write scope. The call takes no body. Without page=full it queues the short page that the rest of this section describes.
curl -X POST https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Idempotency-Key: reception-test-1"

The answer is 201 with a job, as for any job. Its kind is test, and it carries the profile, the transport and the warnings of its render. The printer prints it the next time it polls. Then:

  • A test print is never billed and does not count as a print of yours.
  • It is offered to the printer for one hour only, so a page does not print the next morning.
  • A printer takes at most 5 test prints in any minute and 3 waiting at a time. The next is 429 rate_limited with a Retry-After header. The limit is per printer, so a page, a script and a second person share it. It stops a loop or a double click and is not a quota.
  • It waits in the printer’s queue of 50 like any job, and a suspended customer or a paused location refuses it.
  • A printer added by its paper width has no known maker before its first connection, so a test print queued then is made for a Star. If the printer turns out to be an Epson, the page ends failed with the reason rendered_for_other_vendor and nothing prints. Press Test print after the first connection.

The page is a ReceiptLine document that is rendered for the printer’s own profile. It has a heading with the name of your organization and the words test print (for an organization called Harbour Hotel, Harbour Hotel test print; a long name takes more than one line), the printer’s name, the time in UTC, a table of three columns with lines, one line in each type style, and the cut. This is its text view at 48 columns. In the text view, double width letters are spaced out, and bold, underline and inverse are not visible. On paper, all of them are.

------------------------------------------------
Harbour Hotel test print
------------------------------------------------
Printer: Reception left
Time (UTC): 2026-10-09 12:05:41
------------------------------------------------
+-----------------------------------+---+------+
|Item |Qty| Price|
+-----------------------------------+---+------+
|Espresso | 2| 7.00|
|Croissant | 1| 3.50|
|Orange juice | 1| 4.00|
+-----------------------------------+---+------+
Normal
Bold
D o u b l e w i d t h
Double height
D o u b l e W a n d H
Underlined
Inverted
------------------------------------------------

A Star and an Epson print the same document, in the width, the character set and the commands of their profiles. The paper may differ in the details a model decides: the line spacing, the thickness of an underline, the feed before the cut, and the cut. Whether the page as a whole looks right on each model is still being checked. See Supported printers.

The full test page

To check that a printer can print everything, ask for the long page. Add page=full to the call:

curl -X POST "https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0/test-print?page=full" \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Idempotency-Key: reception-test-full-1"

The page is about 80 cm of paper, and up to about 100 cm on a printer whose line feed is longer, so load a fresh roll. It shows every type style, a table, the Tillcast logo, a ruler for the width of the paper, a gray ramp, a density bar, 15 barcodes (every kind Tillcast prints) and 10 QR codes at every error level and four sizes. A barcode that is wider than the paper may not fit on narrow paper, and the page says so above it. Print it on a Star and on an Epson and compare the two.

  • Without page, or with page=basic, you get the short page above. The idempotency key, the limits and the answer are the same for both.
  • In solid black you may see a fine dotted pattern. It is the same on a Star and on an Epson. It comes from the way images are turned into dots and is normal. A whole missing line, or a frame with a missing edge, points at the printer or its settings.

If nothing prints

See Troubleshooting. The welcome receipt does not print when the printer has turned it off, when the printer is an Epson, or when a job was already waiting.