Перегляд вихідного коду сторінки Фіскальний реєстратор МІНІ-ФП54.01



'''МІНІ-ФП54.01''' — портативний фіскальний реєстратор виробництва '''Юнісістем'''. Пристрій має акумулятор, контрольну стрічку в електронній формі, інтерфейси підключення до ПК через '''USB''' або '''RS-232''', а також канали передачі даних через '''Ethernet''' та '''GSM/GPRS'''.

Модель підходить для роздрібної торгівлі, виїзної торгівлі, інтернет-магазинів, аптек, кафе, барів, ресторанів та сфери послуг.

== Короткий опис ==
{| class="wikitable"
!Параметр
!Значення
|-
|Назва
|МІНІ-ФП54.01
|-
|Тип пристрою
|Фіскальний реєстратор
|-
|Виробник
|Юнісістем
|-
|Версія ПЗ
|5401F3
|-
|Підключення до ПК
|USB або RS-232
|-
|Передача даних
|Ethernet, GSM/GPRS
|-
|Bluetooth
|Опція
|-
|Основний офіційний спосіб інтеграції
|DLL / OLE-сервер для Windows
|-
|Альтернативна інтеграція
|Пряма робота через протокол обміну
|}

== Важливі висновки для інтеграції ==
{| class="wikitable"
!Статус
!Висновок
!Коментар
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Рекомендовано
|Для Windows використовувати офіційний DLL / OLE-сервер
|Це найшвидший шлях інтеграції з POS-системою або Python-застосунком через COM/OLE.
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Можливо
|Для Linux/macOS можна реалізувати власний драйвер через serial-порт
|Потрібна реалізація протоколу обміну з фіскальним реєстратором.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Обережно
|Офіційних Python-прикладів не знайдено
|Python можна використовувати через pywin32 або pyserial, але готового SDK саме для Python на сторінці підтримки немає.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не робити
|Не підключати одночасно USB і RS-232 до одного ПК
|Для роботи з ПК потрібно використовувати один інтерфейс підключення.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не плутати
|Ethernet/GSM не є основним інтерфейсом POS-команд
|Ethernet і GSM/GPRS використовуються переважно для передачі даних до ДПС.
|}

== Основні характеристики ==
{| class="wikitable"
!Характеристика
!Значення
|-
|Кількість товарів
|16 384
|-
|Кількість відділів
|64
|-
|Кількість касирів
|32
|-
|Кількість символів у рядку
|32
|-
|Кількість символів у назві товару
|48
|-
|Початкове повідомлення
|12 рядків
|-
|Заключне повідомлення
|2 рядки
|-
|Дисплей покупця
|Вбудований, 2×16 символів
|-
|Друк
|Термодрук
|-
|Ширина стрічки
|58 мм
|-
|Швидкість друку
|8 рядків/с
|-
|Живлення
|Вбудований Li-Pol акумулятор
|-
|Акумулятор
|7,4 В; 2 А·год, опційно 3,6 А·год
|-
|RS-232
|1 порт
|-
|USB
|1 порт
|-
|Bluetooth
|Опція
|-
|Грошова скринька
|micro-jack 2,5 мм
|-
|Ethernet
|Є
|-
|GSM/GPRS
|Вбудований
|-
|Габарити
|181 × 123 × 102 мм
|-
|Маса
|0,73 кг
|}

== Підключення до компʼютера ==
МІНІ-ФП54.01 може підключатися до компʼютера через:

* '''USB''';
* '''RS-232 / COM-порт'''.

Типова схема підключення:<pre>
POS-система / касова програма
        ↓
Драйвер або власна інтеграція
        ↓
USB або RS-232
        ↓
МІНІ-ФП54.01
</pre>

=== USB-підключення ===
USB-підключення зручне для сучасних ПК і ноутбуків. Після встановлення USB-драйвера пристрій зазвичай працює як віртуальний COM-порт.

Приклад:<pre>
Windows:
COM3, COM4, COM5 ...

Linux:
 /dev/ttyUSB0
 /dev/ttyACM0

macOS:
 /dev/tty.usbserial-*
 /dev/tty.usbmodem-*
</pre>
{| class="wikitable"
!Статус
!Примітка
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Добре
|USB простіше використовувати на сучасних робочих місцях.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Перевірити
|Потрібно встановити USB-драйвер виробника.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Ризик
|У різних ОС назва порту буде різною, тому її не можна жорстко зашивати в код.
|}

=== RS-232 / COM-порт ===
RS-232 підходить для класичних POS-систем, касових терміналів і embedded-рішень.
{| class="wikitable"
!Статус
!Примітка
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Добре
|Serial-протокол простіше реалізувати кросплатформно.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Перевірити
|Потрібен фізичний COM-порт або USB-RS232 адаптер.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Ризик
|Дешеві USB-RS232 адаптери можуть давати нестабільний звʼязок.
|}

== Ethernet, GSM/GPRS і Bluetooth ==
Пристрій має Ethernet-порт і GSM/GPRS-модем для передачі даних.
{| class="wikitable"
!Інтерфейс
!Призначення
!Коментар
|-
|USB
|Підключення до ПК
|Основний варіант для POS-інтеграції.
|-
|RS-232
|Підключення до ПК
|Зручний для serial-інтеграції.
|-
|Ethernet
|Передача даних через інтернет
|Використовується для звʼязку з ДПС.
|-
|GSM/GPRS
|Передача даних через мобільну мережу
|Дає змогу працювати без дротового інтернету.
|-
|Bluetooth
|Опційне підключення
|Може використовуватися зі смартфоном або планшетом за наявності сумісного ПЗ.
|}

== Операційні системи ==

=== Windows ===
Для Windows виробник надає:

* USB-драйвер;
* DLL-бібліотеку / OLE-сервер;
* програму UNI-PROGress для налаштування РРО;
* Uniq Commander для налаштування комунікаційного блоку;
* обробку для «1С:Підприємство».

Рекомендована схема для Windows:<pre>
POS-система
    ↓
Python / C# / 1C / інше ПЗ
    ↓
OLE/DLL Юнісістем
    ↓
USB або COM
    ↓
МІНІ-ФП54.01
</pre>
{| class="wikitable"
!Статус
!Висновок
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Рекомендовано
|Windows — найпростіша ОС для інтеграції через офіційний OLE/DLL.
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Плюс
|Можна використовувати Python через pywin32.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Уточнити
|Потрібно знати реальний ProgID OLE-сервера і точні назви методів.
|}

=== Linux ===
Linux не є основною цільовою платформою для офіційного OLE/DLL-драйвера. Але інтеграція можлива через serial-порт, якщо реалізувати протокол обміну.

Схема:<pre>
POS-система
    ↓
Python-сервіс
    ↓
pyserial
    ↓
/dev/ttyUSB0 або /dev/ttyS0
    ↓
МІНІ-ФП54.01
</pre>
{| class="wikitable"
!Статус
!Висновок
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Можливо
|Linux може працювати з пристроєм через serial-порт.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Потрібно
|Реалізувати протокол обміну.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Немає
|Готового офіційного Python SDK для Linux не знайдено.
|}

=== macOS ===
Для macOS ситуація аналогічна Linux: готового офіційного OLE/DLL-драйвера немає, але можна працювати через serial-порт, якщо система бачить пристрій як `/dev/tty.*`.
{| class="wikitable"
!Статус
!Висновок
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Можливо
|Потрібна власна serial-інтеграція.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не готово з коробки
|Офіційного macOS SDK не знайдено.
|}

== Варіанти інтеграції ==

=== Варіант 1. Через OLE/DLL у Windows ===
Це найпростіший варіант для Windows.<pre>
Python → pywin32 → OLE-сервер → USB/COM → МІНІ-ФП54.01
</pre>Переваги:

* не потрібно вручну реалізовувати низькорівневий протокол;
* простіше стартувати;
* можна викликати готові методи драйвера;
* підходить для POS-систем на Windows.

Недоліки:

* залежність від Windows;
* залежність від конкретної версії OLE-сервера;
* потрібно встановити та зареєструвати COM/OLE-компонент;
* потрібно знати ProgID і назви методів.

=== Варіант 2. Через serial-порт напряму ===
Цей варіант підходить для Windows, Linux, macOS та embedded-систем.<pre>
Python → pyserial → протокол обміну → USB/COM або RS-232 → МІНІ-ФП54.01
</pre>Переваги:

* кросплатформність;
* незалежність від OLE;
* можна запускати як локальний сервіс;
* зручно для Docker, Linux POS, Raspberry Pi, embedded-терміналів.

Недоліки:

* потрібно реалізувати протокол обміну;
* потрібно обробляти контрольні суми, ACK/NAK, таймаути, повтори;
* складніше тестувати;
* потрібна офіційна документація протоколу.

== Python-інтеграція ==
Офіційних прикладів саме для Python на сторінці підтримки не знайдено. Але Python можна використовувати у двох режимах:
{| class="wikitable"
!Варіант
!Пакет Python
!ОС
!Коментар
|-
|OLE/DLL
|pywin32
|Windows
|Найпростіший варіант, якщо встановлено OLE-сервер.
|-
|Serial
|pyserial
|Windows / Linux / macOS
|Потрібна реалізація протоколу обміну.
|-
|Mock-драйвер
|pytest / unittest
|Будь-яка
|Для тестування без фізичного пристрою.
|}

== Python через OLE/DLL у Windows ==

=== Встановлення залежності ===
<syntaxhighlight lang="bash"> pip install pywin32 </syntaxhighlight>

=== Пошук ProgID OLE-сервера ===
Після встановлення OLE-сервера потрібно знайти його ProgID.

Приклад через PowerShell:

<syntaxhighlight lang="powershell"> Get-ChildItem "Registry::HKEY_CLASSES_ROOT" |
  Where-Object { $_.Name -match "Ecr|T400|MINI|FP|Unisystem|Uni" } |
  Select-Object -First 50
</syntaxhighlight>

Приклад через Python:

<syntaxhighlight lang="python"> import winreg

keywords = ["Ecr", "T400", "MINI", "FP", "Unisystem", "Uni"]

with winreg.OpenKey(winreg.HKEY_CLASSES_ROOT, "") as root:
    total = winreg.QueryInfoKey(root)[0]

    for index in range(total):
        try:
            name = winreg.EnumKey(root, index)
            if any(keyword.lower() in name.lower() for keyword in keywords):
                print(name)
        except OSError:
            pass
</syntaxhighlight>
{| class="wikitable"
!Статус
!Коментар
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Важливо
|Назва ProgID у прикладах нижче умовна. Її треба уточнити після встановлення реального OLE-сервера.
|}

=== Базова структура Python-обгортки ===
<syntaxhighlight lang="python"> import win32com.client

class MiniFP54OleDriver:
    """
    Python-обгортка над OLE-сервером Юнісістем.

    Увага:
    - ProgID потрібно взяти з реальної інсталяції OLE-сервера.
    - Назви методів потрібно звірити з документацією до конкретної версії OLE.
    """

    def __init__(self, prog_id: str):
        self.prog_id = prog_id
        self.driver = None

    def connect_to_ole(self):
        self.driver = win32com.client.Dispatch(self.prog_id)

    def open_port(self, port: int, baudrate: int = 115200):
        """
        Приклад.
        Реальна назва методу може бути OpenPort, openPort або іншою.
        """
        return self.driver.OpenPort(port, baudrate)

    def close_port(self):
        return self.driver.ClosePort()

    def get_status(self):
        return self.driver.GetStatus()

    def get_version(self):
        return self.driver.GetSoftVersion()

    def open_shift(self):
        return self.driver.OpenShift()

    def close_shift(self):
        return self.driver.ZReport()

    def open_receipt(self):
        return self.driver.OpenReceipt()

    def sell_item(self, name: str, price: float, quantity: float, tax_group: int = 1):
        return self.driver.Sale(name, quantity, price, tax_group)

    def pay_cash(self, amount: float):
        payment_type = 0
        return self.driver.Pay(payment_type, amount)

    def close_receipt(self):
        return self.driver.CloseReceipt()
</syntaxhighlight>

=== Приклад smoke-тесту через OLE ===
<syntaxhighlight lang="python"> from mini_fp54_ole import MiniFP54OleDriver

PROG_ID = "PUT_REAL_PROG_ID_HERE"

driver = MiniFP54OleDriver(PROG_ID)

driver.connect_to_ole()

try:
    print("Open port:", driver.open_port(port=3, baudrate=115200))
    print("Version:", driver.get_version())
    print("Status:", driver.get_status())
finally:
    print("Close port:", driver.close_port())
</syntaxhighlight>

=== Приклад продажу через OLE ===
<syntaxhighlight lang="python"> from mini_fp54_ole import MiniFP54OleDriver

driver = MiniFP54OleDriver("PUT_REAL_PROG_ID_HERE") driver.connect_to_ole()

try:
    driver.open_port(port=3, baudrate=115200)

    driver.open_shift()
    driver.open_receipt()

    driver.sell_item(
        name="Кава",
        price=50.00,
        quantity=1,
        tax_group=1,
    )

    driver.pay_cash(50.00)
    driver.close_receipt()
finally:
    driver.close_port()
</syntaxhighlight>
{| class="wikitable"
!Статус
!Що треба перевірити перед запуском
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Обовʼязково
|Чи правильний ProgID OLE-сервера.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Обовʼязково
|Чи правильні назви методів.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Обовʼязково
|Чи правильний COM-порт.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не запускати в production
|Поки не перевірено на тестовому РРО або у нефіскальному режимі.
|}

== Python через serial-порт ==

=== Встановлення залежності ===
<syntaxhighlight lang="bash"> pip install pyserial </syntaxhighlight>

=== Базовий serial-клієнт ===
<syntaxhighlight lang="python"> import serial from dataclasses import dataclass

@dataclass class MiniFP54SerialConfig:
    port: str
    baudrate: int = 115200
    timeout: float = 3.0
    encoding: str = "cp1251"
class MiniFP54SerialClient:
    """
    Базовий serial-клієнт для МІНІ-ФП54.01.

    Це не повний драйвер.
    Для реальної роботи потрібно реалізувати офіційний протокол:
    - формат пакета;
    - службові байти;
    - довжину;
    - контрольну суму;
    - ACK/NAK;
    - повтори;
    - таймаути;
    - парсинг статусів і помилок.
    """

    def __init__(self, config: MiniFP54SerialConfig):
        self.config = config
        self.connection: serial.Serial | None = None

    def connect(self):
        self.connection = serial.Serial(
            port=self.config.port,
            baudrate=self.config.baudrate,
            timeout=self.config.timeout,
            bytesize=serial.EIGHTBITS,
            parity=serial.PARITY_NONE,
            stopbits=serial.STOPBITS_ONE,
        )

    def disconnect(self):
        if self.connection and self.connection.is_open:
            self.connection.close()

    def send_raw(self, payload: bytes, read_size: int = 1024) -> bytes:
        if not self.connection or not self.connection.is_open:
            raise RuntimeError("Serial port is not open")

        self.connection.write(payload)
        self.connection.flush()

        return self.connection.read(read_size)

    def send_text_command(self, command: str) -> str:
        """
        Умовний приклад текстової команди.
        Реальний формат треба взяти з протоколу обміну.
        """
        payload = command.encode(self.config.encoding)
        response = self.send_raw(payload)

        return response.decode(self.config.encoding, errors="replace")
</syntaxhighlight>

=== Приклад smoke-тесту через serial ===
<syntaxhighlight lang="python"> from mini_fp54_serial import MiniFP54SerialClient, MiniFP54SerialConfig

client = MiniFP54SerialClient(
    MiniFP54SerialConfig(
        port="COM3",       # Linux: "/dev/ttyUSB0"
        baudrate=115200,
        timeout=3.0,
    )
)

client.connect()

try:
    response = client.send_text_command("GET_STATUS")
    print(response)
finally:
    client.disconnect()
</syntaxhighlight>
{| class="wikitable"
!Статус
!Коментар
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Умовний приклад
|Команда GET_STATUS наведена як приклад. Реальну команду потрібно брати з протоколу обміну.
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Корисно
|Така структура підходить для побудови власного драйвера.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не достатньо
|Без реалізації контрольної суми та службових байтів це не production-драйвер.
|}

== Тестування драйвера без пристрою ==
Без фізичного МІНІ-ФП54.01 можна тестувати не сам фіскальний реєстратор, а логіку інтеграції.

Мета тестування без пристрою:

* перевірити бізнес-логіку POS-системи;
* перевірити порядок команд;
* перевірити обробку помилок;
* перевірити логування;
* перевірити поведінку при timeout;
* перевірити поведінку при відсутності паперу;
* перевірити поведінку при розриві зʼєднання.

=== Архітектура тестування без пристрою ===
<pre>
POS-система
    ↓
FiscalDriverInterface
    ↓
FakeMiniFP54Driver
    ↓
Unit / integration tests
</pre>

=== Інтерфейс драйвера ===
<syntaxhighlight lang="python"> from abc import ABC, abstractmethod

class FiscalDriverInterface(ABC):
    @abstractmethod
    def open_shift(self) -> str:
        pass

    @abstractmethod
    def close_shift(self) -> str:
        pass

    @abstractmethod
    def open_receipt(self) -> str:
        pass

    @abstractmethod
    def sell_item(self, name: str, price: float, quantity: float) -> str:
        pass

    @abstractmethod
    def pay_cash(self, amount: float) -> str:
        pass

    @abstractmethod
    def close_receipt(self) -> str:
        pass

    @abstractmethod
    def get_status(self) -> str:
        pass
</syntaxhighlight>

=== Fake-драйвер ===
<syntaxhighlight lang="python"> class FakeMiniFP54Driver(FiscalDriverInterface):
    def __init__(self):
        self.shift_opened = False
        self.receipt_opened = False
        self.items = []
        self.total = 0.0

    def open_shift(self) -> str:
        if self.shift_opened:
            return "ERROR;SHIFT_ALREADY_OPEN"

        self.shift_opened = True
        return "OK;SHIFT_OPENED"

    def close_shift(self) -> str:
        if not self.shift_opened:
            return "ERROR;SHIFT_NOT_OPEN"

        if self.receipt_opened:
            return "ERROR;RECEIPT_IS_OPEN"

        self.shift_opened = False
        return "OK;Z_REPORT_PRINTED"

    def open_receipt(self) -> str:
        if not self.shift_opened:
            return "ERROR;SHIFT_NOT_OPEN"

        if self.receipt_opened:
            return "ERROR;RECEIPT_ALREADY_OPEN"

        self.receipt_opened = True
        self.items = []
        self.total = 0.0

        return "OK;RECEIPT_OPENED"

    def sell_item(self, name: str, price: float, quantity: float) -> str:
        if not self.receipt_opened:
            return "ERROR;RECEIPT_NOT_OPEN"

        if price <= 0:
            return "ERROR;INVALID_PRICE"

        if quantity <= 0:
            return "ERROR;INVALID_QUANTITY"

        amount = round(price * quantity, 2)
        self.items.append(
            {
                "name": name,
                "price": price,
                "quantity": quantity,
                "amount": amount,
            }
        )
        self.total = round(self.total + amount, 2)

        return f"OK;ITEM_ADDED;{amount:.2f}"

    def pay_cash(self, amount: float) -> str:
        if not self.receipt_opened:
            return "ERROR;RECEIPT_NOT_OPEN"

        if amount < self.total:
            return "ERROR;PAYMENT_LESS_THAN_TOTAL"

        change = round(amount - self.total, 2)

        return f"OK;PAYMENT_ACCEPTED;CHANGE={change:.2f}"

    def close_receipt(self) -> str:
        if not self.receipt_opened:
            return "ERROR;RECEIPT_NOT_OPEN"

        if not self.items:
            return "ERROR;EMPTY_RECEIPT"

        self.receipt_opened = False

        return f"OK;RECEIPT_CLOSED;TOTAL={self.total:.2f}"

    def get_status(self) -> str:
        return (
            "OK;"
            f"SHIFT_OPENED={self.shift_opened};"
            f"RECEIPT_OPENED={self.receipt_opened}"
        )
</syntaxhighlight>

=== Unit-тест успішного продажу ===
<syntaxhighlight lang="python"> def test_success_sale_flow():
    driver = FakeMiniFP54Driver()

    assert driver.open_shift() == "OK;SHIFT_OPENED"
    assert driver.open_receipt() == "OK;RECEIPT_OPENED"

    result = driver.sell_item("Кава", price=50.00, quantity=2)
    assert result == "OK;ITEM_ADDED;100.00"

    result = driver.pay_cash(100.00)
    assert result == "OK;PAYMENT_ACCEPTED;CHANGE=0.00"

    result = driver.close_receipt()
    assert result == "OK;RECEIPT_CLOSED;TOTAL=100.00"

    result = driver.close_shift()
    assert result == "OK;Z_REPORT_PRINTED"
</syntaxhighlight>

=== Unit-тест помилки: чек без відкритої зміни ===
<syntaxhighlight lang="python"> def test_open_receipt_without_shift():
    driver = FakeMiniFP54Driver()

    result = driver.open_receipt()

    assert result == "ERROR;SHIFT_NOT_OPEN"
</syntaxhighlight>

=== Unit-тест помилки: оплата менша за суму чека ===
<syntaxhighlight lang="python"> def test_payment_less_than_total():
    driver = FakeMiniFP54Driver()

    driver.open_shift()
    driver.open_receipt()
    driver.sell_item("Кава", price=50.00, quantity=2)

    result = driver.pay_cash(50.00)

    assert result == "ERROR;PAYMENT_LESS_THAN_TOTAL"
</syntaxhighlight>

== Емуляція serial-пристрою без фізичного РРО ==
Для тестування serial-драйвера без пристрою можна зробити локальний емулятор.

=== Варіант для Linux/macOS ===
Можна створити пару віртуальних serial-портів через `socat`.

<syntaxhighlight lang="bash"> socat -d -d pty,raw,echo=0 pty,raw,echo=0 </syntaxhighlight>

Після запуску `socat` покаже два порти, наприклад:<pre>
/dev/pts/3
/dev/pts/4
</pre>Один порт використовує тестовий POS-драйвер, інший — емулятор пристрою.

=== Простий Python-емулятор ===
<syntaxhighlight lang="python"> import serial

PORT = "/dev/pts/4" BAUDRATE = 115200

def handle_command(command: str) -> str:
    command = command.strip()

    if command == "GET_STATUS":
        return "OK;READY\n"

    if command == "GET_VERSION":
        return "OK;MINI-FP54.01;5401F3\n"

    if command.startswith("SALE"):
        return "OK;ITEM_ADDED\n"

    if command.startswith("PAY"):
        return "OK;PAYMENT_ACCEPTED\n"

    if command == "CLOSE_RECEIPT":
        return "OK;RECEIPT_CLOSED\n"

    return "ERROR;UNKNOWN_COMMAND\n"
with serial.Serial(PORT, BAUDRATE, timeout=1) as ser:
    print(f"Fake MINI-FP54.01 emulator started on {PORT}")

    while True:
        raw = ser.readline()

        if not raw:
            continue

        command = raw.decode("cp1251", errors="replace")
        response = handle_command(command)

        ser.write(response.encode("cp1251"))
        ser.flush()
</syntaxhighlight>
{| class="wikitable"
!Статус
!Коментар
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Добре для розробки
|Емулятор дозволяє тестувати POS-сценарії без фізичного пристрою.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Не замінює РРО
|Емулятор не перевіряє реальний фіскальний протокол.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Не для production
|Не можна вважати інтеграцію готовою без тестів із реальним пристроєм.
|}

== Тестування з реальним пристроєм ==

=== Підготовка ===

# Встановити USB-драйвер виробника.
# Встановити DLL/OLE-сервер, якщо використовується Windows.
# Підключити пристрій через USB або RS-232.
# Переконатися, що використовується тільки один інтерфейс.
# Перевірити, який COM-порт отримав пристрій.
# Перевірити наявність паперу.
# Перевірити заряд акумулятора або живлення.
# Перевірити Ethernet або GSM/GPRS для передачі даних.
# Виконати команду отримання статусу.
# Виконати тестовий друк або службову операцію.

=== Мінімальний чек-лист smoke-тесту ===
{| class="wikitable"
!№
!Тест
!Очікуваний результат
|-
|1
|Відкрити порт
|Драйвер не повертає помилку
|-
|2
|Отримати статус
|Пристрій відповідає
|-
|3
|Отримати версію ПЗ
|Повертається версія пристрою
|-
|4
|Перевірити папір
|Немає помилки паперу
|-
|5
|Відкрити зміну
|Зміна відкрита
|-
|6
|Відкрити чек
|Чек відкритий
|-
|7
|Додати товар
|Рядок товару надруковано або прийнято
|-
|8
|Провести оплату
|Оплата прийнята
|-
|9
|Закрити чек
|Чек закритий
|-
|10
|Надрукувати X-звіт
|Звіт друкується без закриття зміни
|-
|11
|Надрукувати Z-звіт
|Зміна закрита
|-
|12
|Перевірити передачу даних
|Дані передаються через Ethernet або GSM/GPRS
|}

== Робота в реальному режимі ==
Реальний режим — це робота з фіскалізованим пристроєм, який використовується для реєстрації розрахункових операцій.

=== Перед запуском ===
Перед production-запуском потрібно:

# Зареєструвати РРО.
# Виконати фіскалізацію.
# Виконати персоналізацію.
# Налаштувати податкові групи.
# Налаштувати типи оплат.
# Налаштувати касирів.
# Налаштувати заголовок і підвал чека.
# Перевірити передачу даних.
# Перевірити роботу POS-системи з реальним драйвером.
# Провести тестовий день роботи.

{| class="wikitable"
!Статус
!Правило
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Обовʼязково
|Усі операції продажу мають проходити через фіскальний реєстратор.
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |Обовʼязково
|Наприкінці зміни потрібно виконувати Z-звіт.
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |Контроль
|Потрібно перевіряти статус передачі даних.
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |Небезпечно
|Не можна ігнорувати помилки фіскального реєстратора.
|}

=== Типовий робочий цикл ===
<pre>
1. Увімкнути фіскальний реєстратор.
2. Перевірити звʼязок із POS-системою.
3. Перевірити папір.
4. Відкрити зміну.
5. Пробивати чеки продажу.
6. За потреби виконувати повернення.
7. За потреби друкувати X-звіт.
8. Наприкінці дня друкувати Z-звіт.
9. Перевірити передачу даних.
</pre>

== Обробка помилок ==

=== Типові помилки інтеграції ===
{| class="wikitable"
!Помилка
!Причина
!Що робити
|-
|Немає звʼязку з пристроєм
|Неправильний COM-порт або кабель
|Перевірити порт, кабель, драйвер, живлення
|-
|Timeout
|Пристрій не відповідає
|Повторити команду, перевірити стан РРО
|-
|Port busy
|Порт зайнятий іншою програмою
|Закрити інші програми, які використовують COM-порт
|-
|Немає паперу
|Закінчилась чекова стрічка
|Замінити папір і повторити операцію
|-
|Зміна не відкрита
|POS намагається пробити чек без відкритої зміни
|Спочатку виконати відкриття зміни
|-
|Чек уже відкритий
|Попередній чек не закритий
|Закрити або анулювати чек
|-
|Помилка передачі даних
|Немає Ethernet/GSM-звʼязку
|Перевірити інтернет, SIM-карту, налаштування
|}

=== Рекомендований retry-механізм ===
<syntaxhighlight lang="python"> import time

class FiscalCommandError(Exception):
    pass
def execute_with_retry(command, retries: int = 3, delay: float = 1.0):
    last_error = None

    for attempt in range(1, retries + 1):
        try:
            result = command()

            if isinstance(result, str) and result.startswith("OK"):
                return result

            last_error = result

        except Exception as exc:
            last_error = exc

        time.sleep(delay)

    raise FiscalCommandError(f"Command failed after {retries} retries: {last_error}")
</syntaxhighlight>

== Логування ==
Для production-інтеграції потрібно логувати:

* дату й час команди;
* тип команди;
* параметри команди;
* відповідь пристрою;
* код помилки;
* COM-порт;
* тривалість виконання;
* номер чека;
* номер зміни.

=== Приклад логування в Python ===
<syntaxhighlight lang="python"> import logging import time

logging.basicConfig(
    filename="mini_fp54.log",
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
)

def log_fiscal_command(command_name: str, callback):
    started_at = time.time()

    try:
        result = callback()
        duration = round(time.time() - started_at, 3)

        logging.info(
            "command=%s duration=%s result=%s",
            command_name,
            duration,
            result,
        )

        return result

    except Exception as exc:
        duration = round(time.time() - started_at, 3)

        logging.exception(
            "command=%s duration=%s error=%s",
            command_name,
            duration,
            exc,
        )

        raise
</syntaxhighlight>

== Рекомендована структура Python-проєкту ==
<pre>
mini_fp54/
├── __init__.py
├── interfaces.py
├── ole_driver.py
├── serial_driver.py
├── fake_driver.py
├── errors.py
├── logger.py
├── config.py
└── tests/
    ├── test_fake_driver.py
    ├── test_sale_flow.py
    └── test_errors.py
</pre>

=== Призначення файлів ===
{| class="wikitable"
!Файл
!Призначення
|-
|interfaces.py
|Спільний інтерфейс драйвера
|-
|ole_driver.py
|Робота через OLE/DLL у Windows
|-
|serial_driver.py
|Робота через serial-порт
|-
|fake_driver.py
|Mock-драйвер для тестів
|-
|errors.py
|Власні класи помилок
|-
|logger.py
|Логування команд і відповідей
|-
|config.py
|Налаштування порту, швидкості, режиму роботи
|-
|tests/
|Unit та integration-тести
|}

== Production checklist ==
{| class="wikitable"
!Статус
!Перевірка
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|USB-драйвер встановлено
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|OLE/DLL встановлено, якщо використовується Windows
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|COM-порт визначено
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Отримання статусу працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Відкриття зміни працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Продаж товару працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Оплата готівкою працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Оплата карткою працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Закриття чека працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|X-звіт працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Z-звіт працює
|-
| style="background:#d4edda; color:#155724; font-weight:bold;" |□
|Передача даних працює
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |□
|Перевірено поведінку при timeout
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |□
|Перевірено поведінку при відсутності паперу
|-
| style="background:#fff3cd; color:#856404; font-weight:bold;" |□
|Перевірено поведінку при втраті інтернету
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |□
|Немає hardcoded COM-порту в production-коді
|-
| style="background:#f8d7da; color:#721c24; font-weight:bold;" |□
|Немає ігнорування помилок РРО
|}

== Висновок ==
МІНІ-ФП54.01 найпростіше інтегрувати у Windows через офіційний DLL/OLE-сервер. Python можна використовувати через пакет `pywin32`, якщо встановлено та зареєстровано OLE-сервер.

Для Linux, macOS або embedded-систем можлива інтеграція через `pyserial`, але для цього потрібно реалізувати протокол обміну з пристроєм. Такий варіант гнучкіший, але складніший і потребує повного тестування з реальним фіскальним реєстратором.

Для розробки без фізичного пристрою варто використовувати mock-драйвер або serial-емулятор. Це дозволяє перевірити POS-логіку, але не замінює тестування з реальним РРО.

== Джерела ==

* Офіційна сторінка МІНІ-ФП54.01: https://unisystem.ua/catalog/fiskalnye-registratory/fiskalnyj-registrator-mini-fp54-01/
* Сторінка підтримки Юнісістем: https://unisystem.ua/podderzhka/