Concepts overview
The Tillcast hierarchy
Everything in Tillcast sits in one chain: organization, customer, location, printer, job.
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.
- 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.
- 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.
- 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.
- 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.
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.
statusis one ofnever_connected,online,offline,wrong_host,mac_mismatch,customer_suspendedandlocation_suspended. The last two say that the customer or the location is paused, and so is the printer.last_seen_atis when the printer last polled. It is in the answer for a single printer and is written at most once a minute.status_codeis the last status code the printer sent, for example200 OKor, from a Star,410 Out of paperand420 Cover open.brand,modelandmacare what the printer said about itself. They are claims of whoever polled with the URL, and they arenulluntil the printer has connected. An Epson reports none of them.
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.