From 03728f1085efeb4f3c204cdced10624abeeacf34 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Fri, 15 Nov 2024 10:38:54 -0500 Subject: [PATCH 1/9] feat: Add Networking APIs to spec --- .../specifications/networking/networking.md | 273 +++++++++ src/openrpc/network.json | 573 ++++++++++++++++++ src/schemas/network.json | 14 + src/sdks/core/sdk.config.json | 14 +- 4 files changed, 872 insertions(+), 2 deletions(-) create mode 100644 requirements/specifications/networking/networking.md create mode 100644 src/openrpc/network.json create mode 100644 src/schemas/network.json diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md new file mode 100644 index 000000000..df004830e --- /dev/null +++ b/requirements/specifications/networking/networking.md @@ -0,0 +1,273 @@ +# Networking Requirements + +Document Status: Proposed Specification + +See [Firebolt Requirements Governance](../../governance.md) for more info. + +| Contributor | Organization | +| --------------- | -------------- | +| Bart Catrysse | Liberty Global | +| Brian Chow | Sky | +| Jeremy LaCivita | Comcast | +| Joe Martin | Comcast | + +## 1. Overview + +To provide the best experience to users, content partners want to understand details about a device's network connection, such as the device's connection state, connection type, and that connection's performance capabilities. Content partners also want to be notified of key changes to the device's connection, such as connect/disconnect events or IP changes. This data can be used to gauge how those changes may impact the user's experience and react appropriately. + +App partners also have different requirements of what network details are made available to them. For instance, most app partners simply want to know the device's current connection state, type, and be notified of changes to that connection. Other app partners may have more sophisticated needs, requiring access to details on the the configurations of all available network interfaces, including interface MACs, IPs, and wireless connection details. + +This information can be used to gracefully handle cases when the device has poor or no network connectivity, provide valuable data into how the user's network performance is impacting their experience, and to unlock more advanced networking features on the device (such as Wake-on-LAN functionality). + +These APIs will be surfaced in the Firebolt `Network` module. + +### 1.1. User Stories + +As an app, I want to... + +- Get the device's network connection state and connection type +- Get details on each of the device's interfaces, such as name, MAC address, and IP configuration +- Get details on the wireless connection, such as SSID and signal strength +- Be notified of key changes to the device's network connection, such as connection state, TCP/IP configuration, or wireless signal + +## 2. Table of Contents + +- [1. Overview](#1-overview) + - [1.1. User Stories](#11-user-stories) +- [2. Table of Contents](#2-table-of-contents) +- [3. Constants, Types, and Schemas](#3-constants-types-and-schemas) + - [3.1. Connection States](#31-connection-states) + - [3.2. Interface Types](#32-interface-types) + - [3.3 Ethernet Standards](#33-ethernet-standards) + - [3.4. Wireless Standards](#34-wireless-standards) +- [4. Network APIs](#4-network-apis) + - [4.1. Connection Status](#41-connection-status) + - [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 + +### 3.1. Connection States + +The Firebolt `Network` module **MUST** have a `ConnectionState` enumeration: + +- `connected` +- `disconnected` +- `unknown` + +### 3.2. Interface Types + +The Firebolt `Network` module **MUST** have an `InterfaceType` enumeration: + +- `ethernet` +- `wifi` +- `other` +- `unknown` + +### 3.3 Ethernet Standards + +The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration: + +- `Fast Ethernet` +- `Gibabit Ethernet` +- `10 Gigabit Ethernet` + +### 3.4. Wireless Standards + +The Firebolt `Network` module **MUST** have an `WirelessStandard` enumeration: + +| Standard | Description | +| ---------- | ------------- | +| `802.11ac` | | +| `802.11ax` | | +| `802.11be` | | +| `802.11n` | | +| `legacy` | `802.11a/b/g` | + +## 4. Network APIs + +Apps need to get various details about the device's network configuration and capabilities, such as whether the device is connected to a network, what type of connection is used, and details on the network interfaces available on the device. + +Apps also need to be aware of changes to the device's network connection that may occur, either through user-initiated changes or via external factors. + +To facilitate this, the `Network` module will surface methods that provide various details of the device's connection to the local network while also allowing apps to subscribe to various events triggered by key changes to the network connection. + +### 4.1. Connection Status + +The `Network` module **MUST** have a `connectionStatus` method that returns an object describing the device's current network connection status. + +This method **MUST** return the following properties: + +| Property | Type | +| ----------- | --------- | +| `connected` | `boolean` | + +The following properties are **OPTIONAL**: + +| Property | Type | +| -------- | ----------------------- | +| `type` | `Network.InterfaceType` | + +The result **MUST** be based on the device's preferred/default network interface. + +If the device's preferred interface has both an active network connection and valid IP configuration, the `connected` value **MUST** be `true`, otherwise `false` is returned. + +If `connected` is `false`, `type` **MUST NOT** be returned. + +This method **MUST** have a corresponding `onStatusChanged` event returning the properties listed above to notify listeners when any of the properties have changed and taken effect. + +Access to these methods **MUST** require the `use` role of the `xrn:firebolt:capability:network:connectionstatus` capability. + +```javascript +Network.connectionStatus() +//> { +//> "connected": true, +//> "type": "wifi" +//> } +``` + +### 4.2. Interfaces + +The `Network` module **MUST** have an `interfaces` method that describes each network interface on the device. + +This method **MUST** return an array of objects with the following properties: + +| Property | Type | Description | +| ------------------ | -------------------------- | -------------------------------------------------------------------- | +| `connectionState` | `Network.ConnectionState` | | +| `interface` | `string` | Name of the interface (e.g. eth0) | +| `macAddress` | `string` | | +| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing | +| `subtype` | `Network.InterfaceSubtype` | | +| `type` | `Network.InterfaceType` | | +| `wakeOnLanEnabled` | `boolean` | | + +This method **MUST** have a corresponding `onInterfaceChanged` event returning an object with the properties listed above to notify listeners when an interface's properties have changed and taken effect. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:interfaces` capability. + +```javascript +Network.interfaces() +//> [ +//> { +//> connectionState: "disconnected" +//> interface: "wifi0" +//> macAddress: "00:00:00:00:00:00" +//> preferred: false +//> subtype: "802.11ac" +//> type: "wifi" +//> wakeOnLanEnabled: true +//> }, +//> { +//> connectionState: "connected" +//> interface: "eth0" +//> macAddress: "00:00:00:00:00:00" +//> preferred: true +//> subtype: "Gibabit Ethernet" +//> type: "ethernet" +//> wakeOnLanEnabled: true +//> }, +//> ] +``` + +### 4.3. IP Properties + +The `Network` module **MUST** have an `ipProperties` method that returns an object describing the TCP/IP properties of an interface. + +This method **MUST** return the following properties: + +| Property | Type | +| ------------------ | ---------- | +| `interface` | `string` | +| `ipv4Addresses` | `[]string` | +| `ipv4DNSAddresses` | `[]string` | +| `ipv6Addresses` | `[]string` | +| `ipv6DNSAddresses` | `[]string` | + +The method **MUST** require a `string` parameter denoting the interface name on which the result shall be based. + +The `ipv4Addresses` and `ipv6Addresses` values **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. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:ipproperties` capability. + +```javascript +Network.ipProperties("eth0") +//> { +//> interface: "eth0" +//> ipv4Addresses: ["192.168.1.100/24"] +//> ipv4DNSAddresses: ["75.75.75.75"] +//> ipv6Addresses: ["2001:db8:abcd:0012::0/64"] +//> ipv6DNSAddresses: ["2001:558:feed::1"] +//> } +``` + +### 4.4. Wifi Status + +The `Network` module **MUST** have a `wifiStatus` method that returns an object describing an interface's connection status to a wireless network. + +| Property | Type | Description | +| ----------------- | -------------------------- | --------------------------------------- | +| `connectionState` | `Network.ConnectionState` | | +| `interface` | `string` | | +| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | +| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | +| `ssid` | `string` | Wireless network name | + +The method **MUST** support a required `string` parameter denoting the interface name of which the result is based. + +If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. + +If the wireless interface is not connected to a network, the `connectionState` **MUST** return `disconnected`, the `mode` must be `unknown`, `signalStrength` must be `-255` and the `ssid` blank. + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability. + +```javascript +Network.wifiStatus("wifi0") +//> { +//> connectionState: "connected" +//>  interface: "wifi0" +//> mode: "802.11ac" +//>  signalStrength: -50 +//>  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 thresholds may be operator-dependent, but a general guide may be: + +| 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 | +| --------------- | --------- | ------------------------------------- | +| `interface` | `string` | The interface name | +| `currentValue` | `integer` | Current signal strength / RSSI value | +| `previousValue` | `integer` | Previous signal strength / RSSI value | + +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:onwifisignalstrengthchange` capability. + +```javascript +Network.onWifiSignalStrengthChange(10000) +//> { +//>  interface: "wifi0" +//>  currentValue: -60 +//>  previousValue: -50 +//> } +``` diff --git a/src/openrpc/network.json b/src/openrpc/network.json new file mode 100644 index 000000000..6a78f8c89 --- /dev/null +++ b/src/openrpc/network.json @@ -0,0 +1,573 @@ +{ + "openrpc": "1.2.4", + "info": { + "title": "Network", + "description": "A module that surfaces details of the device's network connection, including IP configuration and network capabilities.", + "version": "0.0.0" + }, + "methods": [ + { + "name": "connectionStatus", + "summary": "Get the device's current network connection status. The result is based on the current preferred network interface.", + "params": [], + "tags": [ + { + "name": "property:readonly" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:status" + ] + } + ], + "result": { + "name": "connectionStatus", + "summary": "The current connection status", + "schema": { + "type": "object", + "properties": { + "connected": { + "type": "boolean" + }, + "type": { + "$ref": "#/components/schemas/InterfaceType" + } + }, + "required": [ + "connected" + ] + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": { + "connected": true, + "type": "wifi" + } + } + } + ] + }, + { + "name": "interfaces", + "summary": "Get details of the enabled network interfaces on the device.", + "params": [], + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:interfaces" + ] + } + ], + "result": { + "name": "interfaces", + "summary": "The enabled interfaces on the device", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InterfaceDetails" + } + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": [ + { + "connectionState": "disconnected", + "interface": "wifi0", + "macAddress": "00:00:00:00:00:00", + "preferred": false, + "subtype": "802.11ac", + "type": "wifi", + "wakeOnLanEnabled": true + }, + { + "connectionState": "connected", + "interface": "eth0", + "macAddress": "00:00:00:00:00:01", + "preferred": true, + "subtype": "Gibabit Ethernet", + "type": "ethernet", + "wakeOnLanEnabled": true + } + ] + } + } + ] + }, + { + "name": "onInterfaceChanged", + "summary": "Get notified when the properties of an interface has changed", + "params": [], + "tags": [ + { + "name": "event" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:interfaces" + ] + } + ], + "result": { + "name": "interfaceDetails", + "summary": "The interface that changed", + "schema": { + "$ref": "#/components/schemas/InterfaceDetails" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": { + "connectionState": "connected", + "interface": "wifi0", + "macAddress": "00:00:00:00:00:00", + "preferred": true, + "subtype": "802.11ac", + "type": "wifi", + "wakeOnLanEnabled": true + } + } + } + ] + }, + { + "name": "ipProperties", + "summary": "Get the TCP/IP properties for the provided interface", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:ipproperties" + ] + } + ], + "params": [ + { + "name": "interface", + "description": "The network interface name", + "required": true, + "schema": { + "type": "string" + } + } + ], + "result": { + "name": "ipProperties", + "summary": "The IP properties for the provided interface", + "schema": { + "$ref": "#/components/schemas/IPProperties" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [ + { + "name": "interface", + "value": "eth0" + } + ], + "result": { + "name": "Default Result", + "value": { + "interface": "eth0", + "ipv4Addresses": [ + "192.168.1.100/24" + ], + "ipv4DNSAddresses": [ + "75.75.75.75" + ], + "ipv6Addresses": [ + "2001:db8:abcd:0012::0/64" + ], + "ipv6DNSAddresses": [ + "2001:558:feed::1" + ] + } + } + } + ] + }, + { + "name": "onIpPropertiesChanged", + "summary": "Get notified when the TCP/IP properties for an interface change", + "tags": [ + { + "name": "event" + }, + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:ipproperties" + ] + } + ], + "params": [], + "result": { + "name": "ipProperties", + "summary": "The IP properties for the provided interface", + "schema": { + "$ref": "#/components/schemas/IPProperties" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [], + "result": { + "name": "Default Result", + "value": { + "interface": "eth0", + "ipv4Addresses": [ + "192.168.1.100/24" + ], + "ipv4DNSAddresses": [ + "75.75.75.75" + ], + "ipv6Addresses": [ + "2001:db8:abcd:0012::0/64" + ], + "ipv6DNSAddresses": [ + "2001:558:feed::1" + ] + } + } + } + ] + }, + { + "name": "wifiStatus", + "summary": "Get details on the wireless connection for the provided interface", + "tags": [ + { + "name": "capabilities", + "x-uses": [ + "xrn:firebolt:capability:network:wifistatus" + ] + } + ], + "params": [ + { + "name": "interface", + "description": "The wireless network interface name", + "required": true, + "schema": { + "type": "string" + } + } + ], + "result": { + "name": "wifiStatus", + "summary": "Details on the wireless connection", + "schema": { + "$ref": "#/components/schemas/WifiStatusResult" + } + }, + "examples": [ + { + "name": "Default Example", + "params": [ + { + "name": "interface", + "value": "wifi0" + } + ], + "result": { + "name": "Default Result", + "value": { + "connectionState": "connected", + "interface": "wifi0", + "mode": "802.11ac", + "signalStrength": -60, + "ssid": "MyNetwork" + } + } + } + ] + }, + { + "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:onwifisignalstrengthchange" + ] + } + ], + "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": { + "interface": { + "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": [ + "interface", + "currentValue", + "previousValue" + ] + } + }, + "examples": [ + { + "name": "Default Example", + "params": [ + { + "name": "interval", + "value": 10000 + } + ], + "result": { + "name": "Default Result", + "value": { + "interface": "wifi0", + "currentValue": -60, + "previousValue": -50 + } + } + } + ] + } + ], + "components": { + "schemas": { + "ConnectionState": { + "title": "ConnectionState", + "description": "Network connection states", + "type": "string", + "enum": [ + "connected", + "disconnected" + ] + }, + "EthernetStandard": { + "title": "EthernetStandard", + "description": "Ethernet connection standards", + "type": "string", + "enum": [ + "Fast Ethernet", + "Gibabit Ethernet", + "10 Gigabit Ethernet" + ] + }, + "InterfaceDetails": { + "title": "InterfaceDetails", + "description": "Details of a network interface", + "type": "object", + "properties": { + "connectionState": { + "$ref": "#/components/schemas/ConnectionState" + }, + "interface": { + "type": "string", + "description": "Network interface name" + }, + "macAddress": { + "type": "string", + "description": "Interface MAC address" + }, + "preferred": { + "type": "boolean", + "description": "Whether this is the device's preferred/default interface" + }, + "subtype": { + "$ref": "#/components/schemas/InterfaceSubtype" + }, + "type": { + "$ref": "#/components/schemas/InterfaceType" + }, + "wakeOnLanEnabled": { + "type": "boolean", + "description": "Network interface name" + } + }, + "required": [ + "connectionState", + "interface", + "macAddress", + "preferred", + "subtype", + "type", + "wakeOnLanEnabled" + ] + }, + "InterfaceType": { + "title": "InterfaceType", + "description": "Network interface type", + "type": "string", + "enum": [ + "ethernet", + "wifi", + "other", + "unknown" + ] + }, + "InterfaceSubtype": { + "description": "Network interface subtype", + "anyOf": [ + { + "$ref": "#/components/schemas/EthernetStandard" + }, + { + "$ref": "#/components/schemas/WirelessStandard" + }, + { + "type": "string", + "enum": [ + "other", + "unknown" + ] + } + ] + }, + "IPProperties": { + "title": "IPProperties", + "description": "Details of a network interface", + "type": "object", + "properties": { + "interface": { + "type": "string", + "description": "Network interface name" + }, + "ipv4Addresses": { + "type": "array", + "description": "IPv4 addresses in CIDR notation", + "items": { + "type": "string" + } + }, + "ipv4DNSAddresses": { + "type": "array", + "description": "IPv4 DNS addresses", + "items": { + "type": "string" + } + }, + "ipv6Addresses": { + "type": "array", + "description": "IPv6 addresses in CIDR notation", + "items": { + "type": "string" + } + }, + "ipv6DNSAddresses": { + "type": "array", + "description": "IPv6 DNS addresses in CIDR notation", + "items": { + "type": "string" + } + } + }, + "required": [ + "interface", + "ipv4Addresses", + "ipv4DNSAddresses", + "ipv6Addresses", + "ipv6DNSAddresses" + ] + }, + "NetworkStatusDetails": { + "title": "NetworkStatusDetails", + "description": "Connection status of a network interface", + "type": "object", + "properties": { + "connectionState": { + "$ref": "#/components/schemas/ConnectionState" + }, + "type": { + "$ref": "#/components/schemas/InterfaceType" + } + }, + "required": [ + "connectionState", + "type" + ] + }, + "WifiStatusResult": { + "title": "InterfaceDetails", + "description": "Details of a network interface", + "type": "object", + "properties": { + "connectionState": { + "$ref": "#/components/schemas/ConnectionState" + }, + "interface": { + "type": "string", + "description": "Network interface name" + }, + "mode": { + "$ref": "#/components/schemas/WirelessStandard" + }, + "signalStrength": { + "$ref": "https://meta.comcast.com/firebolt/schemas/network#/definitions/SignalStrength" + }, + "ssid": { + "type": "string", + "description": "The SSID of the connected wireless network", + "maxLength": 32 + } + }, + "required": [ + "connectionState", + "interface", + "mode", + "signalStrength", + "ssid" + ] + }, + "WirelessStandard": { + "title": "WirelessStandard", + "description": "Wireless connection standards", + "type": "string", + "enum": [ + "802.11ac", + "802.11ax", + "802.11be", + "802.11n", + "legacy", + "other" + ] + } + } + } +} diff --git a/src/schemas/network.json b/src/schemas/network.json new file mode 100644 index 000000000..ba10cdbff --- /dev/null +++ b/src/schemas/network.json @@ -0,0 +1,14 @@ +{ + "$id": "https://meta.comcast.com/firebolt/schemas/network", + "title": "Network", + "definitions": { + "SignalStrength": { + "title": "SignalStrength", + "description": "Relative signal strength indicator (RSSI), in dBm", + "type": "integer", + "default": -255, + "minimum": -255, + "maximum": 0 + } + } +} diff --git a/src/sdks/core/sdk.config.json b/src/sdks/core/sdk.config.json index c682afc3b..2dde1126b 100644 --- a/src/sdks/core/sdk.config.json +++ b/src/sdks/core/sdk.config.json @@ -76,7 +76,7 @@ { "module": "Internal", "use": [ - "xrn:firebolt:capability:lifecycle:initialize" + "xrn:firebolt:capability:lifecycle:initialize" ] }, { @@ -111,6 +111,16 @@ "xrn:firebolt:capability:metrics:media" ] }, + { + "module": "Network", + "use": [ + "xrn:firebolt:capability:network:interfaces", + "xrn:firebolt:capability:network:ipproperties", + "xrn:firebolt:capability:network:onwifisignalstrengthchange", + "xrn:firebolt:capability:network:status", + "xrn:firebolt:capability:network:wifistatus" + ] + }, { "module": "Parameters", "use": [ @@ -139,4 +149,4 @@ ] } ] -} \ No newline at end of file +} From 7736abefddbf4b704fe77238b4e1e9cb1750adba Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Mon, 25 Nov 2024 13:19:35 -0500 Subject: [PATCH 2/9] feat: Update networking spec --- .../specifications/networking/networking.md | 109 +++++++++------- src/openrpc/network.json | 119 ++++++++++-------- 2 files changed, 130 insertions(+), 98 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index df004830e..19ba1a453 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -78,7 +78,7 @@ The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration: The Firebolt `Network` module **MUST** have an `WirelessStandard` enumeration: -| Standard | Description | +| Name | Description | | ---------- | ------------- | | `802.11ac` | | | `802.11ax` | | @@ -114,6 +114,8 @@ The result **MUST** be based on the device's preferred/default network interface If the device's preferred interface has both an active network connection and valid IP configuration, the `connected` value **MUST** be `true`, otherwise `false` is returned. +If `connected` is `true`, `type` **MUST** be one of: `ethernet`, `wifi`, or `other`. + If `connected` is `false`, `type` **MUST NOT** be returned. This method **MUST** have a corresponding `onStatusChanged` event returning the properties listed above to notify listeners when any of the properties have changed and taken effect. @@ -134,15 +136,17 @@ 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 | -| ------------------ | -------------------------- | -------------------------------------------------------------------- | -| `connectionState` | `Network.ConnectionState` | | -| `interface` | `string` | Name of the interface (e.g. eth0) | -| `macAddress` | `string` | | -| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing | -| `subtype` | `Network.InterfaceSubtype` | | -| `type` | `Network.InterfaceType` | | -| `wakeOnLanEnabled` | `boolean` | | +| Property | Type | Description | +| ------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------- | +| `capability` | `Network.EthernetStandard`
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` | | + +If `connectionState` is `disconnected`, `preferred` **MUST** be `false`. This method **MUST** have a corresponding `onInterfaceChanged` event returning an object with the properties listed above to notify listeners when an interface's properties have changed and taken effect. @@ -152,21 +156,21 @@ Access to this method **MUST** require the `use` role of the `xrn:firebolt:capab Network.interfaces() //> [ //> { -//> connectionState: "disconnected" -//> interface: "wifi0" -//> macAddress: "00:00:00:00:00:00" -//> preferred: false -//> subtype: "802.11ac" -//> type: "wifi" +//> capability: "802.11ac", +//> connectionState: "disconnected", +//> interfaceName: "wifi0", +//> macAddress: "00:00:00:00:00:00", +//> preferred: false, +//> type: "wifi", //> wakeOnLanEnabled: true //> }, //> { -//> connectionState: "connected" -//> interface: "eth0" -//> macAddress: "00:00:00:00:00:00" -//> preferred: true -//> subtype: "Gibabit Ethernet" -//> type: "ethernet" +//> capability: "Gibabit Ethernet", +//> connectionState: "connected", +//> interfaceName: "eth0", +//> macAddress: "00:00:00:00:00:00", +//> preferred: true, +//> type: "ethernet", //> wakeOnLanEnabled: true //> }, //> ] @@ -180,7 +184,7 @@ This method **MUST** return the following properties: | Property | Type | | ------------------ | ---------- | -| `interface` | `string` | +| `interfaceName` | `string` | | `ipv4Addresses` | `[]string` | | `ipv4DNSAddresses` | `[]string` | | `ipv6Addresses` | `[]string` | @@ -188,7 +192,7 @@ This method **MUST** return the following properties: The method **MUST** require a `string` parameter denoting the interface name on which the result shall be based. -The `ipv4Addresses` and `ipv6Addresses` values **MUST** be presented in CIDR notation. +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. @@ -199,10 +203,10 @@ Access to this method **MUST** require the `use` role of the `xrn:firebolt:capab ```javascript Network.ipProperties("eth0") //> { -//> interface: "eth0" -//> ipv4Addresses: ["192.168.1.100/24"] -//> ipv4DNSAddresses: ["75.75.75.75"] -//> ipv6Addresses: ["2001:db8:abcd:0012::0/64"] +//> interfaceName: "eth0", +//> ipv4Addresses: ["192.168.1.100/24"], +//> ipv4DNSAddresses: ["75.75.75.75"], +//> ipv6Addresses: ["2001:db8:abcd:0012::0/64"], //> ipv6DNSAddresses: ["2001:558:feed::1"] //> } ``` @@ -211,29 +215,38 @@ Network.ipProperties("eth0") The `Network` module **MUST** have a `wifiStatus` method that returns an object describing an interface's connection status to a wireless network. -| Property | Type | Description | -| ----------------- | -------------------------- | --------------------------------------- | -| `connectionState` | `Network.ConnectionState` | | -| `interface` | `string` | | -| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | -| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | -| `ssid` | `string` | Wireless network name | - The method **MUST** support a required `string` parameter denoting the interface name of which the result is based. +This method **MUST** return the following properties: + +| Property | Type | +| ----------------- | ------------------------- | +| `connectionState` | `Network.ConnectionState` | +| `interfaceName` | `string` | + +The following properties are **OPTIONAL**: + +| Property | Type | Description | +| ---------------- | -------------------------- | --------------------------------------- | +| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | +| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | +| `ssid` | `string` | Wireless network name | + If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. -If the wireless interface is not connected to a network, the `connectionState` **MUST** return `disconnected`, the `mode` must be `unknown`, `signalStrength` must be `-255` and the `ssid` blank. +If the wireless interface is not connected to a network, `connectionState` **MUST** be `disconnected`. + +If the wireless interface is not connected to a network, `mode`, `signalStrength` and `ssid` **MUST NOT** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability. ```javascript Network.wifiStatus("wifi0") //> { -//> connectionState: "connected" -//>  interface: "wifi0" -//> mode: "802.11ac" -//>  signalStrength: -50 +//> connectionState: "connected", +//>  interfaceName: "wifi0", +//> mode: "802.11ac", +//>  signalStrength: -50, //>  ssid: "MyNetwork" //> } ``` @@ -255,19 +268,19 @@ The thresholds may be operator-dependent, but a general guide may be: This method **MUST** return the following properties: -| Property | Type | Description | -| --------------- | --------- | ------------------------------------- | -| `interface` | `string` | The interface name | -| `currentValue` | `integer` | Current signal strength / RSSI value | -| `previousValue` | `integer` | Previous signal strength / RSSI value | +| 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:onwifisignalstrengthchange` capability. ```javascript Network.onWifiSignalStrengthChange(10000) //> { -//>  interface: "wifi0" -//>  currentValue: -60 +//>  interfaceName: "wifi0", +//>  currentValue: -60, //>  previousValue: -50 //> } ``` diff --git a/src/openrpc/network.json b/src/openrpc/network.json index 6a78f8c89..319005b7b 100644 --- a/src/openrpc/network.json +++ b/src/openrpc/network.json @@ -50,6 +50,16 @@ "type": "wifi" } } + }, + { + "name": "Example with no network connection", + "params": [], + "result": { + "name": "Default Result", + "value": { + "connected": false + } + } } ] }, @@ -83,20 +93,20 @@ "name": "Default Result", "value": [ { + "capability": "802.11ac", "connectionState": "disconnected", - "interface": "wifi0", + "interfaceName": "wifi0", "macAddress": "00:00:00:00:00:00", "preferred": false, - "subtype": "802.11ac", "type": "wifi", "wakeOnLanEnabled": true }, { + "capability": "Gibabit Ethernet", "connectionState": "connected", - "interface": "eth0", + "interfaceName": "eth0", "macAddress": "00:00:00:00:00:01", "preferred": true, - "subtype": "Gibabit Ethernet", "type": "ethernet", "wakeOnLanEnabled": true } @@ -134,11 +144,11 @@ "result": { "name": "Default Result", "value": { + "capability": "802.11ac", "connectionState": "connected", - "interface": "wifi0", + "interfaceName": "wifi0", "macAddress": "00:00:00:00:00:00", "preferred": true, - "subtype": "802.11ac", "type": "wifi", "wakeOnLanEnabled": true } @@ -159,7 +169,7 @@ ], "params": [ { - "name": "interface", + "name": "interfaceName", "description": "The network interface name", "required": true, "schema": { @@ -179,14 +189,14 @@ "name": "Default Example", "params": [ { - "name": "interface", + "name": "interfaceName", "value": "eth0" } ], "result": { "name": "Default Result", "value": { - "interface": "eth0", + "interfaceName": "eth0", "ipv4Addresses": [ "192.168.1.100/24" ], @@ -233,7 +243,7 @@ "result": { "name": "Default Result", "value": { - "interface": "eth0", + "interfaceName": "eth0", "ipv4Addresses": [ "192.168.1.100/24" ], @@ -264,7 +274,7 @@ ], "params": [ { - "name": "interface", + "name": "interfaceName", "description": "The wireless network interface name", "required": true, "schema": { @@ -284,7 +294,7 @@ "name": "Default Example", "params": [ { - "name": "interface", + "name": "interfaceName", "value": "wifi0" } ], @@ -292,12 +302,28 @@ "name": "Default Result", "value": { "connectionState": "connected", - "interface": "wifi0", + "interfaceName": "wifi0", "mode": "802.11ac", "signalStrength": -60, "ssid": "MyNetwork" } } + }, + { + "name": "Example with no network connection", + "params": [ + { + "name": "interfaceName", + "value": "wifi0" + } + ], + "result": { + "name": "Default Result", + "value": { + "connectionState": "disconnected", + "interfaceName": "wifi0" + } + } } ] }, @@ -331,7 +357,7 @@ "schema": { "type": "object", "properties": { - "interface": { + "interfaceName": { "type": "string" }, "currentValue": { @@ -342,7 +368,7 @@ } }, "required": [ - "interface", + "interfaceName", "currentValue", "previousValue" ] @@ -360,7 +386,7 @@ "result": { "name": "Default Result", "value": { - "interface": "wifi0", + "interfaceName": "wifi0", "currentValue": -60, "previousValue": -50 } @@ -395,10 +421,27 @@ "description": "Details of a network interface", "type": "object", "properties": { + "capability": { + "anyOf": [ + { + "$ref": "#/components/schemas/EthernetStandard" + }, + { + "$ref": "#/components/schemas/WirelessStandard" + }, + { + "type": "string", + "enum": [ + "other", + "unknown" + ] + } + ] + }, "connectionState": { "$ref": "#/components/schemas/ConnectionState" }, - "interface": { + "interfaceName": { "type": "string", "description": "Network interface name" }, @@ -410,9 +453,6 @@ "type": "boolean", "description": "Whether this is the device's preferred/default interface" }, - "subtype": { - "$ref": "#/components/schemas/InterfaceSubtype" - }, "type": { "$ref": "#/components/schemas/InterfaceType" }, @@ -422,11 +462,11 @@ } }, "required": [ + "capability", "connectionState", - "interface", + "interfaceName", "macAddress", "preferred", - "subtype", "type", "wakeOnLanEnabled" ] @@ -442,30 +482,12 @@ "unknown" ] }, - "InterfaceSubtype": { - "description": "Network interface subtype", - "anyOf": [ - { - "$ref": "#/components/schemas/EthernetStandard" - }, - { - "$ref": "#/components/schemas/WirelessStandard" - }, - { - "type": "string", - "enum": [ - "other", - "unknown" - ] - } - ] - }, "IPProperties": { "title": "IPProperties", - "description": "Details of a network interface", + "description": "TCP/IP properties of a network interface", "type": "object", "properties": { - "interface": { + "interfaceName": { "type": "string", "description": "Network interface name" }, @@ -499,7 +521,7 @@ } }, "required": [ - "interface", + "interfaceName", "ipv4Addresses", "ipv4DNSAddresses", "ipv6Addresses", @@ -524,14 +546,14 @@ ] }, "WifiStatusResult": { - "title": "InterfaceDetails", - "description": "Details of a network interface", + "title": "WifiStatusResult", + "description": "Status of a wireless connection", "type": "object", "properties": { "connectionState": { "$ref": "#/components/schemas/ConnectionState" }, - "interface": { + "interfaceName": { "type": "string", "description": "Network interface name" }, @@ -549,10 +571,7 @@ }, "required": [ "connectionState", - "interface", - "mode", - "signalStrength", - "ssid" + "interfaceName" ] }, "WirelessStandard": { From d5ad8a8d6d9296ed397340e14f42eaea439216c4 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Mon, 25 Nov 2024 15:37:14 -0500 Subject: [PATCH 3/9] feat: Update wifi signal event capability --- requirements/specifications/networking/networking.md | 2 +- src/openrpc/network.json | 2 +- src/sdks/core/sdk.config.json | 1 - 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index 19ba1a453..e63072724 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -274,7 +274,7 @@ This method **MUST** return the following properties: | `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:onwifisignalstrengthchange` capability. +Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability. ```javascript Network.onWifiSignalStrengthChange(10000) diff --git a/src/openrpc/network.json b/src/openrpc/network.json index 319005b7b..acebb9b1e 100644 --- a/src/openrpc/network.json +++ b/src/openrpc/network.json @@ -337,7 +337,7 @@ { "name": "capabilities", "x-uses": [ - "xrn:firebolt:capability:network:onwifisignalstrengthchange" + "xrn:firebolt:capability:network:wifistatus" ] } ], diff --git a/src/sdks/core/sdk.config.json b/src/sdks/core/sdk.config.json index 2dde1126b..aeac6125e 100644 --- a/src/sdks/core/sdk.config.json +++ b/src/sdks/core/sdk.config.json @@ -116,7 +116,6 @@ "use": [ "xrn:firebolt:capability:network:interfaces", "xrn:firebolt:capability:network:ipproperties", - "xrn:firebolt:capability:network:onwifisignalstrengthchange", "xrn:firebolt:capability:network:status", "xrn:firebolt:capability:network:wifistatus" ] From 04077fdd343920450a04990c70162dcbc07c75e3 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Tue, 26 Nov 2024 10:42:23 -0500 Subject: [PATCH 4/9] feat: Update networking spec doc --- .../specifications/networking/networking.md | 36 +++++++------------ 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index e63072724..8587d0d40 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -98,17 +98,12 @@ To facilitate this, the `Network` module will surface methods that provide vario The `Network` module **MUST** have a `connectionStatus` method that returns an object describing the device's current network connection status. -This method **MUST** return the following properties: - -| Property | Type | -| ----------- | --------- | -| `connected` | `boolean` | - -The following properties are **OPTIONAL**: +This method **MUST** support returning the following properties: -| Property | Type | -| -------- | ----------------------- | -| `type` | `Network.InterfaceType` | +| Property | Type | Required | +| ----------- | ----------------------- | -------- | +| `connected` | `boolean` | Yes | +| `type` | `Network.InterfaceType` | No | The result **MUST** be based on the device's preferred/default network interface. @@ -217,20 +212,15 @@ The `Network` module **MUST** have a `wifiStatus` method that returns an object The method **MUST** support a required `string` parameter denoting the interface name of which the result is based. -This method **MUST** return the following properties: - -| Property | Type | -| ----------------- | ------------------------- | -| `connectionState` | `Network.ConnectionState` | -| `interfaceName` | `string` | - -The following properties are **OPTIONAL**: +This method **MUST** support returning the following properties: -| Property | Type | Description | -| ---------------- | -------------------------- | --------------------------------------- | -| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | -| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | -| `ssid` | `string` | Wireless network name | +| Property | Type | Description | Required | +| ----------------- | -------------------------- | --------------------------------------- | -------- | +| `connectionState` | `Network.ConnectionState` | | Yes | +| `interfaceName` | `string` | | Yes | +| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | No | +| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | No | +| `ssid` | `string` | Wireless network name | No | If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. From 2cfae394bdc0ad9092054e641a8b91fb54e451b3 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Tue, 26 Nov 2024 12:56:17 -0500 Subject: [PATCH 5/9] feat: Update networking spec doc --- .../specifications/networking/networking.md | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index 8587d0d40..7d46d1438 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -15,7 +15,7 @@ See [Firebolt Requirements Governance](../../governance.md) for more info. To provide the best experience to users, content partners want to understand details about a device's network connection, such as the device's connection state, connection type, and that connection's performance capabilities. Content partners also want to be notified of key changes to the device's connection, such as connect/disconnect events or IP changes. This data can be used to gauge how those changes may impact the user's experience and react appropriately. -App partners also have different requirements of what network details are made available to them. For instance, most app partners simply want to know the device's current connection state, type, and be notified of changes to that connection. Other app partners may have more sophisticated needs, requiring access to details on the the configurations of all available network interfaces, including interface MACs, IPs, and wireless connection details. +App partners also have different requirements of what network details are made available to them.  For instance, most app partners simply want to know the device's current connection state, type, and be notified of changes to that connection.  Other app partners may have more sophisticated needs, requiring access to details on the the configurations of all available network interfaces, including interface MAC addresses, IPs, and interface capabilities. This information can be used to gracefully handle cases when the device has poor or no network connectivity, provide valuable data into how the user's network performance is impacting their experience, and to unlock more advanced networking features on the device (such as Wake-on-LAN functionality). @@ -98,12 +98,12 @@ To facilitate this, the `Network` module will surface methods that provide vario The `Network` module **MUST** have a `connectionStatus` method that returns an object describing the device's current network connection status. -This method **MUST** support returning the following properties: +This method **MUST** support the following properties: -| Property | Type | Required | -| ----------- | ----------------------- | -------- | -| `connected` | `boolean` | Yes | -| `type` | `Network.InterfaceType` | No | +| Property | Type | Required in Response | +| ----------- | ----------------------- | -------------------- | +| `connected` | `boolean` | Yes | +| `type` | `Network.InterfaceType` | No | The result **MUST** be based on the device's preferred/default network interface. @@ -115,6 +115,12 @@ If `connected` is `false`, `type` **MUST NOT** be returned. This method **MUST** have a corresponding `onStatusChanged` event returning the properties listed above to notify listeners when any of the properties have changed and taken effect. +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. ```javascript @@ -212,15 +218,15 @@ The `Network` module **MUST** have a `wifiStatus` method that returns an object The method **MUST** support a required `string` parameter denoting the interface name of which the result is based. -This method **MUST** support returning the following properties: +This method **MUST** support the following properties: -| Property | Type | Description | Required | -| ----------------- | -------------------------- | --------------------------------------- | -------- | -| `connectionState` | `Network.ConnectionState` | | Yes | -| `interfaceName` | `string` | | Yes | -| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | No | -| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | No | -| `ssid` | `string` | Wireless network name | No | +| Property | Type | Description | Required in Response | +| ----------------- | -------------------------- | --------------------------------------- | -------------------- | +| `connectionState` | `Network.ConnectionState` | | Yes | +| `interfaceName` | `string` | | Yes | +| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | No | +| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | No | +| `ssid` | `string` | Wireless network name | No | If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. @@ -247,7 +253,7 @@ The `Network` module **MUST** have an `onWifiSignalStrengthChange` event to noti 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 thresholds may be operator-dependent, but a general guide may be: +The platform **SHOULD** implement the following thresholds: | RSSI Threshold (in dBm) | Description | | ----------------------- | ----------- | From 0f18875e31c5d493e4323c64321b1ac2cdf4be46 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Fri, 20 Dec 2024 16:10:53 -0500 Subject: [PATCH 6/9] feat: Update networking spec --- .../specifications/networking/networking.md | 76 ++++----------- src/openrpc/network.json | 93 ++----------------- 2 files changed, 28 insertions(+), 141 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index 7d46d1438..ec9c4ce3b 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -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 @@ -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 @@ -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. @@ -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`
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`
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`. @@ -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" //> }, //> ] ``` @@ -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 | @@ -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. @@ -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 -//> } -``` diff --git a/src/openrpc/network.json b/src/openrpc/network.json index acebb9b1e..79103f917 100644 --- a/src/openrpc/network.json +++ b/src/openrpc/network.json @@ -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" } ] } @@ -149,8 +147,7 @@ "interfaceName": "wifi0", "macAddress": "00:00:00:00:00:00", "preferred": true, - "type": "wifi", - "wakeOnLanEnabled": true + "type": "wifi" } } } @@ -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": { @@ -411,9 +341,9 @@ "description": "Ethernet connection standards", "type": "string", "enum": [ - "Fast Ethernet", - "Gibabit Ethernet", - "10 Gigabit Ethernet" + "FE", + "GE", + "10GE" ] }, "InterfaceDetails": { @@ -455,10 +385,6 @@ }, "type": { "$ref": "#/components/schemas/InterfaceType" - }, - "wakeOnLanEnabled": { - "type": "boolean", - "description": "Network interface name" } }, "required": [ @@ -467,8 +393,7 @@ "interfaceName", "macAddress", "preferred", - "type", - "wakeOnLanEnabled" + "type" ] }, "InterfaceType": { @@ -514,7 +439,7 @@ }, "ipv6DNSAddresses": { "type": "array", - "description": "IPv6 DNS addresses in CIDR notation", + "description": "IPv6 DNS addresses notation", "items": { "type": "string" } From 5be39a604fc11d7baca68aab6f4aa95b44fdc5eb Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Wed, 8 Jan 2025 14:52:29 -0500 Subject: [PATCH 7/9] fix: Clean up network spec; rename ethernet enum values --- .../specifications/networking/networking.md | 26 +++++++++---------- src/openrpc/network.json | 8 +++--- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index ec9c4ce3b..e77ba7941 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -69,11 +69,11 @@ The Firebolt `Network` module **MUST** have an `InterfaceType` enumeration: The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration: -| Name | Description | -| ------ | -------------------- | -| `FE` | Fast Ethernet | -| `GE` | Gigbabit Ethernet | -| `10GE` | 10 Gigbabit Ethernet | +| Name | +| ---------------------- | +| `Fast Ethernet` | +| `Gigbabit Ethernet` | +| `10 Gigbabit Ethernet` | ### 3.4. Wireless Standards @@ -99,7 +99,7 @@ To facilitate this, the `Network` module will surface methods that provide vario The `Network` module **MUST** have a `connectionStatus` method that returns an object describing the device's current network connection status. -This method **MUST** support the following properties: +This method's response **MUST** support the following properties: | Property | Type | Required in Response | | ----------- | ----------------------- | -------------------- | @@ -108,7 +108,7 @@ This method **MUST** support the following properties: The result **MUST** be based on the device's preferred/default network interface. -If the device's preferred interface has both an active network connection and valid IP configuration, the `connected` value **MUST** be `true`, otherwise `false` is returned. +If the device's preferred interface has both link-layer connectivity and valid IP configuration, the `connected` value **MUST** be `true`, otherwise `false` is returned. If `connected` is `true`, `type` **MUST** be one of: `ethernet`, `wifi`, or `other`. @@ -134,7 +134,7 @@ Network.connectionStatus() The `Network` module **MUST** have an `interfaces` method that describes each network interface on the device. -This method **MUST** return an array of objects with the following properties: +This method's response **MUST** return an array of objects with the following properties for each enabled interface: | Property | Type | Description | | ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | @@ -163,7 +163,7 @@ Network.interfaces() //> type: "wifi" //> }, //> { -//> capability: "GE", +//> capability: "Gigabit Ethernet", //> connectionState: "connected", //> interfaceName: "eth0", //> macAddress: "00:00:00:00:00:00", @@ -179,7 +179,7 @@ The `Network` module **MUST** have an `ipProperties` method that returns an obje 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: +This method's response **MUST** return the following properties: | Property | Type | | ------------------ | ---------- | @@ -214,7 +214,7 @@ The `Network` module **MUST** have a `wifiStatus` method that returns an object The method **MUST** support a required `string` parameter denoting the interface name of which the result is based. -This method **MUST** support the following properties: +This method's response **MUST** support the following properties: | Property | Type | Description | Required in Response | | ----------------- | -------------------------- | --------------------------------------- | -------------------- | @@ -226,9 +226,7 @@ This method **MUST** support the following properties: If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. -If the wireless interface is not connected to a network, `connectionState` **MUST** be `disconnected`. - -If the wireless interface is not connected to a network, `mode`, `signalStrength` and `ssid` **MUST NOT** be returned. +If the wireless interface is not connected to a network, `connectionState` **MUST** be `disconnected`. Additionally, `mode`, `signalStrength` and `ssid` **MUST NOT** be returned. Access to this method **MUST** require the `use` role of the `xrn:firebolt:capability:network:wifistatus` capability. diff --git a/src/openrpc/network.json b/src/openrpc/network.json index 79103f917..5e2cd2588 100644 --- a/src/openrpc/network.json +++ b/src/openrpc/network.json @@ -101,7 +101,7 @@ "type": "wifi" }, { - "capability": "GE", + "capability": "Gigabit Ethernet", "connectionState": "connected", "interfaceName": "eth0", "macAddress": "00:00:00:00:00:01", @@ -341,9 +341,9 @@ "description": "Ethernet connection standards", "type": "string", "enum": [ - "FE", - "GE", - "10GE" + "Fast Ethernet", + "Gigabit Ethernet", + "10 Gigabit Ethernet" ] }, "InterfaceDetails": { From be85c8f3703fc9d89eb73d99460b73773311eda3 Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Fri, 10 Jan 2025 13:27:21 -0500 Subject: [PATCH 8/9] feat: Add bn wireless protocol; update property names --- .../specifications/networking/networking.md | 52 ++++++++++--------- src/openrpc/network.json | 50 +++++++++--------- 2 files changed, 52 insertions(+), 50 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index e77ba7941..abcda6df6 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -79,13 +79,15 @@ The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration: The Firebolt `Network` module **MUST** have an `WirelessStandard` enumeration: -| Name | Description | -| ---------- | ------------- | -| `802.11ac` | | -| `802.11ax` | | -| `802.11be` | | -| `802.11n` | | -| `legacy` | `802.11a/b/g` | +| Name | Description | +| ---------- | ----------- | +| `802.11ac` | WIFI 5 | +| `802.11ax` | WIFI 6/6E | +| `802.11be` | WIFI 7 | +| `802.11bn` | WIFI 8 | +| `802.11n` | WIFI 4 | +| `legacy` | 802.11a/b/g | +| `other` | | ## 4. Network APIs @@ -136,14 +138,14 @@ The `Network` module **MUST** have an `interfaces` method that describes each ne This method's response **MUST** return an array of objects with the following properties for each enabled interface: -| Property | Type | Description | -| ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | -| `capability` | `Network.EthernetStandard`
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`) | +| Property | Type | Description | +| ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `connectionState` | `Network.ConnectionState` | | +| `interfaceName` | `string` | | +| `macAddress` | `string` | | +| `preferred` | `boolean` | Whether the interface is the preferred/default interface for routing | +| `standard` | `Network.EthernetStandard`
or `WirelessStandard` | The physical connection standard supported by the interface (e.g. `Gigbabit Ethernet`, `802.11ac`) | +| `type` | `Network.InterfaceType` | The generalized type of interface (e.g. `ethernet` or `wifi`) | If `connectionState` is `disconnected`, `preferred` **MUST** be `false`. @@ -155,19 +157,19 @@ Access to this method **MUST** require the `use` role of the `xrn:firebolt:capab Network.interfaces() //> [ //> { -//> capability: "802.11ac", //> connectionState: "disconnected", //> interfaceName: "wifi0", //> macAddress: "00:00:00:00:00:00", //> preferred: false, +//> standard: "802.11ac", //> type: "wifi" //> }, //> { -//> capability: "Gigabit Ethernet", //> connectionState: "connected", //> interfaceName: "eth0", //> macAddress: "00:00:00:00:00:00", //> preferred: true, +//> standard: "Gigabit Ethernet", //> type: "ethernet" //> }, //> ] @@ -216,13 +218,13 @@ The method **MUST** support a required `string` parameter denoting the interface This method's response **MUST** support the following properties: -| Property | Type | Description | Required in Response | -| ----------------- | -------------------------- | --------------------------------------- | -------------------- | -| `connectionState` | `Network.ConnectionState` | | Yes | -| `interfaceName` | `string` | | Yes | -| `mode` | `Network.WirelessStandard` | Current wireless mode (e.g. `802.11ac`) | No | -| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | No | -| `ssid` | `string` | Wireless network name | No | +| Property | Type | Description | Required in Response | +| ----------------- | -------------------------- | ------------------------------------------- | -------------------- | +| `connectionState` | `Network.ConnectionState` | | Yes | +| `interfaceName` | `string` | | Yes | +| `protocol` | `Network.WirelessStandard` | Current wireless protocol (e.g. `802.11ac`) | No | +| `signalStrength` | `integer` | Signal strength / RSSI value (in dBm) | No | +| `ssid` | `string` | Wireless network name | No | If no wireless interface matches the provided name, a `-40404 / Wireless interface not found` JSON-RPC error **MUST** be returned. @@ -235,7 +237,7 @@ Network.wifiStatus("wifi0") //> { //> connectionState: "connected", //>  interfaceName: "wifi0", -//> mode: "802.11ac", +//> protocol: "802.11ac", //>  signalStrength: -50, //>  ssid: "MyNetwork" //> } diff --git a/src/openrpc/network.json b/src/openrpc/network.json index 5e2cd2588..c6b4b2bc9 100644 --- a/src/openrpc/network.json +++ b/src/openrpc/network.json @@ -93,19 +93,19 @@ "name": "Default Result", "value": [ { - "capability": "802.11ac", "connectionState": "disconnected", "interfaceName": "wifi0", "macAddress": "00:00:00:00:00:00", "preferred": false, + "standard": "802.11ac", "type": "wifi" }, { - "capability": "Gigabit Ethernet", "connectionState": "connected", "interfaceName": "eth0", "macAddress": "00:00:00:00:00:01", "preferred": true, + "standard": "Gigabit Ethernet", "type": "ethernet" } ] @@ -142,11 +142,11 @@ "result": { "name": "Default Result", "value": { - "capability": "802.11ac", "connectionState": "connected", "interfaceName": "wifi0", "macAddress": "00:00:00:00:00:00", "preferred": true, + "standard": "802.11ac", "type": "wifi" } } @@ -300,7 +300,7 @@ "value": { "connectionState": "connected", "interfaceName": "wifi0", - "mode": "802.11ac", + "protocol": "802.11ac", "signalStrength": -60, "ssid": "MyNetwork" } @@ -351,7 +351,22 @@ "description": "Details of a network interface", "type": "object", "properties": { - "capability": { + "connectionState": { + "$ref": "#/components/schemas/ConnectionState" + }, + "interfaceName": { + "type": "string", + "description": "Network interface name" + }, + "macAddress": { + "type": "string", + "description": "Interface MAC address" + }, + "preferred": { + "type": "boolean", + "description": "Whether this is the device's preferred/default interface" + }, + "standard": { "anyOf": [ { "$ref": "#/components/schemas/EthernetStandard" @@ -368,31 +383,16 @@ } ] }, - "connectionState": { - "$ref": "#/components/schemas/ConnectionState" - }, - "interfaceName": { - "type": "string", - "description": "Network interface name" - }, - "macAddress": { - "type": "string", - "description": "Interface MAC address" - }, - "preferred": { - "type": "boolean", - "description": "Whether this is the device's preferred/default interface" - }, "type": { "$ref": "#/components/schemas/InterfaceType" } }, "required": [ - "capability", "connectionState", "interfaceName", "macAddress", "preferred", + "standard", "type" ] }, @@ -482,7 +482,7 @@ "type": "string", "description": "Network interface name" }, - "mode": { + "protocol": { "$ref": "#/components/schemas/WirelessStandard" }, "signalStrength": { @@ -501,15 +501,15 @@ }, "WirelessStandard": { "title": "WirelessStandard", - "description": "Wireless connection standards", + "description": "Wireless standards", "type": "string", "enum": [ "802.11ac", "802.11ax", "802.11be", + "802.11bn", "802.11n", - "legacy", - "other" + "legacy" ] } } From fa6469860d30be73aa625296b158c3e819756e0a Mon Sep 17 00:00:00 2001 From: alkalinecoffee Date: Thu, 23 Jan 2025 14:01:19 -0500 Subject: [PATCH 9/9] feat: Add clarification to networking spec --- requirements/specifications/networking/networking.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index abcda6df6..73917f3ed 100644 --- a/requirements/specifications/networking/networking.md +++ b/requirements/specifications/networking/networking.md @@ -13,11 +13,11 @@ See [Firebolt Requirements Governance](../../governance.md) for more info. ## 1. Overview -To provide the best experience to users, content partners want to understand details about a device's network connection, such as the device's connection state, connection type, and that connection's performance capabilities. Content partners also want to be notified of key changes to the device's connection, such as connect/disconnect events or IP changes. This data can be used to gauge how those changes may impact the user's experience and react appropriately. +To provide the best experience to users, content partners want to understand details about a device's network connection, such as the device's connection state, connection type, and that connection's performance capabilities. Content partners also want to be notified of key changes to the device's connection, such as connect/disconnect events or IP changes which may be impactful to the user's experience. This data can be used to gauge how those changes impact the user's experience while allowing the app to react appropriately. -App partners also have different requirements of what network details are made available to them.  For instance, most app partners simply want to know the device's current connection state, type, and be notified of changes to that connection.  Other app partners may have more sophisticated needs, requiring access to details on the the configurations of all available network interfaces, including interface MAC addresses, IPs, and interface capabilities. +App partners also have different requirements of what network details are made available to them. While most app partners simply want to know the device's current connection state and to be notified of changes to that connection, other partners have more sophisticated needs, requiring access to the configuration details of all available network interfaces on the device, including interface MAC addresses, IPs, and interface capabilities. -This information can be used to gracefully handle cases when the device has poor or no network connectivity, provide valuable data into how the user's network performance is impacting their experience, and to unlock more advanced networking features on the device (such as Wake-on-LAN functionality). +This information can be used to gracefully handle cases when the device has poor or no network connectivity, provide valuable data into how the user's network performance is impacting their experience, or to support more advanced networking features on the device (such as Wake-on-LAN functionality). These APIs will be surfaced in the Firebolt `Network` module. @@ -28,7 +28,7 @@ As an app, I want to... - Get the device's network connection state and connection type - Get details on each of the device's interfaces, such as name, MAC address, and IP configuration - Get details on the wireless connection, such as SSID and signal strength -- Be notified of key changes to the device's network connection, such as connection state, TCP/IP configuration, or wireless signal +- Be notified of key changes to the device's network connection, such as connection state or TCP/IP configuration ## 2. Table of Contents @@ -38,7 +38,7 @@ As an app, I want to... - [3. Constants, Types, and Schemas](#3-constants-types-and-schemas) - [3.1. Connection States](#31-connection-states) - [3.2. Interface Types](#32-interface-types) - - [3.3 Ethernet Standards](#33-ethernet-standards) + - [3.3. Ethernet Standards](#33-ethernet-standards) - [3.4. Wireless Standards](#34-wireless-standards) - [4. Network APIs](#4-network-apis) - [4.1. Connection Status](#41-connection-status) @@ -65,7 +65,7 @@ The Firebolt `Network` module **MUST** have an `InterfaceType` enumeration: - `other` - `unknown` -### 3.3 Ethernet Standards +### 3.3. Ethernet Standards The Firebolt `Network` module **MUST** have an `EthernetStandard` enumeration: