@devicefarmer/stf-device-db

@devicefarmer/stf-device-db is an open-data smartphone, tablet, and wearable database with deterministic dynamic SVG generation for DeviceFarmer STF.

Data Pipeline & Sources

The database (dist/devices.json) is generated by scripts/build-db.mjs with Node.js's built-in fetch and no native dependencies:

1. Google Play Supported Devices (supported_devices.csv): retail brand, marketing name, device codename and model. Google publishes the list without a stated license, and only these factual identifiers are taken from it.
2. LineageOS Wiki (LineageOS/lineage_wiki): hardware specifications (release, soc, cpu_cores, cpu_freq, ram, storage), read from the repository tarball. Licensed under CC-BY-SA-3.0.
3. Wikidata SPARQL (query.wikidata.org): publication dates (P577) of smartphone and tablet models (wd:Q19723451, wd:Q17517, wd:Q155972). Dedicated to the public domain under CC0.

Coverage

Every model in the Google Play list has a brand and a marketing name, about 45,000 models in all. Hardware specifications come only from LineageOS, so only about 1,400 models (3%), mostly phones LineageOS supports, have cpu and memory, and about 1,450 have a date. For everything else these fields are null; STF fills them from the connected device.

The data is rebuilt monthly by the Update device database workflow, which opens a pull request when the sources change.

Requirements

• Node.js >= 22.12

Building & Testing

To rebuild dist/devices.json from the upstream sources and verify the database:

npm install
npm run build
npm test

Releasing

1. Run the Prepare release workflow with the new version. It bumps package.json, updates CHANGELOG.md and pushes a release/v<version> branch.
2. Open a pull request for that branch, label it ignore-for-release and merge it once the checks pass.
3. Run the Release workflow with the same version. It tags the release, creates the GitHub release and publishes to npm through trusted publishing, with no npm token.

Usage

Install via NPM:

npm install --save @devicefarmer/stf-device-db

find(properties)

Query device metadata by model (primary, case-insensitive), name (codename fallback / disambiguator), and optional brand / manufacturer / platform guards:

const db = require('@devicefarmer/stf-device-db')

const data = db.find({
  model: 'Nexus 5',
  name: 'hammerhead',
  manufacturer: 'LGE'
})

data returns:

{
  name: { id: 'Nexus 5', long: 'LGE Nexus 5' },
  brand: 'LGE',
  marketName: 'Nexus 5',
  date: '2013-10-31',
  cpu: {
    name: 'Qualcomm MSM8974 Snapdragon 800',
    cores: 4,
    freq: 2.26
  },
  memory: {
    ram: 2048, // MB
    rom: 16    // GB
  },
  image: 'Nexus_5.svg'
}

If neither model nor name matches an entry in dist/devices.json (or platform is non-Android, or brand/manufacturer belongs to a conflicting OEM), find() returns null.

sample() & brandsMatch(a, b)

• db.sample() returns a random device record ({ model, name, brand, marketName, date, cpu, memory, image }) from dist/devices.json for test/mock device generation.
• db.brandsMatch(a, b) checks whether two brand/manufacturer strings belong to the same OEM brand family (e.g. Xiaomi/Redmi/POCO, HMD Global/Nokia, Motorola/Lenovo, Nothing/CMF by Nothing).

generateDeviceSvg(params) & getDeviceSvgDataUri(params)

Generate deterministic, form-factor-aware device SVGs (x24, x120, x800) across wearable, foldable-tablet, legacy-16-9, modern-punch-hole, and ultra-tall-21-9 profiles:

const svg = db.generateDeviceSvg({
  model: 'Pixel 9',
  name: 'tokay',
  width: 1080,
  height: 2424,
  xdpi: 422,
  ydpi: 422,
  sdk: 34,
  size: 'x120'
})

const dataUri = db.getDeviceSvgDataUri({ model: 'Pixel 9', size: 'x24' })

Migrating from v1.x to v2.0

• Static JPEG files under dist/icon/* and dist/photo/* (and dist/devices-latest.json) are replaced by dist/devices.json + runtime generateDeviceSvg() / getDeviceSvgDataUri().
• memory.ram remains in MB, while memory.rom is now in GB, matching STF's hardware probe.
• Legacy carrier, maker, os, display, and flags fields from 1.x were replaced by brand, marketName, YYYY-MM-DD date, nullable cpu/memory, and image SVG tokens.

Contributing

See CONTRIBUTING.md.

License

• Data (dist/devices.json): Licensed under CC-BY-SA-4.0, adapted from the LineageOS Wiki (CC-BY-SA-3.0) and Wikidata (CC0).
• Code (index.js, index.d.ts, brands.js, scripts/*, test/*): Licensed under Apache-2.0.

Google Play device identifiers

The brand, marketing name, codename and model of every device come from the Google Play Supported Devices list, which Google publishes without a stated license. They are used deliberately: no openly licensed source maps Android model numbers to marketing names at this scale, and LineageOS alone would cover about 2% of the models. Only these factual identifiers are taken. The CC-BY-SA-4.0 grant covers DeviceFarmer's selection and arrangement of them, not the identifiers themselves, and does not license the Google Play list as a whole.

See LICENSE for full details.