From df5bda5f283c357492f52c93b640f849a27d598c Mon Sep 17 00:00:00 2001 From: Yevhenii Vaskivskyi Date: Sat, 19 Feb 2022 20:09:43 +0100 Subject: [PATCH] Additions for the 0.2.0 --- README.md | 85 +++++++++++++++++++++++++++++++++++++--- asusrouter/asusrouter.py | 8 +++- setup.cfg | 7 ++-- 3 files changed, 90 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 71ff99e..fe71136 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,91 @@ -**AsusRouter** is an API wrapper for communication with ASUSWRT-powered routers using the HTTP protocol. +## AsusRouter + +**AsusRouter** is an API wrapper for communication with ASUSWRT-powered routers using the HTTP or HTTPS protocols. + + +## Supported features + +- **Monitoring data** when `enable_monitor` parameter of `AsusRrouter` is set to `True` (default) +- **Sending commands** to the device when `enable_control` is set to `True` (default is `False`) +- SSL server certificates on the device side (including certificate check on connection from Trusted Root Certificates or your own specified certificate file)s -It is small, only partially done and has a lot of limitations, but with time AsusRouter has a chance to grow into a full-powered control library for your device. ## Installation -Installation of the latest release is available through PyPI: +Installation of the latest release is available from PyPI: ``` pip install asusrouter ``` + +## Usage + +Once installed, you can import `AsusRouter` class from the module. Example shows the default parameters except for `host`, `username` and `password`. + +```python +from asusrouter.asusrouter import AsusRouter + +router = AsusRouter(host = "router.my.address", #required - both IP and URL supported + username = "admin", #required + password = "password", #required + port = None, #optional - default port would be selected based on use_ssl parameter + use_ssl = False, #optional + cert_check = True, #optional + cert_path = "", #optional + cache_time = 5, #optional + enable_monitor = True, #optional + enable_control = False, #optional + use_ssl = True, #optional + cert_check = False) #optional +``` + +The module has the initialization method to load all the known data (all the monitors and methods from the next section, require `enable_monitor` to be `True`): + +```python +router.async_initialize() +``` + + +#### Monitors and additional methods + +`AsusRouter` class has 3 monitors to load large part of useful data from the device. All of them require `enable_monitor` parameter of `AsusRrouter` to be set to `True`. The following methods can be used: + +```python +router.async_monitor_main() + +router.async_monitor_nvram() + +router.async_monitor_misc() +``` + +Moreover, some additional methods are also available (that could partially rely on one of the monitors): + +```python +router.async_find_interfaces() +``` + +The detailed description of monitors and monitoring methods is available here (*in work*). + + +#### Commands + +`AsusRouter` class supports sending commands to the device using the `async_command` method. Sending commands requires `enable_command` parameter of `AsusRrouter` to be set to `True`. + +For example, to reboot the device: + +```python +# This command will REBOOT your device if connected! +router.async_command(commands = {"rc_service": "reboot"}, action_mode = "apply") +``` + +Commands to the method should be sent as a `dict` of `command: value`. Please, refer to the Command List (*in work*) for the detailed explanation on the available commands. + + ## Supported devices and firmware -Currently, **AsusRouter** is tested only on one router model. If you have successfully tested it on other models or with other software, you are welcome to submit a pull request and add more devices. +Currently, **AsusRouter** is tested on my only router model. If you wish to help me making it better, feel free to open a [Pull Request](https://github.com/Vaskivskyi/asusrouter/pulls) with your model name and firmware (if everything works well). Chances are much higher that some problems may occur on other devices, so [Issues](https://github.com/Vaskivskyi/asusrouter/issues) are waiting for a new one. + ### Devices @@ -20,8 +93,10 @@ Currently, **AsusRouter** is tested only on one router model. If you have succes |---|---| |RT-AC66U|Complete| + ### Firmware |Version|Build|Extended|Support level| |-------|-----|--------|-------------| -|3.0.0.4|382|52287-g798e87f|Complete| \ No newline at end of file +|3.0.0.4|382|52287-g798e87f|Complete| + diff --git a/asusrouter/asusrouter.py b/asusrouter/asusrouter.py index aa23ad8..07869ae 100644 --- a/asusrouter/asusrouter.py +++ b/asusrouter/asusrouter.py @@ -370,6 +370,10 @@ async def async_load(self, page : str | None = None) -> dict: result = {} + if not self._enable_monitor: + _LOGGER.error(_MSG_ERROR_NO_MONITOR) + return result + if page is None: return result @@ -558,12 +562,12 @@ async def async_monitor_misc(self) -> None: self._monitor_misc = monitor_misc - async def async_find_interfaces(self, useCache : bool = True) -> None: + async def async_find_interfaces(self, use_cache : bool = True) -> None: """Find available interfaces/type dictionary""" if self._monitor_nvram is None: await self.async_monitor_nvram() - elif useCache == False: + elif use_cache == False: await self.async_monitor_nvram() ports = {} diff --git a/setup.cfg b/setup.cfg index 7153839..73c34b9 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = asusrouter -version = 0.1.0 +version = 0.2.0 author = Yevhenii Vaskivskyi author_email = yevhenii@vaskivskyi.com license = Apache-2.0 @@ -9,8 +9,8 @@ long_description = file: README.md long_description_content_type = text/markdown url = https://github.com/Vaskivskyi/asusrouter project_urls = - Source Code = https://github.com/Vaskivskyi/asusrouter - Bug Reports = https://github.com/Vaskivskyi/asusrouter/issues + Source Code = https://github.com/Vaskivskyi/asusrouter + Bug Reports = https://github.com/Vaskivskyi/asusrouter/issues classifiers = Development Status :: 3 - Alpha Intended Audience :: Developers @@ -25,6 +25,7 @@ python_requires = >=3.10.0 install_requires = aiohttp ==3.8.1 urllib3 ==1.26.8 + xmltodict ==0.12.0 [options.packages.find] include = asusrouter*