MobileModels/tools/DEVICE_MAPPER_USAGE.md

Device Mapper Usage

This tool builds a cross-platform lookup index from brands/*.md.

1) Build index

python3 tools/device_mapper.py build

Output file: dist/device_index.json

2) Query from command line

python3 tools/device_mapper.py find --name 'iPhone14,5' --brand Apple
python3 tools/device_mapper.py find --name 'M2102J2SC' --brand Xiaomi
python3 tools/device_mapper.py find --name 'L55M5-AD' --brand Xiaomi

3) JSON structure

• records: normalized device records
  • device_name: standard marketing name
  • brand: normalized brand
  • manufacturer_brand: manufacturer-level brand (e.g. Xiaomi)
  • market_brand: market sub-brand (e.g. Xiaomi / Redmi / POCO)
  • device_type: phone | tablet | wear | tv | other
  • aliases: all known searchable aliases
• lookup: normalized alias -> candidate record.id[]
• brand_aliases: normalized brand aliases to filter by app-provided brand
• brand_management: brand governance metadata
  • manufacturer_aliases: canonical brand aliases (华为/huawei/HUAWEI -> HUAWEI)
  • manufacturer_to_parent: child -> parent brand (e.g. OnePlus -> OPPO)
  • parent_to_children: parent -> child brands
  • market_brand_aliases: sub-brand aliases (redmi -> Redmi)
  • stats: includes parent/manufacturer/market-level counts and Xiaomi combined + separated counts

4) App-side integration (iOS / Android / Harmony)

1. Load dist/device_index.json into memory.
2. Normalize input name and optional brand.
3. Use lookup[normalized_name] to fetch candidate records.
4. If brand exists, normalize it by brand_management:
   • manufacturer aliases (e.g. 华为/huawei/HUAWEI -> HUAWEI)
   • market sub-brand aliases (e.g. redmi -> Redmi, xiaomi -> manufacturer-level Xiaomi combined)
5. Filter records by normalized manufacturer/market brand as needed.
6. Return first candidate (or show all candidates when ambiguous).

Normalization rule should match this script:

• lower-case
• keep only [0-9a-z\u4e00-\u9fff]
• remove all spaces, hyphens, underscores and punctuation

5) Device type mapping

Supported categories:

• phone
• tablet
• wear
• tv
• other

Type inference uses keyword + source-file default fallback to reduce misses.