Skip to navigation

Concepts overview

Organization, customer, location, printer and job, and how a printer reaches Tillcast.
View as Markdown

The Tillcast hierarchy

Everything in Tillcast sits in one chain: organization, customer, location, printer, job.

LevelWhat it isExample
OrganizationThe software vendor that uses Tillcast. Its people sign in to the dashboard, it owns API keys, and it has customers.A property management system
CustomerA company that uses the organization’s software. It owns one or more locations. Its short code is the host of its printers’ URLs.A hotel company
LocationOne site of a customer. A location can be paused.One hotel
PrinterOne physical printer, with a name and a maker, Star or Epson. It has its own secret in its URL. After it connects, Tillcast reads its brand and model from the printer.”Reception left”
JobOne document to print. A job is created under a printer.A guest bill

You can create customers, locations and printers in the dashboard or through the API. Anyone can create an organization in the dashboard, and it is active at once. See the Quickstart, and Provision a venue from your software for a vendor that sets printers up for its own customers.

Ids carry a prefix and an object field names the kind of object: org_, loc_, prn_ and job_, each followed by a ULID. key_ is the id of an API key record, never part of the key itself. The customer is the exception. Its id is cus_ and an 8-character code, for example cus_c3x9k2m3, because people type the code into printers as part of the URL.

An object that belongs to another organization looks like a missing object, with the answer 404. See Security and data.

How a printer connects

A printer connects to Tillcast. Tillcast never connects to the printer.

  1. You enter the printer URL in the printer’s web settings. A Star printer takes it in its CloudPRNT settings, and an Epson in its Server Direct Print settings.
  2. The printer sends a small request over HTTPS to that URL about every 5 seconds. This is a poll. The 5 second interval is the default.
  3. If a job is waiting, the answer to the poll carries it, or says that one is ready. The printer downloads the job, prints it and confirms.
  4. Tillcast marks the job as printed. See Jobs.

Because the printer makes every request, the venue network only has to allow outgoing HTTPS. There is no VPN, no port forwarding and no local server. A new job can wait up to about one poll interval before the printer asks for it.

Tillcast supports the two technologies below. Your documents are the same for both, and the printer’s profile decides which commands Tillcast makes of them.

TechnologyMakerWhere you enter the URL
CloudPRNT, HTTP modeStarThe printer’s CloudPRNT settings. See Set up a Star printer
Server Direct PrintEpsonThe printer’s Web Config. See Set up an Epson printer

Push to printers, so that a job prints without waiting for a poll, is planned and not built. Printers that cannot poll a server, such as those of other makers, will need Tillcast Bridge, a small device in the venue for printers on its network. It is planned and not available. See Supported printers and the roadmap.

Status of a printer

The printer answers show where a printer stands.

  • status is one of never_connected, online, offline, wrong_host, mac_mismatch, customer_suspended and location_suspended. The last two say that the customer or the location is paused, and so is the printer.
  • last_seen_at is when the printer last polled. It is in the answer for a single printer and is written at most once a minute.
  • status_code is the last status code the printer sent, for example 200 OK or, from a Star, 410 Out of paper and 420 Cover open.
  • brand, model and mac are what the printer said about itself. They are claims of whoever polled with the URL, and they are null until the printer has connected. An Epson reports none of them.
A printer that stops polling reads offline

A printer that has connected and has not polled for about 4 minutes has the status offline, and connection reads disconnected. The status is worked out when you read the printer, from last_seen_at, so it appears 3 to 4 minutes after the last poll and goes at the printer’s next poll. Keep a printer’s polling interval at 60 seconds or less.

The printer object also has the fields connection and condition. connection is disconnected when the status is offline; the checks behind condition are not all built, so use status_code for that.

Where to go next