diff --git a/doc/api/index.rst b/doc/api/index.rst index 61381ca..77a28e4 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -78,7 +78,7 @@ findings on our `support page`_ so we can make Pybricks even better. nxtdevices iodevices parameters - tools + tools/index robotics media messaging diff --git a/doc/api/tools.rst b/doc/api/tools.rst deleted file mode 100644 index fd7bb87..0000000 --- a/doc/api/tools.rst +++ /dev/null @@ -1,89 +0,0 @@ -:mod:`tools ` -- Timing and Data logging -======================================================== - -.. automodule:: pybricks.tools - :no-members: - -.. autofunction:: wait - -.. autoclass:: pybricks.tools.StopWatch - :no-members: - - .. automethod:: pybricks.tools.StopWatch.time - - .. automethod:: pybricks.tools.StopWatch.pause - - .. automethod:: pybricks.tools.StopWatch.resume - - .. automethod:: pybricks.tools.StopWatch.reset - -.. autoclass:: pybricks.tools.DataLog - :no-members: - - .. automethod:: pybricks.tools.DataLog.log - - By default, this class creates a ``csv`` file on the EV3 brick with the - name ``log`` and the current date and time. For example, if you - use this class on 13 February 2020 on 10:07 and 44.431260 - seconds, the file is called ``log_2020_02_13_10_07_44_431260.csv``. - - See :ref:`managing files on the EV3 ` to learn how to upload - the log file back to your computer. - -.. toggle-header:: - :header: **Show/hide example: Logging and visualizing measurements** - - - - **Example** - - This example shows how to log the angle of a rotating wheel as time passes. - - .. literalinclude:: ../../examples/ev3/datalog/main.py - - In this example, the generated file has the following contents:: - - time, angle - 3, 0 - 108, 6 - 212, 30 - 316, 71 - 419, 124 - 523, 176 - 628, 228 - 734, 281 - 838, 333 - 942, 385 - - When you upload the file to your computer as shown above, you can open it - in a spreadsheet editor. You can then generate a graph of the data, as - shown in :numref:`fig_datalog_graph`. - - In this example, we see that the motor angle changes slowly at first. Then - the angle begins to change faster, and the graph becomes a straight line. - This means that the motor has reached a constant speed. You can verify that - the angle increases by 500 degrees per second. - - .. _fig_datalog_graph: - - .. figure:: ../api/images/datalog_graph.png - :width: 100 % - - Original file contents (left) and a generated graph (right). - - -.. toggle-header:: - :header: **Show/hide example: Using the optional arguments** - - **Example** - - This example shows how to log data beyond just numbers. It also shows how - you can use the optional arguments of the ``DataLog`` class to choose the - file name and extension. - - In this example, ``timestamp=False``, which means that the date and time - are not added to the file name. This can be convenient because the file - name will always be the same. However, this means that the contents of - ``my_file.txt`` will be overwritten every time you run this script. - - .. literalinclude:: ../../examples/ev3/datalog_extra/main.py diff --git a/doc/api/tools/datalog.rst b/doc/api/tools/datalog.rst new file mode 100644 index 0000000..3342be9 --- /dev/null +++ b/doc/api/tools/datalog.rst @@ -0,0 +1,73 @@ +Data logging +^^^^^^^^^^^^^^^^^^^^^^^^^ + +At the moment, this class is only available on EV3. + +.. autoclass:: pybricks.tools.DataLog + :no-members: + + .. automethod:: pybricks.tools.DataLog.log + + By default, this class creates a ``csv`` file on the EV3 brick with the + name ``log`` and the current date and time. For example, if you + use this class on 13 February 2020 on 10:07 and 44.431260 + seconds, the file is called ``log_2020_02_13_10_07_44_431260.csv``. + + See :ref:`managing files on the EV3 ` to learn how to upload + the log file back to your computer. + + +Examples +------------------- + +Logging and visualizing measurements +************************************ + +This example shows how to log the angle of a rotating wheel as time passes. + +.. literalinclude:: ../../../examples/ev3/datalog/main.py + +In this example, the generated file has the following contents:: + + time, angle + 3, 0 + 108, 6 + 212, 30 + 316, 71 + 419, 124 + 523, 176 + 628, 228 + 734, 281 + 838, 333 + 942, 385 + +When you upload the file to your computer as shown above, you can open it +in a spreadsheet editor. You can then generate a graph of the data, as +shown in :numref:`fig_datalog_graph`. + +In this example, we see that the motor angle changes slowly at first. Then +the angle begins to change faster, and the graph becomes a straight line. +This means that the motor has reached a constant speed. You can verify that +the angle increases by 500 degrees per second. + +.. _fig_datalog_graph: + +.. figure:: ../../api/images/datalog_graph.png + :width: 100 % + + Original file contents (left) and a generated graph (right). + + +Using the optional arguments +**************************** + +This example shows how to log data beyond just numbers. It also shows how +you can use the optional arguments of the ``DataLog`` class to choose the +file name and extension. + +In this example, ``timestamp=False``, which means that the date and time +are not added to the file name. This can be convenient because the file +name will always be the same. However, this means that the contents of +``my_file.txt`` will be overwritten every time you run this script. + +.. literalinclude:: ../../../examples/ev3/datalog_extra/main.py diff --git a/doc/api/tools/index.rst b/doc/api/tools/index.rst new file mode 100644 index 0000000..9bc023a --- /dev/null +++ b/doc/api/tools/index.rst @@ -0,0 +1,28 @@ +:mod:`tools ` -- General purpose tools +======================================================== + +.. automodule:: pybricks.tools + :no-members: + +.. toctree:: + :maxdepth: 1 + :hidden: + + datalog + +Timing +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autofunction:: wait + +.. autoclass:: pybricks.tools.StopWatch + :no-members: + + .. automethod:: pybricks.tools.StopWatch.time + + .. automethod:: pybricks.tools.StopWatch.pause + + .. automethod:: pybricks.tools.StopWatch.resume + + .. automethod:: pybricks.tools.StopWatch.reset +