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

```bash
# Install dependencies
pip install pyserial

# Or using uv
uv pip install pyserial
```

## Usage

### Basic Usage

```bash
# 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:

```bash
# 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`):

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

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

**Get help:**
```bash
# 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`):
   ```bash
   socat -d -d pty,raw,echo=0 pty,raw,echo=0
   ```

2. Run the appropriate simulator on one port:
   ```bash
   # 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