mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-13 04:16:29 +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 |
|
||||
| ---------- | ---------------------------------------------------------------------- |
|
||||
| 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 |
|
||||
|
||||
**Example response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"interfaces": {
|
||||
"eth0": {
|
||||
"interfaces": [
|
||||
{
|
||||
"interface": "eth0",
|
||||
"ip_address": "192.168.1.100/24",
|
||||
"gateway": "192.168.1.1",
|
||||
"id": "Wired connection 1",
|
||||
"type": "802-3-ethernet",
|
||||
"nameservers": ["192.168.1.1"],
|
||||
"method": "static",
|
||||
"primary": true
|
||||
"type": "ethernet",
|
||||
"primary": true,
|
||||
"enabled": true,
|
||||
"connected": true,
|
||||
"ipv4": {
|
||||
"method": "static",
|
||||
"ip_address": "192.168.1.100/24",
|
||||
"gateway": "192.168.1.1",
|
||||
"nameservers": ["192.168.1.1"],
|
||||
},
|
||||
"ipv6": null,
|
||||
"wifi": null,
|
||||
"vlan": null,
|
||||
}
|
||||
},
|
||||
],
|
||||
"docker": {
|
||||
"interface": "hassio",
|
||||
"address": "172.30.32.0/23",
|
||||
@ -1434,49 +1440,89 @@ Get network information.
|
||||
|
||||
</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.
|
||||
|
||||
</ApiEndpoint>
|
||||
|
||||
<ApiEndpoint path="/network/<interface>/update" method="post">
|
||||
|
||||
<ApiEndpoint path="/network/interface/<interface>/update" method="post">
|
||||
Update the settings for a network interface.
|
||||
|
||||
**Payload:**
|
||||
|
||||
| key | type | optional | description |
|
||||
| ------- | ------ | -------- | ---------------------------------------------------------------------- |
|
||||
| address | string | True | The new IP address for the interface in the X.X.X.X/XX format |
|
||||
| dns | list | True | List of DNS servers to use |
|
||||
| gateway | string | True | The gateway the interface should use |
|
||||
| method | string | True | Set if the interface should use DHCP or not, can be `dhcp` or `static` |
|
||||
| enabled | bool | True | Enable/Disable an ethernet interface / VLAN got removed with disabled |
|
||||
| ipv4 | dict | True | A struct with ipv4 interface settings |
|
||||
| ipv6 | dict | True | A struct with ipv6 interface settings |
|
||||
| wifi | dict | True | A struct with Wireless connection settings |
|
||||
|
||||
**You need to supply at least one key in the payload.**
|
||||
**ipv4 / ipv6:**
|
||||
|
||||
:::warning
|
||||
If you change the `address` or `gateway` you may need to reconnect to the new address
|
||||
:::
|
||||
| key | type | optional | description |
|
||||
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
|
||||
| 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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"ip_address": "192.168.1.100/24",
|
||||
"gateway": "192.168.1.1",
|
||||
"id": "Wired connection 1",
|
||||
"type": "802-3-ethernet",
|
||||
"nameservers": ["192.168.1.1"],
|
||||
"method": "static",
|
||||
"primary": true
|
||||
"accesspoints": [
|
||||
{
|
||||
"mode": "infrastructure",
|
||||
"ssid": "MY_TestWifi",
|
||||
"mac": "00:00:00:00",
|
||||
"frequency": 24675,
|
||||
"signal": 90
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</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
|
||||
|
||||
<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 |
|
||||
| ----------- | ------- | ---------------------------------------------------------------------------- |
|
||||
| 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. |
|
||||
| gateway | string | The IP address of the gateway. |
|
||||
| id | string | The ID of the interface. |
|
||||
| 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". |
|
||||
| type | string | The interface type: `ethernet`, `wireless` or `vlan`. |
|
||||
| enabled | boolean | Return True if the interface is enabled. |
|
||||
| connected | boolean | Return True if the interface is connected to the network. |
|
||||
| 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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user