# Encoding and special characters

> Which characters eKasa allows in an item name and receipt text, and how text is converted to the printer encoding (ibm852, windows-1250).

Source: https://ekasa.ninedigit.sk/en/docs/encoding

Your software sends eKasa text in `utf8` (HTTP API) or `unicode` (.NET library), that is with characters in the range
`0` to `65535`. The printer, however, prints in an encoding with characters in the range `0` to `255`, usually
`ibm852` or `windows-1250`. Before printing, eKasa therefore converts the received text to the printer encoding.

Encoding matters for two reasons. The eKasa system does not allow the name of goods or a service to contain arbitrary
characters, and it rejects almost all control characters in an item name. And not every character has a
representation in the encoding selected for the printer.

**Your software**: text in utf8 or unicode, characters 0 to 65535
→ receipt text
**eKasa**: checks allowed characters and converts to the printer encoding
→ code page
**Printer**: ibm852 or windows-1250, characters 0 to 255

The article covers three topics:

- [Allowed and forbidden characters](#allowed-and-forbidden-characters): What an item name and texts with tokens may contain.
- [Conversion to the printer encoding](#conversion-to-the-printer-encoding): How diacritics and symbols are written in ibm852 and windows-1250.
- [Choosing the encoding](#choosing-the-encoding): The codePageName and codePageTableNumber settings.

## Allowed and forbidden characters

The rules apply to the item name and to texts that support [tokens](https://ekasa.ninedigit.sk/en/docs/token-syntax) (header, footer, item
description, non-fiscal receipt). Compared with the item name, texts with tokens additionally allow the characters
`0x1A`, `0x1E` and `0x1F`, which are used to write tokens (see
[control characters in tokens](https://ekasa.ninedigit.sk/en/docs/token-syntax#control-characters)).

### Overview by range

Control characters `0` to `31` and `127` to `159` are forbidden, except line feed and carriage return. All other
characters are allowed.

| Decimal | Hexadecimal | Characters | Item name | Texts with tokens |
|---|---|---|:---:|:---:|
| `0` – `9` | `0x00` – `0x09` | control characters | no | no |
| `10` | `0x0A` | Line feed (new line) | yes | yes |
| `11` – `12` | `0x0B` – `0x0C` | control characters | no | no |
| `13` | `0x0D` | Carriage Return | yes | yes |
| `14` – `25` | `0x0E` – `0x19` | control characters | no | no |
| `26` | `0x1A` | Substitute (`<SUB>`) | no | yes |
| `27` – `29` | `0x1B` – `0x1D` | control characters | no | no |
| `30` – `31` | `0x1E` – `0x1F` | Record Separator (`<RS>`), Unit Separator (`<US>`) | no | yes |
| `32` – `126` | `0x20` – `0x7E` | space, letters, digits and symbols | yes | yes |
| `127` | `0x7F` | Delete | no | no |
| `128` – `159` | `0x80` – `0x9F` | control characters | no | no |
| `160` – `65535` | `0xA0` – `0xFFFF` | all other characters | yes | yes |

### Control characters 0 to 31

The full list of control characters at the start of the table. Characters `127` / `0x7F` (Delete) and `128` to `159`
/ `0x80` to `0x9F` are forbidden as well.

| Decimal | Hexadecimal | Description | Item name | Texts with tokens |
|---|---|---|:---:|:---:|
| `0` | `0x00` | Null | no | no |
| `1` | `0x01` | Start of Header | no | no |
| `2` | `0x02` | Start of Text | no | no |
| `3` | `0x03` | End of Text | no | no |
| `4` | `0x04` | End of Transmission | no | no |
| `5` | `0x05` | Enquiry | no | no |
| `6` | `0x06` | Acknowledge | no | no |
| `7` | `0x07` | Bell | no | no |
| `8` | `0x08` | Backspace | no | no |
| `9` | `0x09` | Horizontal Tabulation | no | no |
| `10` | `0x0A` | Line feed | yes | yes |
| `11` | `0x0B` | Vertical Tabulation | no | no |
| `12` | `0x0C` | Form Feed | no | no |
| `13` | `0x0D` | Carriage Return | yes | yes |
| `14` | `0x0E` | Shift Out | no | no |
| `15` | `0x0F` | Shift In | no | no |
| `16` | `0x10` | Data Link Escape | no | no |
| `17` | `0x11` | Device Control 1 | no | no |
| `18` | `0x12` | Device Control 2 | no | no |
| `19` | `0x13` | Device Control 3 | no | no |
| `20` | `0x14` | Device Control 4 | no | no |
| `21` | `0x15` | Negative Acknowledge | no | no |
| `22` | `0x16` | Synchronous Idle | no | no |
| `23` | `0x17` | End of Transmission Block | no | no |
| `24` | `0x18` | Cancel | no | no |
| `25` | `0x19` | Medium | no | no |
| `26` | `0x1A` | Substitute | no | yes |
| `27` | `0x1B` | Escape | no | no |
| `28` | `0x1C` | File Separator | no | no |
| `29` | `0x1D` | Group Separator | no | no |
| `30` | `0x1E` | Record Separator | no | yes |
| `31` | `0x1F` | Unit Separator | no | yes |

## Conversion to the printer encoding

How a character is actually printed depends on the encoding selected for the printer. Before printing, eKasa converts
the received `unicode` (for the library) or `utf8` (for the HTTP API) text to the printer encoding. The same character
therefore has a different value in each encoding:

| Symbol | Value | After conversion to `windows-1250` | After conversion to `ibm852` |
| :-----: | ----- | ----- | ----- |
| ľ | `318` | `190` | `150` |
| š | `353` | `154` | `231` |
| č | `269` | `232` | `159` |
| ť | `357` | `157` | `156` |

Not every character has a representation in the encoding selected for the printer. To print some special symbols,
such as `€`, `±` or `©`, you need to use the `windows-1250` encoding, because they are not in `ibm852`.

Overview of the available characters in the most common encodings:

| Code page | Character list |
|-----|---|
| `ibm852` | [Character Grid for IBM852](https://www.fileformat.info/info/charset/IBM852/grid.htm) |
| `windows-1250` | [Character Grid for windows-1250](https://www.fileformat.info/info/charset/windows-1250/grid.htm) |

## Choosing the encoding

The encoding is set by two settings in the configuration:

| Setting | Meaning | Default value |
|-----|-----|----|
| `printers.pos.codePageName` | the code page name, for example `ibm852` or `windows-1250` | `ibm852` |
| `printers.pos.codePageTableNumber` | the code page number in the printer | `18` |

Standard printers have the code pages at these positions:

| Encoding | When | `codePageName` | `codePageTableNumber` |
|---|---|---|---|
| `ibm852` | default setting | `ibm852` | `18` |
| `windows-1250` | you need to print characters such as `€`, `±` or `©` | `windows-1250` | `45` |

To find the code pages of your printer, see the printer manufacturer's documentation. In some cases this information
is also shown on the "SELF TEST" printout, which is printed when you switch the printer on while holding the **FEED**
button.

## Where next

- [Tokens and text formatting](https://ekasa.ninedigit.sk/en/docs/token-syntax): The SUB, RS and US control characters in receipt text.
- [Receipt items](https://ekasa.ninedigit.sk/en/docs/receipt-registration/items): The item name and other item properties.
- [Printer information](https://ekasa.ninedigit.sk/en/docs/printer-info): Number of characters per line.
