# Printer status

> Printer status via the API or the .NET library: readiness, paper state and error type, what each device reports and what eKasa does when the printer is not ready.

Source: https://ekasa.ninedigit.sk/en/docs/printer-status

Check the printer status before issuing a receipt, for example to warn the operator about paper running out or an
open cover. The response contains the overall readiness (`state`), the paper state (`paperState`) and the error type
(`errorState`).

**HTTP API:**

```http
GET {server_address}/api/v1/printers/status
```

**.NET library:**

```csharp
PrinterStatusInfo printerStatus = await client.GetPrinterStatusInfoAsync(cancellationToken);
```

Example printer status:

```json
{
  "state": "Ready",
  "paperState": "Ready",
  "errorState": "None"
}
```

## The `state` property

The printer's overall readiness.

| Value | Description |
|---|---|
| `Ready` | The printer is ready. |
| `Error` | The printer is not ready (busy or in an error state). |
| `Unknown` | The status could not be determined (mostly as a result of another error). |

## The `paperState` property

*Available from version `6.6`.*

The state of the paper and the mechanism. The value `null` means the storage or printer in use does not provide this
information. It does not claim that the paper is fine.

| Value | Description |
|---|---|
| `Ready` | Paper is loaded correctly and ready for printing. |
| `NearEnd` | The roll is almost empty. Printing continues; this is a warning. |
| `Empty` | There is no paper in the printer. |
| `CoverOpen` | The printer cover is open. |
| `PaperJam` | The paper in the printer is jammed. |
| `null` | The paper state is not available. |

## The `errorState` property

*Available from version `9.0.6`.*

The type of error not related to paper.

| Value | Description |
|---|---|
| `None` | The printer responded and is not in any of the error states in this section. |
| `CutterError` | An error of the automatic paper cutter. |
| `Recoverable` | A temporary error that clears by itself once the cause is removed, for example an overheated print head or low supply voltage. |
| `Unrecoverable` | A fault that cannot be fixed without servicing the device. We recommend that the caller contact service. |
| `null` | The cause cannot be determined. The printer or connected device does not report this type of error state. |

The values `None` and `null` do not mean the same thing. `None` is the printer's answer that it reports no error
unrelated to paper, so the cause lies elsewhere. `null` means the device or printer cannot be asked about the cause.

## Examples by situation

A ready printer with enough paper:

```json
{
  "state": "Ready",
  "paperState": "Ready",
  "errorState": "None"
}
```

The roll is running out; printing continues, this is a warning:

```json
{
  "state": "Ready",
  "paperState": "NearEnd",
  "errorState": "None"
}
```

Empty roll:

```json
{
  "state": "Error",
  "paperState": "Empty",
  "errorState": "None"
}
```

Open cover:

```json
{
  "state": "Error",
  "paperState": "CoverOpen",
  "errorState": "None"
}
```

Open cover together with an error; the cover and the error are not mutually exclusive:

```json
{
  "state": "Error",
  "paperState": "CoverOpen",
  "errorState": "CutterError"
}
```

Cutter error reported by a built-in printer, which does not report the paper state alongside the error:

```json
{
  "state": "Error",
  "paperState": null,
  "errorState": "CutterError"
}
```

A storage that provides neither the paper state nor the cause of an error (for example CHDÚ-SK):

```json
{
  "state": "Ready",
  "paperState": null,
  "errorState": null
}
```

The printer did not respond:

```json
{
  "state": "Unknown",
  "paperState": null,
  "errorState": null
}
```

## What each device reports

| Printer connection | `state` | `paperState` | `errorState` |
|---|---|---|---|
| CHDÚ-SK | yes | always `null` | always `null` |
| CHDÚ Lite, firmware older than `v1.4` | yes | always `null` | always `null` |
| CHDÚ Lite, firmware `v1.4` and newer | yes | `Ready`, `NearEnd`, `Empty`, `CoverOpen` | always `null` |
| External via USB (ESC/POS) | yes | yes, all values | yes, including `None` |
| Built-in (Sunmi device) | yes | `Ready`, `NearEnd`, `Empty`, `CoverOpen`, `PaperJam` | only a specific cause, otherwise `null` |
| Built-in (PAX device) | yes | `Ready`, `Empty`, `CoverOpen`, `PaperJam` | only a specific cause, otherwise `null` |
| Built-in (Ingenico device) | yes | `Ready`, `NearEnd`, `Empty`, `CoverOpen`, `PaperJam` | only a specific cause, otherwise `null` |
| Device without a supported printer | always `Ready` | always `null` | always `null` |

Built-in printers always report a single status value through the manufacturer's SDK, so it does not tell you that
no other error occurred. That is why `errorState` is never `None` for them. It contains either a specific cause or
`null`.

## Behaviour when the printer is not ready

The application reacts to a printer error state differently depending on how the printer is connected.

| Printer connection | Receipt is issued | Behaviour when the printer is not ready |
|----|----|----|
| `CHDU-SK` | yes | A printer error state (for example when the operator has not plugged it into the mains) does not affect the application: once the printer is switched on, the data from the storage is sent to it later (up to the buffer size). However, if the storage's internal buffer fills up (roughly 10–12 receipts), the storage locks up and has to be switched off and on again to continue working. |
| `CHDU Lite` | no | When the printer is in an error state, the attempt to register a receipt fails immediately. The device has no built-in buffer for sending the print output later. |
| The device's built-in printer (Sunmi, Pax, Ingenico, ..) | no | When the printer is in an error state, the attempt to register a receipt fails. |
| External via USB | no | Readiness is checked before the receipt is written to the protected data storage, so if there is an error the receipt is not created at all. A receipt that fails to print is never printed again, because the original may be issued only once. |

CHDÚ-SK is the only storage type with which a receipt is created even when the printer is not ready. The storage
keeps the print output in its internal memory (buffer) and prints it later. With all the others, printer readiness
is checked before the receipt is issued, so a receipt that cannot be printed is not created at all. This is not a
recommended mode of operation, because the buffer size is limited and a full buffer leaves the storage
unresponsive.
