diff --git a/requirements/specifications/networking/networking.md b/requirements/specifications/networking/networking.md index df004830..19ba1a45 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 6a78f8c8..319005b7 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": {