Programming Standard
Conventions for writing scenes, automations and gateway logic in a way that stays maintainable years later.
The essentials
- One convention across every controller and gateway family
- Every automation must be commented
- Version-control mandatory for gateway configuration
- Safe defaults for every actuator (fail-off, fail-closed)
Purpose
Make every Smart Citizens configuration understandable to any engineer on the team without tribal knowledge.
Scope
Applies to all scenes, automations, gateway rules, dashboards and touch-panel layouts delivered by Smart Citizens.
Design principles
Principle 1
Readable first — clarity over cleverness
Principle 2
Deterministic — same trigger, same outcome, every time
Principle 3
Fail-safe — actuators return to a defined state on error
Principle 4
Reversible — every automation can be disabled in one click
Engineering requirements
Engineering requirements
- Configuration stored in Smart Citizens Git repo per site
- Semantic versioning on every gateway config bundle
- Comments on every automation describing intent + owner
- No hard-coded credentials; secrets injected at deploy time
- Every scene has a documented rollback
Best practices
Naming
Naming: Scenes use verb-noun ('Dim Living to 30%')
Grouping
Grouping: Automations grouped by subsystem, not room
Testing
Testing: Every automation gets a unit-style dry run
Review
Review: Every merge requires a second engineer review
Installation workflow
Installation workflow
How it works
1. Repo bootstrap
Clone the Smart Citizens site template and set project variables.
2. Base scenes
Import the standard scene library and localise names.
Configuration & programming workflow
Configuration & programming workflow
How it works
1. Author
Write scenes and automations in the editor per naming rules.
2. Comment
Add intent + owner + date to every automation header.
3. Peer review
Second engineer reviews and approves the pull request.
4. Deploy
Bundle is tagged, signed and deployed to the site controller.
5. Verify
Verify checksum on the controller matches the tag.
Commissioning steps
Commissioning steps
How it works
1. Dry run
Trigger every new automation manually and confirm expected behaviour.
2. Idle observation
Watch the system for 30 min for unintended triggers.
3. Rollback drill
Roll back to previous tag and confirm state.
Validation checklist
Validation checklist
- All configuration in version control
- Every automation has a comment header
- Rollback tag exists and is documented
- No hard-coded secrets in the bundle
- Un-commented automations
- Configuration edited directly on the controller
- Hard-coded API tokens
- Merges without peer review
Quality assurance checklist
Naming audit
Random 20% of scenes match the naming convention.
Comment coverage
100% of automations have a comment header.
Rollback tested
Rollback drill has been executed at least once.
Acceptance criteria
| Feature | Target | Verification method | Priority |
|---|---|---|---|
Version-controlled bundle | 100% | Git log | High |
Peer review | 100% of merges | Repository review record | High |
Rollback rehearsed | Once per site | Commissioning report | Medium |
Risk matrix
| Feature | Likelihood | Impact | Mitigation |
|---|---|---|---|
Un-reviewed hot fix | Medium | High | Emergency merge requires second engineer within 24 h |
Secret leaked in repo | Low | High | Pre-commit secret scanning; secrets injected at deploy |
Common mistakes & troubleshooting
Troubleshooting tips
How it works
Unexpected trigger
Search the repo for automations bound to overlapping conditions.
Rollback fails
Verify the previous tag exists and controller has the target firmware.
Documentation requirements
Documentation requirements
- Repository README per site
- Scene catalogue
- Automation index
- Rollback runbook
Maintenance timeline
Maintenance timeline
How it works
Monthly
Review automation trigger counts; deprecate unused rules.
Quarterly
Refresh secrets and rotate deploy keys.
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
Which VCS do you use?
Git, on the Smart Citizens engineering GitHub organisation, one private repo per site.
How are secrets managed?
Secrets are stored in the Smart Citizens vault and injected at deploy time; never committed to the repo.
Smart Citizens Engineering. "Programming Standard." Smart Citizens, 2026-01-15. https://ai.smartcitizens.ae/standards/programming-standard.
Smart Citizens Engineering (2026). Programming Standard. Smart Citizens. Retrieved 2026-07-23, from https://ai.smartcitizens.ae/standards/programming-standard
Design your smart environment with Smart Citizens
Talk to Smart Citizens engineers for a bespoke design, budget estimate, and rollout roadmap.