Skip to main content

​
Overview

Device names allow you to assign custom, human-friendly names to devices based on their serial numbers. These names are separate from saved device labels and persist across connections.
Device names are keyed by serial number (for both USB and wireless devices), while saved devices are keyed by IP address (wireless only).

​
GET /api/device-names

Get all custom device names.

​
Response

​
names
object
required
Object mapping device serial numbers to custom names
  • Key: Device serial number
  • Value: Custom name string

​
Example Request

curl http://localhost:3000/api/device-names

const response = await fetch('http://localhost:3000/api/device-names');
const data = await response.json();
console.log(data.names);

​
Example Response

{
  "names": {
    "ABC123456789": "John's Phone",
    "192.168.1.100:5555": "Living Room Tablet",
    "XYZ987654321": "Test Device"
  }
}

​
PUT /api/device-names/:serial

Set or update a custom name for a device.

​
Path Parameters

​
serial
string
required
Device serial number (must be URL-encoded if it contains special characters like :)Examples:
  • USB device: ABC123456789
  • Wireless device: 192.168.1.100:5555 (encode as 192.168.1.100%3A5555)

​
Request Body

​
name
string
required
Custom device name (will be trimmed of whitespace)

​
Response

​
ok
boolean
required
Always returns true

​
Example Request

# USB device
curl -X PUT http://localhost:3000/api/device-names/ABC123456789 \
  -H "Content-Type: application/json" \
  -d '{"name": "Johns Phone"}'

# Wireless device (URL-encode the colon)
curl -X PUT http://localhost:3000/api/device-names/192.168.1.100%3A5555 \
  -H "Content-Type: application/json" \
  -d '{"name": "Living Room Tablet"}'

// USB device
await fetch('http://localhost:3000/api/device-names/ABC123456789', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: "John's Phone" })
});

// Wireless device (JavaScript automatically encodes)
const serial = '192.168.1.100:5555';
await fetch(
  `http://localhost:3000/api/device-names/${encodeURIComponent(serial)}`,
  {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Living Room Tablet' })
  }
);

​
Example Response

{
  "ok": true
}

​
Error Response

Returns 400 if name is missing or empty: 
{
  "error": "El nombre es requerido"
}

​
DELETE /api/device-names/:serial

Remove a custom name for a device.

​
Path Parameters

​
serial
string
required
Device serial number (must be URL-encoded if it contains special characters)

​
Response

​
ok
boolean
required
Always returns true (even if the serial doesn’t exist)

​
Example Request

# USB device
curl -X DELETE http://localhost:3000/api/device-names/ABC123456789

# Wireless device
curl -X DELETE http://localhost:3000/api/device-names/192.168.1.100%3A5555

// USB device
await fetch('http://localhost:3000/api/device-names/ABC123456789', {
  method: 'DELETE'
});

// Wireless device
const serial = '192.168.1.100:5555';
await fetch(
  `http://localhost:3000/api/device-names/${encodeURIComponent(serial)}`,
  { method: 'DELETE' }
);

​
Example Response

{
  "ok": true
}

​
Usage in Device Lists

Custom names are automatically included in device list responses from /api/devices: 
{
  "devices": [
    {
      "serial": "ABC123456789",
      "status": "device",
      "label": "Samsung Galaxy S21",
      "ip": null,
      "wireless": false,
      "customName": "John's Phone"  // ← Custom name appears here
    }
  ]
}
The customName field will be:
  • The custom name if one is set
  • null if no custom name exists

​
UI Implementation Example

// Fetch devices
const { devices } = await fetch('http://localhost:3000/api/devices')
  .then(r => r.json());

devices.forEach(device => {
  // Display custom name if available, otherwise show label
  const displayName = device.customName || device.label;
  console.log(`${displayName} (${device.serial})`);
  
  // Show "Edit name" button
  // On click:
  const newName = prompt('Enter custom name:');
  if (newName) {
    await fetch(
      `http://localhost:3000/api/device-names/${encodeURIComponent(device.serial)}`,
      {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name: newName })
      }
    );
  }
});

​
Difference from Saved Device Labels

​
Device Names (this API)

  • Key: Serial number (USB or wireless)
  • Scope: All devices (USB and wireless)
  • Purpose: Custom names for device identification
  • Appears in: /api/devices response as customName field
  • Storage: device-names.json

​
Saved Device Labels

  • Key: IP address + port
  • Scope: Wireless devices only
  • Purpose: Quick reconnection to wireless devices
  • Appears in: /api/saved-devices response as label field
  • Storage: devices.json

​
Example Scenario

A wireless device at 192.168.1.100:5555 with serial ABC123 can have:
  • Custom name: "John's Phone" (set via /api/device-names/ABC123)
  • Saved device label: "Samsung Galaxy S21" (set via /api/saved-devices)
When the device appears in /api/devices: 
{
  "serial": "ABC123",
  "label": "Samsung Galaxy S21",  // Auto-detected or saved device label
  "customName": "John's Phone",    // Custom name from device-names API
  "wireless": true
}

​
Storage

Device names are stored in:
  • File: device-names.json in the server directory
  • Format: JSON object with serial numbers as keys
  • Persistence: Survives server restarts
  • Cache: Loaded into memory on first access
Example device-names.json: 
{
  "ABC123456789": "John's Phone",
  "192.168.1.100:5555": "Living Room Tablet",
  "XYZ987654321": "Test Device"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us