Merge pull request #62 from tiagocoutinho/gpio-doc

GPIO doc

Author: tiagocoutinho

docs/user_guide/gpio.md

@@ -167,8 +167,8 @@ Here are the line configuration options with their restrictions and defaults:
     * possible values: `input`, `output`
     * default: **input**
 * *active*:
-    * possible values: `active`, `low`
-    * default: **active**
+    * possible values: `high`, `low`
+    * default: **high**
 * *bias*:
     * possbile values: `pull-up`, `pull-down`, `none`
     * default: **none**
@@ -294,6 +294,8 @@ event = next(iter(lines))
 
 ```
 
+### asyncio
+
 Async API is also supported:
 
 ```python
@@ -309,3 +311,62 @@ async def main():
 
 asyncio.run(main())
 ```
+
+## Configuration events
+
+Linuxpy GPIO API supports watching for line configuration events:
+
+```python
+
+with find() as gpio:
+    for event in gpio.info_stream([5, 10]):
+        print(event)
+
+```
+
+The example above will listen for configuration change, line request and line
+released events on lines 5 and 10.
+
+If you need fine control you can manually register for line watch and then
+listen for events. So the above example can also be written as:
+
+```python
+
+with find() as gpio:
+    with gpio.watching([5, 10]):
+        for event in gpio:
+            print(event)
+```
+
+Or even:
+
+```python
+
+with find() as gpio:
+    gpio.watch_lines([5, 10])
+    try:
+        for event in gpio:
+            print(event)
+    finally:
+        gpio.unwatch_lines([5, 10])
+
+```
+
+### asyncio
+
+Async API is also supported on configuration events:
+
+```python
+import asyncio
+import contextlib
+
+
+async def main():
+    with find() as gpio:
+        async with contextlib.aclosing(gpio.async_info_stream([5, 10])) as stream:
+            async for event in stream:
+                print(event)
+
+
+asyncio.run(main())
+```

linuxpy/gpio/device.py

@@ -541,10 +541,10 @@ def __getitem__(self, key: Union[int, tuple, slice]) -> Request:
         return self.request(lines)
 
     def __iter__(self) -> Iterable[LineInfoEvent]:
-        """Infinite stream of line info events
+        """Infinite stream of line config events
 
         Returns:
-            Iterable[LineInfoEvent]: the stream of line info events
+            Iterable[LineInfoEvent]: the stream of line config events
         """
         return event_info_stream((self,))
 
@@ -557,10 +557,28 @@ def __aiter__(self) -> AsyncIterator[LineInfoEvent]:
         return async_event_info_stream((self,))
 
     def info_stream(self, lines: Collection[int]) -> Iterable[LineInfoEvent]:
+        """Register for watching line config events on the given lines
+        and stream them
+
+        Args:
+            lines (Collection[int]): line numbers to watch for config events
+
+        Returns:
+            Iterable[LineInfoEvent]: the stream of line config events
+        """
         with self.watching(lines):
             yield from iter(self)
 
     async def async_info_stream(self, lines: Collection[int]) -> AsyncIterator[LineInfoEvent]:
+        """Register for watching line config events on the given lines
+        and async stream them
+
+        Args:
+            lines (Collection[int]): line numbers to watch for config events
+
+        Returns:
+            AsyncIterator[LineInfoEvent]: the asynchronous stream of line info events
+        """
         with self.watching(lines):
             async with aclosing(self.__aiter__()) as stream:
                 async for event in stream:
@@ -577,21 +595,47 @@ def get_info(self) -> Info:
         return get_info(self)
 
     def watch_line(self, line: int):
+        """Register the given line for config events
+
+        Args:
+            line (int): the line number to register
+        """
         watch_line_info(self, line)
 
     def unwatch_line(self, line: int):
+        """Unregister the given line from config events
+
+        Args:
+            line (int): the line number to unregister
+        """
         unwatch_line_info(self, line)
 
     def watch_lines(self, lines: Collection[int]):
+        """Register the given lines for config events
+
+        Args:
+            lines (Collection[int]): the line numbers to register
+        """
         for line in lines:
             self.watch_line(line)
 
     def unwatch_lines(self, lines: Collection[int]):
+        """Unregister the given lines from config events
+
+        Args:
+            lines (Collection[int]): the lines number to unregister
+        """
         for line in lines:
             self.unwatch_line(line)
 
     @contextlib.contextmanager
     def watching(self, lines):
+        """A context manager during which the given lines are registered
+        for line config events
+
+        Args:
+            lines (_type_): the line numbers to listen for config events
+        """
         self.watch_lines(lines)
         try:
             yield

scripts/setup-gpio-sim.py

@@ -45,15 +45,19 @@ def mkdir(path):
     path.mkdir()
 
 
+def cleanup(path):
+    # clean up first
+    if path.exists():
+        live.write_text("0")
+        for directory, _, _ in path.walk(top_down=False):
+            directory.rmdir()
+
+
 path = CONFIGFS_PATH / cfg["name"]
 live = path / "live"
 
-# clean up first
-if path.exists():
-    live.write_text("0")
-    for directory, _, _ in path.walk(top_down=False):
-        directory.rmdir()
 
+cleanup(path)
 
 mkdir(path)
 for bank_id, bank in enumerate(cfg["banks"]):