docs: tutorial is now done.

Signed-off-by: Romain Bezut <[email protected]>

docs/requirements.txt

@@ -1,5 +1,5 @@
 furo==2024.8.6
 sphinx==8.0.2
-sphinx_inline_tabs==2023.4.21
 sphinx_autodoc_typehints==2.4.4
+sphinx_inline_tabs==2023.4.21
 sphinx_copybutton==0.5.2

docs/start/tutorial.rst

@@ -187,4 +187,42 @@ commands to the device (as it is restarting).
 Reading reports
 ---------------
 
+Reports are push by the device to the serial link regularly and contain detection results.
+Advanced reports cat be requested using the engineering mode, which will not be covered in
+this tutorial (see :meth:`LD2410.set_engineering_mode` and :class:`ReportEngineeringStatus`).
 
+Three methods are provided to get the same thing, reports:
+- :meth:`LD2410.get_last_report` to get the latest received report immediately
+- :meth:`LD2410.get_next_report` to wait and get the next available report
+- :meth:`LD2410.get_reports` to get reports in an asynchronous iterator
+
+Note that reports are not generated while the configuration mode is active.
+
+The following example runs with the already configured value and reports static and moving
+targets as they arrive. Run this and hang around in front of the sensor to see changes.
+
+.. literalinclude:: ../../examples/read_basic_reports.py
+   :caption: examples/read_basic_reports.py
+   :linenos:
+
+And of course the output result:
+
+.. code-block:: console
+
+   $ ./examples/read_basic_reports.py
+     STATIC > dist  37 (energy  56) | MOVING > dist  27 (energy  71) | DETECT > dist  33
+     STATIC > dist  27 (energy  56) | MOVING > dist  34 (energy  45) | DETECT > dist  32
+     STATIC > dist  34 (energy  54) |                                | DETECT > dist  32
+     STATIC > dist  34 (energy  54) | MOVING > dist  38 (energy  41) | DETECT > dist  31
+     STATIC > dist  38 (energy  53) | MOVING > dist  41 (energy  41) | DETECT > dist  32
+     STATIC > dist  41 (energy  55) | MOVING > dist  47 (energy  71) | DETECT > dist  32
+     STATIC > dist  47 (energy  56) |                                | DETECT > dist  33
+     STATIC > dist  47 (energy  56) |                                | DETECT > dist  34
+     STATIC > dist  47 (energy  57) |                                | DETECT > dist  36
+     STATIC > dist  47 (energy  57) |                                | DETECT > dist  36
+
+
+Depending on your use case, you might want to change the configuration parameters and run
+this script again to find suitable values.
+
+This tutorial is now complete, to go further consider taking a look at the :ref:`reference`.

examples/read_basic_reports.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+
+import asyncio
+from aio_ld2410 import LD2410, TargetStatus
+
+def format_basic_report(rep) -> str:
+    items = []
+
+    if rep.target_status & TargetStatus.STATIC:
+        items.append(
+            f'STATIC > dist {rep.static_distance:3d}'
+            f' (energy {rep.static_energy:3d})'
+        )
+    else:
+        items.append(30 * ' ')
+
+    if rep.target_status & TargetStatus.MOVING:
+        items.append(
+            f'MOVING > dist {rep.moving_distance:3d}'
+            f' (energy {rep.moving_energy:3d})'
+        )
+    else:
+        items.append(30 * ' ')
+
+    if rep.target_status:
+        items.append(f'DETECT > dist {rep.detection_distance:3d}')
+    else:
+        items.append('')
+
+    return ' | '.join(items)
+
+
+async def main():
+    async with LD2410('/dev/ttyUSB0') as device:
+        async for report in device.get_reports():
+            print('  ' + format_basic_report(report.basic))
+
+if __name__ == '__main__':
+    asyncio.run(main())

examples/read_simple_configuration.py

@@ -5,7 +5,7 @@
 from collections.abc import Iterable
 
 def format_values(values: Iterable[int]) -> str:
-    return ' | '.join(map(lambda val: f'{val:3d}', values))
+    return ' | '.join(map('{:3d}'.format, values))
 
 async def main():
     async with LD2410('/dev/ttyUSB0') as device:

tests/requirements-linting.txt

@@ -1,4 +1,4 @@
 mypy==1.11.2
-ruff==0.6.7
+ruff==0.6.8
 construct-typing==0.6.2
 typing_extensions==4.12.2