Skip to content

Commit d991cb6

Browse files
kbeaugrandkbeaugrand
committed
Add feature specifications for device import/export, portal settings, device synchronization jobs, metrics collection jobs, and planning command jobs
- Created specifications for device import/export (Feature ID: 021) detailing user stories, acceptance criteria, functional requirements, and success criteria. - Established portal settings specifications (Feature ID: 023) focusing on OIDC configuration, branding, feature flags, and cloud provider identification. - Developed device synchronization jobs specifications (Feature ID: 024) to automate synchronization of devices, edge devices, and AWS IoT Things with acceptance scenarios and requirements. - Introduced metrics collection jobs specifications (Feature ID: 025) for automatic collection of device metrics, Prometheus integration, and telemetry ingestion. - Defined planning command jobs specifications (Feature ID: 026) for automated command execution based on schedules, day-off handling, and layer-based targeting.
1 parent bde8308 commit d991cb6

File tree

15 files changed

+2502
-0
lines changed

15 files changed

+2502
-0
lines changed

‎specs/011-lorawan-commands-management/spec.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Feature Specification: LoRaWAN Commands Management
2+
3+
**Feature ID**: 011
4+
**Feature Branch**: `011-lorawan-commands-management`
5+
**Created**: 2026-02-03
6+
**Status**: Draft
7+
**Source**: Analysis from `specs/011-lorawan-commands-management/analyze.md`
8+
9+
---
10+
11+
## User Scenarios & Testing
12+
13+
### User Story 1 - Define Commands for Device Model (Priority: P1)
14+
15+
As an IoT administrator, I need to define reusable command templates for a LoRaWAN device model so that operators can execute standardized commands on any device using that model without needing to know the technical payload details.
16+
17+
**Why this priority**: This is the foundational capability - without command definitions, no command execution is possible. It enables the entire LoRaWAN remote control workflow.
18+
19+
**Independent Test**: Can be fully tested by creating a device model, defining commands with hex payloads and port numbers, and verifying commands are persisted and retrievable.
20+
21+
**Acceptance Scenarios**:
22+
23+
1. **Given** I have a LoRaWAN device model, **When** I define a new command with name, hex frame payload, and LoRaWAN port, **Then** the command is saved and associated with that model.
24+
2. **Given** a command exists for a device model, **When** I modify the command's frame payload or port, **Then** the changes are persisted.
25+
3. **Given** I provide an invalid hex frame (odd characters, non-hex values, or >255 characters), **When** I attempt to save the command, **Then** validation errors are displayed.
26+
4. **Given** I provide a port outside the valid range (1-223), **When** I attempt to save the command, **Then** a port range error is displayed.
27+
28+
---
29+
30+
### User Story 2 - Execute Command on Device (Priority: P1)
31+
32+
As an IoT operator, I need to execute a defined command on a specific LoRaWAN device so that I can remotely control or configure the device without physical access.
33+
34+
**Why this priority**: Command execution is the primary business value - operators need to remotely control devices for operations, configuration changes, and troubleshooting.
35+
36+
**Independent Test**: Can be fully tested by selecting a device, choosing a command, executing it, and observing success/failure feedback.
37+
38+
**Acceptance Scenarios**:
39+
40+
1. **Given** a device with a model that has defined commands, **When** I select and execute a command, **Then** the command is sent to the device and I receive confirmation.
41+
2. **Given** downlink is disabled on the device model, **When** I attempt to execute a command, **Then** the system prevents execution with an appropriate message.
42+
3. **Given** the LoRa network server is unavailable, **When** I attempt to execute a command, **Then** I receive an error message indicating the failure.
43+
4. **Given** I execute a confirmed command, **When** the device acknowledges receipt, **Then** the confirmation status is displayed.
44+
45+
---
46+
47+
### User Story 3 - View Commands for Device Model (Priority: P2)
48+
49+
As an IoT administrator, I need to view all commands defined for a device model so that I can audit existing configurations and understand available device capabilities.
50+
51+
**Why this priority**: Visibility into existing commands is essential for ongoing management and troubleshooting, but secondary to creation and execution.
52+
53+
**Independent Test**: Can be fully tested by navigating to a device model's command configuration and verifying the complete list is displayed.
54+
55+
**Acceptance Scenarios**:
56+
57+
1. **Given** a device model with multiple commands, **When** I view the model's command configuration, **Then** all commands are listed with their names, ports, and frame previews.
58+
2. **Given** a device model with no commands defined, **When** I view the command configuration, **Then** an empty state message is displayed.
59+
60+
---
61+
62+
### User Story 4 - Manage Built-in Commands (Priority: P3)
63+
64+
As an IoT administrator, I need to understand that certain commands are protected as built-in commands so that I don't accidentally modify critical device functionality.
65+
66+
**Why this priority**: Built-in command protection prevents accidental misconfiguration but is less frequently encountered than general command management.
67+
68+
**Independent Test**: Can be fully tested by attempting to edit or delete a built-in command and verifying the action is blocked.
69+
70+
**Acceptance Scenarios**:
71+
72+
1. **Given** a built-in command exists for a device model, **When** I attempt to edit it, **Then** the edit is prevented and a message explains it's protected.
73+
2. **Given** a built-in command exists, **When** I attempt to delete it, **Then** the deletion is blocked with an explanation.
74+
75+
---
76+
77+
### Edge Cases
78+
79+
- What happens when a device model is deleted that has associated commands? (Commands should be cascade deleted)
80+
- How does the system handle command execution when the device is offline? (Command is queued for delivery when device reconnects)
81+
- What happens if two operators execute different commands on the same device simultaneously? (Both commands are queued and executed in order)
82+
- How are commands handled for devices that have been moved to a different model? (Device inherits new model's commands)
83+
84+
---
85+
86+
## Requirements
87+
88+
### Functional Requirements
89+
90+
- **FR-001**: System MUST allow defining commands for LoRaWAN device models with name, hex frame payload, and LoRaWAN port
91+
- **FR-002**: System MUST validate hex frame payloads contain only valid hexadecimal characters (0-9, A-F) with even character count
92+
- **FR-003**: System MUST validate hex frame payloads do not exceed 255 characters
93+
- **FR-004**: System MUST validate LoRaWAN port is within the valid range (1-223)
94+
- **FR-005**: System MUST support both confirmed and unconfirmed downlink modes for command delivery
95+
- **FR-006**: System MUST encode command payloads to Base64 format for transmission
96+
- **FR-007**: System MUST prevent modification or deletion of built-in commands
97+
- **FR-008**: System MUST only allow command execution on devices whose model has downlink enabled
98+
- **FR-009**: Users MUST be able to view all commands associated with a device model
99+
- **FR-010**: System MUST provide execution feedback indicating success or failure with error details
100+
- **FR-011**: System MUST log all command execution attempts with device ID, command name, and result
101+
102+
### Key Entities
103+
104+
- **DeviceModelCommand**: A command template defined at the model level containing:
105+
- Name (descriptive command identifier)
106+
- Frame (hexadecimal payload data)
107+
- Port (LoRaWAN port number 1-223)
108+
- Confirmed (boolean for delivery confirmation requirement)
109+
- IsBuiltin (boolean for system-protected commands)
110+
- DeviceModelId (association to parent model)
111+
112+
- **Command Execution Request**: Runtime data for executing a command:
113+
- Device identifier (target device)
114+
- Command identifier (which command to execute)
115+
116+
---
117+
118+
## Success Criteria
119+
120+
### Measurable Outcomes
121+
122+
- **SC-001**: Administrators can define a new command for a device model in under 2 minutes
123+
- **SC-002**: Operators can execute a command on a device with confirmation within 5 seconds (network dependent)
124+
- **SC-003**: 95% of command executions complete successfully on first attempt (when device is reachable)
125+
- **SC-004**: Reduce manual on-site device configuration visits by 80% through remote command execution
126+
- **SC-005**: 100% of command execution attempts are logged for audit purposes
127+
128+
---
129+
130+
## Traceability
131+
132+
### Source Analysis
133+
- **Analysis Path**: `specs/011-lorawan-commands-management/analyze.md`
134+
- **Analyzed By**: excavator.specifier
135+
136+
### Code References
137+
- LoRaWANCommandsController: Command CRUD operations
138+
- LoRaWANDevicesController: Command execution endpoint
139+
- LoRaWANCommandService: Business logic for command management
140+
- LoRaWanManagementService: Network server integration
141+
142+
### Dependencies
143+
- **Depends On**:
144+
- 009-lorawan-device-model-management (commands are defined at model level)
145+
- 008-lorawan-device-management (commands are executed on devices)
146+
- **Depended By**:
147+
- 026-planning-command-jobs (scheduled command execution)

‎specs/012-lorawan-frequency-plans/spec.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Feature Specification: LoRaWAN Frequency Plans
2+
3+
**Feature ID**: 012
4+
**Feature Branch**: `012-lorawan-frequency-plans`
5+
**Created**: 2026-02-03
6+
**Status**: Draft
7+
**Source**: Analysis from `specs/012-lorawan-frequency-plans/analyze.md`
8+
9+
---
10+
11+
## User Scenarios & Testing
12+
13+
### User Story 1 - Select Frequency Plan for Concentrator (Priority: P1)
14+
15+
As an IoT administrator, I need to select the appropriate frequency plan when configuring a LoRaWAN concentrator so that the gateway operates on the correct radio frequencies for my geographical region and complies with local regulations.
16+
17+
**Why this priority**: Frequency plan selection is mandatory for concentrator configuration - without it, the gateway cannot communicate with devices. Incorrect frequency selection can cause regulatory violations.
18+
19+
**Independent Test**: Can be fully tested by creating or editing a concentrator, viewing the frequency plan dropdown, selecting a region, and verifying the selection is saved.
20+
21+
**Acceptance Scenarios**:
22+
23+
1. **Given** I am configuring a new concentrator, **When** I access the region/frequency plan field, **Then** I see a dropdown with all supported frequency plans organized by region.
24+
2. **Given** I am in Europe, **When** I select "Europe 863-870 MHz", **Then** the frequency plan is applied to the concentrator configuration.
25+
3. **Given** I am in the United States, **When** I view frequency options, **Then** I see multiple FSB (Frequency Sub-Band) options to choose from.
26+
4. **Given** a concentrator already has a frequency plan, **When** I view its configuration, **Then** the current frequency plan is pre-selected.
27+
28+
---
29+
30+
### User Story 2 - View Available Frequency Plans (Priority: P2)
31+
32+
As an IoT administrator, I need to view all supported frequency plans so that I can plan my LoRaWAN network deployment across multiple regions.
33+
34+
**Why this priority**: Understanding available options helps in network planning, but the primary use case is configuration during concentrator setup.
35+
36+
**Independent Test**: Can be fully tested by accessing the frequency plans endpoint and verifying the complete list is returned.
37+
38+
**Acceptance Scenarios**:
39+
40+
1. **Given** LoRa features are enabled in the portal, **When** I request the frequency plans list, **Then** I receive all 22 supported frequency plans.
41+
2. **Given** I am reviewing frequency plans, **When** I examine the list, **Then** each plan shows a human-readable name and technical identifier.
42+
3. **Given** LoRa features are disabled, **When** I attempt to access frequency plans, **Then** the feature is unavailable with an appropriate message.
43+
44+
---
45+
46+
### Edge Cases
47+
48+
- What happens if a frequency plan is selected but later becomes deprecated? (Existing configurations remain valid; new configurations should warn users)
49+
- How are regional variations handled (e.g., AS923 groups for different Asian countries)? (Multiple sub-plans provided for regional specifics)
50+
- What happens when creating a concentrator in a region without a matching frequency plan? (User must select closest appropriate plan)
51+
52+
---
53+
54+
## Requirements
55+
56+
### Functional Requirements
57+
58+
- **FR-001**: System MUST provide a predefined list of supported LoRaWAN frequency plans
59+
- **FR-002**: System MUST include frequency plans for major global regions:
60+
- Europe (EU 863-870 MHz)
61+
- United States (US 902-928 MHz with FSB options)
62+
- Asia (AS 923-925 MHz with regional groups)
63+
- Australia (AU 915-928 MHz with FSB options)
64+
- China (CN 470-510 MHz with sub-band options)
65+
- **FR-003**: Each frequency plan MUST have a unique identifier and human-readable name
66+
- **FR-004**: System MUST display frequency plans in alphabetical order by name
67+
- **FR-005**: Frequency plan selection MUST be required for concentrator configuration
68+
- **FR-006**: System MUST validate that LoRa features are enabled before providing frequency plan data
69+
- **FR-007**: System MUST persist the selected frequency plan with the concentrator configuration
70+
71+
### Key Entities
72+
73+
- **FrequencyPlan**: Read-only reference data containing:
74+
- FrequencyPlanID (unique technical identifier, e.g., "EU_863_870", "US_902_928_FSB_1")
75+
- Name (human-readable description, e.g., "Europe 863-870 MHz", "United States 902-928 MHz, FSB 1")
76+
77+
### Supported Frequency Plans
78+
79+
| Region | Plans Available |
80+
|--------|----------------|
81+
| Europe | EU_863_870 |
82+
| United States | US_902_928_FSB_1 through FSB_8 |
83+
| Asia | AS_923_925_1 through AS_923_925_4 |
84+
| Australia | AU_915_928_FSB_1 through FSB_8 |
85+
| China | CN_470_510_FSB_1 through FSB_11 |
86+
87+
---
88+
89+
## Success Criteria
90+
91+
### Measurable Outcomes
92+
93+
- **SC-001**: Administrators can identify and select the correct frequency plan within 30 seconds
94+
- **SC-002**: 100% of concentrators have a valid frequency plan configured before activation
95+
- **SC-003**: Zero regulatory compliance issues due to incorrect frequency configuration (when correct plan is selected)
96+
- **SC-004**: Portal supports LoRaWAN deployments across 5+ major geographical regions
97+
98+
---
99+
100+
## Traceability
101+
102+
### Source Analysis
103+
- **Analysis Path**: `specs/012-lorawan-frequency-plans/analyze.md`
104+
- **Analyzed By**: excavator.specifier
105+
106+
### Code References
107+
- LoRaWANFrequencyPlansController: Frequency plan retrieval
108+
- FrequencyPlan DTO: Data structure for frequency plan information
109+
- LoRaFeatureActiveFilter: Feature gate for LoRa functionality
110+
111+
### Dependencies
112+
- **Depends On**:
113+
- Portal configuration (LoRa features must be enabled)
114+
- **Depended By**:
115+
- 010-lorawan-concentrator-management (concentrators require frequency plan selection)

0 commit comments

Comments
 (0)