138 lines
3.1 KiB
Markdown
138 lines
3.1 KiB
Markdown
# 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
|