Bose-SoundTouch/docs/guides/MAC-ADDRESS-MAPPING.md

MAC Address to Serial Number Mapping

Understanding and troubleshooting device identification in SoundTouch service

This guide explains how the SoundTouch service handles device identification through MAC address to serial number mapping, and how to troubleshoot related issues.

📋 Overview

The SoundTouch service uses two different identifiers for devices:

• MAC Address (A81B6A536A98) - Used in HTTP API requests and UPnP discovery
• Serial Number (I6332527703739342000020) - Used for internal file storage

The service automatically maps between these identifiers so that API requests using MAC addresses can access files stored using serial numbers.

🔍 How It Works

Request Flow

1. HTTP Request: GET /streaming/account/3230304/device/A81B6A536A98/presets
2. MAC Resolution: A81B6A536A98 → I6332527703739342000020
3. File Access: accounts/3230304/devices/I6332527703739342000020/Presets.xml

UPnP Discovery Integration

The service extracts MAC addresses from UPnP device descriptions:

<!-- From http://192.168.1.100:8091/XD/BO5EBO5E-F00D-F00D-FEED-A81B6A536A98.xml -->
<root xmlns="urn:schemas-upnp-org:device-1-0">
    <device>
        <friendlyName>Sound Machinery</friendlyName>
        <modelName>SoundTouch 10</modelName>
        <serialNumber>A81B6A536A98</serialNumber>  <!-- MAC address here -->
    </device>
</root>

⚙️ Automatic Setup

The mapping is created automatically when the service starts:

1. Directory Scan: Service scans data/accounts/{account}/devices/{serial}/
2. DeviceInfo.xml: Reads MAC address from each device's info file
3. Mapping Creation: Creates MAC → Serial mapping in memory
4. Normalization: Handles different MAC address formats automatically

🛠️ Supported MAC Address Formats

The service handles all common MAC address formats automatically:

Format	Example	Status
Standard	A81B6A536A98	✅ Supported
Lowercase	a81b6a536a98	✅ Supported
With Colons	A8:1B:6A:53:6A:98	✅ Supported
With Dashes	A8-1B-6A-53-6A-98	✅ Supported
Mixed Case	a81B6a536A98	✅ Supported
With Spaces	A81B6A536A98	✅ Supported

🔧 Troubleshooting

Problem: API requests fail with "file not found" errors

Symptoms:

GET /streaming/account/3230304/device/A81B6A536A98/presets
→ 500 Internal Server Error
→ Log: "open .../devices/A81B6A536A98/Presets.xml: no such file or directory"

Diagnosis:

1. Check if mapping exists:

   # Look for device directory
   ls data/accounts/3230304/devices/
   # Should show serial numbers like: I6332527703739342000020
   

2. Check DeviceInfo.xml:

   cat data/accounts/3230304/devices/I6332527703739342000020/DeviceInfo.xml
   # Look for <macAddress> field
   

Solutions:

Solution 1: Restart the Service

The mapping is created at startup. Simply restart:

sudo systemctl restart soundtouch-service

Solution 2: Check DeviceInfo.xml Format

Ensure the MAC address is present:

<info deviceID="I6332527703739342000020">
    <networkInfo type="SCM">
        <macAddress>A81B6A536A98</macAddress>  <!-- Must be present -->
        <ipAddress>192.168.178.35</ipAddress>
    </networkInfo>
</info>

Solution 3: Manual Device Addition

If the device was added manually, ensure proper structure:

# Create device directory using serial number
mkdir -p data/accounts/3230304/devices/I6332527703739342000020

# Create DeviceInfo.xml with MAC address
cat > data/accounts/3230304/devices/I6332527703739342000020/DeviceInfo.xml << EOF
<?xml version="1.0" encoding="UTF-8"?>
<info deviceID="I6332527703739342000020">
    <name>My SoundTouch Device</name>
    <networkInfo type="SCM">
        <macAddress>A81B6A536A98</macAddress>
        <ipAddress>192.168.1.100</ipAddress>
    </networkInfo>
</info>
EOF

Problem: UPnP discovery not creating mappings

Check UPnP accessibility:

# Test UPnP endpoint directly
curl http://192.168.1.100:8091/XD/BO5EBO5E-F00D-F00D-FEED-A81B6A536A98.xml

# Should return XML with <serialNumber> field

Enable debug logging:

# Check service logs for UPnP activity
journalctl -u soundtouch-service -f | grep UPnP

Problem: Case or format mismatches

This should be handled automatically, but you can verify:

Test different formats:

# All of these should work the same:
curl http://localhost:8000/streaming/account/3230304/device/A81B6A536A98/presets
curl http://localhost:8000/streaming/account/3230304/device/a81b6a536a98/presets
curl http://localhost:8000/streaming/account/3230304/device/A8:1B:6A:53:6A:98/presets

📊 Monitoring and Diagnostics

Check Current Mappings

The service logs mapping creation at startup:

journalctl -u soundtouch-service | grep "MAC.*serial"

Verify File Structure

Ensure proper directory organization:

data/
└── accounts/
    └── 3230304/
        └── devices/
            └── I6332527703739342000020/     # Serial number directory
                ├── DeviceInfo.xml           # Contains MAC address
                ├── Presets.xml
                └── Sources.xml

🔗 Related Documentation

• Device Initial Setup - Setting up new devices
• Troubleshooting Guide - General troubleshooting steps
• SoundTouch Service - Service configuration and management

🏗️ Technical Implementation

For developers interested in the technical details:

Normalization Algorithm

// MAC addresses are normalized by:
// 1. Removing spaces, colons, and dashes
// 2. Converting to uppercase
// Examples:
// "a8:1b:6a:53:6a:98" → "A81B6A536A98"
// "A8-1B-6A-53-6A-98" → "A81B6A536A98"

Lookup Process

// 1. Try exact match first
// 2. If not found, try normalized version
// 3. Return serial number for file access

Performance

• Lookup Time: O(1) - Hash map lookup
• Memory Usage: ~40 bytes per device mapping
• Initialization: Scans all devices once at startup

📝 Best Practices

1. Use Discovery: Let UPnP discovery create mappings automatically
2. Consistent Format: Store MAC addresses consistently in DeviceInfo.xml
3. Service Restart: Restart service after manual device additions
4. Monitoring: Check logs for mapping creation during startup
5. Backup: Keep DeviceInfo.xml files backed up

⚠️ Known Limitations

• Mappings are created only at service startup
• Manual device additions require service restart
• MAC addresses must be present in DeviceInfo.xml
• No automatic cleanup of stale mappings (restart required)