mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-10 10:56:28 +00:00
New network API doc (#721)
* New network API doc * Apply suggestions from code review Co-authored-by: Joakim Sørensen <joasoe@gmail.com> Co-authored-by: Franck Nijhof <git@frenck.dev> * Add VLAN payload * Update docs/api/supervisor/endpoints.md Co-authored-by: Joakim Sørensen <joasoe@gmail.com> * Apply suggestions from code review Co-authored-by: Joakim Sørensen <joasoe@gmail.com> Co-authored-by: Joakim Sørensen <joasoe@gmail.com> Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
Pascal Vizeli
GitHub
parent
8d282edc8c
commit
ea486b226d
@ -1404,25 +1404,31 @@ Get network information.
|
|||||||
|
|
||||||
| key | description |
|
| key | description |
|
||||||
| ---------- | ---------------------------------------------------------------------- |
|
| ---------- | ---------------------------------------------------------------------- |
|
||||||
| interfaces | A dictionary of [Network interface models](api/supervisor/models.md#network-interface) |
|
| interfaces | A list of [Network interface models](api/supervisor/models.md#network-interface) |
|
||||||
| docker | Information about the internal docker network |
|
| docker | Information about the internal docker network |
|
||||||
|
|
||||||
**Example response:**
|
**Example response:**
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"interfaces": {
|
"interfaces": [
|
||||||
"eth0": {
|
{
|
||||||
"interface": "eth0",
|
"interface": "eth0",
|
||||||
"ip_address": "192.168.1.100/24",
|
"type": "ethernet",
|
||||||
"gateway": "192.168.1.1",
|
"primary": true,
|
||||||
"id": "Wired connection 1",
|
"enabled": true,
|
||||||
"type": "802-3-ethernet",
|
"connected": true,
|
||||||
"nameservers": ["192.168.1.1"],
|
"ipv4": {
|
||||||
"method": "static",
|
"method": "static",
|
||||||
"primary": true
|
"ip_address": "192.168.1.100/24",
|
||||||
|
"gateway": "192.168.1.1",
|
||||||
|
"nameservers": ["192.168.1.1"],
|
||||||
|
},
|
||||||
|
"ipv6": null,
|
||||||
|
"wifi": null,
|
||||||
|
"vlan": null,
|
||||||
}
|
}
|
||||||
},
|
],
|
||||||
"docker": {
|
"docker": {
|
||||||
"interface": "hassio",
|
"interface": "hassio",
|
||||||
"address": "172.30.32.0/23",
|
"address": "172.30.32.0/23",
|
||||||
@ -1434,49 +1440,89 @@ Get network information.
|
|||||||
|
|
||||||
</ApiEndpoint>
|
</ApiEndpoint>
|
||||||
|
|
||||||
<ApiEndpoint path="/network/<interface>/info" method="get">
|
<ApiEndpoint path="/network/interface/<interface>/info" method="get">
|
||||||
|
|
||||||
Returns a [Network interface model](api/supervisor/models.md#network-interface) for a specific network interface.
|
Returns a [Network interface model](api/supervisor/models.md#network-interface) for a specific network interface.
|
||||||
|
|
||||||
</ApiEndpoint>
|
</ApiEndpoint>
|
||||||
|
|
||||||
<ApiEndpoint path="/network/<interface>/update" method="post">
|
<ApiEndpoint path="/network/interface/<interface>/update" method="post">
|
||||||
|
|
||||||
Update the settings for a network interface.
|
Update the settings for a network interface.
|
||||||
|
|
||||||
**Payload:**
|
**Payload:**
|
||||||
|
|
||||||
| key | type | optional | description |
|
| key | type | optional | description |
|
||||||
| ------- | ------ | -------- | ---------------------------------------------------------------------- |
|
| ------- | ------ | -------- | ---------------------------------------------------------------------- |
|
||||||
| address | string | True | The new IP address for the interface in the X.X.X.X/XX format |
|
| enabled | bool | True | Enable/Disable an ethernet interface / VLAN got removed with disabled |
|
||||||
| dns | list | True | List of DNS servers to use |
|
| ipv4 | dict | True | A struct with ipv4 interface settings |
|
||||||
| gateway | string | True | The gateway the interface should use |
|
| ipv6 | dict | True | A struct with ipv6 interface settings |
|
||||||
| method | string | True | Set if the interface should use DHCP or not, can be `dhcp` or `static` |
|
| wifi | dict | True | A struct with Wireless connection settings |
|
||||||
|
|
||||||
**You need to supply at least one key in the payload.**
|
**ipv4 / ipv6:**
|
||||||
|
|
||||||
:::warning
|
| key | type | optional | description |
|
||||||
If you change the `address` or `gateway` you may need to reconnect to the new address
|
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
|
||||||
:::
|
| method | string | True | Set if the interface should use DHCP or not, can be `dhcp`, `static` or `disabled` |
|
||||||
|
| address | list | True | The new IP address for the interface in the X.X.X.X/XX format as list |
|
||||||
|
| nameservers | list | True | List of DNS servers to use |
|
||||||
|
| gateway | string | True | The gateway the interface should use |
|
||||||
|
|
||||||
When the call is complete it returns the changed [Network interface model](api/supervisor/models.md#network-interface).
|
**wifi:**
|
||||||
|
|
||||||
|
| key | type | optional | description |
|
||||||
|
| ------ | ------ | -------- | ------------------------------------------------------------------------------ |
|
||||||
|
| mode | string | True | Set the mode `infrastructure` (default), `mesh`, `adhoc` or `ap` |
|
||||||
|
| auth | string | True | Set the auth mode: `open` (default), `web`, `wpa-psk` |
|
||||||
|
| ssid | string | True | Set the SSID for connect into |
|
||||||
|
| psk | string | True | The shared key which is used with `web` or `wpa-psk` |
|
||||||
|
|
||||||
|
</ApiEndpoint>
|
||||||
|
|
||||||
|
<ApiEndpoint path="/network/interface/<interface>/accesspoints" method="get">
|
||||||
|
|
||||||
|
Return a list of available [Access Points](api/supervisor/models.md#access-points) on this Wireless interface.
|
||||||
|
|
||||||
|
**This function only works with Wireless interfaces!**
|
||||||
|
|
||||||
|
**Returned data:**
|
||||||
|
|
||||||
|
| key | description |
|
||||||
|
| ------------ | ---------------------------------------------------------------------- |
|
||||||
|
| accesspoints | A list of [Access Points](api/supervisor/models.md#access-points) |
|
||||||
|
|
||||||
**Example response:**
|
**Example response:**
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"ip_address": "192.168.1.100/24",
|
"accesspoints": [
|
||||||
"gateway": "192.168.1.1",
|
{
|
||||||
"id": "Wired connection 1",
|
"mode": "infrastructure",
|
||||||
"type": "802-3-ethernet",
|
"ssid": "MY_TestWifi",
|
||||||
"nameservers": ["192.168.1.1"],
|
"mac": "00:00:00:00",
|
||||||
"method": "static",
|
"frequency": 24675,
|
||||||
"primary": true
|
"signal": 90
|
||||||
|
}
|
||||||
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
</ApiEndpoint>
|
</ApiEndpoint>
|
||||||
|
|
||||||
|
<ApiEndpoint path="/network/interface/<interface>/vlan/<id>" method="post">
|
||||||
|
|
||||||
|
Create a new VLAN *id* on this network interface.
|
||||||
|
|
||||||
|
**This function only works with ethernet interfaces!**
|
||||||
|
|
||||||
|
**Payload:**
|
||||||
|
|
||||||
|
| key | type | optional | description |
|
||||||
|
| ------- | ------ | -------- | ---------------------------------------------------------------------- |
|
||||||
|
| ipv4 | dict | True | A struct with ipv4 interface settings |
|
||||||
|
| ipv6 | dict | True | A struct with ipv6 interface settings |
|
||||||
|
|
||||||
|
</ApiEndpoint>
|
||||||
|
|
||||||
### Observer
|
### Observer
|
||||||
|
|
||||||
<ApiEndpoint path="/observer/info" method="get">
|
<ApiEndpoint path="/observer/info" method="get">
|
||||||
|
|||||||
@ -95,13 +95,49 @@ These models are describing objects that are getting returned from the superviso
|
|||||||
| key | type | description |
|
| key | type | description |
|
||||||
| ----------- | ------- | ---------------------------------------------------------------------------- |
|
| ----------- | ------- | ---------------------------------------------------------------------------- |
|
||||||
| interface | string | The interface name i.e eth0. |
|
| interface | string | The interface name i.e eth0. |
|
||||||
| ip_address | string | The IP address and the netmask in a X.X.X.X/XX format. |
|
| type | string | The interface type: `ethernet`, `wireless` or `vlan`. |
|
||||||
| gateway | string | The IP address of the gateway. |
|
| enabled | boolean | Return True if the interface is enabled. |
|
||||||
| id | string | The ID of the interface. |
|
| connected | boolean | Return True if the interface is connected to the network. |
|
||||||
| type | string | The interface type. |
|
|
||||||
| nameservers | list | A list containing the IP addresses of the configured nameservers as strings. |
|
|
||||||
| method | string | The method used to set the IP can be "static" or "dhcp". |
|
|
||||||
| primary | boolean | `true` if it's the primary network interface. |
|
| primary | boolean | `true` if it's the primary network interface. |
|
||||||
|
| ipv4 | struct or null | An IP config struct with IPv4 connection details. |
|
||||||
|
| ipv6 | struct or null | An IP config struct with IPv6 connection details. |
|
||||||
|
| wifi | struct or null | An Wifi config struct with wireless connection details. |
|
||||||
|
| vlan | struct or null | An Vlan config struct with details about the vlan. |
|
||||||
|
|
||||||
|
### IP configuration
|
||||||
|
|
||||||
|
| key | type | description |
|
||||||
|
| ----------- | ------- | ---------------------------------------------------------------------------- |
|
||||||
|
| method | string | The method used to set the IP can be `static`, `dhcp` or `disabled`. |
|
||||||
|
| address | list | A list with IP address and the netmask in a X.X.X.X/XX format. |
|
||||||
|
| gateway | string | The IP address of the gateway. |
|
||||||
|
| nameservers | list | A list containing the IP addresses of the configured nameservers as strings. |
|
||||||
|
|
||||||
|
### Wifi configuration
|
||||||
|
|
||||||
|
| key | type | description |
|
||||||
|
| ----------- | ------- | ---------------------------------------------------------------------------- |
|
||||||
|
| mode | string | Set the mode `infrastructure`, `mesh`, `adhoc` or `ap`. |
|
||||||
|
| auth | string | Set the auth mode: `open`, `web` or `wpa-psk`. |
|
||||||
|
| ssid | string | Set the SSID for the Wireless. |
|
||||||
|
| signal | integer | Percentage of signal strength. |
|
||||||
|
|
||||||
|
### VLAN configuration
|
||||||
|
|
||||||
|
| key | type | description |
|
||||||
|
| ------- | ------- | ---------------------------------------------------------------------------- |
|
||||||
|
| id | integer | The VLAN ID. |
|
||||||
|
| parent | string | Parent interface which is the vlan attached. |
|
||||||
|
|
||||||
|
## Access-Points
|
||||||
|
|
||||||
|
| key | type | description |
|
||||||
|
| ---------- | ------- | ---------------------------------------------------------------------------- |
|
||||||
|
| mode | string | One of: `infrastructure`, `mesh` or `adhoc`. |
|
||||||
|
| ssid | string | Wireless network ID. |
|
||||||
|
| frequency | integer | The operating frequency of this Access Point. |
|
||||||
|
| signal | integer | Percentage of signal strength. |
|
||||||
|
| mac | string | MAC Address of the Access Point. |
|
||||||
|
|
||||||
## Panel
|
## Panel
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user