# Etekcity ESF-551 BLE
This package provides a basic unofficial interface for interacting with [Etekcity ESF-551 Smart Fitness Scale](https://etekcity.com/products/smart-fitness-scale-esf551) using Bluetooth Low Energy (BLE). It allows you to easily connect to the scale, receive weight and impedance measurements, manage the display unit settings, and calculate various body metrics.
It has only been tested on the ESF-551 model. I have no idea whether it might also work with some other bluetooth bathroom scale models from Etekcity. If you try it with a different model, please let me know whether it works or not.
**Disclaimer: This is an unofficial, community-developed library. It is not affiliated with, officially maintained by, or in any way officially connected with Etekcity, VeSync Co., Ltd. (the owner of the Etekcity brand), or any of their subsidiaries or affiliates. The official Etekcity website can be found at https://www.etekcity.com, and the official VeSync website at https://www.vesync.com. The names "Etekcity" and "VeSync" as well as related names, marks, emblems and images are registered trademarks of their respective owners.**
[](https://www.buymeacoffee.com/ronnnnnnn)
## Installation
Install the package using pip:
```bash
pip install etekcity_esf551_ble
```
## Quick Start
Here's a basic example of how to use the library:
```python
import asyncio
from etekcity_esf551_ble import (
IMPEDANCE_KEY,
WEIGHT_KEY,
EtekcitySmartFitnessScale,
ScaleData,
WeightUnit,
BodyMetrics,
Sex,
)
async def main():
def notification_callback(data: ScaleData):
print(f"Weight: {data.measurements[WEIGHT_KEY]} kg")
print(f"Display Unit: {data.display_unit.name}")
if IMPEDANCE_KEY in data.measurements:
print(f"Impedance: {data.measurements[IMPEDANCE_KEY]} Ω")
# Calculate body metrics
# Note: Replace with your actual height, age and sex
body_metrics = BodyMetrics(
weight_kg=data.measurements[WEIGHT_KEY],
height_m=1.75, # Example height
age=30, # Example age
sex=Sex.Male, # Example sex
impedance=data.measurements[IMPEDANCE_KEY]
)
print(f"Body Mass Index: {body_metrics.body_mass_index:.2f}")
print(f"Body Fat Percentage: {body_metrics.body_fat_percentage:.1f}%")
print(f"Fat-Free Weight: {body_metrics.fat_free_weight:.2f} kg")
print(f"Subcutaneous Fat Percentage: {body_metrics.subcutaneous_fat_percentage:.1f}%")
print(f"Visceral Fat Value: {body_metrics.visceral_fat_value}")
print(f"Body Water Percentage: {body_metrics.body_water_percentage:.1f}%")
print(f"Basal Metabolic Rate: {body_metrics.basal_metabolic_rate} calories")
print(f"Skeletal Muscle Percentage: {body_metrics.skeletal_muscle_percentage:.1f}%")
print(f"Muscle Mass: {body_metrics.muscle_mass:.2f} kg")
print(f"Bone Mass: {body_metrics.bone_mass:.2f} kg")
print(f"Protein Percentage: {body_metrics.protein_percentage:.1f}%")
print(f"Metabolic Age: {body_metrics.metabolic_age} years")
# Replace XX:XX:XX:XX:XX:XX with your scale's Bluetooth address
scale = EtekcitySmartFitnessScale("XX:XX:XX:XX:XX:XX", notification_callback)
scale.display_unit = WeightUnit.KG # Set display unit to kilograms
await scale.async_start()
await asyncio.sleep(30) # Wait for measurements
await scale.async_stop()
asyncio.run(main())
```
For a real-life usage example of this library, check out the [Etekcity Fitness Scale BLE Integration for Home Assistant](https://github.com/ronnnnnnnnnnnnn/etekcity_fitness_scale_ble).
## API Reference
### `EtekcitySmartFitnessScale`
The main class for interacting with the scale.
#### Methods:
- `__init__(self, address: str, notification_callback: Callable[[ScaleData], None], display_unit: WeightUnit = None)`
- `async_start()`: Start scanning for and connecting to the scale.
- `async_stop()`: Stop the connection to the scale.
#### Properties:
- `display_unit`: Get or set the display unit (WeightUnit.KG, WeightUnit.LB or WeightUnit.ST). Returns None if the display unit is currently unknown (not set by the user and not yet received from the scale together with a stable weight measurement).
- `hw_version`: Get the hardware version of the scale (read-only).
- `sw_version`: Get the software version of the scale (read-only).
### `EtekcitySmartFitnessScaleWithBodyMetrics`
An extended version of EtekcitySmartFitnessScale that automatically calculates body metrics.
#### Methods:
- `__init__(self, address: str, notification_callback: Callable[[ScaleData], None], sex: Sex, birthdate: date, height_m: float, display_unit: WeightUnit = None)`
- `async_start()`: Start scanning for and connecting to the scale.
- `async_stop()`: Stop the connection to the scale.
#### Properties:
- `display_unit`: Get or set the display unit (WeightUnit.KG, WeightUnit.LB or WeightUnit.ST). Returns None if the display unit is currently unknown (not set by the user and not yet received from the scale together with a stable weight measurement).
- `hw_version`: Get the hardware version of the scale (read-only).
- `sw_version`: Get the software version of the scale (read-only).
### `WeightUnit`
An enum representing the possible display units:
- `WeightUnit.KG`: Kilograms
- `WeightUnit.LB`: Pounds
- `WeightUnit.ST`: Stones
### `ScaleData`
A dataclass containing scale measurement data:
- `name`: Scale name
- `address`: Scale Bluetooth address
- `hw_version`: Hardware version
- `sw_version`: Software version
- `display_unit`: Current display unit (concerns only the weight as displayed on the scale, the measurement itself is always provided by the API in kilograms)
- `measurements`: Dictionary of measurements (currently supports: weight in kilograms and impedance in ohms)
### `BodyMetrics`
A class for calculating various body composition metrics based on height, age, sex, and the weight and impedance as measured by the scale, similar to the metrics calculated and shown in the VeSync app. Note that currently "Athlete Mode" is not supported.
#### Methods:
- `__init__(self, weight_kg: float, height_m: float, age: int, sex: Sex, impedance: int)`
#### Properties:
- `body_mass_index`: Body Mass Index (BMI)
- `body_fat_percentage`: Estimated body fat percentage
- `fat_free_weight`: Weight of non-fat body mass in kg
- `subcutaneous_fat_percentage`: Estimated subcutaneous fat percentage
- `visceral_fat_value`: Estimated visceral fat level (unitless)
- `body_water_percentage`: Estimated body water percentage
- `basal_metabolic_rate`: Estimated basal metabolic rate in calories
- `skeletal_muscle_percentage`: Estimated skeletal muscle percentage
- `muscle_mass`: Estimated muscle mass in kg
- `bone_mass`: Estimated bone mass in kg
- `protein_percentage`: Estimated protein percentage
- `weight_score`: Calculated weight score (0-100)
- `fat_score`: Calculated fat score (0-100)
- `bmi_score`: Calculated BMI score (0-100)
- `health_score`: Overall health score based on other metrics (0-100)
- `metabolic_age`: Estimated metabolic age in years
### `Sex`
An enum representing biological sex for body composition calculations:
- `Sex.Male`
- `Sex.Female`
## Compatibility
- Tested on Mac (Apple Silicon) and Raspberry Pi 4
- Compatibility with Windows is unknown
## Troubleshooting
On Raspberry Pi 4 (and possibly other Linux machines using BlueZ), if you encounter a `org.bluez.Error.InProgress` error, try the following in `bluetoothctl`:
```
power off
power on
scan on
```
(See https://github.com/home-assistant/core/issues/76186#issuecomment-1204954485)
## Support the Project
If you find this unofficial project helpful, consider buying me a coffee! Your support helps maintain and improve this library.
[](https://www.buymeacoffee.com/ronnnnnnn)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer
This is an independent project developed by the community. It is not endorsed by, directly affiliated with, maintained, authorized, or sponsored by Etekcity, VeSync Co., Ltd., or any of their affiliates or subsidiaries. All product and company names are the registered trademarks of their original owners. The use of any trade name or trademark is for identification and reference purposes only and does not imply any association with the trademark holder of their product brand.
Raw data
{
"_id": null,
"home_page": null,
"name": "etekcity-esf551-ble",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ble, bluetooth, esf551, etekcity, fitness scale, health, iot, smart home, smart scale, weight",
"author": null,
"author_email": "Ron <ronnnnnnn@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/29/1a/4a03bcae9939a44953cfb47169a0ffc2c567418539f83c56db024fffd3ae/etekcity_esf551_ble-0.2.1.tar.gz",
"platform": null,
"description": "# Etekcity ESF-551 BLE\n\nThis package provides a basic unofficial interface for interacting with [Etekcity ESF-551 Smart Fitness Scale](https://etekcity.com/products/smart-fitness-scale-esf551) using Bluetooth Low Energy (BLE). It allows you to easily connect to the scale, receive weight and impedance measurements, manage the display unit settings, and calculate various body metrics.\n\nIt has only been tested on the ESF-551 model. I have no idea whether it might also work with some other bluetooth bathroom scale models from Etekcity. If you try it with a different model, please let me know whether it works or not.\n\n**Disclaimer: This is an unofficial, community-developed library. It is not affiliated with, officially maintained by, or in any way officially connected with Etekcity, VeSync Co., Ltd. (the owner of the Etekcity brand), or any of their subsidiaries or affiliates. The official Etekcity website can be found at https://www.etekcity.com, and the official VeSync website at https://www.vesync.com. The names \"Etekcity\" and \"VeSync\" as well as related names, marks, emblems and images are registered trademarks of their respective owners.**\n\n[](https://www.buymeacoffee.com/ronnnnnnn)\n\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install etekcity_esf551_ble\n```\n\n\n## Quick Start\n\nHere's a basic example of how to use the library:\n\n```python\nimport asyncio\nfrom etekcity_esf551_ble import (\n IMPEDANCE_KEY,\n WEIGHT_KEY,\n EtekcitySmartFitnessScale,\n ScaleData,\n WeightUnit,\n BodyMetrics,\n Sex,\n)\n\nasync def main():\n def notification_callback(data: ScaleData):\n print(f\"Weight: {data.measurements[WEIGHT_KEY]} kg\")\n print(f\"Display Unit: {data.display_unit.name}\")\n if IMPEDANCE_KEY in data.measurements:\n print(f\"Impedance: {data.measurements[IMPEDANCE_KEY]} \u03a9\")\n \n # Calculate body metrics\n # Note: Replace with your actual height, age and sex\n body_metrics = BodyMetrics(\n weight_kg=data.measurements[WEIGHT_KEY],\n height_m=1.75, # Example height\n age=30, # Example age\n sex=Sex.Male, # Example sex\n impedance=data.measurements[IMPEDANCE_KEY]\n )\n print(f\"Body Mass Index: {body_metrics.body_mass_index:.2f}\")\n print(f\"Body Fat Percentage: {body_metrics.body_fat_percentage:.1f}%\")\n print(f\"Fat-Free Weight: {body_metrics.fat_free_weight:.2f} kg\")\n print(f\"Subcutaneous Fat Percentage: {body_metrics.subcutaneous_fat_percentage:.1f}%\")\n print(f\"Visceral Fat Value: {body_metrics.visceral_fat_value}\")\n print(f\"Body Water Percentage: {body_metrics.body_water_percentage:.1f}%\")\n print(f\"Basal Metabolic Rate: {body_metrics.basal_metabolic_rate} calories\")\n print(f\"Skeletal Muscle Percentage: {body_metrics.skeletal_muscle_percentage:.1f}%\")\n print(f\"Muscle Mass: {body_metrics.muscle_mass:.2f} kg\")\n print(f\"Bone Mass: {body_metrics.bone_mass:.2f} kg\")\n print(f\"Protein Percentage: {body_metrics.protein_percentage:.1f}%\")\n print(f\"Metabolic Age: {body_metrics.metabolic_age} years\")\n\n # Replace XX:XX:XX:XX:XX:XX with your scale's Bluetooth address\n scale = EtekcitySmartFitnessScale(\"XX:XX:XX:XX:XX:XX\", notification_callback)\n scale.display_unit = WeightUnit.KG # Set display unit to kilograms\n\n await scale.async_start()\n await asyncio.sleep(30) # Wait for measurements\n await scale.async_stop()\n\nasyncio.run(main())\n```\nFor a real-life usage example of this library, check out the [Etekcity Fitness Scale BLE Integration for Home Assistant](https://github.com/ronnnnnnnnnnnnn/etekcity_fitness_scale_ble).\n\n\n## API Reference\n\n### `EtekcitySmartFitnessScale`\n\nThe main class for interacting with the scale.\n\n#### Methods:\n\n- `__init__(self, address: str, notification_callback: Callable[[ScaleData], None], display_unit: WeightUnit = None)`\n- `async_start()`: Start scanning for and connecting to the scale.\n- `async_stop()`: Stop the connection to the scale.\n\n#### Properties:\n\n- `display_unit`: Get or set the display unit (WeightUnit.KG, WeightUnit.LB or WeightUnit.ST). Returns None if the display unit is currently unknown (not set by the user and not yet received from the scale together with a stable weight measurement).\n- `hw_version`: Get the hardware version of the scale (read-only).\n- `sw_version`: Get the software version of the scale (read-only).\n\n### `EtekcitySmartFitnessScaleWithBodyMetrics`\n\nAn extended version of EtekcitySmartFitnessScale that automatically calculates body metrics.\n\n#### Methods:\n\n- `__init__(self, address: str, notification_callback: Callable[[ScaleData], None], sex: Sex, birthdate: date, height_m: float, display_unit: WeightUnit = None)`\n- `async_start()`: Start scanning for and connecting to the scale.\n- `async_stop()`: Stop the connection to the scale.\n\n#### Properties:\n\n- `display_unit`: Get or set the display unit (WeightUnit.KG, WeightUnit.LB or WeightUnit.ST). Returns None if the display unit is currently unknown (not set by the user and not yet received from the scale together with a stable weight measurement).\n- `hw_version`: Get the hardware version of the scale (read-only).\n- `sw_version`: Get the software version of the scale (read-only).\n\n### `WeightUnit`\n\nAn enum representing the possible display units:\n\n- `WeightUnit.KG`: Kilograms\n- `WeightUnit.LB`: Pounds\n- `WeightUnit.ST`: Stones\n\n### `ScaleData`\n\nA dataclass containing scale measurement data:\n\n- `name`: Scale name\n- `address`: Scale Bluetooth address\n- `hw_version`: Hardware version\n- `sw_version`: Software version\n- `display_unit`: Current display unit (concerns only the weight as displayed on the scale, the measurement itself is always provided by the API in kilograms)\n- `measurements`: Dictionary of measurements (currently supports: weight in kilograms and impedance in ohms)\n\n### `BodyMetrics`\n\nA class for calculating various body composition metrics based on height, age, sex, and the weight and impedance as measured by the scale, similar to the metrics calculated and shown in the VeSync app. Note that currently \"Athlete Mode\" is not supported.\n\n#### Methods:\n\n- `__init__(self, weight_kg: float, height_m: float, age: int, sex: Sex, impedance: int)`\n\n#### Properties:\n\n- `body_mass_index`: Body Mass Index (BMI)\n- `body_fat_percentage`: Estimated body fat percentage\n- `fat_free_weight`: Weight of non-fat body mass in kg\n- `subcutaneous_fat_percentage`: Estimated subcutaneous fat percentage\n- `visceral_fat_value`: Estimated visceral fat level (unitless)\n- `body_water_percentage`: Estimated body water percentage\n- `basal_metabolic_rate`: Estimated basal metabolic rate in calories\n- `skeletal_muscle_percentage`: Estimated skeletal muscle percentage\n- `muscle_mass`: Estimated muscle mass in kg\n- `bone_mass`: Estimated bone mass in kg\n- `protein_percentage`: Estimated protein percentage\n- `weight_score`: Calculated weight score (0-100)\n- `fat_score`: Calculated fat score (0-100)\n- `bmi_score`: Calculated BMI score (0-100)\n- `health_score`: Overall health score based on other metrics (0-100)\n- `metabolic_age`: Estimated metabolic age in years\n\n### `Sex`\n\nAn enum representing biological sex for body composition calculations:\n\n- `Sex.Male`\n- `Sex.Female`\n\n\n## Compatibility\n\n- Tested on Mac (Apple Silicon) and Raspberry Pi 4\n- Compatibility with Windows is unknown\n\n\n## Troubleshooting\n\nOn Raspberry Pi 4 (and possibly other Linux machines using BlueZ), if you encounter a `org.bluez.Error.InProgress` error, try the following in `bluetoothctl`:\n\n```\npower off\npower on\nscan on\n```\n(See https://github.com/home-assistant/core/issues/76186#issuecomment-1204954485)\n\n\n## Support the Project\n\nIf you find this unofficial project helpful, consider buying me a coffee! Your support helps maintain and improve this library.\n\n[](https://www.buymeacoffee.com/ronnnnnnn)\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n## Disclaimer\n\nThis is an independent project developed by the community. It is not endorsed by, directly affiliated with, maintained, authorized, or sponsored by Etekcity, VeSync Co., Ltd., or any of their affiliates or subsidiaries. All product and company names are the registered trademarks of their original owners. The use of any trade name or trademark is for identification and reference purposes only and does not imply any association with the trademark holder of their product brand.\n",
"bugtrack_url": null,
"license": null,
"summary": "An unofficial Python package for interacting with Etekcity ESF-551 Smart Fitness Scales using BLE. Not affiliated with Etekcity, VeSync Co., Ltd., or any of their subsidiaries.",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/ronnnnnnnnnnnnn/etekcity_esf551_ble/issues",
"Documentation": "https://github.com/ronnnnnnnnnnnnn/etekcity_esf551_ble#readme",
"Homepage": "https://github.com/ronnnnnnnnnnnnn/etekcity_esf551_ble",
"Source Code": "https://github.com/ronnnnnnnnnnnnn/etekcity_esf551_ble"
},
"split_keywords": [
"ble",
" bluetooth",
" esf551",
" etekcity",
" fitness scale",
" health",
" iot",
" smart home",
" smart scale",
" weight"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1cc0ce23641a21f54ae77846888909dbbbbea86f209e461a14cee60218fdd227",
"md5": "7b41fbe5d5fd3b37e720c975954d5b88",
"sha256": "9014ef5dcde26ece3b2aeb241c3c3e66f791fb3092810b99d1e25ec98771a5d3"
},
"downloads": -1,
"filename": "etekcity_esf551_ble-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b41fbe5d5fd3b37e720c975954d5b88",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12633,
"upload_time": "2024-10-19T22:03:46",
"upload_time_iso_8601": "2024-10-19T22:03:46.350761Z",
"url": "https://files.pythonhosted.org/packages/1c/c0/ce23641a21f54ae77846888909dbbbbea86f209e461a14cee60218fdd227/etekcity_esf551_ble-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "291a4a03bcae9939a44953cfb47169a0ffc2c567418539f83c56db024fffd3ae",
"md5": "036261e140dc49fea5b902aba559f491",
"sha256": "ddc35b4ffdb5371d5f92ba93ba8962bd4d2ba76398506d9a7bdf4cdf08876fd1"
},
"downloads": -1,
"filename": "etekcity_esf551_ble-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "036261e140dc49fea5b902aba559f491",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11749,
"upload_time": "2024-10-19T22:03:47",
"upload_time_iso_8601": "2024-10-19T22:03:47.853697Z",
"url": "https://files.pythonhosted.org/packages/29/1a/4a03bcae9939a44953cfb47169a0ffc2c567418539f83c56db024fffd3ae/etekcity_esf551_ble-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 22:03:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ronnnnnnnnnnnnn",
"github_project": "etekcity_esf551_ble",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "etekcity-esf551-ble"
}
JSON
