Merge pull request #11 from fabaff/readme

Add README file

README.rst

@@ -0,0 +1,114 @@
+aioesphomeapi
+=============
+
+``aioesphomeapi`` allows you to interact with devices flashed with `ESPHome <https://esphome.io/>`_.
+
+Installation
+------------
+
+The module is available from the `Python Package Index <https://pypi.python.org/pypi>`_.
+
+.. code:: bash
+
+    $ pip3 install aioesphomeapi
+
+Usage
+-----
+
+It's required that you enable the `Native API <https://esphome.io/components/api.html>`_ component for the device.
+
+.. code:: yaml
+
+   # Example configuration entry
+   api:
+     password: 'MyPassword'
+
+Check the output to get the local address of the device or use the ``name:``under ``esphome:`` from the device configuration.
+
+.. code:: bash
+
+   [17:56:38][C][api:095]: API Server:
+   [17:56:38][C][api:096]:   Address: api_test.local:6053
+
+
+The sample code below will connect to the device and retrieve details.
+
+.. code:: python
+
+   import aioesphomeapi
+   import asyncio
+   
+   async def main():
+       """Connect to an ESPHome device and get details."""
+       loop = asyncio.get_running_loop()
+   
+       # Establish connection 
+       api = aioesphomeapi.APIClient(loop, "api_test.local", 6053, "MyPassword")
+       await api.connect(login=True)
+       
+       # Get API version of the device's firmware
+       print(api.api_version)
+       
+       # Show device details
+       device_info = await api.device_info()
+       print(device_info)
+       
+       # List all entities of the device
+       entities = await api.list_entities_services()
+       print(entities)
+       
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())
+
+Subscribe to state changes of an ESPHome device.
+
+.. code:: python
+
+   import aioesphomeapi
+   import asyncio
+   
+   async def main():
+       """Connect to an ESPHome device and wait for state changes."""
+       loop = asyncio.get_running_loop()
+       cli = aioesphomeapi.APIClient(loop, "api_test.local", 6053, "MyPassword")
+       
+       await cli.connect(login=True)
+
+        def change_callback(state):
+           """Print the state changes of the device.."""
+           print(state)
+       
+       # Subscribe to the state changes
+       await cli.subscribe_states(change_callback)
+   
+   loop = asyncio.get_event_loop()
+   try:
+       asyncio.ensure_future(main())
+       loop.run_forever()
+    except KeyboardInterrupt:
+       pass
+   finally:
+       loop.close()
+
+Other examples:
+
+- `Camera <https://gist.github.com/micw/202f9dee5c990f0b0f7e7c36b567d92b>`_
+- `Async print <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-async-py>`_
+- `Simple print <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-print-simple-py`_
+- `InfluxDB <https://gist.github.com/fpletz/d071c72e45d17ba274fd61ca7a465033#file-esphome-sensor-influxdb-py>`_
+
+Development
+-----------
+
+For development is recommended to use a Python virtual environment (``venv``).
+
+.. code:: bash
+
+    $ python3 -m venv .
+    $ source bin/activate
+    $ python3 setup.py develop
+
+License
+-------
+
+``aioesphomeapi`` is licensed under MIT, for more details check LICENSE.

setup.py

@@ -1,13 +1,21 @@
 #!/usr/bin/env python3
 """aioesphomeapi setup script."""
+import os
+
 from setuptools import find_packages, setup
 
+here = os.path.abspath(os.path.dirname(__file__))
+
+with open(os.path.join(here, 'README.rst'), encoding='utf-8') as readme_file:
+    long_description = readme_file.read()
+
+
 VERSION = '2.6.1'
 PROJECT_NAME = 'aioesphomeapi'
 PROJECT_PACKAGE_NAME = 'aioesphomeapi'
 PROJECT_LICENSE = 'MIT'
 PROJECT_AUTHOR = 'Otto Winter'
-PROJECT_COPYRIGHT = ' 2019, Otto Winter'
+PROJECT_COPYRIGHT = ' 2019-2020, Otto Winter'
 PROJECT_URL = 'https://esphome.io/'
 PROJECT_EMAIL = 'contact@otto-winter.com'
 
@@ -36,6 +44,8 @@ setup(
     download_url=DOWNLOAD_URL,
     author=PROJECT_AUTHOR,
     author_email=PROJECT_EMAIL,
+    description='Python API for interacting with ESPHome devices.',
+    long_description=long_description,
     license=PROJECT_LICENSE,
     packages=find_packages(),
     include_package_data=True,