Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 0 additions & 65 deletions FlashFirmware.bat

This file was deleted.

105 changes: 23 additions & 82 deletions UPLOAD_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,8 @@ The latest SledLink release package is available on GitHub:
**[Download Latest Release](https://github.com/thompcd/SledLink/releases/latest)**

Each release includes:
- Pre-compiled firmware binaries (ready to flash instantly)
- Arduino source code for both controllers
- Upload/flash scripts for Windows
- Upload scripts for Windows, Mac, and Linux
- This guide

---
Expand All @@ -25,51 +24,21 @@ Each release includes:

---

## Flash Your Firmware
## Upload Your Firmware

---

## Standard Method: Quick Flash (Recommended)

Pre-compiled firmware is ready to flash instantly - no compilation needed!

### Windows - Quick Flash

1. **Download the SledLink folder** to your computer from GitHub
2. **Extract the ZIP file** to a convenient location
3. **Connect your controller** via USB cable to your computer
4. **Double-click** `FlashFirmware.bat` in the main folder
5. **Select your controller type:**
- Type `1` if flashing a SLED Controller (with encoder)
- Type `2` if flashing a JUDGE Controller (display only)
6. **Flash happens automatically** - takes about 10 seconds
7. **Done!** Your controller restarts automatically

That's it! Your system is now ready to use.

### What is "Flashing"?

Flashing writes the firmware directly to your controller's memory using pre-compiled binaries. It's much faster than compiling (10 seconds vs 60+ seconds) and requires no additional software beyond Windows.
Firmware is compiled fresh from source code during upload. This ensures compatibility with your system and allows for easy customization.

---

## For Advanced Users & Developers
### Windows

### Compile Firmware from Source Code

If you need to modify the firmware or want the full Arduino development environment, you can compile from source instead of flashing pre-compiled binaries. This takes 60+ seconds instead of ~10 seconds.

---

### Windows - Compile from Source

1. **Download the SledLink folder** to your computer
1. **Download the SledLink folder** to your computer from GitHub
2. **Extract the ZIP file** to a convenient location
3. **Open the `tools` folder** in the release package
4. **Double-click** `Compile Firmware (Windows).bat`
5. **Follow the prompts** on screen
3. **Double-click** `Upload Firmware (Windows).bat` in the main folder
4. **Follow the prompts** on screen
5. The compilation and upload happens automatically

### Mac - Compile from Source
### Mac

1. **Download the SledLink folder** to your computer
2. **Open Terminal** (press Cmd+Space, type "Terminal", press Enter)
Expand Down Expand Up @@ -104,7 +73,7 @@ If you need to modify the firmware or want the full Arduino development environm

---

### How Compile-from-Source Works
### How Upload Works

1. **Checks for Arduino CLI** - The build tool. Installs it if needed.
2. **Sets up ESP32 support** - Downloads ESP32 tools (first time only, ~500MB)
Expand All @@ -116,21 +85,9 @@ If you need to modify the firmware or want the full Arduino development environm

## Troubleshooting

### Flash Method Issues

#### "FlashFirmware.bat won't run" or Windows Defender blocks it

- **Windows Defender SmartScreen:** Click **"More info"** then **"Run anyway"**
- **Right-click** the `.bat` file and select **"Run as administrator"**
- **Temporary solution:** Run from Command Prompt: `FlashFirmware.bat`

#### "esptool.exe not found"

- Make sure you **extracted the entire release ZIP** with all directories
- The file `firmware/tools/esptool.exe` must be present
- Try **re-downloading the release** if files seem to be missing
### "No serial devices found"

#### "No device found" during flash
Your controller might not be connected or recognized by Windows.

Try these in order:

Expand All @@ -140,19 +97,25 @@ Try these in order:
4. **Check Device Manager:**
- Press `Win+X`, select "Device Manager"
- Look for your device under "Ports (COM & LPT)"
- If it shows a warning icon, you need USB drivers
- If it shows a warning icon, you need USB drivers (see "USB Driver Issues" below)

#### "Flash failed" or timeout error
### "Upload failed" or timeout error

1. **Hold the BOOT button** on the ESP32 board during the first 5 seconds of flash
- The flash tool will tell you when it's starting
1. **Hold the BOOT button** on the ESP32 board during the first 5 seconds of upload
- The upload tool will tell you when it's starting
- You can release BOOT after it begins
2. **Try a different USB cable** (charge-only cables won't work)
3. **Try a different USB port**
4. **Close other programs** that might be using the serial port (Arduino IDE, PuTTY, etc.)
5. **Try restarting your computer**

#### USB Driver Issues
### Windows: "Script won't run" or security error

- **Right-click** `Upload Firmware (Windows).bat` and select **"Run as administrator"**
- If Windows SmartScreen blocks it, click **"More info"** then **"Run anyway"**
- **Temporary solution:** Run from Command Prompt: `"Upload Firmware (Windows).bat"`

### USB Driver Issues

If Windows doesn't recognize your device:

Expand All @@ -166,28 +129,6 @@ If Windows doesn't recognize your device:

If you're not sure which driver you need, try one - it won't hurt to have both installed.

---

### Method 2: Compile from Source - Troubleshooting

### "No serial devices found"

- **Try a different USB cable.** Some cables are "charge only" and don't have data wires.
- **Try a different USB port** on your computer.
- **Wait a few seconds** after plugging in for drivers to load.
- **Check Device Manager** (Windows) to see if the device appears with a warning icon.

### "Upload failed"

- **Unplug and replug** the USB cable, then try again.
- **Hold the BOOT button** on the ESP32 while the upload starts, then release it.
- **Close other programs** that might be using the serial port (like Arduino IDE or PuTTY).

### Windows: "Script won't run" or security error

- **Right-click** the `.bat` file and select **"Run as administrator"**
- If Windows SmartScreen blocks it, click **"More info"** then **"Run anyway"**

### Mac: "Permission denied"

Run this command first:
Expand Down
97 changes: 24 additions & 73 deletions build_release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -64,68 +64,21 @@ fi
echo ""
echo "Creating release directory..."
rm -rf "$OUTPUT_DIR"
mkdir -p "$OUTPUT_DIR/firmware/SledController"
mkdir -p "$OUTPUT_DIR/firmware/JudgeController"
mkdir -p "$OUTPUT_DIR/firmware/tools"
mkdir -p "$OUTPUT_DIR/firmware"
mkdir -p "$OUTPUT_DIR/tools"
mkdir -p "$OUTPUT_DIR/source"

# Copy flash tools (main method for users)
echo "Copying flash tools..."
cp "$SCRIPT_DIR/FlashFirmware.bat" "$OUTPUT_DIR/"
cp "$SCRIPT_DIR/flash_firmware.ps1" "$OUTPUT_DIR/"
chmod +x "$OUTPUT_DIR/flash_firmware.ps1"

# Copy compile/upload tools (advanced method for developers)
echo "Copying advanced compile tools..."
# Copy upload tools for compiling from source
echo "Copying upload tools..."
cp "$SCRIPT_DIR/upload_firmware.sh" "$OUTPUT_DIR/tools/"
cp "$SCRIPT_DIR/upload_firmware.ps1" "$OUTPUT_DIR/tools/"
cp "$SCRIPT_DIR/Upload Firmware (Windows).bat" "$OUTPUT_DIR/tools/Compile Firmware (Windows).bat"
cp "$SCRIPT_DIR/Upload Firmware (Windows).bat" "$OUTPUT_DIR/"
chmod +x "$OUTPUT_DIR/tools/upload_firmware.sh"

# Copy source code
echo "Copying source code..."
cp -r "$SCRIPT_DIR/arduino" "$OUTPUT_DIR/source/"

# Compile firmware binaries
echo ""
echo "Compiling firmware binaries..."
echo " SledController..."
arduino-cli compile --fqbn esp32:esp32:esp32 --export-binaries \
--output-dir "$SCRIPT_DIR/firmware_binaries/SledController" \
"$SCRIPT_DIR/arduino/SledController" 2>&1 | grep -E "(Compiling|Archiving|Sketch uses|Global variables)" || true

echo " JudgeController..."
arduino-cli compile --fqbn esp32:esp32:esp32 --export-binaries \
--output-dir "$SCRIPT_DIR/firmware_binaries/JudgeController" \
"$SCRIPT_DIR/arduino/JudgeController" 2>&1 | grep -E "(Compiling|Archiving|Sketch uses|Global variables)" || true

# Package binaries into release
echo "Packaging firmware binaries..."
for controller in SledController JudgeController; do
BIN_DIR="$SCRIPT_DIR/firmware_binaries/$controller"
OUT_DIR="$OUTPUT_DIR/firmware/$controller"

if [ -f "$BIN_DIR/${controller}.ino.bin" ]; then
cp "$BIN_DIR/${controller}.ino.bin" "$OUT_DIR/firmware.bin"
cp "$BIN_DIR/${controller}.ino.bootloader.bin" "$OUT_DIR/bootloader.bin"
cp "$BIN_DIR/${controller}.ino.partitions.bin" "$OUT_DIR/partitions.bin"
echo " ✓ $controller"
else
echo " ✗ $controller - binaries not found!"
fi
done

# Extract and copy esptool
echo "Extracting esptool for Windows..."
ESPTOOL_DIR=$(find ~/.arduino15/packages/esp32/tools/esptool_py -type d -maxdepth 2 2>/dev/null | head -1)
if [ -f "$ESPTOOL_DIR/esptool.exe" ]; then
cp "$ESPTOOL_DIR/esptool.exe" "$OUTPUT_DIR/firmware/tools/"
echo " ✓ esptool.exe bundled"
else
echo " ⚠ esptool.exe not found - Windows flashing may not work"
fi

# Copy documentation
echo "Copying documentation..."
cp "$SCRIPT_DIR/UPLOAD_GUIDE.md" "$OUTPUT_DIR/"
Expand All @@ -145,37 +98,35 @@ RELEASE INFORMATION
Build Date: $(date +%Y-%m-%d)
Download: https://github.com/thompcd/SledLink/releases/tag/$VERSION

This release contains PRE-COMPILED firmware ready to flash instantly!
This release contains source code and tools to compile and upload firmware to the SledLink system.

CONTENTS
--------
firmware/ - Pre-compiled firmware binaries (ready to flash)
SledController/ - Sled controller binaries
JudgeController/ - Judge controller binaries
tools/ - esptool.exe for Windows

Flash Firmware.bat - Main method: Double-click to flash firmware instantly

source/ - Arduino source code (for advanced users and developers)
source/ - Arduino source code
arduino/SledController/ - Sled controller source
arduino/JudgeController/ - Judge controller source

tools/ - Advanced tools (for developers)
Compile Firmware (Windows).bat - Compile and upload from source code
upload_firmware.sh - Mac/Linux compile and upload script
upload_firmware.ps1 - Windows PowerShell compile and upload script
tools/ - Upload utilities
upload_firmware.sh - Mac/Linux upload script
upload_firmware.ps1 - Windows PowerShell upload script

Upload Firmware (Windows).bat - Double-click to upload firmware

QUICK START - FLASH FIRMWARE (RECOMMENDED)
-------------------------------------------
Pre-compiled firmware flashes in ~10 seconds - no compilation needed!

QUICK START - UPLOAD FIRMWARE
-----------------------------
The firmware is compiled fresh from source code during upload.

Windows:
1. Connect the controller via USB
2. Double-click "Flash Firmware.bat"
3. Select controller type (1=Sled, 2=Judge)
4. Firmware flashes automatically!
5. Controller restarts automatically
2. Double-click "Upload Firmware (Windows).bat"
3. Follow the prompts

Mac/Linux:
1. Connect the controller via USB
2. Open Terminal in this folder
3. Run: ./tools/upload_firmware.sh
4. Follow the prompts


WHICH CONTROLLER IS WHICH?
Expand All @@ -197,13 +148,13 @@ See UPLOAD_GUIDE.md for detailed troubleshooting steps.

Common issues:
- "No device found" - Try a different USB cable (some are charge-only)
- "Flash failed" - Hold BOOT button on ESP32 during flash
- "Upload failed" - Hold BOOT button on ESP32 during upload
- Driver issues - Install CP210x or CH340 USB driver for your OS


SUPPORT
-------
For issues, visit: https://github.com/thompcd/SledLink/issues
For issues, visit: https://github.com/tulsasoftware/SledLink/issues

================================================================================
HEREDOC
Expand Down
7 changes: 1 addition & 6 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,13 +225,8 @@ SledLink/
├── upload_firmware.ps1 # Windows PowerShell upload script
├── Upload Firmware (Windows).bat # Windows launcher (double-click)
│ # Flash Tools (pre-compiled binaries)
├── flash_firmware.sh # Mac/Linux flash script
├── flash_firmware.ps1 # Windows PowerShell flash script
├── Flash Firmware (Windows).bat # Windows launcher (double-click)
│ # Release & Documentation
├── build_release.sh # Build release package with binaries
├── build_release.sh # Build release package
├── UPLOAD_GUIDE.md # User guide for firmware upload
└── release/ # Generated release packages (git-ignored)
```
Expand Down
3 changes: 1 addition & 2 deletions docs/RELEASE_PROCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,7 @@ git push origin v3.0.1
3. It will:
- Validate the tag
- Install dependencies
- Compile both firmwares
- Create release package
- Create release package with source code and upload tools
- Create GitHub release
- Upload ZIP file

Expand Down
Loading