jat255 · jat255 · Feb 1, 2026 · Feb 1, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -220,7 +220,7 @@ The tool emulates Garmin devices by rewriting manufacturer and product IDs in FI
 - Product: 3122 (EDGE_830)
 - Software version: 975 (v9.75 in FIT format)
 - Hardware version: 255
-- Serial number: Auto-generated random 10-digit number (1,000,000,000 to 4,294,967,295)
+- Unit ID: Auto-generated random 10-digit number (1,000,000,000 to 4,294,967,295)
 
 **Supported devices**: 70+ devices from supplemental registry and fit_tool library, including:
 - Modern bike computers (Edge 1050, 1040, 840, 540, etc.)
@@ -230,18 +230,18 @@ The tool emulates Garmin devices by rewriting manufacturer and product IDs in FI
 
 **Custom device IDs**: Users can enter any numeric device ID manually during profile configuration.
 
-**CRITICAL: Serial Numbers and Garmin Connect Recognition**
+**CRITICAL: Unit IDs and Garmin Connect Recognition**
 
-For Garmin Connect to correctly recognize an activity as coming from a specific device (affecting Training Effect, Training Status, challenges, badges, etc.), **both the device product ID and serial number must match a valid Garmin device**. The mapping of serial number ranges to device models is proprietary Garmin information and not publicly documented.
+For Garmin Connect to correctly recognize an activity as coming from a specific device (affecting Training Effect, Training Status, challenges, badges, etc.), **both the device product ID and Unit ID must match a valid Garmin device**. The mapping of Unit ID number ranges to device models is proprietary Garmin information and not publicly documented. This field is stored in the `serial_number` field in the FIT file, but actually corresponds to the "Unit ID" displayed on the device, not the Serial Number
 
 **Serial Number Behavior**:
 - **Auto-generated (default)**: Random 10-digit integer - may not be recognized as valid by Garmin Connect
-- **User-provided (recommended)**: Users can enter their actual Garmin device's serial number during profile setup
+- **User-provided (recommended)**: Users can enter their actual Garmin device's Unit ID during profile setup
   - Find in device: Settings → About → Copyright Info → Unit ID
   - Find in Garmin Connect: Device settings page
-  - Serial number MUST match the selected device model for proper Garmin Connect recognition
+  - Unit ID MUST match the selected device model for proper Garmin Connect recognition
 
-**Implementation**: Serial numbers are stored in the `Profile.serial_number` field, validated as uint32z format (1B to 4.3B), and written to FIT file DeviceInfoMessage records.
+**Implementation**: Unit IDs are stored in the `Profile.serial_number` field, validated as uint32z format (1B to 4.3B), and written to FIT file DeviceInfoMessage records.
 
 **Firmware version maintenance**: Versions sourced from gpsinformation.net can be updated via extraction scripts:
 - `./extract_firmware_versions.sh` - Fetches latest firmware data from gpsinformation.net

diff --git a/README.md b/README.md
@@ -121,35 +121,51 @@ fit-file-faker --profile zwift -ua    # Upload Zwift files to personal account
 
 See the [profiles guide](https://jat255.github.io/Fit-File-Faker/profiles/) for comprehensive multi-profile documentation.
 
-## ⚠️ Important: Device Serial Numbers
+## ⚠️ Important: Device Serial Numbers/Unit IDs
 
-For Garmin Connect to correctly recognize an activity as coming from a specific device (which affects Training Status, challenges, badges, and other features), **both the device ID and serial number must match a valid Garmin device**.
+For Garmin Connect to correctly recognize an activity as coming from a specific device (which affects Training Status, challenges, badges, and other features), **both the device ID and serial number (Unit ID) must match a valid Garmin device**. This is a bit confusing on Garmin's implementation, since they call the value "serial number" in the FIT file, but it actually needs to be your device's *Unit ID*, not the *serial number*. To find the Unit ID, you can look either on your device (may vary depending on your device) or in the Garmin Connect app:
+
+### Garmin Connect app
+
+<div align="center">
+  <img src="docs/assets/unit_id_android.png" alt="Finding Unit ID on Garmin Connect" width="200" />
+  <p><em>Finding your device's Unit ID in the Garmin Connect Android app</em></p>
+  <p><em>Go to "Devices → [Your Device] → System → About"</em> to see the Unit ID</p>
+</div>
+
+### On an Edge device
+
+<div align="center">
+  <img src="docs/assets/unit_id_edge_1040.jpg" alt="Finding Unit ID on Garmin Device" width="500" />
+  <p><em>Finding your device's Unit ID on an Edge 1040 device</em></p>
+  <p><em>Go to "Menu → System → About → Copyright Info"</em> to see the Unit ID</p>
+</div>
 
 ### Why This Matters
 
-Garmin Connect uses internal validation to ensure that:
+Garmin Connect uses server-side validation to ensure that (so far as we know):
 - The device product ID (e.g., Edge 1050, Fenix 8) is legitimate
-- The serial number is valid for that specific device type
-- The combination of device ID + serial number represents a real device
+- The Unit ID is valid for that specific device type
+- The combination of device ID + Unit ID represents a real device
 
-If the serial number doesn't match the device type, Garmin Connect may:
+If the Unit ID doesn't match the device type, Garmin Connect may:
 - Not apply Training Effect calculations correctly
 - Not count the activity toward challenges or badges
 - Not update Training Status or training load metrics
 - Display the activity with incorrect device information
 
 ### Recommendations
 
-**Option 1: Use Your Real Garmin Device Serial Number (Recommended)**
+**Option 1: Use Your Real Garmin Device Unit ID (Recommended)**
 
 If you own a Garmin device and want your activities to count properly for all Garmin Connect features:
 
-1. Find your device's serial number (Unit ID):
+1. Find your device's Unit ID:
    - On the device: Settings → About → Copyright Info → Unit ID
    - On Garmin Connect: Device settings page
    - On the device packaging or receipt
 2. During profile setup, choose to customize the serial number
-3. Enter your actual device's serial number
+3. Enter your actual device's Unit ID as the serial number
 4. Select the matching device model (e.g., if you have an Edge 830, select Edge 830)
 
 **Option 2: Accept Limited Functionality**
@@ -163,14 +179,15 @@ If you don't own a Garmin device or don't need full Garmin Connect integration:
 
 ### What We Don't Know
 
-The mapping of serial number ranges to specific device models is proprietary Garmin information and not publicly documented. This means:
-- We cannot automatically generate valid serial numbers for specific devices
-- Random serial numbers may or may not be accepted by Garmin Connect
-- The only guaranteed way to ensure full functionality is to use a real device's serial number
+The mapping of Unit ID ranges to specific device models is proprietary Garmin information and not publicly documented. This means:
+- We cannot automatically generate valid Unit IDs/serial numbers for specific devices
+- Random Unit IDs/serial numbers may or may not be accepted by Garmin Connect
+- The only guaranteed way to ensure full functionality is to use a real device's Unit ID
+
+### Finding Your Unit ID
 
-### Finding Your Serial Number
+When you customize the serial number/Unit ID during profile creation, the tool will show you where to find it:
 
-When you customize the serial number during profile creation, the tool will show you where to find it:
 ```bash
 fit-file-faker --config-menu
 # Select "Create new profile" → customize device → customize serial number

diff --git a/docs/assets/unit_id_android.png b/docs/assets/unit_id_android.png
diff --git a/docs/assets/unit_id_edge_1040.jpg b/docs/assets/unit_id_edge_1040.jpg
diff --git a/docs/developer-guide.md b/docs/developer-guide.md
@@ -489,7 +489,7 @@ The tool emulates Garmin devices by rewriting manufacturer and product IDs in FI
 - **Product**: 3122 (`EDGE_830`)
 - **Software version**: 975 (v9.75 in FIT format)
 - **Hardware version**: 255
-- **Serial number**: Auto-generated random 10-digit number
+- **Serial number**: Auto-generated random 10-digit number instead of real Unit ID
 
 **Supported devices**: 70+ devices from the supplemental registry and `fit_tool` library, including:
 
@@ -502,15 +502,15 @@ The tool emulates Garmin devices by rewriting manufacturer and product IDs in FI
 
 #### Serial Numbers and Garmin Connect Recognition
 
-!!! warning "Critical: Device Serial Numbers Must Match Device Type"
-    For Garmin Connect to correctly recognize an activity as coming from a specific device, **both the device product ID and serial number must represent a valid Garmin device**. This affects:
+!!! warning "Critical: Device Serial Numbers Must be a valid *Unit ID* for a given Device Type"
+    For Garmin Connect to correctly recognize an activity as coming from a specific device, **both the device product ID and serial number must represent a valid Garmin device**. The serial number stored in the FIT file must be a valid *Unit ID* for the device. This affects:
 
     - **Training Effect calculations**: VO2 Max, Training Load, Recovery Time
     - **Training Status**: Productive, Maintaining, Peaking, etc.
     - **Challenges and Badges**: Activity may not count toward goals
     - **Device attribution**: Incorrect device shown in activity details
 
-    **The mapping of serial number ranges to device models is proprietary Garmin information** and not publicly documented.
+    **The mapping of serial number/Unit ID ranges to device models is proprietary Garmin information** and not publicly documented.
 
 **Serial Number Behavior**:
 
@@ -519,15 +519,15 @@ The tool emulates Garmin devices by rewriting manufacturer and product IDs in FI
    - Activities will upload but advanced features may not work correctly
 
 2. **User-provided (recommended for full functionality)**: During profile creation/editing, users can:
-   - Enter their actual Garmin device's serial number (Unit ID)
+   - Enter their actual Garmin device's Unit ID as the serial number
    - This ensures full Garmin Connect integration
-   - Serial number must match the selected device model for proper recognition
+   - The Unit ID must match the selected device model for proper recognition
 
 3. **Validation**: The tool validates serial numbers are valid `uint32z` format but **cannot** validate device-specific ranges
 
 **Best Practice**: If users own a Garmin device and want full Garmin Connect features, they should:
 - Configure their profile to use the same device model as their physical device
-- Enter their actual device's serial number (found in Settings → About → Copyright Info → Unit ID)
+- Enter their actual device's Unit ID as the serial number (found in Settings → About → Copyright Info → Unit ID)
 - This guarantees proper activity recognition and feature availability
 
 ### File Naming Convention

diff --git a/docs/index.md b/docs/index.md
@@ -223,54 +223,79 @@ If you select **Yes**, you can:
 
 1. **Choose from common devices** - Curated list of 11 popular devices
 2. **View all devices** - Access full catalog of 70+ devices organized by category
-3. **Enter a custom numeric device ID** (advanced users) - Allows you to specify a custom "device id" in the resulting FIT file; most users should not want this option, but it is available if you wish
+3. **Enter a custom numeric device ID** - Allows you to specify a custom "device id" in the resulting FIT file; this can allow you to match your FIT files to a real Garmin device that you may already have on your account 
+4. **Enter a custom serial number/Unit ID** - Allows you to specify the unique device that the FIT file will appear to have been written by. This is important for enabling certain features on Garmin Connect (see next section). 
 
 !!! tip "Custom Device IDs"
     If you enter a numeric device ID that's not in the registry, the tool will show a warning but still create/update the profile. This allows using newer Garmin devices or less common models.
+
+### ⚠️ Important: Device Serial Numbers/Unit IDs
 
-### Example: Different Devices for Different Profiles
+For Garmin Connect to correctly recognize an activity as coming from a specific device (which affects Training Status, challenges, badges, and other features), **both the device ID and serial number (Unit ID) must match a valid Garmin device**. This is a bit confusing on Garmin's implementation, since they call the value "serial number" in the FIT file, but it actually needs to be your device's *Unit ID*, not the *serial number*. To find the Unit ID, you can look either on your device (may vary depending on your device) or in the Garmin Connect app:
 
-```json
-{
-  "profiles": [
-    {
-      "name": "tpv",
-      "app_type": "tp_virtual",
-      "garmin_username": "user@example.com",
-      "garmin_password": "secret",
-      "fitfiles_path": "/path/to/tpv",
-      "manufacturer": 1,
-      "device": 3122,  // Edge 830 (default)
-      "serial_number": 1234567890,
-      "software_version": 975
-    },
-    {
-      "name": "zwift",
-      "app_type": "zwift",
-      "garmin_username": "user@example.com",
-      "garmin_password": "secret",
-      "fitfiles_path": "/path/to/zwift",
-      "manufacturer": 1,
-      "device": 2713,  // Edge 1030
-      "serial_number": 2362467083,
-      "software_version": 2922
-    }
-  ]
-}
-```
+#### Garmin Connect app
 
-### Why Customize Device Simulation?
+<div align="center">
+  <img src="assets/unit_id_android.png" alt="Finding Unit ID on Garmin Connect" width="200" />
+  <p><em>Finding your device's Unit ID in the Garmin Connect Android app</em></p>
+  <p><em>Go to "Devices → [Your Device] → System → About"</em> to see the Unit ID</p>
+</div>
 
-- **Match your actual device**: If you own an Edge 1030, simulate that device (with its serial number) for consistency
-- **Testing**: Try different devices to see how Garmin Connect responds
-- **Feature compatibility**: Some Garmin devices may enable different features in Garmin Connect
+#### On an Edge device
 
-!!! note "Backward Compatibility"
-    Existing profiles without device settings automatically default to Edge 830, maintaining the original behavior prior to v2.1.0.
+<div align="center">
+  <img src="assets/unit_id_edge_1040.jpg" alt="Finding Unit ID on Garmin Device" width="500" />
+  <p><em>Finding your device's Unit ID on an Edge 1040 device</em></p>
+  <p><em>Go to "Menu → System → About → Copyright Info"</em> to see the Unit ID</p>
+</div>
 
-## Usage
+#### Why This Matters
+
+Garmin Connect uses server-side validation to ensure that (so far as we know):
+
+- The device product ID (e.g., Edge 1050, Fenix 8) is legitimate
+- The Unit ID is valid for that specific device type
+- The combination of device ID + Unit ID represents a real device
+
+If the Unit ID doesn't match the device type, Garmin Connect may:
+
+- Not apply Training Effect calculations correctly
+- Not count the activity toward challenges or badges
+- Not update Training Status or training load metrics
+- Display the activity with incorrect device information
+
+#### Recommendations
 
+**Option 1: Use Your Real Garmin Device Unit ID (Recommended)**
 
+If you own a Garmin device and want your activities to count properly for all Garmin Connect features:
+
+1. Find your device's Unit ID:
+     - On the device: Settings → About → Copyright Info → Unit ID
+     - On Garmin Connect: Device settings page
+     - On the device packaging or receipt
+2. During profile setup, choose to customize the serial number
+3. Enter your actual device's Unit ID as the serial number
+4. Select the matching device model (e.g., if you have an Edge 830, select Edge 830)
+
+**Option 2: Accept Limited Functionality**
+
+If you don't own a Garmin device or don't need full Garmin Connect integration:
+
+- The tool will generate a random serial number automatically
+- Activities will upload successfully to Garmin Connect
+- Basic activity data (distance, time, power, heart rate) will display correctly
+- However, advanced features may not work as expected
+
+#### What We Don't Know
+
+The mapping of Unit ID ranges to specific device models is proprietary Garmin information and not publicly documented. This means:
+
+- We cannot automatically generate valid Unit IDs/serial numbers for specific devices
+- Random Unit IDs/serial numbers may or may not be accepted by Garmin Connect
+- The only guaranteed way to ensure full functionality is to use a real device's Unit ID
+
+## Usage
 
 ### Command-line Options
 

diff --git a/fit_file_faker/config.py b/fit_file_faker/config.py
@@ -632,7 +632,7 @@ class Profile:
         fitfiles_path: Path to directory containing FIT files to process
         manufacturer: Manufacturer ID to use for device simulation (defaults to Garmin)
         device: Device/product ID to use for device simulation (defaults to Edge 830)
-        serial_number: Device serial number (auto-generated if not specified)
+        serial_number: Device serial number (should be the device's Unit ID; auto-generated if not specified)
         software_version: Firmware version in FIT format (e.g., 2922 = v29.22). If None,
             no FileCreatorMessage will be added to FIT files.
 
@@ -680,7 +680,7 @@ def __post_init__(self):
         if self.device is None:
             self.device = GarminProduct.EDGE_830.value
 
-        # Generate serial number if not specified
+        # Generate serial number if Unit ID not specified
         if self.serial_number is None:
             import random
 
@@ -1926,12 +1926,15 @@ def create_profile_wizard(self) -> Profile | None:
             if customize_serial:
                 # Show instructions for finding device serial number
                 console.print(
-                    "\n[dim]To find your device's serial number (Unit ID):[/dim]"
+                    '\n[dim]The "serial number" value should be set to your device\'s Unit ID[/dim]'
                 )
+                console.print("\n[dim]To find your device's Unit ID:[/dim]")
                 console.print(
                     "[dim]  On device: Settings → About → Copyright Info → Unit ID[/dim]"
                 )
-                console.print("[dim]  On Garmin Connect: Device settings page[/dim]\n")
+                console.print(
+                    "[dim]  On Garmin Connect (may not work for all devices): Device settings page → System → About[/dim]\n"
+                )
 
                 serial_input = questionary.text(
                     "Enter 10-digit serial number:",
@@ -2235,7 +2238,7 @@ def edit_profile_wizard(self) -> None:
             console.print(
                 "\n[yellow]⚠️  Important:[/yellow] For full Garmin Connect features (Training Effect, "
                 "challenges, badges),\n"
-                "   the serial number should match your actual Garmin device.\n"
+                '   the serial number should match the "Unit ID" of an actual Garmin device.\n'
                 "   Random serial numbers may cause activities to not count properly.\n"
             )
             edit_serial = questionary.confirm(
@@ -2267,13 +2270,14 @@ def edit_profile_wizard(self) -> None:
                 elif serial_choice == "custom":
                     # Show instructions for finding device serial number
                     console.print(
-                        "\n[dim]To find your device's serial number (Unit ID):[/dim]"
+                        '\n[dim]The "serial number" value should be set to your device\'s Unit ID[/dim]'
                     )
+                    console.print("\n[dim]To find your device's Unit ID:[/dim]")
                     console.print(
                         "[dim]  On device: Settings → About → Copyright Info → Unit ID[/dim]"
                     )
                     console.print(
-                        "[dim]  On Garmin Connect: Device settings page[/dim]\n"
+                        "[dim]  On Garmin Connect (may not work for all devices): Device settings page → System → About[/dim]\n"
                     )
 
                     serial_input = questionary.text(