jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-10 19:06:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

New network API doc (#721)

Browse Source 
* 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 2020-11-10 17:53:54 +01:00 committed by GitHub
parent 8d282edc8c
commit ea486b226d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 118 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/api/supervisor/endpoints.md
View File

@ -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">

48
docs/api/supervisor/models.md
View File

@ -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