# Sagemcom API Client in Python
(Unofficial) async Python client to interact with Sagemcom F@st routers via internal API's. This client offers helper functions to retrieve common used functions, but also offers functionality to do custom requests via XPATH notation.
Python 3.9+ required.
## Features
- Retrieve detailed information of your Sagemcom F@st device
- Retrieve connected devices (wifi and ethernet)
- Reboot Sagemcom F@st device
- Retrieve and set all values of your Sagemcom F@st device
## Supported devices
The Sagemcom F@st series is used by multiple cable companies, where some cable companies did rebrand the router. Examples are the b-box from Proximus, Home Hub from bell and the Smart Hub from BT.
| Router Model | Provider(s) | Authentication Method | Comments |
| --------------------- | -------------------- | --------------------- | ----------------------------- |
| Sagemcom F@st 3864 | Optus | sha512 | username: guest, password: "" |
| Sagemcom F@st 3865b | Proximus (b-box3) | md5 | |
| Sagemcom F@st 3890V3 | Delta / Zeelandnet | sha512 | |
| Sagemcom F@st 3896 | | sha512 | username: admin |
| Sagemcom F@st 4360Air | KPN | md5 | |
| Sagemcom F@st 4353 | Belong Gateway | md5 | username: admin, password: "" |
| Sagemcom F@st 5250 | Bell (Home Hub 2000) | md5 | username: guest, password: "" |
| Sagemcom F@st 5280 | | sha512 | |
| Sagemcom F@st 5290 / FWR226e | Frontier | md5 | username: admin |
| Sagemcom F@st 5359 | KPN (Box 12) | sha512 | username: admin |
| Sagemcom F@st 5364 | BT (Smart Hub) | md5 | username: guest, password: "" |
| SagemCom F@st 5366SD | Eir F3000 | md5 | |
| Sagemcom F@st 5370e | Telia | sha512 | |
| Sagemcom F@st 5380 | TDC | md5 | |
| Sagemcom F@st 5566 | Bell (Home Hub 3000) | md5 | username: guest, password: "" |
| Sagemcom F@st 5688T | Salt (FibreBox_X6) | sha512 | username: admin |
| Sagemcom F@st 5689 | Bell (Home Hub 4000) | md5 | username: admin, password: "" |
| Sagemcom F@st 5655V2 | MásMóvil | md5 | |
| Sagemcom F@st 5657IL | | md5 | |
| Speedport Pro | Telekom | md5 | username: admin |
> Contributions welcome. If you router model is supported by this package, but not in the list above, please create [an issue](https://github.com/iMicknl/python-sagemcom-api/issues/new) or pull request.
## Installation
```bash
pip install sagemcom_api
```
## Getting Started
Depending on the router model, Sagemcom is using different encryption methods for authentication, which can be found in [the table above](#supported-devices). This package supports MD5 and SHA512 encryption. If you receive a `LoginTimeoutException`, you will probably need to use another encryption type.
The following script can be used as a quickstart.
```python
import asyncio
from sagemcom_api.client import SagemcomClient
from sagemcom_api.enums import EncryptionMethod
from sagemcom_api.exceptions import NonWritableParameterException
HOST = ""
USERNAME = ""
PASSWORD = ""
ENCRYPTION_METHOD = EncryptionMethod.SHA512 # or EncryptionMethod.MD5
async def main() -> None:
async with SagemcomClient(HOST, USERNAME, PASSWORD, ENCRYPTION_METHOD) as client:
try:
await client.login()
except Exception as exception: # pylint: disable=broad-except
print(exception)
return
# Print device information of Sagemcom F@st router
device_info = await client.get_device_info()
print(f"{device_info.id} {device_info.model_name}")
# Print connected devices
devices = await client.get_hosts()
for device in devices:
if device.active:
print(f"{device.id} - {device.name}")
# Retrieve values via XPath notation, output is a dict
custom_command_output = await client.get_value_by_xpath("Device/UserInterface/AdvancedMode")
print(custom_command_output)
# Set value via XPath notation and catch specific errors
try:
custom_command_output = await client.set_value_by_xpath("Device/UserInterface/AdvancedMode", "true")
except NonWritableParameterException as exception: # pylint: disable=broad-except
print("Not allowed to set AdvancedMode parameter on your device.")
return
print(custom_command_output)
asyncio.run(main())
```
## Functions
- `login()`
- `get_device_info()`
- `get_hosts()`
- `get_port_mappings()`
- `reboot()`
- `get_value_by_xpath(xpath)`
- `set_value_by_xpath(xpath, value)`
## Advanced
### Determine the EncryptionMethod
If you are not sure which encryption method to use, you can leave it empty or pass `None` and use `get_encryption_method` to determine the encryption method.
`get_encryption_method` will return an `EncryptionMethod` when a match is found. Best would be to use this function only during your initial investigation.
This function will throw a `LoginTimeoutException` when no match is found, since this is still a HTTP Time Out. This could caused by the wrong encryption method, but also by trying to connect to an inaccessible host.
### Handle exceptions
Some functions may cause an error when an attempt is made to execute it. These exceptions are thrown by the client and need to be [handled in your Python program](https://docs.python.org/3/tutorial/errors.html#handling-exceptions). Best practice is to catch some specific exceptions and handle them gracefully.
```python
from sagemcom_api.exceptions import *
try:
await client.set_value_by_xpath("Device/UserInterface/AdvancedMode", "true")
except NonWritableParameterException as exception:
print("You don't have rights to write to this parameter.")
except UnknownPathException as exception:
print("The xpath does not exist.")
```
### Run your custom commands
Not all values can be retrieved by helper functions in this client implementation. By using XPath, you are able to return all values via the API. The result will be a dict response, or [an exception](#handle-exceptions) when the attempt was not successful.
```python
try:
result = await client.get_value_by_xpath("Device/DeviceSummary")
except Exception as exception:
print(exception)
```
### Use your own aiohttp ClientSession
> ClientSession is the heart and the main entry point for all client API operations. The session contains a cookie storage and connection pool, thus cookies and connections are shared between HTTP requests sent by the same session.
In order to change settings like the time-out, it is possible to pass your custom [aiohttp ClientSession](https://docs.aiohttp.org/en/stable/client_advanced.html).
```python
from aiohttp import ClientSession, ClientTimeout
session = ClientSession(timeout=ClientTimeout(100))
client = SagemcomClient(session=session)
```
## Inspired by
- [wuseman/SAGEMCOM-FAST-5370e-TELIA](https://github.com/wuseman/SAGEMCOM-FAST-5370e-TELIA)
- [insou22/optus-router-tools](https://github.com/insou22/optus-router-tools)
- [onegambler/bthomehub_client](https://github.com/onegambler/bthomehub_client)
Raw data
{
"_id": null,
"home_page": "https://github.com/iMicknl/python-sagemcom-api",
"name": "sagemcom_api",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "sagemcom, f@st",
"author": "Mick Vleeshouwer",
"author_email": "mick@imick.nl",
"download_url": "https://files.pythonhosted.org/packages/17/45/d77ab14be40f99deb9740ac813d5d00dea6fa0cc09e813f4a2523a41ad1c/sagemcom_api-1.2.1.tar.gz",
"platform": null,
"description": "# Sagemcom API Client in Python\n\n(Unofficial) async Python client to interact with Sagemcom F@st routers via internal API's. This client offers helper functions to retrieve common used functions, but also offers functionality to do custom requests via XPATH notation.\n\nPython 3.9+ required.\n\n## Features\n\n- Retrieve detailed information of your Sagemcom F@st device\n- Retrieve connected devices (wifi and ethernet)\n- Reboot Sagemcom F@st device\n- Retrieve and set all values of your Sagemcom F@st device\n\n## Supported devices\n\nThe Sagemcom F@st series is used by multiple cable companies, where some cable companies did rebrand the router. Examples are the b-box from Proximus, Home Hub from bell and the Smart Hub from BT.\n\n| Router Model | Provider(s) | Authentication Method | Comments |\n| --------------------- | -------------------- | --------------------- | ----------------------------- |\n| Sagemcom F@st 3864 | Optus | sha512 | username: guest, password: \"\" |\n| Sagemcom F@st 3865b | Proximus (b-box3) | md5 | |\n| Sagemcom F@st 3890V3 | Delta / Zeelandnet | sha512 | |\n| Sagemcom F@st 3896 | | sha512 | username: admin |\n| Sagemcom F@st 4360Air | KPN | md5 | |\n| Sagemcom F@st 4353 | Belong Gateway | md5 | username: admin, password: \"\" |\n| Sagemcom F@st 5250 | Bell (Home Hub 2000) | md5 | username: guest, password: \"\" |\n| Sagemcom F@st 5280 | | sha512 | |\n| Sagemcom F@st 5290 / FWR226e | Frontier | md5 | username: admin |\n| Sagemcom F@st 5359 | KPN (Box 12) | sha512 | username: admin |\n| Sagemcom F@st 5364 | BT (Smart Hub) | md5 | username: guest, password: \"\" |\n| SagemCom F@st 5366SD | Eir F3000 | md5 | |\n| Sagemcom F@st 5370e | Telia | sha512 | |\n| Sagemcom F@st 5380 | TDC | md5 | |\n| Sagemcom F@st 5566 | Bell (Home Hub 3000) | md5 | username: guest, password: \"\" |\n| Sagemcom F@st 5688T | Salt (FibreBox_X6) | sha512 | username: admin |\n| Sagemcom F@st 5689 | Bell (Home Hub 4000) | md5 | username: admin, password: \"\" |\n| Sagemcom F@st 5655V2 | M\u00e1sM\u00f3vil | md5 | |\n| Sagemcom F@st 5657IL | | md5 | |\n| Speedport Pro | Telekom | md5 | username: admin |\n\n> Contributions welcome. If you router model is supported by this package, but not in the list above, please create [an issue](https://github.com/iMicknl/python-sagemcom-api/issues/new) or pull request.\n\n## Installation\n\n```bash\npip install sagemcom_api\n```\n\n## Getting Started\n\nDepending on the router model, Sagemcom is using different encryption methods for authentication, which can be found in [the table above](#supported-devices). This package supports MD5 and SHA512 encryption. If you receive a `LoginTimeoutException`, you will probably need to use another encryption type.\n\nThe following script can be used as a quickstart.\n\n```python\nimport asyncio\nfrom sagemcom_api.client import SagemcomClient\nfrom sagemcom_api.enums import EncryptionMethod\nfrom sagemcom_api.exceptions import NonWritableParameterException\n\nHOST = \"\"\nUSERNAME = \"\"\nPASSWORD = \"\"\nENCRYPTION_METHOD = EncryptionMethod.SHA512 # or EncryptionMethod.MD5\n\nasync def main() -> None:\n async with SagemcomClient(HOST, USERNAME, PASSWORD, ENCRYPTION_METHOD) as client:\n try:\n await client.login()\n except Exception as exception: # pylint: disable=broad-except\n print(exception)\n return\n\n # Print device information of Sagemcom F@st router\n device_info = await client.get_device_info()\n print(f\"{device_info.id} {device_info.model_name}\")\n\n # Print connected devices\n devices = await client.get_hosts()\n\n for device in devices:\n if device.active:\n print(f\"{device.id} - {device.name}\")\n\n # Retrieve values via XPath notation, output is a dict\n custom_command_output = await client.get_value_by_xpath(\"Device/UserInterface/AdvancedMode\")\n print(custom_command_output)\n\n # Set value via XPath notation and catch specific errors\n try:\n custom_command_output = await client.set_value_by_xpath(\"Device/UserInterface/AdvancedMode\", \"true\")\n except NonWritableParameterException as exception: # pylint: disable=broad-except\n print(\"Not allowed to set AdvancedMode parameter on your device.\")\n return\n\n print(custom_command_output)\n\nasyncio.run(main())\n```\n\n## Functions\n\n- `login()`\n- `get_device_info()`\n- `get_hosts()`\n- `get_port_mappings()`\n- `reboot()`\n- `get_value_by_xpath(xpath)`\n- `set_value_by_xpath(xpath, value)`\n\n## Advanced\n\n### Determine the EncryptionMethod\n\nIf you are not sure which encryption method to use, you can leave it empty or pass `None` and use `get_encryption_method` to determine the encryption method.\n\n`get_encryption_method` will return an `EncryptionMethod` when a match is found. Best would be to use this function only during your initial investigation.\n\nThis function will throw a `LoginTimeoutException` when no match is found, since this is still a HTTP Time Out. This could caused by the wrong encryption method, but also by trying to connect to an inaccessible host.\n\n### Handle exceptions\n\nSome functions may cause an error when an attempt is made to execute it. These exceptions are thrown by the client and need to be [handled in your Python program](https://docs.python.org/3/tutorial/errors.html#handling-exceptions). Best practice is to catch some specific exceptions and handle them gracefully.\n\n```python\nfrom sagemcom_api.exceptions import *\n\ntry:\n await client.set_value_by_xpath(\"Device/UserInterface/AdvancedMode\", \"true\")\nexcept NonWritableParameterException as exception:\n print(\"You don't have rights to write to this parameter.\")\nexcept UnknownPathException as exception:\n print(\"The xpath does not exist.\")\n```\n\n### Run your custom commands\n\nNot all values can be retrieved by helper functions in this client implementation. By using XPath, you are able to return all values via the API. The result will be a dict response, or [an exception](#handle-exceptions) when the attempt was not successful.\n\n```python\ntry:\n result = await client.get_value_by_xpath(\"Device/DeviceSummary\")\nexcept Exception as exception:\n print(exception)\n```\n\n### Use your own aiohttp ClientSession\n\n> ClientSession is the heart and the main entry point for all client API operations. The session contains a cookie storage and connection pool, thus cookies and connections are shared between HTTP requests sent by the same session.\n\nIn order to change settings like the time-out, it is possible to pass your custom [aiohttp ClientSession](https://docs.aiohttp.org/en/stable/client_advanced.html).\n\n```python\nfrom aiohttp import ClientSession, ClientTimeout\n\nsession = ClientSession(timeout=ClientTimeout(100))\nclient = SagemcomClient(session=session)\n```\n\n## Inspired by\n\n- [wuseman/SAGEMCOM-FAST-5370e-TELIA](https://github.com/wuseman/SAGEMCOM-FAST-5370e-TELIA)\n- [insou22/optus-router-tools](https://github.com/insou22/optus-router-tools)\n- [onegambler/bthomehub_client](https://github.com/onegambler/bthomehub_client)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client to interact with SagemCom F@st routers via internal API's.",
"version": "1.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/iMicknl/python-sagemcom-api/issues",
"Homepage": "https://github.com/iMicknl/python-sagemcom-api",
"Repository": "https://github.com/iMicknl/python-sagemcom-api"
},
"split_keywords": [
"sagemcom",
" f@st"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "295a59aa512db295553369974c2003ecd2cf161287008d1fde1b8cf55ae99790",
"md5": "9259b509f89959a23dce8dacdf6f916d",
"sha256": "31c770b42fdb4c936a7913ea96f0f1babf0a7617e2ff34ae792904d0978bf098"
},
"downloads": -1,
"filename": "sagemcom_api-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9259b509f89959a23dce8dacdf6f916d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 11511,
"upload_time": "2024-06-08T21:36:33",
"upload_time_iso_8601": "2024-06-08T21:36:33.263438Z",
"url": "https://files.pythonhosted.org/packages/29/5a/59aa512db295553369974c2003ecd2cf161287008d1fde1b8cf55ae99790/sagemcom_api-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1745d77ab14be40f99deb9740ac813d5d00dea6fa0cc09e813f4a2523a41ad1c",
"md5": "d016d39352783623e9280959afa85163",
"sha256": "5f7f3a1c021cb9de0297295bbc3015d4354f50e1a6ac3556969da7a0a9d838a1"
},
"downloads": -1,
"filename": "sagemcom_api-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "d016d39352783623e9280959afa85163",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 12084,
"upload_time": "2024-06-08T21:36:35",
"upload_time_iso_8601": "2024-06-08T21:36:35.057074Z",
"url": "https://files.pythonhosted.org/packages/17/45/d77ab14be40f99deb9740ac813d5d00dea6fa0cc09e813f4a2523a41ad1c/sagemcom_api-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-08 21:36:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iMicknl",
"github_project": "python-sagemcom-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sagemcom_api"
}
JSON
