basic1/UPLOAD_TOOL.md

# Lua Game Upload Tool

Rapidly upload and execute Lua games on your RP2350 via USB serial for quick iteration during development!

## Features

- Upload Lua game files directly to the SD card via USB serial
- Automatically launches the uploaded game immediately
- No need to manually swap SD cards or restart the device
- Perfect for rapid game development and testing

## Requirements

### Computer Side
- Python 3.x
- pyserial library: `pip install pyserial`

### RP2350 Side
- Firmware must be built with serial uploader support (already included)
- SD card inserted and formatted (FAT32)
- USB connection to computer

## Usage

### 1. Connect Your Device

Connect your RP2350 to your computer via USB. The device will appear as a serial port:
- **Linux/Mac**: Usually `/dev/ttyACM0` or `/dev/ttyUSB0`
- **Windows**: Usually `COM3`, `COM4`, etc.

### 2. Upload a Lua Game

Basic usage:
```bash
python upload_game.py my_game.lua
```

Specify a custom serial port:
```bash
python upload_game.py my_game.lua /dev/ttyACM0    # Linux/Mac
python upload_game.py my_game.lua COM3            # Windows
```

The script will:
1. Read your Lua file
2. Upload it to the RP2350 via serial
3. Save it to `/games/<filename>.lua` on the SD card
4. Automatically launch the game!

### 3. View Available Serial Ports

Run the script without arguments to see available ports:
```bash
python upload_game.py
```

## Example Workflow

```bash
# Edit your game
vim snake.lua

# Upload and test (the game starts immediately!)
python upload_game.py snake.lua

# Make changes
vim snake.lua

# Upload again (instantly replaces and restarts)
python upload_game.py snake.lua
```

## Protocol Details

The tool uses a simple text-based protocol over USB serial:

```
UPLOAD <filename> <size_in_bytes>
<base64_encoded_file_content>
END
```

**Response:**
```
OK <bytes_written>
LAUNCHED <game_name>
```

## Troubleshooting

### "No serial port found"
- Make sure your device is connected via USB
- Check if the device appears in your system (use `ls /dev/tty*` on Linux/Mac)
- On Linux, you may need to add your user to the `dialout` group: `sudo usermod -a -G dialout $USER`

### "Permission denied"
On Linux/Mac, you may need permissions to access the serial port:
```bash
sudo chmod 666 /dev/ttyACM0  # Quick fix
# OR
sudo usermod -a -G dialout $USER && newgrp dialout  # Permanent fix
```

### "Upload failed" or "ERROR" messages
- Make sure the SD card is properly inserted and formatted (FAT32)
- Check that there's enough space on the SD card
- Verify the Lua file is valid (syntax errors will appear when game launches)

### Game doesn't appear or launch
- Check the serial output from the RP2350 for error messages
- Ensure the Lua file has proper metadata comments at the top:
  ```lua
  -- NAME: My Game
  -- DESCRIPTION: A fun game
  ```

## Tips for Rapid Development

1. **Use a serial terminal** alongside uploads to see debug output:
   ```bash
   screen /dev/ttyACM0 115200
   ```

2. **Create a watch script** to auto-upload on file changes:
   ```bash
   while inotifywait -e modify my_game.lua; do
       python upload_game.py my_game.lua
   done
   ```

3. **Use printf() in Lua** for debugging:
   ```lua
   function update(event)
       print("Event type: " .. event.type)
       -- your code here
   end
   ```

## File Size Limits

- Maximum file size: 64 KB
- This should be plenty for most Lua games
- If you need more, consider splitting assets or code

## Related Files

- `lib/serial_uploader.h` - C++ header for serial upload handler
- `lib/serial_uploader.cpp` - C++ implementation
- `upload_game.py` - Python upload script

Happy game development! 🎮