# Pelican Device Simulator

A Python-based simulator for Pelican coin counting devices (301, 305, 309) and CDS (501, 524, 709, 726) coin machines. This simulator implements the PeliHost communication protocol for development and testing purposes.

## Features

- **Full 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

## Installation

```bash
# Install dependencies
pip install pyserial

# Or using uv
uv pip install pyserial
```

## Usage

### Basic Usage

```bash
# Run with default settings (/dev/ttyUSB0, 9600 baud)
python main.py

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

# Specify baud rate
python main.py --port /dev/ttyUSB0 --baudrate 9600
```

### Command Line Options

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

## Protocol Overview

### Message Format

All 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`**

## Protocol Specification

This simulator is based on the official PeliHost protocol specification (PeliHost_09_03_30-III). The document is included in this repository as `PeliHost_09_03_30-III.pdf`.

## Development

### Project Structure

```
pelican-simulator/
   main.py                     # Main simulator implementation
   pyproject.toml              # Project dependencies
   README.md                   # This file
   PeliHost_09_03_30-III.pdf  # Protocol specification
```

### Key Components

- **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.)

## Testing

To test the simulator with your Pelican client:

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 simulator on one port:
   ```bash
   python main.py --port /dev/pts/X
   ```

3. Connect your client to the other port

## License

This is a development/testing tool. The Pelican protocol is proprietary to CT-Coin & ASAP Electronics.

## Technical Support

For questions about the Pelican protocol:
- ASAP Electronics
- Email: info@asap.dk
- URL: www.asap.dk