feat: initial working version of aiosoma with tests (#1)

.github/workflows/ci.yml

@@ -36,8 +36,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - "3.7"
-          - "3.8"
           - "3.9"
           - "3.10"
           - "3.11"

README.md

@@ -1,14 +1,14 @@
 # Asynchronous SOMA Connect library
 
 <p align="center">
-  <a href="https://github.com/Djelibeybi/asyncio-soma-connect/actions?query=workflow%3ACI">
-    <img src="https://img.shields.io/github/workflow/status/Djelibeybi/asyncio-soma-connect/CI/main?label=CI&logo=github&style=flat-square" alt="CI Status" >
+  <a href="https://github.com/Djelibeybi/aiosoma/actions?query=workflow%3ACI">
+    <img src="https://img.shields.io/github/workflow/status/Djelibeybi/aiosoma/CI/main?label=CI&logo=github&style=flat-square" alt="CI Status" >
   </a>
-  <a href="https://asyncio-soma-connect.readthedocs.io">
-    <img src="https://img.shields.io/readthedocs/asyncio-soma-connect.svg?logo=read-the-docs&logoColor=fff&style=flat-square" alt="Documentation Status">
+  <a href="https://aiosoma.readthedocs.io">
+    <img src="https://img.shields.io/readthedocs/aiosoma.svg?logo=read-the-docs&logoColor=fff&style=flat-square" alt="Documentation Status">
   </a>
-  <a href="https://codecov.io/gh/Djelibeybi/asyncio-soma-connect">
-    <img src="https://img.shields.io/codecov/c/github/Djelibeybi/asyncio-soma-connect.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
+  <a href="https://codecov.io/gh/Djelibeybi/aiosoma">
+    <img src="https://img.shields.io/codecov/c/github/Djelibeybi/aiosoma.svg?logo=codecov&logoColor=fff&style=flat-square" alt="Test coverage percentage">
   </a>
 </p>
 <p align="center">
@@ -23,20 +23,22 @@
   </a>
 </p>
 <p align="center">
-  <a href="https://pypi.org/project/asyncio-soma-connect/">
-    <img src="https://img.shields.io/pypi/v/asyncio-soma-connect.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
+  <a href="https://pypi.org/project/aiosoma/">
+    <img src="https://img.shields.io/pypi/v/aiosoma.svg?logo=python&logoColor=fff&style=flat-square" alt="PyPI Version">
   </a>
-  <img src="https://img.shields.io/pypi/pyversions/asyncio-soma-connect.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
-  <img src="https://img.shields.io/pypi/l/asyncio-soma-connect.svg?style=flat-square" alt="License">
+  <img src="https://img.shields.io/pypi/pyversions/aiosoma.svg?style=flat-square&logo=python&amp;logoColor=fff" alt="Supported Python versions">
+  <img src="https://img.shields.io/pypi/l/aiosoma.svg?style=flat-square" alt="License">
 </p>
 
-Async library that connects to SOMA Connect
+Asyncio library that controls SOMA Shades via a SOMA Connect device.
 
 ## Installation
 
 Install this via pip (or your favourite package manager):
 
-`pip install asyncio-soma-connect`
+`pip install aiosoma`
+
+## Usage
 
 ## Contributors ✨
 

docs/conf.py

@@ -6,10 +6,10 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "Asynchronous SOMA Connect library"
+project = "Asyncio SOMA Connect"
 copyright = "2022, Avi Miller"
 author = "Avi Miller"
-release = '0.0.0'
+release = "0.0.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -24,12 +24,12 @@
     ".md",
 ]
 
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/usage.md

@@ -1,9 +1,108 @@
 # Usage
 
-To use this package, import it:
+To use this package, import `Aiosoma`:
 
 ```python
-import asyncio_soma_connect
+from aiosoma import Aiosoma
 ```
 
-TODO: Document usage
+Next, create an `Aiosoma` object using either the hostname or IP address and port
+of your SOMA Connect. Using a static IP address is recommended.
+
+```python
+from aiosoma import Aiosoma
+
+soma = Aiosoma("soma-connect.local", 3000)
+```
+
+## Methods
+
+### list_devices()
+
+Use to list all the devices visible to SOMA Connect. The `mac` address of the
+shade you want to control is a required parameter for all the other methods.
+
+```json
+{
+  "result": "success",
+  "version": "2.3.1",
+  "shades": [
+    {
+      "name": "Office",
+      "mac": "aa:bb:cc:dd:ee:ff",
+      "type": "shade",
+      "gen": "2S"
+    },
+    {
+      "name": "Kitchen",
+      "mac": "aa:b1:cc:d1:ee:f1",
+      "type": "shade",
+      "gen": "2S"
+    },
+    {
+      "name": "Lounge",
+      "mac": "a1:bb:c1:dd:e1:ff",
+      "type": "shade",
+      "gen": "2S"
+    }
+  ]
+}
+```
+
+### get_shade_state(mac)
+
+Returns the firmware version and current position of the shade:
+
+```json
+{
+  "result": "success",
+  "version": "2.3.1",
+  "mac": "aa:bb:cc:dd:ee:ff",
+  "position": 100
+}
+```
+
+### open_shade(mac)
+
+This method will open the shade unless stopped by manually calling `stop_shade()`.
+
+Returns:
+
+```json
+{ "result": "success", "version": "2.3.1", "mac": "aa:bb:cc:dd:ee:ff" }
+```
+
+### close_shade(mac)
+
+This method will close the shade unless stopped by manually calling `stop_shade()`.
+
+Returns:
+
+```json
+{ "result": "success", "version": "2.3.1", "mac": "aa:bb:cc:dd:ee:ff" }
+```
+
+### stop_shade(mac)
+
+This method will stop any movement currently in progress.
+
+Returns:
+
+```json
+{ "result": "success", "version": "2.3.1", "mac": "aa:bb:cc:dd:ee:ff" }
+```
+
+### set_shade_position(MAC, position: int)
+
+This method will set the shade to the position specified, where 0 is fully open
+and 100 is fully closed.
+
+Returns:
+
+```json
+{ "result": "success", "version": "2.3.1", "mac": "aa:bb:cc:dd:ee:ff" }
+```
+
+### get_battery_level(mac)
+
+Returns the current battery level of the shade: