Skip to content

Commit

Permalink
Merge pull request #6753 from TheThingsNetwork/feature/relay-api-shake
Browse files Browse the repository at this point in the history 
Restructure relay API messages
  • Loading branch information
@adriansmares
adriansmares authored Dec 11, 2023
2 parents 16b68eb + 3e607c7 commit 7133999
Show file tree
Hide file tree
Showing 21 changed files with 2,980 additions and 2,748 deletions.
54 changes: 27 additions & 27 deletions api/ttn/lorawan/v3/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -276,11 +276,11 @@
- [Message `MACState.UplinkMessage.RxMetadata.RelayMetadata`](#ttn.lorawan.v3.MACState.UplinkMessage.RxMetadata.RelayMetadata)
- [Message `MACState.UplinkMessage.TxSettings`](#ttn.lorawan.v3.MACState.UplinkMessage.TxSettings)
- [Message `RelayParameters`](#ttn.lorawan.v3.RelayParameters)
- [Message `RelayUplinkForwardingRule`](#ttn.lorawan.v3.RelayUplinkForwardingRule)
- [Message `ResetAndGetEndDeviceRequest`](#ttn.lorawan.v3.ResetAndGetEndDeviceRequest)
- [Message `ServedRelayParameters`](#ttn.lorawan.v3.ServedRelayParameters)
- [Message `ServingRelayForwardingLimits`](#ttn.lorawan.v3.ServingRelayForwardingLimits)
- [Message `ServingRelayParameters`](#ttn.lorawan.v3.ServingRelayParameters)
- [Message `ServingRelayParameters.ForwardingLimits`](#ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits)
- [Message `ServingRelayParameters.UplinkForwardingRule`](#ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule)
- [Message `Session`](#ttn.lorawan.v3.Session)
- [Message `SetEndDeviceRequest`](#ttn.lorawan.v3.SetEndDeviceRequest)
- [Message `UpdateEndDeviceRequest`](#ttn.lorawan.v3.UpdateEndDeviceRequest)
Expand Down Expand Up @@ -4373,6 +4373,21 @@ This is used internally by the Network Server.
| `serving` | [`ServingRelayParameters`](#ttn.lorawan.v3.ServingRelayParameters) | | Parameters related to a relay which is serving end devices. |
| `served` | [`ServedRelayParameters`](#ttn.lorawan.v3.ServedRelayParameters) | | Parameters related to an end device served by a relay. |

### <a name="ttn.lorawan.v3.RelayUplinkForwardingRule">Message `RelayUplinkForwardingRule`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `limits` | [`RelayUplinkForwardLimits`](#ttn.lorawan.v3.RelayUplinkForwardLimits) | | Bucket configuration for the served end device. If unset, no individual limits will apply to the end device, but the relay global limitations will apply. |
| `last_w_f_cnt` | [`uint32`](#uint32) | | Last wake on radio frame counter used by the served end device. |
| `device_id` | [`string`](#string) | | End device identifier of the served end device. |
| `session_key_id` | [`bytes`](#bytes) | | Session key ID of the session keys used to derive the root relay session key. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |

### <a name="ttn.lorawan.v3.ResetAndGetEndDeviceRequest">Message `ResetAndGetEndDeviceRequest`</a>

| Field | Type | Label | Description |
Expand Down Expand Up @@ -4404,25 +4419,7 @@ This is used internally by the Network Server.
| `backoff` | <p>`uint32.lte`: `63`</p> |
| `serving_device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |

### <a name="ttn.lorawan.v3.ServingRelayParameters">Message `ServingRelayParameters`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `second_channel` | [`RelaySecondChannel`](#ttn.lorawan.v3.RelaySecondChannel) | | Second wake on radio channel configuration. |
| `default_channel_index` | [`uint32`](#uint32) | | Index of the default wake on radio channel. |
| `cad_periodicity` | [`RelayCADPeriodicity`](#ttn.lorawan.v3.RelayCADPeriodicity) | | Channel activity detection periodicity. |
| `uplink_forwarding_rules` | [`ServingRelayParameters.UplinkForwardingRule`](#ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule) | repeated | Configured uplink forwarding rules. |
| `limits` | [`ServingRelayParameters.ForwardingLimits`](#ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits) | | Configured forwarding limits. If unset, the default value from Network Server configuration will be used. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `default_channel_index` | <p>`uint32.lte`: `255`</p> |
| `cad_periodicity` | <p>`enum.defined_only`: `true`</p> |
| `uplink_forwarding_rules` | <p>`repeated.max_items`: `16`</p> |

### <a name="ttn.lorawan.v3.ServingRelayParameters.ForwardingLimits">Message `ServingRelayParameters.ForwardingLimits`</a>
### <a name="ttn.lorawan.v3.ServingRelayForwardingLimits">Message `ServingRelayForwardingLimits`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
Expand All @@ -4432,20 +4429,23 @@ This is used internally by the Network Server.
| `uplink_messages` | [`RelayForwardLimits`](#ttn.lorawan.v3.RelayForwardLimits) | | Bucket configuration for uplink messages across all served end devices. If unset, no individual limits will apply to uplink messages across all served end devices, but the relay overall limitations will still apply. |
| `overall` | [`RelayForwardLimits`](#ttn.lorawan.v3.RelayForwardLimits) | | Bucket configuration for all relay messages. If unset, no overall limits will apply to the relay, but individual limitations will still apply. |

### <a name="ttn.lorawan.v3.ServingRelayParameters.UplinkForwardingRule">Message `ServingRelayParameters.UplinkForwardingRule`</a>
### <a name="ttn.lorawan.v3.ServingRelayParameters">Message `ServingRelayParameters`</a>

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| `limits` | [`RelayUplinkForwardLimits`](#ttn.lorawan.v3.RelayUplinkForwardLimits) | | Bucket configuration for the served end device. If unset, no individual limits will apply to the end device, but the relay global limitations will apply. |
| `last_w_f_cnt` | [`uint32`](#uint32) | | Last wake on radio frame counter used by the served end device. |
| `device_id` | [`string`](#string) | | End device identifier of the served end device. |
| `session_key_id` | [`bytes`](#bytes) | | Session key ID of the session keys used to derive the root relay session key. |
| `second_channel` | [`RelaySecondChannel`](#ttn.lorawan.v3.RelaySecondChannel) | | Second wake on radio channel configuration. |
| `default_channel_index` | [`uint32`](#uint32) | | Index of the default wake on radio channel. |
| `cad_periodicity` | [`RelayCADPeriodicity`](#ttn.lorawan.v3.RelayCADPeriodicity) | | Channel activity detection periodicity. |
| `uplink_forwarding_rules` | [`RelayUplinkForwardingRule`](#ttn.lorawan.v3.RelayUplinkForwardingRule) | repeated | Configured uplink forwarding rules. |
| `limits` | [`ServingRelayForwardingLimits`](#ttn.lorawan.v3.ServingRelayForwardingLimits) | | Configured forwarding limits. If unset, the default value from Network Server configuration will be used. |

#### Field Rules

| Field | Validations |
| ----- | ----------- |
| `device_id` | <p>`string.max_len`: `36`</p><p>`string.pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`</p> |
| `default_channel_index` | <p>`uint32.lte`: `255`</p> |
| `cad_periodicity` | <p>`enum.defined_only`: `true`</p> |
| `uplink_forwarding_rules` | <p>`repeated.max_items`: `16`</p> |

### <a name="ttn.lorawan.v3.Session">Message `Session`</a>

Expand Down
100 changes: 50 additions & 50 deletions api/ttn/lorawan/v3/api.swagger.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19323,54 +19323,6 @@
"default": "ENABLED",
"description": " - ENABLED: No restrictions are in place.\n - WARNING: Warnings are being emitted that the provider will be deprecated in the future.\n - DISABLED: New integrations cannot be set up, and old ones do not start."
},
"ServingRelayParametersForwardingLimits": {
"type": "object",
"properties": {
"reset_behavior": {
"$ref": "#/definitions/v3RelayResetLimitCounter",
"description": "Reset behavior of the buckets upon limit update."
},
"join_requests": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for join requests.\nIf unset, no individual limits will apply to join requests, but the relay overall limitations will apply."
},
"notifications": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for unknown device notifications.\nIf unset, no individual limits will apply to unknown end device notifications, but the relay overall\nlimitations will still apply."
},
"uplink_messages": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for uplink messages across all served end devices.\nIf unset, no individual limits will apply to uplink messages across all served end devices, but the relay\noverall limitations will still apply."
},
"overall": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for all relay messages.\nIf unset, no overall limits will apply to the relay, but individual limitations will still apply."
}
}
},
"ServingRelayParametersUplinkForwardingRule": {
"type": "object",
"properties": {
"limits": {
"$ref": "#/definitions/v3RelayUplinkForwardLimits",
"description": "Bucket configuration for the served end device.\nIf unset, no individual limits will apply to the end device, but the relay global limitations will apply."
},
"last_w_f_cnt": {
"type": "integer",
"format": "int64",
"description": "Last wake on radio frame counter used by the served end device."
},
"device_id": {
"type": "string",
"description": "End device identifier of the served end device."
},
"session_key_id": {
"type": "string",
"format": "byte",
"description": "Session key ID of the session keys used to derive the root relay session key."
}
}
},
"TxAcknowledgmentResult": {
"type": "string",
"enum": [
Expand Down Expand Up @@ -25693,6 +25645,29 @@
}
}
},
"v3RelayUplinkForwardingRule": {
"type": "object",
"properties": {
"limits": {
"$ref": "#/definitions/v3RelayUplinkForwardLimits",
"description": "Bucket configuration for the served end device.\nIf unset, no individual limits will apply to the end device, but the relay global limitations will apply."
},
"last_w_f_cnt": {
"type": "integer",
"format": "int64",
"description": "Last wake on radio frame counter used by the served end device."
},
"device_id": {
"type": "string",
"description": "End device identifier of the served end device."
},
"session_key_id": {
"type": "string",
"format": "byte",
"description": "Session key ID of the session keys used to derive the root relay session key."
}
}
},
"v3Right": {
"type": "string",
"enum": [
Expand Down Expand Up @@ -25909,6 +25884,31 @@
}
}
},
"v3ServingRelayForwardingLimits": {
"type": "object",
"properties": {
"reset_behavior": {
"$ref": "#/definitions/v3RelayResetLimitCounter",
"description": "Reset behavior of the buckets upon limit update."
},
"join_requests": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for join requests.\nIf unset, no individual limits will apply to join requests, but the relay overall limitations will apply."
},
"notifications": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for unknown device notifications.\nIf unset, no individual limits will apply to unknown end device notifications, but the relay overall\nlimitations will still apply."
},
"uplink_messages": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for uplink messages across all served end devices.\nIf unset, no individual limits will apply to uplink messages across all served end devices, but the relay\noverall limitations will still apply."
},
"overall": {
"$ref": "#/definitions/v3RelayForwardLimits",
"description": "Bucket configuration for all relay messages.\nIf unset, no overall limits will apply to the relay, but individual limitations will still apply."
}
}
},
"v3ServingRelayParameters": {
"type": "object",
"properties": {
Expand All @@ -25929,12 +25929,12 @@
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/ServingRelayParametersUplinkForwardingRule"
"$ref": "#/definitions/v3RelayUplinkForwardingRule"
},
"description": "Configured uplink forwarding rules."
},
"limits": {
"$ref": "#/definitions/ServingRelayParametersForwardingLimits",
"$ref": "#/definitions/v3ServingRelayForwardingLimits",
"description": "Configured forwarding limits.\nIf unset, the default value from Network Server configuration will be used."
}
}
Expand Down
84 changes: 48 additions & 36 deletions api/ttn/lorawan/v3/end_device.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,52 @@ message BoolValue {
bool value = 1;
}

message ServingRelayForwardingLimits {
option (thethings.flags.message) = {
select: true,
set: true
};

// Reset behavior of the buckets upon limit update.
RelayResetLimitCounter reset_behavior = 1;
// Bucket configuration for join requests.
// If unset, no individual limits will apply to join requests, but the relay overall limitations will apply.
RelayForwardLimits join_requests = 2;
// Bucket configuration for unknown device notifications.
// If unset, no individual limits will apply to unknown end device notifications, but the relay overall
// limitations will still apply.
RelayForwardLimits notifications = 3;
// Bucket configuration for uplink messages across all served end devices.
// If unset, no individual limits will apply to uplink messages across all served end devices, but the relay
// overall limitations will still apply.
RelayForwardLimits uplink_messages = 4;
// Bucket configuration for all relay messages.
// If unset, no overall limits will apply to the relay, but individual limitations will still apply.
RelayForwardLimits overall = 5;
}

message RelayUplinkForwardingRule {
option (thethings.flags.message) = {
select: true,
set: true
};

// Bucket configuration for the served end device.
// If unset, no individual limits will apply to the end device, but the relay global limitations will apply.
RelayUplinkForwardLimits limits = 1;
// Last wake on radio frame counter used by the served end device.
uint32 last_w_f_cnt = 2;

// End device identifier of the served end device.
string device_id = 3 [(validate.rules).string = {
pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
max_len: 36,
ignore_empty: true
}];
// Session key ID of the session keys used to derive the root relay session key.
bytes session_key_id = 4;
}

message ServingRelayParameters {
option (thethings.flags.message) = {
select: true,
Expand All @@ -100,45 +146,11 @@ message ServingRelayParameters {
uint32 default_channel_index = 2 [(validate.rules).uint32.lte = 255];
// Channel activity detection periodicity.
RelayCADPeriodicity cad_periodicity = 3 [(validate.rules).enum.defined_only = true];
message UplinkForwardingRule {
// Bucket configuration for the served end device.
// If unset, no individual limits will apply to the end device, but the relay global limitations will apply.
RelayUplinkForwardLimits limits = 1;
// Last wake on radio frame counter used by the served end device.
uint32 last_w_f_cnt = 2;

// End device identifier of the served end device.
string device_id = 3 [(validate.rules).string = {
pattern: "^[a-z0-9](?:[-]?[a-z0-9]){2,}$",
max_len: 36,
ignore_empty: true
}];
// Session key ID of the session keys used to derive the root relay session key.
bytes session_key_id = 4;
}
// Configured uplink forwarding rules.
repeated UplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
message ForwardingLimits {
// Reset behavior of the buckets upon limit update.
RelayResetLimitCounter reset_behavior = 1;
// Bucket configuration for join requests.
// If unset, no individual limits will apply to join requests, but the relay overall limitations will apply.
RelayForwardLimits join_requests = 2;
// Bucket configuration for unknown device notifications.
// If unset, no individual limits will apply to unknown end device notifications, but the relay overall
// limitations will still apply.
RelayForwardLimits notifications = 3;
// Bucket configuration for uplink messages across all served end devices.
// If unset, no individual limits will apply to uplink messages across all served end devices, but the relay
// overall limitations will still apply.
RelayForwardLimits uplink_messages = 4;
// Bucket configuration for all relay messages.
// If unset, no overall limits will apply to the relay, but individual limitations will still apply.
RelayForwardLimits overall = 5;
}
repeated RelayUplinkForwardingRule uplink_forwarding_rules = 4 [(validate.rules).repeated.max_items = 16];
// Configured forwarding limits.
// If unset, the default value from Network Server configuration will be used.
ForwardingLimits limits = 5;
ServingRelayForwardingLimits limits = 5;
}

message ServedRelayParameters {
Expand Down
2 changes: 1 addition & 1 deletion pkg/networkserver/mac/relay.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ func relayForwardLimitsFields(limits *ttnpb.RelayForwardLimits, prefix string) [
}
}

func relayConfigureForwardLimitsFields(limits *ttnpb.ServingRelayParameters_ForwardingLimits) log.Fielder {
func relayConfigureForwardLimitsFields(limits *ttnpb.ServingRelayForwardingLimits) log.Fielder {
if limits == nil {
return log.Fields()
}
Expand Down
4 changes: 2 additions & 2 deletions pkg/networkserver/mac/relay_configure_fwd_limit.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import (
var (
// defaultRelayForwardingLimits is the default relay forward limits, based on the contents of the
// relay specification.
defaultRelayForwardingLimits = &ttnpb.ServingRelayParameters_ForwardingLimits{
defaultRelayForwardingLimits = &ttnpb.ServingRelayForwardingLimits{
JoinRequests: &ttnpb.RelayForwardLimits{
BucketSize: ttnpb.RelayLimitBucketSize_RELAY_LIMIT_BUCKET_SIZE_2,
ReloadRate: 4,
Expand Down Expand Up @@ -142,7 +142,7 @@ func HandleRelayConfigureFwdLimitAns(
// either of these conditions is not true, the current serving parameters will be nil.
return nil
}
currentServing.Limits = &ttnpb.ServingRelayParameters_ForwardingLimits{
currentServing.Limits = &ttnpb.ServingRelayForwardingLimits{
ResetBehavior: req.ResetLimitCounter,
JoinRequests: req.JoinRequestLimits,
Notifications: req.NotifyLimits,
Expand Down
Loading

0 comments on commit 7133999

Please sign in to comment.