Profiles and print options
A profile says what the renderer makes of a document for one printer: the commands the printer’s maker speaks, how many characters fit on a line, the character set of the text, and how large a job may be. It is the id of a preset, for example star-starprnt-utf8-80mm.
The profile is chosen by whoever sets the printer up, with one exception: a printer that is added by its paper width. For that printer Tillcast reads a Star’s width from what the Star reports, and an Epson’s line width is checked on paper. Nobody types a brand or a model. An Epson reports neither its model nor its paper width, and no other report changes a profile.
The default profile
A printer added without a profile and without paper_width gets the default of its maker. The maker is the vendor of the printer, star or epson. A maker that is named when the printer is added cannot be changed. A printer added by its paper width has its maker read from its first connection, once.
Choose the profile of your paper when you add the printer, or add it by its paper width. A printer left on a wider profile than its paper is sent lines wider than its paper, and a document that was rendered for it keeps them, because a job is rendered when it is accepted. What a printer does with such a line has not been seen on a device. A 58 mm Star needs star-starprnt-utf8-58mm, and a 58 mm Epson needs epson-58mm-35 or epson-58mm-30.
The profiles you can set
A column is 12 dots wide, so the print width in dots, divided by 12 and rounded down, is the number of columns. The widths are the makers’ figures. Read your printer’s print width in its manual and choose the profile with that many columns.
The column “Checked on a device” is the evidence that the API and the dashboard show for each profile:
device_verified: a document has printed on a real printer with this profile. No profile has yet.documented: made from the maker’s documentation, and of a kind that has been seen printing. The UTF-8 stream that an earlier release built by hand printed on a Star mC-Print3. The stream the renderer makes now has been delivered on production, and how it looks on paper is being checked.unverified: made from the maker’s documentation alone.
A profile does not name a model, because no model has run with it on a device yet. See Supported printers.
In the UTF-8 profiles the Star is switched to read the text as UTF-8, so Polish and other letters need no code page, and print_options.encoding is not available. The Star code page profiles send code page 852, which has all the Polish letters. The Epson profiles send multilingual unless print_options.encoding names another: the renderer writes each character in the first of five code pages that has it. A character the set does not have prints as ?, and the job’s warnings say where with character_unmappable.
Other profiles exist in the registry for makers and command sets that no connection carries yet, for example the Star Line profiles. They cannot be set: the answer is 422 profile_not_connectable.
Add a printer by its paper width
Send paper_width, 58mm or 80mm, and none of vendor, profile, print_options and allowed_mac, and Tillcast finds out the rest when the printer first connects. In the dashboard this is the Add printer form: it asks for a name and the Paper width, and the maker, the profile, the allowed device and the print options are under Advanced. The paper width cannot be changed afterwards.
The answer for one printer says what is known and where it comes from:
A printer added before these fields existed, and a printer added without paper_width, reads explicit, explicit, null and done, and is never detected.
- Before the first connection the printer reads
star, withvendor_sourcedefault,detectionpendingand the default profile of its paper. A page sent in that time is made for a Star. - A Star is asked for its print area on its first connection. Tillcast chooses the StarPRNT UTF-8 profile for it,
star-starprnt-utf8-80mmorstar-starprnt-utf8-58mm, and where the report and the paper you said differ, the narrower one wins. A report that cannot be used, such as a Star Line printer, a 104 mm printer or an answer with no usable print area, leavesdetectionatundetectedand the printer on the default profile of its paper. A Star that does not answer stayspendingand prints for the paper you said. - An Epson is recognised by what it sends when it first connects. It then reads
epson, once, withvendor_sourcedetected. It reports no line width, so its profile is the default of its paper,epson-80mm-48orepson-58mm-35, withprofile_sourcedefault, until its line width is checked on paper. - An edit waits for the maker. Until the maker is known, a change that names
profile,print_optionsorallowed_mac, or turnswelcome_printon, is409 printer_not_identified. The name, theclient_reference_idandwelcome_print: falsego through. - A named value is never overridden. With a
vendor,paper_widthis only recorded and chooses the default profile of that paper, and nothing is detected. Aprofilethat was named stays. - Let the real printer connect first. A request that is shaped like an Epson’s first call, or like a Star’s answer about its paper, sent to the address before the printer connects decides the maker. It stays until the printer is deleted and added again.
Check the line width of an Epson on paper
In the dashboard the page of an Epson added by its paper width says Check the line width and has a Print calibration sheet button, which an owner or a developer sees. The sheet has two rulers, each with a code of four symbols under it: 48 and 42 columns on 80 mm paper, 35 and 30 on 58 mm. Look at the paper and type the code under the longest ruler that stays on one line. A ruler that is cut off, or that runs on to a second line, is too long for the printer. Tillcast then sets the profile of that ruler (epson-80mm-48, epson-80mm-42, epson-58mm-35 or epson-58mm-30), profile_source reads confirmed, and a cpl in the printer’s print_options is taken away, because the width read on paper replaces it.
- The sheet is a test job that is offered to the printer for 20 minutes. A code works for 30 minutes and takes 5 tries, and a new sheet replaces the old one and its code.
- The code is a typo guard and not proof that anyone stands at the printer. A code that is not one of the sheet’s two is refused and sets no profile. The code does not show that the person who typed it is looking at the paper, and anyone who sees the sheet can read both codes.
- The sheet and its code are in the dashboard. With the API, set the profile yourself, as under Set a profile, once the maker is known.
Recognising a maker from its first connection, reading a Star’s print area and the sheet have not been checked on a device.
Set a profile
profile and print_options are fields of the request that adds a printer and of PATCH /v1/printers/{printer}. Both need a key with printers:write, or a signed-in owner or developer in the dashboard. The Edit printer dialog has a Profile choice and an optional Print options section. The Add printer dialog has them under Advanced, once a maker is chosen there.
- On a create, a
profilethat is left out, ornull, is the default of thevendor. - On a change, a field that is left out stays.
nulltakes the profile away, so the default applies again. print_optionson a change replaces the options as a whole. A field you leave out of the object is unset, andnullor{}takes them all away.- The answer for one printer,
GET /v1/printers/{printer}, carries the effectiveprofile, itsprofile_sourceand theprint_optionsthat were set. The lists of printers carry none of them: retrieve the printer. - A change applies to the jobs created from then on. A job that is already queued keeps the profile it was rendered for.
- A change is checked as a whole: the profile the printer would have after it, with the options that stay. If you change only the
profileand the stored options do not fit the new profile, the answer is422 print_options_invalid. Send the options in the same request. - A printer added by its paper width that has not told its maker yet takes no change of
profile,print_optionsorallowed_mac: the answer is409 printer_not_identified. A change that names aprofileof your own givesprofile_sourceexplicit.
Print options
print_options is laid over the profile. Every field is optional, and a field that is left out keeps the profile’s own value.
The encoding names are cp437, cp852, cp858, cp860, cp863, cp865, cp866, cp1252 and multilingual. The last one switches between code pages for each character, and an Epson uses it when encoding is left out.
The encoding of an Epson. An Epson prints in multilingual unless encoding says another. The renderer then selects a code page for each character, so the Swedish and the Polish letters, the euro and the typographic quotes and dashes all print in one text. cp1252 suits Western European text only: it prints the Swedish letters and loses the Polish ones. cp852 suits Central European text, such as Polish and Czech: it prints the Polish letters but not the en dash, and loses the Swedish letters. A character that the encoding does not have prints as ?, and the job gets a character_unmappable warning with its line and column.
This was checked on paper on one Epson TM-m30III-H, with a Swedish and a Polish sample. Czech and other languages were not tried, and other Epson models have not been checked on a device. If a letter prints wrong on another model, set encoding to the code page that model has.
To keep code page 852, which was the Epson default before 2026-10-26, or to choose another name:
A change to print_options replaces all of them, so send the other options you use, such as cpl or cutting, in the same request.
The values are checked one by one against their ranges. They are not checked against each other or against the paper. A cpl of 48 with a margin of 6 asks the printer for 54 columns, and what a printer does with a print area wider than its paper has not been tried on a device.
Refusals
The refusals name the field in param, and never repeat the value that was sent.
Star Line mode printers, such as the TSP650II, TSP700II and TSP800II with a network interface, cannot be used through the API yet, because their profiles cannot be set.