diff --git a/docs/requirements.txt b/docs/requirements.txt index 274e46c..51c35a2 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/start/tutorial.rst b/docs/start/tutorial.rst index 7aa00a5..93a4223 100644 --- a/docs/start/tutorial.rst +++ b/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`. diff --git a/examples/read_basic_reports.py b/examples/read_basic_reports.py new file mode 100755 index 0000000..be7d15e --- /dev/null +++ b/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()) diff --git a/examples/read_simple_configuration.py b/examples/read_simple_configuration.py index d3fb678..f9b5900 100755 --- a/examples/read_simple_configuration.py +++ b/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: diff --git a/tests/requirements-linting.txt b/tests/requirements-linting.txt index db9a173..6ba70cf 100644 --- a/tests/requirements-linting.txt +++ b/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