coin-counter-simulators/README.md

Device Simulators

Python-based simulators for coin counting devices. This package includes:

• Pelican Simulator: For Pelican coin counting devices (301, 305, 309) and CDS (501, 524, 709, 726) coin machines
• Glory Simulator: For Glory MACH6 coin/currency counters

Both simulators implement their respective communication protocols for development and testing purposes.

Features

Pelican Simulator

• Full PeliHost Protocol Implementation:

  • RS232 serial communication (9600 baud, 8N1)
  • STX/ETX message framing
  • CRC-16 checksum validation
  • Link management (construct/destruct)

• Supported Commands:

  • Construct/Destruct Link (0x01/0x03)
  • Get Value (0x11) - current count, total count, software version, machine status
  • Get/Set Display (0x31/0x33)
  • Lock Display (0x37)
  • Lock Keyboard (0x39)

• Device State Simulation:

  • 20 coin type counters
  • Display management (2x20 character LCD)
  • Keyboard lock/unlock
  • Motor status
  • Program states

Glory Simulator

• Enhanced Serial Port Mode:

  • RS232 serial communication (9600 baud, 8N1)
  • STX/ETX message framing
  • ACK/NAK handshaking

• Supported Commands:

  • Status (SS), Clear (CB/CS/CG/CC)
  • Get Data (GD/GT/GS/GG/GI/GV)
  • Motor Control (MG/MS)
  • Bag Stop (SV)
  • Accept (AB/AS/AG)
  • ID Management (ID/IS/IG)
  • Partial Count (PC)
  • Beep (BB)

• Device State Simulation:

  • Batch, subtotal, and grand total counters
  • Partial count management
  • Bag stop functionality
  • Motor control
  • Station value configuration

Installation

# Install dependencies
pip install pyserial

# Or using uv
uv pip install pyserial

Usage

Basic Usage

# Run Pelican simulator with default settings (/dev/ttyUSB0, 9600 baud)
python main.py pelican

# Run Glory simulator with default settings
python main.py glory

# Specify serial port
python main.py pelican --port /dev/ttyS0
python main.py glory --port /dev/ttyUSB1

# Specify baud rate
python main.py pelican --port /dev/ttyUSB0 --baudrate 9600
python main.py glory --port /dev/ttyUSB1 --baudrate 9600

Running Individual Simulators

You can also run the simulators directly:

# Run Pelican simulator directly
python pelican.py --port /dev/ttyUSB0

# Run Glory simulator directly
python glory.py --port /dev/ttyUSB1

Command Line Options

The main.py script requires a simulator type (either pelican or glory):

python main.py {pelican|glory} [OPTIONS]

Options:

• --port, -p: Serial port device (default: /dev/ttyUSB0)
• --baudrate, -b: Baud rate (default: 9600)

Get help:

# General help
python main.py --help

# Pelican-specific help
python main.py pelican --help

# Glory-specific help
python main.py glory --help

Protocol Overview

Pelican Protocol

Message Format

All Pelican messages follow this structure:

STX (0x02) | Length | Data Bytes | CRC-Hi | CRC-Lo | ETX (0x03)

Example: Construct Link

Request:

02 09 01 36 39 33 39 30 32 37 34 [CRC] 03
       ^  ^-----------------^
       |   Password "69390274"
       Command 0x01

Response:

02 02 02 00 [CRC] 03
       ^  ^
       |  Status (00=OK)
       Response 0x02

Password

The fixed password for establishing a link is: 69390274

Glory Protocol

Message Format

All Glory messages follow this structure:

STX (0x02) | ASCII Command | ETX (0x03)

Example Commands

Status Request:

02 53 53 03     (STX 'S' 'S' ETX)

Status Response:

02 53 54 24 30 4F 4B 30 03     (STX 'S' 'T' '$' '0' 'O' 'K' '0' ETX)
                 ^--^  ^----^
                 Mode  Status

Start Motor:

02 4D 47 03     (STX 'M' 'G' ETX)

Protocol Specifications

• Pelican: Based on the official PeliHost protocol specification (PeliHost_09_03_30-III)
• Glory: Based on the Glory MACH6 Enhanced Serial Port Mode specification

Documentation for both protocols can be found in the docs/ directory.

Development

Project Structure

simulators/
├── main.py                 # Unified entry point for both simulators
├── pelican.py              # Pelican simulator implementation
├── glory.py                # Glory MACH6 simulator implementation
├── pyproject.toml          # Project dependencies
├── README.md               # This file
└── docs/                   # Protocol documentation

Key Components

Pelican Simulator

• CRC Calculation: Implements the CRC-16-CCITT algorithm as specified
• Message Parser: Validates STX/ETX framing and CRC checksums
• Command Handlers: Individual handlers for each protocol command
• Device State: Maintains simulated device state (counters, display, etc.)

Glory Simulator

• Message Parser: Validates STX/ETX framing for ASCII commands
• Command Handlers: Handlers for all Enhanced Serial Port Mode commands
• Device State: Simulates batch/sub/grand totals, bag stops, and motor control
• ACK/NAK Handling: Implements message acknowledgment protocol

Testing

Testing with Virtual Serial Ports

To test the simulators with your client applications:

1. Create a virtual serial port pair (e.g., using socat):

   socat -d -d pty,raw,echo=0 pty,raw,echo=0
   

2. Run the appropriate simulator on one port:

   # For Pelican
   python main.py pelican --port /dev/pts/X
   
   # For Glory
   python main.py glory --port /dev/pts/X
   

3. Connect your client to the other port

License

This is a development/testing tool. The protocols are proprietary to their respective manufacturers:

• Pelican protocol: CT-Coin & ASAP Electronics
• Glory protocol: Glory Global Solutions

Technical Support

For questions about the protocols:

• Pelican/ASAP Electronics
  • Email: info@asap.dk
  • URL: www.asap.dk
• Glory Global Solutions
  • URL: www.glory-global.com