Naming Conventions¶
Public Alias¶
All public-facing documentation uses CanEast as the sanitized alias. No real IPs, hostnames, or ports in the public docs tree. sanitize.py enforces this on every pipeline run.
Node Naming Pattern¶
Pattern: {region}{site}{type}{n}
| Segment | Meaning | Values |
|---|---|---|
| region | Geographic region | cae (Canada East), caw (Canada West), cac (Canada Central) |
| site | Site number | 1, 2, 3... |
| type | Device type | node, mqtt, fw, jmp, ot |
| n | Sequential number | 1, 2, 3... |
Region codes¶
| Code | Region | Current sites |
|---|---|---|
| cae | Canada East | cae1 (primary home), cae2 (future), cae3 (future) |
| caw | Canada West | caw1 (future) |
| cac | Canada Central | future |
Examples: - site1node3 -- site 1, compute node 3 - site1mqtt1 -- site 1, MQTT broker 1 - site1fw1 -- site 1, firewall 1 - site1jmp1 -- site 1, jump box 1
See ADR-0024 for full rationale.
OT Sensor Naming Pattern¶
Pattern: site{cluster}ot{zone}{type}{nn}
Where {type} is a 3-char function code (see ADR OT-0001 for full registry) and {nn} is 2-digit zero-padded.
| Code | Full Name |
|---|---|
| snr | Sensor node (multi-sensor, ESP32 or equivalent) |
| cam | Vision/camera node |
| gwy | Gateway node (protocol bridge, MQTT broker) |
| ctr | Controller node (actuator, relays, valves) |
| dsp | Display node |
| pwr | Power monitor node |
| hvc | HVAC node |
| mtr | Motor/mechanical node |
| aud | Audio node |
| net | Network node |
| sec | Security node |
| env | Environmental node |
| Zone | Location |
|---|---|
| ot-zone | Basement |
| ot-zone | Main floor / garage |
| ot-zone | Outdoor |
| ot-zone | Rack monitoring |
Example: site1ot1snr01 -- cluster 1, basement zone, sensor node 01
See ADR OT-0001 for full rationale and type code registry.
MQTT Topic Structure¶
Pattern: site1/ot{zone}/{type}{nn}/{measurement}
Node-name to topic mapping is deterministic: strip site digit from region prefix, keep zone and type+sequence, join with slashes. Example: site1ot1snr01 → topic prefix site1/ot-zone/snr01/
| Topic | Description |
|---|---|
| site1/ot-zone/snr01/level | Sump pit level in mm (HC-SR04) |
| site1/ot-zone/snr01/flood | Float switch state (0/1) |
| site1/ot-zone/snr01/status | Firmware heartbeat |
| site1/ot-zone/snr01/rssi | WiFi signal strength |
Phase 6 planned (manufacturing QC):
| Topic | Description |
|---|---|
| site1/ot/manufacturing/qc/pass | QC pass event |
| site1/ot/manufacturing/qc/fail | QC fail event |
ADR Numbering¶
| Series | Scope | Current count |
|---|---|---|
| 0001+ | Platform-wide decisions | 0001-0030 |
| OT-0001+ | OT-specific decisions | OT-0001-OT-0006 |
Total: 36 ADRs
Branch Naming¶
| Pattern | Use |
|---|---|
| feature/short-description | New functionality |
| fix/short-description | Bug or config fix |
| docs/short-description | Documentation only |
| hotfix/short-description | Urgent fix -- 24h max lifetime |
| release/ot-x.y.z | OT GitFlow release branches only |
Commit Message Format (Conventional Commits)¶
Pattern: <type>(<scope>): <description>
Types: feat, fix, docs, chore, refactor, test, ci
Examples: - feat(ansible): add common role with NTP and timezone config - fix(esp32): correct HC-SR04 trigger pin assignment - docs(adr): add ADR-0022 ADO consolidation - ci(pipeline): add generate-context step to pipeline