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:

python upload_game.py my_game.lua

Specify a custom serial port:

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:

python upload_game.py

Example Workflow

# 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:

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:

  -- NAME: My Game
  -- DESCRIPTION: A fun game
  

Tips for Rapid Development

1. Use a serial terminal alongside uploads to see debug output:

   screen /dev/ttyACM0 115200
   

2. Create a watch script to auto-upload on file changes:

   while inotifywait -e modify my_game.lua; do
       python upload_game.py my_game.lua
   done
   

3. Use printf() in Lua for debugging:

   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! 🎮