Skip to navigation

Profiles and print options

How Tillcast knows the commands, the paper width and the character set of a printer.
View as Markdown

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.

MakerDefault profileColumnsPaper
starstar-starprnt-utf8-80mm4880 mm
epsonepson-80mm-484880 mm

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

ProfileColumnsTextPaper and print widthChecked on a device
star-starprnt-utf8-80mm48UTF-8StarPRNT, 576 dots on 80 mm paper. The default of a star printerdocumented
star-starprnt-utf8-58mm32UTF-8StarPRNT, 384 dots on 58 mm paperunverified
star-starprnt-cp852-80mm48Code page 852StarPRNT, 576 dots. The text is in a code page, not in UTF-8 modeunverified
star-starprnt-cp852-58mm32Code page 852StarPRNT, 384 dotsunverified
epson-80mm-4848MultilingualESC/POS, 576 dots on 80 mm paper. The default of an epson printerunverified
epson-80mm-4242MultilingualESC/POS, 512 dots, for a unit that prints at 180 dpiunverified
epson-58mm-3535MultilingualESC/POS, 420 dots on 58 mm paperunverified
epson-58mm-3030MultilingualESC/POS, 360 dots on 58 mm paperunverified
epson-legacy-80mm-4242MultilingualESC/POS, 512 dots, and a job of at most 90 KB. For an old unit that takes only 200 KB of XMLunverified

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.

curl https://api.tillcast.com/v1/locations/loc_01M42YMFP03Q1P9N7M5K3H1G0F/printers \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Idempotency-Key: reception-paper-1" \
-H "Content-Type: application/json" \
-d '{"name": "Reception left", "paper_width": "80mm"}'

The answer for one printer says what is known and where it comes from:

FieldValuesMeaning
vendor_sourcedefault, detected, explicitdefault: no maker was named, so the printer reads star until its first connection names it. detected: the first connection decided it. explicit: you named it, or the printer was added without paper_width
profile_sourcedefault, detected, confirmed, explicitdefault: the default of the paper and the maker. detected: a Star’s own report chose the width. confirmed: a code from a printed sheet chose it. explicit: a request or an edit named it
paper_width58mm, 80mm, nullThe paper the printer was added for. null when it was added without paper_width
detectionpending, undetected, donepending: the printer is not settled yet. undetected: a Star reported a paper or a mode Tillcast cannot print on yet, or nothing usable. done: every other printer

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, with vendor_source default, detection pending and 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-80mm or star-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, leaves detection at undetected and the printer on the default profile of its paper. A Star that does not answer stays pending and prints for the paper you said.
  • An Epson is recognised by what it sends when it first connects. It then reads epson, once, with vendor_source detected. It reports no line width, so its profile is the default of its paper, epson-80mm-48 or epson-58mm-35, with profile_source default, 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_options or allowed_mac, or turns welcome_print on, is 409 printer_not_identified. The name, the client_reference_id and welcome_print: false go through.
  • A named value is never overridden. With a vendor, paper_width is only recorded and chooses the default profile of that paper, and nothing is detected. A profile that 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.

curl -X PATCH https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0 \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"profile": "star-starprnt-utf8-58mm", "print_options": {"cutting": false}}'
  • On a create, a profile that is left out, or null, is the default of the vendor.
  • On a change, a field that is left out stays. null takes the profile away, so the default applies again.
  • print_options on a change replaces the options as a whole. A field you leave out of the object is unset, and null or {} takes them all away.
  • The answer for one printer, GET /v1/printers/{printer}, carries the effective profile, its profile_source and the print_options that 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 profile and the stored options do not fit the new profile, the answer is 422 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_options or allowed_mac: the answer is 409 printer_not_identified. A change that names a profile of your own gives profile_source explicit.

print_options is laid over the profile. Every field is optional, and a field that is left out keeps the profile’s own value.

FieldValuesMeaning
cpl16 to 96Characters per line. Left out, the profile’s own width
encodingSee belowThe character set of the text. Not for the UTF-8 profiles
spacingtrue or falseWider line spacing
upside_downtrue or falsePrint the document turned by 180 degrees
cuttingtrue or falseCut the paper at the end of the document. On, unless the profile says otherwise
margin0 to 24The left margin, in characters
margin_right0 to 24The right margin, in characters. Only a few kinds of content read it, mostly images and QR codes printed upside down. Elsewhere a value is accepted and changes nothing
gradienttrue or falseDither images with error diffusion, which is smoother, instead of a plain threshold
gamma0.1 to 10The gamma of images
threshold1 to 255The brightness at which an image pixel prints black

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:

curl -X PATCH https://api.tillcast.com/v1/printers/prn_01M44X7TQ0A9R2H5J8K1M4N7P0 \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"print_options": {"encoding": "cp852"}}'

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.

AnswerWhen
422 profile_unknownThe id is not in the registry
422 profile_not_connectableThe id exists and no connection carries it yet
422 profile_vendor_mismatchThe profile is another maker’s than the printer’s vendor, an epson- profile on a star printer or the other way round
422 print_options_invalidA value is out of its range, or an encoding is not one of the names or is not available for the profile
422 profile_mismatchWhen you create a job: the printer reported a model of Star’s Line mode family and its profile is not a Line mode profile, so the output could not print on it
409 printer_not_identifiedA change to profile, print_options or allowed_mac, or welcome_print turned on, for a printer added by its paper width whose maker is not known yet. Send it again after the printer has connected. A printer that has connected and still gets this answer has not told what it is: delete it and add it again with its maker named
400 parameter_invalidA field has the wrong type, for example a text where a number goes
400 parameter_unknownprint_options has a field it does not have

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.