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

HTTP Request: GET /streaming/account/3230304/device/A81B6A536A98/presets
MAC Resolution: A81B6A536A98 → I6332527703739342000020
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:

Directory Scan: Service scans data/accounts/{account}/devices/{serial}/
DeviceInfo.xml: Reads MAC address from each device’s info file
Mapping Creation: Creates MAC → Serial mapping in memory
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:

Check if mapping exists:

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

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

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

Use Discovery: Let UPnP discovery create mappings automatically
Consistent Format: Store MAC addresses consistently in DeviceInfo.xml
Service Restart: Restart service after manual device additions
Monitoring: Check logs for mapping creation during startup
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)