Skip to content

Commit

Permalink
feat: Update networking spec
Browse files Browse the repository at this point in the history
  • Loading branch information
@alkalinecoffee
alkalinecoffee committed Dec 20, 2024
1 parent 2cfae39 commit 0f18875
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 141 deletions.
76 changes: 19 additions & 57 deletions requirements/specifications/networking/networking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,6 @@ As an app, I want to...
- [4.2. Interfaces](#42-interfaces)
- [4.3. IP Properties](#43-ip-properties)
- [4.4. Wifi Status](#44-wifi-status)
- [4.5. Wifi Signal Strength Change Event](#45-wifi-signal-strength-change-event)

## 3. Constants, Types, and Schemas

Expand All @@ -70,9 +69,11 @@ The Firebolt `Network` module **MUST** have an `InterfaceType` enumeration:

The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration:

- `Fast Ethernet`
- `Gibabit Ethernet`
- `10 Gigabit Ethernet`
| Name | Description |
| ------ | -------------------- |
| `FE` | Fast Ethernet |
| `GE` | Gigbabit Ethernet |
| `10GE` | 10 Gigbabit Ethernet |

### 3.4. Wireless Standards

Expand Down Expand Up @@ -117,8 +118,6 @@ This method **MUST** have a corresponding `onStatusChanged` event returning the

The platform **MUST** trigger the event when the device's preferred network interface changes.

The platform **MUST** trigger the event when the device's preferred network interface changes.

The platform **MUST** trigger the event on connection changes to device's preferred network interface (e.g. connect, disconnect, auth failure, wifi out of range, etc).

Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:network:connectionstatus` capability.
Expand All @@ -137,15 +136,14 @@ The `Network` module **MUST** have an `interfaces` method that describes each ne

This method **MUST** return an array of objects with the following properties:

| Property | Type | Description |
| ------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------- |
| `capability` | `Network.EthernetStandard`</br>or `WirelessStandard` | The connection capability of the interface (e.g. `Gibabit Ethernet`, `802.11ac`) |
| `connectionState` | `Network.ConnectionState` | |
| `interfaceName` | `string` | |
| `macAddress` | `string` | |
| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing |
| `type` | `Network.InterfaceType` | The generalized type of interface (e.g. `ethernet` or `wifi`) |
| `wakeOnLanEnabled` | `boolean` | |
| Property | Type | Description |
| ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
| `capability` | `Network.EthernetStandard`</br>or `WirelessStandard` | The connection capability of the interface (e.g. `GE`, `802.11ac`) |
| `connectionState` | `Network.ConnectionState` | |
| `interfaceName` | `string` | |
| `macAddress` | `string` | |
| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing |
| `type` | `Network.InterfaceType` | The generalized type of interface (e.g. `ethernet` or `wifi`) |

If `connectionState` is `disconnected`, `preferred` **MUST** be `false`.

Expand All @@ -162,17 +160,15 @@ Network.interfaces()
//> interfaceName: "wifi0",
//> macAddress: "00:00:00:00:00:00",
//> preferred: false,
//> type: "wifi",
//> wakeOnLanEnabled: true
//> type: "wifi"
//> },
//> {
//> capability: "Gibabit Ethernet",
//> capability: "GE",
//> connectionState: "connected",
//> interfaceName: "eth0",
//> macAddress: "00:00:00:00:00:00",
//> preferred: true,
//> type: "ethernet",
//> wakeOnLanEnabled: true
//> type: "ethernet"
//> },
//> ]
```
Expand All @@ -181,6 +177,8 @@ Network.interfaces()

The `Network` module **MUST** have an `ipProperties` method that returns an object describing the TCP/IP properties of an interface.

The method **MUST** require a `string` parameter denoting the interface name on which the result shall be based.

This method **MUST** return the following properties:

| Property | Type |
Expand All @@ -191,13 +189,11 @@ This method **MUST** return the following properties:
| `ipv6Addresses` | `[]string` |
| `ipv6DNSAddresses` | `[]string` |

The method **MUST** require a `string` parameter denoting the interface name on which the result shall be based.

The values returned in `ipv4Addresses` and `ipv6Addresses` **MUST** be presented in CIDR notation.

If an invalid interface name is provided, a `-40404 / Interface not found` JSON-RPC error **MUST** be returned.

This method **MUST** have a corresponding `onIpPropertiesChanged` event returning the properties listed above to notify listeners of changes to an interface's IP properties.
This method **MUST** have a corresponding `onIpPropertiesChanged` event returning the properties listed above to notify listeners that an interface's IP properties have changed and taken effect.

Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:ipproperties` capability.

Expand Down Expand Up @@ -246,37 +242,3 @@ Network.wifiStatus("wifi0")
//>  ssid: "MyNetwork"
//> }
```

### 4.5. Wifi Signal Strength Change Event

The `Network` module **MUST** have an `onWifiSignalStrengthChange` event to notify listeners of a significant change in the device's wireless connection signal strength.

The method **MUST** support a required `integer` parameter denoting a time interval, in milliseconds, after which the current RSSI is compared to the previous to determine if the signal strength crossed a threshold.

The platform **SHOULD** implement the following thresholds:

| RSSI Threshold (in dBm) | Description |
| ----------------------- | ----------- |
| -50 and higher | Excellent |
| -50 to -60 | Good |
| -60 to -67 | Fair |
| Below -67 | Weak |

This method **MUST** return the following properties:

| Property | Type | Description |
| --------------- | --------- | ---------------------------------------------- |
| `interfaceName` | `string` | |
| `currentValue` | `integer` | Current signal strength / RSSI value (in dBm) |
| `previousValue` | `integer` | Previous signal strength / RSSI value (in dBm) |

Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability.

```javascript
Network.onWifiSignalStrengthChange(10000)
//> {
//>  interfaceName: "wifi0",
//>  currentValue: -60,
//>  previousValue: -50
//> }
```
93 changes: 9 additions & 84 deletions src/openrpc/network.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,17 +98,15 @@
"interfaceName": "wifi0",
"macAddress": "00:00:00:00:00:00",
"preferred": false,
"type": "wifi",
"wakeOnLanEnabled": true
"type": "wifi"
},
{
"capability": "Gibabit Ethernet",
"capability": "GE",
"connectionState": "connected",
"interfaceName": "eth0",
"macAddress": "00:00:00:00:00:01",
"preferred": true,
"type": "ethernet",
"wakeOnLanEnabled": true
"type": "ethernet"
}
]
}
Expand Down Expand Up @@ -149,8 +147,7 @@
"interfaceName": "wifi0",
"macAddress": "00:00:00:00:00:00",
"preferred": true,
"type": "wifi",
"wakeOnLanEnabled": true
"type": "wifi"
}
}
}
Expand Down Expand Up @@ -326,73 +323,6 @@
}
}
]
},
{
"name": "onWifiSignalStrengthChange",
"summary": "Get notified when there's a significant change to the signal strength of the device's wireless connection. For the specified interval, the platform will check for wifi signal strength, and if the difference crosses a specific threshold, the event will fire. Thresholds for firing this event may be operator-specific--please reference the operator's documentation for more information.",
"tags": [
{
"name": "event"
},
{
"name": "capabilities",
"x-uses": [
"xrn:firebolt:capability:network:wifistatus"
]
}
],
"params": [
{
"name": "interval",
"description": "The interval to check the wireless signal, in milliseconds",
"required": true,
"schema": {
"type": "integer"
}
}
],
"result": {
"name": "wifiSignalStrength",
"summary": "The current and previously-checked values of the wireless signal",
"schema": {
"type": "object",
"properties": {
"interfaceName": {
"type": "string"
},
"currentValue": {
"$ref": "https://meta.comcast.com/firebolt/schemas/network#/definitions/SignalStrength"
},
"previousValue": {
"$ref": "https://meta.comcast.com/firebolt/schemas/network#/definitions/SignalStrength"
}
},
"required": [
"interfaceName",
"currentValue",
"previousValue"
]
}
},
"examples": [
{
"name": "Default Example",
"params": [
{
"name": "interval",
"value": 10000
}
],
"result": {
"name": "Default Result",
"value": {
"interfaceName": "wifi0",
"currentValue": -60,
"previousValue": -50
}
}
}
]
}
],
"components": {
Expand All @@ -411,9 +341,9 @@
"description": "Ethernet connection standards",
"type": "string",
"enum": [
"Fast Ethernet",
"Gibabit Ethernet",
"10 Gigabit Ethernet"
"FE",
"GE",
"10GE"
]
},
"InterfaceDetails": {
Expand Down Expand Up @@ -455,10 +385,6 @@
},
"type": {
"$ref": "#/components/schemas/InterfaceType"
},
"wakeOnLanEnabled": {
"type": "boolean",
"description": "Network interface name"
}
},
"required": [
Expand All @@ -467,8 +393,7 @@
"interfaceName",
"macAddress",
"preferred",
"type",
"wakeOnLanEnabled"
"type"
]
},
"InterfaceType": {
Expand Down Expand Up @@ -514,7 +439,7 @@
},
"ipv6DNSAddresses": {
"type": "array",
"description": "IPv6 DNS addresses in CIDR notation",
"description": "IPv6 DNS addresses notation",
"items": {
"type": "string"
}
Expand Down

0 comments on commit 0f18875

Please sign in to comment.