tk5-c90-projects/HERCULES_READER_COMMANDS.md

# Hercules Card Reader Device Commands

This document contains the Hercules console commands used to manage the card reader device (00C/3505).

## View Device Status

```
devlist 00c
```

**Example Output:**
```
HHC02279I 0:000C 3505 3505 sockdev ascii trunc eof IO[2]
HHC02279I      (no one currently connected)
```

**Key Information:**
- `IO[n]` - Shows the I/O state number
- `(no one currently connected)` - Socket is free
- `(client IP (<unknown>) connected)` - Socket is in use

## Reset Card Reader (When Stuck)

### Method 1: Detach and Reattach (Recommended)

```
detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof
```

This completely removes and recreates the device, clearing any stuck connections.

### Method 2: Devinit (May Not Work if Socket is Wedged)

```
devinit 00c 3505 3505 sockdev ascii trunc eof
```

**Note:** `devinit` may fail with "Address already in use" if the socket is stuck. Use Method 1 instead.

## Common Issues

### Device Stuck in "IO[n] open" State

**Symptoms:**
- `devlist 00c` shows `IO[5] open` or similar
- Client shown as connected even after jobs complete
- New connections rejected with "device busy or interrupt pending"

**Solution:**
```
detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof
```

### Connection Refused from Workflow

**Symptoms:**
- Workflow logs show: `Connection refused` from netcat
- Device shows: `localhost:3505` in devlist

**Problem:** Device bound to localhost only, not accepting external connections.

**Solution:**
Use port number only (binds to all interfaces):
```
detach 00c
attach 00c 3505 3505 sockdev ascii trunc eof
```

**DO NOT USE:**
```
attach 00c 3505 localhost:3505 sockdev ascii trunc eof  # Wrong - localhost only
attach 00c 3505 0.0.0.0:3505 sockdev ascii trunc eof    # Also fails on some systems
```

## Device Configuration for Workflow

For the Gitea workflow to connect successfully, the card reader must be configured to accept connections from any interface:

```
attach 00c 3505 3505 sockdev ascii trunc eof
```

Verify with:
```
devlist 00c
```

Should show:
```
HHC02279I 0:000C 3505 3505 sockdev ascii trunc eof IO[n]
```

**Not:**
```
HHC02279I 0:000C 3505 localhost:3505 sockdev ascii trunc eof IO[n]  # Wrong
```

## Troubleshooting Workflow Socket Issues

If workflows are failing with socket errors:

1. **Check device status:**
   ```
   devlist 00c
   ```

2. **Look for stuck connections:**
   - `IO[5] open` with client connected = stuck

3. **Reset the device:**
   ```
   detach 00c
   attach 00c 3505 3505 sockdev ascii trunc eof
   ```

4. **Verify it's ready:**
   ```
   devlist 00c
   ```
   Should show `(no one currently connected)`

## Prevention

The `submit_job.py` script now includes a 10-second delay between submissions to prevent socket conflicts:
- Upload job submits
- Wait 10 seconds for JES to process
- Compile job submits

This gives Hercules time to fully close the socket between connections.