crosspoint-reader/docs/troubleshooting.md

# Troubleshooting

This document show most common issues and possible solutions while using the device features.

- [Troubleshooting](#troubleshooting)
    - [Images Not Displaying in EPUBs](#images-not-displaying-in-epubs)
    - [Cannot See the Device on the Network](#cannot-see-the-device-on-the-network)
    - [Connection Drops or Times Out](#connection-drops-or-times-out)
    - [Upload Fails](#upload-fails)
    - [Saved Password Not Working](#saved-password-not-working)

### Images Not Displaying in EPUBs

**Problem:** Some images in EPUB books show as placeholders like "[Image: filename.jpg]" instead of the actual image

**Possible Causes:**

1. **Progressive JPEGs are not supported**
   - The device uses a minimal JPEG decoder optimized for embedded systems
   - Progressive/multi-scan JPEGs cannot be decoded due to memory constraints
   - This affects some professionally published EPUBs, especially maps and high-quality photos
   - **Workaround:** Use Calibre or another EPUB editor to convert progressive JPEGs to baseline JPEGs

2. **Unsupported image format**
   - Only JPEG and PNG images are supported
   - Other formats (GIF, WebP, SVG graphics) will show placeholders

3. **Image extraction failed**
   - The image file may be corrupted or the EPUB structure malformed
   - Try re-downloading the EPUB or converting it with Calibre

**How to check if an image is progressive JPEG:**

```python
from PIL import Image
print(Image.open("image.jpg").info.get('progressive', 0))
# Output: 1 = progressive (not supported), 0 = baseline (supported)
```

### Cannot See the Device on the Network

**Problem:** Browser shows "Cannot connect" or "Site can't be reached"

**Solutions:**

1. Verify both devices are on the **same WiFi network**
   - Check your computer/phone WiFi settings
   - Confirm the CrossPoint Reader shows "Connected" status
2. Double-check the IP address
   - Make sure you typed it correctly
   - Include `http://` at the beginning
3. Try disabling VPN if you're using one
4. Some networks have "client isolation" enabled - check with your network administrator

### Connection Drops or Times Out

**Problem:** WiFi connection is unstable

**Solutions:**

1. Move closer to the WiFi router
2. Check signal strength on the device (should be at least `||` or better)
3. Avoid interference from other devices
4. Try a different WiFi network if available

### Upload Fails

**Problem:** File upload doesn't complete or shows an error

**Solutions:**

1. Ensure the file is a valid `.epub` file
2. Check that the SD card has enough free space
3. Try uploading a smaller file first to test
4. Refresh the browser page and try again

### Saved Password Not Working

**Problem:** Device fails to connect with saved credentials

**Solutions:**

1. When connection fails, you'll be prompted to "Forget Network"
2. Select **Yes** to remove the saved password
3. Reconnect and enter the password again
4. Choose to save the new password