Device Naming Convention Standard
A predictable naming scheme for every device, so voice assistants, dashboards and engineers all speak the same language.
The essentials
- One scheme across every controller, protocol and dashboard
- Voice-assistant friendly by design
- Human-readable in both English and Arabic
- Enforced by an automated linter during deploy
Purpose
Prevent misidentification of devices during operation, maintenance, and voice control.
Scope
Every device, scene, automation and dashboard tile delivered by Smart Citizens.
Design principles
Principle 1
Predictable — a new engineer can guess the name
Principle 2
Speakable — voice assistants can parse it
Principle 3
Unambiguous — no two devices share a name
Principle 4
Localised where safe — Arabic aliases for user-facing names
Engineering requirements
Engineering requirements
- Format Floor.Room.Function.Instance for internal IDs
- Human alias in English AND Arabic for user-facing name
- Function taxonomy drawn from the approved list
- Naming linter must pass before deploy
Best practices
Rooms
Rooms: Use owner's actual room names, not developer plan labels
Functions
Functions: Use the approved verbs (Light, Switch, Curtain, Thermostat, Sensor…)
Aliases
Aliases: 'Living Room Light' before 'GF.LIVING.LIGHT.01'
Installation workflow
Installation workflow
How it works
1. Draft room list
Confirm room names with the owner before install.
Configuration & programming workflow
Configuration & programming workflow
How it works
1. Apply IDs
Assign Floor.Room.Function.Instance IDs during pairing.
2. Apply aliases
Assign English + Arabic aliases in the controller.
3. Run linter
Run the naming linter locally before pushing.
Commissioning steps
Commissioning steps
How it works
1. Voice test
Ask the voice assistant for every alias; confirm the right device responds.
Validation checklist
Validation checklist
- Every device has an English + Arabic alias
- Linter passes with zero errors
- No duplicate names across the site
- Reusing 'Light 1' across rooms
- Skipping Arabic aliases
- Naming devices after brand model numbers
Quality assurance checklist
Alias review
Owner has read and approved the alias list.
Voice pass
Voice assistant addresses at least 20 devices correctly by alias.
Acceptance criteria
| Feature | Target | Verification method | Priority |
|---|---|---|---|
Linter | Zero errors | CI report | High |
Alias completeness | 100% | Portal export | High |
Risk matrix
| Feature | Likelihood | Impact | Mitigation |
|---|---|---|---|
Duplicate name causes wrong actuation | Medium | High | Linter blocks deploy |
Common mistakes & troubleshooting
Troubleshooting tips
How it works
Voice control opens wrong device
Check for duplicate or overly-similar aliases and rename.
Documentation requirements
Documentation requirements
- Naming index CSV
- Alias list (EN + AR)
Maintenance timeline
Maintenance timeline
How it works
On every device add
Update the naming index and re-run the linter.
Version & change log
Version 1.0
Approval status: Approved · Effective date: 2026-01-15 · Last revision: 2026-07-08
Author / Reviewer
Author: Smart Citizens Engineering · Reviewer: Dr. Ashraf Nouri
Change log
v1.0 — 2026-07-08
Initial published edition. (Smart Citizens Engineering)
Frequently asked questions
Frequently asked questions
Can owners rename devices themselves?
Aliases yes; internal IDs no — those are locked behind the engineering role.
Smart Citizens Engineering. "Device Naming Convention Standard." Smart Citizens, 2026-01-15. https://ai.smartcitizens.ae/standards/device-naming-convention-standard.
Smart Citizens Engineering (2026). Device Naming Convention Standard. Smart Citizens. Retrieved 2026-07-23, from https://ai.smartcitizens.ae/standards/device-naming-convention-standard
Design your smart environment with Smart Citizens
Talk to Smart Citizens engineers for a bespoke design, budget estimate, and rollout roadmap.