Chương 3 — Ứng dụng Bridge (cầu nối kết nối phần cứng)

Máy tính tiền (Kasse) chạy trong trình duyệt, mà trình duyệt không thể trực tiếp trao đổi với máy đọc thẻ, máy in, cân và màn hình khách hàng. Ứng dụng Bridge chính là cầu nối này: nó chạy cạnh máy tính tiền và kết nối những thiết bị đó với máy tính tiền.

Nó có ba dạng, tất cả đều làm cùng một việc (bản iOS đang ở giai đoạn thử nghiệm):

• Ứng dụng Android trên máy tính bảng
• Ứng dụng máy tính để bàn trên máy tính (Windows/Mac/Linux)
• Ứng dụng iOS (thử nghiệm)

⚠️ Ngôn ngữ: giao diện của ứng dụng Android thực tế là tiếng Anh. Chỉ vài chuỗi cũ được dịch sang tiếng Đức; toàn bộ bảng điều khiển mà người vận hành nhìn thấy (các trạng thái, Power Guard, Keep Bridge Awake, nhật ký, v.v.) đều bằng tiếng Anh.

💡 Thông thường bạn thiết lập Bridge một lần rồi sau đó nó chạy ngầm. Bạn nhập địa chỉ Bridge tại máy tính tiền ← cài đặt ← Bridge (hướng dẫn máy tính tiền, chương 9). Ứng dụng Android chạy như một dịch vụ nền bền vững: vẫn sống ngay cả khi đóng ứng dụng khỏi danh sách, tự động khởi động lại sau khi cập nhật, và một bộ giám sát cứ mỗi 30 giây sẽ khởi động lại máy chủ khi cần.

3-1. Ứng dụng Android — màn hình trạng thái

Một màn hình toàn màn hình (kiosk) với một dòng tóm tắt ở trên cùng và vài thẻ trạng thái. Khi đang chạy, bạn sẽ thấy thông báo «Đang chuẩn bị cầu nối, kết nối máy đọc thẻ và màn hình khách hàng».

• Tóm tắt chung ở phía trên màn hình, ví dụ: «Cầu nối sẵn sàng thanh toán», «Máy đọc thẻ sẵn sàng, đang chờ trình duyệt», «Trình duyệt đã kết nối / máy đọc thẻ ngoại tuyến», «Đang khôi phục kết nối máy đọc thẻ», hoặc «Đang có giao dịch».
• Các thẻ trạng thái (mỗi thẻ có một chấm màu và một từ trạng thái):
• WebSocket — cổng nội bộ mà máy tính tiền kết nối tới.
• Trình duyệt (Browser) — máy tính tiền đã kết nối hay chưa.
• Máy đọc thẻ (POS Terminal) — các trạng thái: mất kết nối / đang kết nối / đang kết nối lại / đã kết nối / bận (Busy) khi có giao dịch.
• Màn hình khách hàng — trạng thái của màn hình thứ hai.
• Power Guard — bảo vệ pin/bộ xử lý/Wi-Fi để tránh mất kết nối khi rảnh rỗi.

Thẻ địa chỉ Bridge

• Hiển thị địa chỉ (địa chỉ nội bộ 127.0.0.1:PORT hoặc địa chỉ mạng với IP của thiết bị) cần được nhập vào máy tính tiền.
• Nút chế độ kết nối có ba trạng thái và luân chuyển sau mỗi lần bấm: nội bộ ← mạng ← tự động (Auto). Chế độ tự động sẽ chuyển sang mạng nếu có địa chỉ mạng nội bộ khả dụng, ngược lại chuyển sang nội bộ.
• Giữ nút chế độ kết nối: tạo hoặc xóa mã ghép nối — một mã gồm 6 ký tự được thêm vào địa chỉ (?token=XXXXXX) để chỉ máy tính tiền được phép mới có thể kết nối. Mã này chỉ áp dụng ở chế độ mạng (ở chế độ nội bộ nó bị bỏ qua) và được hiển thị trong địa chỉ dưới dạng «Paired/Open».

Các thẻ khác và truy cập nhật ký

• Power Guard → «Giữ cho cầu nối luôn thức» (Keep Bridge Awake): mở phần cài đặt pin của Android để Bridge không bị ngắt khi rảnh rỗi.
• Nhật ký: bật/tắt bằng nút Enable/Disable Logs và View Logs mở trang nhật ký; việc tắt sẽ xóa các nhật ký đã lưu. Cách thứ hai để mở nhật ký là giữ (long-press) lên thanh trên cùng của màn hình.
• Trang nhật ký: chỉ đọc — văn bản đơn khoảng cách (monospace) được làm mới mỗi giây và cuộn xuống dưới; không có nút chia sẻ/xuất (để gửi cho bộ phận hỗ trợ, bạn phải sao chép thủ công).
• Trang màn hình khách hàng: trên màn hình thứ hai, hiển thị cho khách các món và tổng đơn hàng bằng một mẫu web. Trên Android, nó tự động bám vào bất kỳ màn hình thứ hai nào được kết nối (không cần chọn thủ công; sẽ bị gỡ bỏ khi rút cáp).

3-2. Ứng dụng máy tính để bàn — «LonioBridge — Host»

Một cửa sổ điều khiển nhỏ để chạy Bridge trên máy tính:

• Biểu mẫu thiết lập:
• Cổng WebSocket (mặc định 8088)
• Địa chỉ kết nối (Bind): chỉ máy tính này hoặc toàn mạng (mặc định 0.0.0.0).
• Màn hình khách hàng: chọn thủ công màn hình dùng làm màn hình khách hàng (hoặc không chọn màn hình nào).
• Khởi động/dừng để chạy cầu nối; các cài đặt được lưu trong tệp ~/.loniobridge/host.properties giữa các lần chạy.
• Chạy tự động (Autostart): với tham số --autostart (trình cài đặt trên Windows sẽ thiết lập nó cùng các tập lệnh bật/tắt để nó khởi động cùng hệ thống).
• Chế độ không cửa sổ (Console): với --console bạn có thể chạy mà không cần giao diện đồ họa.
• Bảng trạng thái: trạng thái máy chủ (đã dừng / đang khởi động / đang lắng nghe trên cổng / cổng không hợp lệ / lỗi), số máy tính tiền đã kết nối, trạng thái máy đọc thẻ, và chỉ báo bận/rảnh (khi có giao dịch).
• Báo cáo hoạt động: nhật ký sự kiện có mốc thời gian; tùy chọn Verbose để ghi các khung dữ liệu thô của máy đọc thẻ (chỉ dùng để gỡ lỗi).

⚠️ Trong cửa sổ máy tính để bàn không có phần chọn máy in hoặc cân; chỉ có cổng, địa chỉ kết nối và màn hình khách hàng. Máy in và cân được cấu hình từ phía máy tính tiền, và Bridge khởi động chúng theo thông báo từ máy tính tiền.

3-3. Những thiết bị nào được kết nối

• Máy đọc thẻ: có hai trình điều khiển, được chọn trong hồ sơ terminal:
• ZVT (mặc định) — thông qua mạng/TCP, với kết nối lại tự động (backoff) và các trạng thái đang kết nối/khôi phục/đã kết nối.
• GP Tom (SoftPOS) — trình điều khiển của Global Payments, chạy trên cùng chiếc máy tính bảng Android và trao đổi với ứng dụng máy đọc thẻ GP (bán/hủy/hoàn tiền; chốt sổ hằng ngày qua đường App2App này hiện chưa được hỗ trợ).
• Màn hình khách hàng: mẫu web (các món và tổng đơn hàng) mà máy tính tiền gửi tới; Android tự động bám vào, còn máy tính để bàn thì chọn thủ công màn hình.
• Máy in:
• ⚠️ Trên Android, việc in hiện tại chỉ được tiếp nhận nhưng chưa triển khai in thật; in thật hoạt động trên máy tính để bàn.
• Máy tính để bàn có ba cách: cổng nối tiếp (serial), máy in hệ thống (Windows), và mạng/TCP (mặc định, cổng 9100); bao gồm cắt giấy và mở ngăn kéo đựng tiền.
• Cân: chỉ trên máy tính để bàn — cổng nối tiếp hoặc USB-HID, với nhận diện đơn vị (kg/g/lb/oz) và trạng thái ổn định/không ổn định. Android không có cân.

3-4. Cấu hình mà người thiết lập cần biết

• Cổng (mặc định 8088) và địa chỉ kết nối (nội bộ so với mạng).
• Sự khác biệt giữa 127.0.0.1 (nội bộ) và IP mạng: nếu máy tính tiền ở trên chính thiết bị này thì nội bộ là đủ; nếu ở trên thiết bị khác thì cần chế độ mạng + IP và cả hai phải ở trên cùng một mạng.
• Mã ghép nối (?token=…) chỉ ở chế độ mạng.
• Cài đặt pin của Android (Keep Bridge Awake) để tránh mất kết nối.

3-5. Xử lý sự cố nhanh