{"id":23221,"library":"aioshelly","title":"aioshelly","description":"Asynchronous library to control Shelly smart home devices (WiFi relays, sensors, etc.). Current version: 13.25.0. Requires Python >=3.11. Released regularly; follows Shelly firmware updates.","status":"active","version":"13.25.0","language":"python","source_language":"en","source_url":"https://github.com/home-assistant-libs/aioshelly","tags":["shelly","smarthome","iot","coap","async"],"install":[{"cmd":"pip install aioshelly","lang":"bash","label":"pip"}],"dependencies":[{"reason":"HTTP client for API calls","package":"aiohttp","optional":false},{"reason":"Fast JSON parsing for CoAP messages","package":"orjson","optional":false},{"reason":"Bluetooth Low Energy communication (BLE)","package":"bleak","optional":true}],"imports":[{"note":"Top-level import was removed in v10. Use aioshelly.device or aioshelly.factory.","wrong":"from aioshelly import ShellyDevice","symbol":"ShellyDevice","correct":"from aioshelly.device import ShellyDevice"},{"note":"CoAP class has own module since v10.","wrong":"from aioshelly import ShellyCoAP","symbol":"ShellyCoAP","correct":"from aioshelly.coap import ShellyCoAP"},{"note":"Factory function moved to aioshelly.factory in v10.","wrong":"from aioshelly import get_device","symbol":"get_device","correct":"from aioshelly.factory import get_device"}],"quickstart":{"code":"import asyncio\nimport aiohttp\nfrom aioshelly.factory import get_device\n\nasync def main():\n    async with aiohttp.ClientSession() as session:\n        # For local CoAP (gen1) device:\n        options = {\n            'ip_address': '192.168.1.100',\n            'auth': {'username': 'admin', 'password': ''}\n        }\n        device = await get_device(session, 'shellyplug-s-XXXX', options)\n        await device.async_setup()\n        print('Device name:', device.name)\n        print('Is on:', device.channels[0].state)\n        await device.channels[0].turn_on()\n        await device.async_update()\n\nasyncio.run(main())","lang":"python","description":"Basic example: discover and control a Shelly Plug S (gen1) using CoAP."},"warnings":[{"fix":"Replace 'from aioshelly import ShellyDevice' with 'from aioshelly.device import ShellyDevice' or use factory.","message":"In v10, top-level imports (from aioshelly import X) were removed. All classes/functions must be imported from their submodules (e.g., aioshelly.device, aioshelly.coap, aioshelly.factory).","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Replace async_get_device() with get_device() from aioshelly.factory.","message":"The async_get_device() function was deprecated in v12 and removed in v13. Use get_device() from aioshelly.factory instead.","severity":"deprecated","affected_versions":">=12.0.0, <13.0.0 (deprecated); >=13.0.0 (removed)"},{"fix":"Always call await device.async_setup() before accessing device properties.","message":"Device initialization must be awaited with device.async_setup() after get_device(). Forgetting this leads to AttributeError on device.channels.","severity":"gotcha","affected_versions":"all"},{"fix":"Verify auth credentials and use correct options dict with 'ip_address' and 'auth' for gen1, or 'auth_key' for gen2+.","message":"CoAP devices (gen1) require the local IP and auth credentials. If auth is wrong, device.update() may fail silently. For gen2/3 devices, use Cloud or local HTTP API with auth key.","severity":"gotcha","affected_versions":"all"},{"fix":"Access channels by index: device.channels[0].state instead of device.channels[0].state (or use dict-style if still needed, but prefer indexing).","message":"In v11, the 'channels' attribute changed from a dict to a list. Iterating over channels now yields indexes instead of channel numbers.","severity":"breaking","affected_versions":">=11.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Add 'await device.async_setup()' after get_device().","cause":"Called device.channels[0].state before device.async_setup() was awaited.","error":"AttributeError: 'NoneType' object has no attribute 'state'"},{"fix":"Upgrade to latest version: pip install --upgrade aioshelly","cause":"Installed version <10.0.0 where submodules didn't exist or different package.","error":"ModuleNotFoundError: No module named 'aioshelly.device'"},{"fix":"Change import to: from aioshelly.factory import get_device","cause":"async_get_device was removed in v13; use get_device instead.","error":"ImportError: cannot import name 'async_get_device' from 'aioshelly'"},{"fix":"Ensure options include 'ip_address' and 'auth' for gen1, or 'auth_key' for gen2+.","cause":"Options dict missing required key for local device.","error":"KeyError: 'ip_address'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}