From 33f6117472d43b0b2520d85f1ee00b6cde805ecf Mon Sep 17 00:00:00 2001 From: sonelu Date: Tue, 19 May 2020 21:07:23 +0100 Subject: [PATCH] documentation updates --- docs/reference/base.rst | 14 ++-- .../base/roboglia.base.BaseRobot.rst | 1 + docs/reference/base/roboglia.base.Joint.rst | 3 + .../base/roboglia.base.JointManager.rst | 66 ++++++++++++++++++ docs/reference/base/roboglia.base.JointPV.rst | 3 + .../reference/base/roboglia.base.JointPVL.rst | 3 + .../base/roboglia.base.SensorXYZ.rst | 54 +++++++++++++++ docs/reference/move.rst | 11 +++ docs/reference/move/roboglia.move.Frame.rst | 41 +++++++++++ docs/reference/move/roboglia.move.Scene.rst | 41 +++++++++++ docs/reference/move/roboglia.move.Script.rst | 68 +++++++++++++++++++ .../reference/move/roboglia.move.Sequence.rst | 42 ++++++++++++ .../reference/move/roboglia.move.StepLoop.rst | 3 + docs/reference/utils.rst | 4 +- roboglia/base/__init__.py | 1 + roboglia/base/joint.py | 7 +- roboglia/base/robot.py | 4 +- roboglia/base/sensor.py | 10 +-- roboglia/dynamixel/bus.py | 27 ++++---- roboglia/dynamixel/register.py | 8 +++ roboglia/i2c/bus.py | 9 +-- roboglia/i2c/device.py | 4 +- roboglia/move/__init__.py | 4 ++ 23 files changed, 388 insertions(+), 40 deletions(-) create mode 100644 docs/reference/base/roboglia.base.JointManager.rst create mode 100644 docs/reference/base/roboglia.base.SensorXYZ.rst create mode 100644 docs/reference/move/roboglia.move.Frame.rst create mode 100644 docs/reference/move/roboglia.move.Scene.rst create mode 100644 docs/reference/move/roboglia.move.Script.rst create mode 100644 docs/reference/move/roboglia.move.Sequence.rst diff --git a/docs/reference/base.rst b/docs/reference/base.rst index 5c430b6..54010db 100755 --- a/docs/reference/base.rst +++ b/docs/reference/base.rst @@ -67,11 +67,12 @@ various structural elements of a robot. :toctree: base BaseRobot + JointManager **Upstream** The following classes from ``base`` module are provided for helping with -the syncronisation of devices' values task. +the synchronization of devices' values task. *Joints* @@ -83,18 +84,11 @@ the syncronisation of devices' values task. JointPV JointPVL -*Sonsors* +*Sensors* .. autosummary:: :nosignatures: :toctree: base Sensor - -*Controller* - -.. autosummary:: - :nosignatures: - :toctree: base - - Controller + SensorXYZ \ No newline at end of file diff --git a/docs/reference/base/roboglia.base.BaseRobot.rst b/docs/reference/base/roboglia.base.BaseRobot.rst index 5f48117..1a5b40a 100644 --- a/docs/reference/base/roboglia.base.BaseRobot.rst +++ b/docs/reference/base/roboglia.base.BaseRobot.rst @@ -31,6 +31,7 @@ roboglia.base.BaseRobot ~BaseRobot.groups ~BaseRobot.inits ~BaseRobot.joints + ~BaseRobot.manager ~BaseRobot.name ~BaseRobot.sensors ~BaseRobot.syncs diff --git a/docs/reference/base/roboglia.base.Joint.rst b/docs/reference/base/roboglia.base.Joint.rst index e8ec826..9b03772 100644 --- a/docs/reference/base/roboglia.base.Joint.rst +++ b/docs/reference/base/roboglia.base.Joint.rst @@ -13,6 +13,7 @@ roboglia.base.Joint .. autosummary:: ~Joint.__init__ + ~Joint.desired @@ -34,6 +35,7 @@ roboglia.base.Joint ~Joint.position_read_register ~Joint.position_write_register ~Joint.range + ~Joint.value @@ -44,5 +46,6 @@ roboglia.base.Joint .. automethod:: __init__ + .. automethod:: desired \ No newline at end of file diff --git a/docs/reference/base/roboglia.base.JointManager.rst b/docs/reference/base/roboglia.base.JointManager.rst new file mode 100644 index 0000000..f882e15 --- /dev/null +++ b/docs/reference/base/roboglia.base.JointManager.rst @@ -0,0 +1,66 @@ +roboglia.base.JointManager +========================== + +.. currentmodule:: roboglia.base + +.. autoclass:: JointManager + + + + + .. rubric:: Methods + + .. autosummary:: + + ~JointManager.__init__ + ~JointManager.atomic + ~JointManager.pause + ~JointManager.resume + ~JointManager.run + ~JointManager.setup + ~JointManager.start + ~JointManager.stop + ~JointManager.stop_submit + ~JointManager.submit + ~JointManager.teardown + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~JointManager.frequency + ~JointManager.joints + ~JointManager.name + ~JointManager.paused + ~JointManager.period + ~JointManager.review + ~JointManager.running + ~JointManager.started + ~JointManager.stopped + ~JointManager.warning + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + .. automethod:: atomic + .. automethod:: pause + .. automethod:: resume + .. automethod:: run + .. automethod:: setup + .. automethod:: start + .. automethod:: stop + .. automethod:: stop_submit + .. automethod:: submit + .. automethod:: teardown + + \ No newline at end of file diff --git a/docs/reference/base/roboglia.base.JointPV.rst b/docs/reference/base/roboglia.base.JointPV.rst index b15d8bc..dd2e9fb 100644 --- a/docs/reference/base/roboglia.base.JointPV.rst +++ b/docs/reference/base/roboglia.base.JointPV.rst @@ -13,6 +13,7 @@ roboglia.base.JointPV .. autosummary:: ~JointPV.__init__ + ~JointPV.desired @@ -35,6 +36,7 @@ roboglia.base.JointPV ~JointPV.position_read_register ~JointPV.position_write_register ~JointPV.range + ~JointPV.value ~JointPV.velocity ~JointPV.velocity_read_register ~JointPV.velocity_write_register @@ -48,5 +50,6 @@ roboglia.base.JointPV .. automethod:: __init__ + .. automethod:: desired \ No newline at end of file diff --git a/docs/reference/base/roboglia.base.JointPVL.rst b/docs/reference/base/roboglia.base.JointPVL.rst index d969592..a7a4241 100644 --- a/docs/reference/base/roboglia.base.JointPVL.rst +++ b/docs/reference/base/roboglia.base.JointPVL.rst @@ -13,6 +13,7 @@ roboglia.base.JointPVL .. autosummary:: ~JointPVL.__init__ + ~JointPVL.desired @@ -39,6 +40,7 @@ roboglia.base.JointPVL ~JointPVL.position_read_register ~JointPVL.position_write_register ~JointPVL.range + ~JointPVL.value ~JointPVL.velocity ~JointPVL.velocity_read_register ~JointPVL.velocity_write_register @@ -52,5 +54,6 @@ roboglia.base.JointPVL .. automethod:: __init__ + .. automethod:: desired \ No newline at end of file diff --git a/docs/reference/base/roboglia.base.SensorXYZ.rst b/docs/reference/base/roboglia.base.SensorXYZ.rst new file mode 100644 index 0000000..d80c8dd --- /dev/null +++ b/docs/reference/base/roboglia.base.SensorXYZ.rst @@ -0,0 +1,54 @@ +roboglia.base.SensorXYZ +======================= + +.. currentmodule:: roboglia.base + +.. autoclass:: SensorXYZ + + + + + .. rubric:: Methods + + .. autosummary:: + + ~SensorXYZ.__init__ + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~SensorXYZ.activate_register + ~SensorXYZ.active + ~SensorXYZ.auto_activate + ~SensorXYZ.device + ~SensorXYZ.name + ~SensorXYZ.value + ~SensorXYZ.x + ~SensorXYZ.x_inverse + ~SensorXYZ.x_offset + ~SensorXYZ.x_register + ~SensorXYZ.y + ~SensorXYZ.y_inverse + ~SensorXYZ.y_offset + ~SensorXYZ.y_register + ~SensorXYZ.z + ~SensorXYZ.z_inverse + ~SensorXYZ.z_offset + ~SensorXYZ.z_register + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + + \ No newline at end of file diff --git a/docs/reference/move.rst b/docs/reference/move.rst index 96005f8..8bf1e59 100644 --- a/docs/reference/move.rst +++ b/docs/reference/move.rst @@ -14,3 +14,14 @@ allowing to store and execute predetermined routine movements. :toctree: move StepLoop + +*Scrips* + +.. autosummary:: + :nosignatures: + :toctree: move + + Script + Scene + Sequence + Frame diff --git a/docs/reference/move/roboglia.move.Frame.rst b/docs/reference/move/roboglia.move.Frame.rst new file mode 100644 index 0000000..2f689a0 --- /dev/null +++ b/docs/reference/move/roboglia.move.Frame.rst @@ -0,0 +1,41 @@ +roboglia.move.Frame +=================== + +.. currentmodule:: roboglia.move + +.. autoclass:: Frame + + + + + .. rubric:: Methods + + .. autosummary:: + + ~Frame.__init__ + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Frame.commands + ~Frame.loads + ~Frame.name + ~Frame.positions + ~Frame.velocities + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + + \ No newline at end of file diff --git a/docs/reference/move/roboglia.move.Scene.rst b/docs/reference/move/roboglia.move.Scene.rst new file mode 100644 index 0000000..54981ec --- /dev/null +++ b/docs/reference/move/roboglia.move.Scene.rst @@ -0,0 +1,41 @@ +roboglia.move.Scene +=================== + +.. currentmodule:: roboglia.move + +.. autoclass:: Scene + + + + + .. rubric:: Methods + + .. autosummary:: + + ~Scene.__init__ + ~Scene.play + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Scene.name + ~Scene.sequences + ~Scene.times + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + .. automethod:: play + + \ No newline at end of file diff --git a/docs/reference/move/roboglia.move.Script.rst b/docs/reference/move/roboglia.move.Script.rst new file mode 100644 index 0000000..598fe4e --- /dev/null +++ b/docs/reference/move/roboglia.move.Script.rst @@ -0,0 +1,68 @@ +roboglia.move.Script +==================== + +.. currentmodule:: roboglia.move + +.. autoclass:: Script + + + + + .. rubric:: Methods + + .. autosummary:: + + ~Script.__init__ + ~Script.atomic + ~Script.from_yaml + ~Script.pause + ~Script.play + ~Script.resume + ~Script.run + ~Script.setup + ~Script.start + ~Script.stop + ~Script.teardown + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Script.frames + ~Script.joints + ~Script.name + ~Script.paused + ~Script.robot + ~Script.running + ~Script.scenes + ~Script.script + ~Script.sequences + ~Script.started + ~Script.stopped + ~Script.times + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + .. automethod:: atomic + .. automethod:: from_yaml + .. automethod:: pause + .. automethod:: play + .. automethod:: resume + .. automethod:: run + .. automethod:: setup + .. automethod:: start + .. automethod:: stop + .. automethod:: teardown + + \ No newline at end of file diff --git a/docs/reference/move/roboglia.move.Sequence.rst b/docs/reference/move/roboglia.move.Sequence.rst new file mode 100644 index 0000000..9e3b7c3 --- /dev/null +++ b/docs/reference/move/roboglia.move.Sequence.rst @@ -0,0 +1,42 @@ +roboglia.move.Sequence +====================== + +.. currentmodule:: roboglia.move + +.. autoclass:: Sequence + + + + + .. rubric:: Methods + + .. autosummary:: + + ~Sequence.__init__ + ~Sequence.play + + + + + + .. rubric:: Attributes + + .. autosummary:: + + ~Sequence.durations + ~Sequence.frames + ~Sequence.name + ~Sequence.times + + + + + + + .. rubric:: Methods in detail + + + .. automethod:: __init__ + .. automethod:: play + + \ No newline at end of file diff --git a/docs/reference/move/roboglia.move.StepLoop.rst b/docs/reference/move/roboglia.move.StepLoop.rst index 0089ed5..b5b3e47 100644 --- a/docs/reference/move/roboglia.move.StepLoop.rst +++ b/docs/reference/move/roboglia.move.StepLoop.rst @@ -15,6 +15,7 @@ roboglia.move.StepLoop ~StepLoop.__init__ ~StepLoop.atomic ~StepLoop.pause + ~StepLoop.play ~StepLoop.resume ~StepLoop.run ~StepLoop.setup @@ -35,6 +36,7 @@ roboglia.move.StepLoop ~StepLoop.running ~StepLoop.started ~StepLoop.stopped + ~StepLoop.times @@ -47,6 +49,7 @@ roboglia.move.StepLoop .. automethod:: __init__ .. automethod:: atomic .. automethod:: pause + .. automethod:: play .. automethod:: resume .. automethod:: run .. automethod:: setup diff --git a/docs/reference/utils.rst b/docs/reference/utils.rst index ac42b84..0d46ede 100644 --- a/docs/reference/utils.rst +++ b/docs/reference/utils.rst @@ -1,6 +1,6 @@ -=============== +================ ``utils`` Module -=============== +================ .. automodule:: roboglia.utils diff --git a/roboglia/base/__init__.py b/roboglia/base/__init__.py index 1c03691..40feb0c 100644 --- a/roboglia/base/__init__.py +++ b/roboglia/base/__init__.py @@ -27,6 +27,7 @@ from .sync import BaseWriteSync # noqa: 401 from .robot import BaseRobot # noqa: 401 +from .robot import JointManager # noqa: 401 register_class(FileBus) register_class(SharedFileBus) diff --git a/roboglia/base/joint.py b/roboglia/base/joint.py index 967e134..bc37772 100644 --- a/roboglia/base/joint.py +++ b/roboglia/base/joint.py @@ -61,7 +61,7 @@ class Joint(): which is also the default maxim: float or ``None`` - Introduces a maximum limit for the joint value; ignored if ``None + Introduces a maximum limit for the joint value; ignored if ``None`` which is also the default auto: bool @@ -343,8 +343,9 @@ class JointPVL(JointPV): It inherits all the paramters from :py:class:`JointPV` and adds the following additional ones: - Paramters - --------- + Parameters + ---------- + load_read: str The register name used to retrieve current load diff --git a/roboglia/base/robot.py b/roboglia/base/robot.py index 0665cb4..050d2d0 100644 --- a/roboglia/base/robot.py +++ b/roboglia/base/robot.py @@ -484,8 +484,8 @@ def submit(self, name, commands, adjustments=False): """Used by a stream of commands to notify the Joint Manager they joint commands they want. - Paramters - --------- + Parameters + ---------- name: str The name of the stream providing the data. It is used to keep the request separate and be able to merge later. diff --git a/roboglia/base/sensor.py b/roboglia/base/sensor.py index 394741a..dafa715 100644 --- a/roboglia/base/sensor.py +++ b/roboglia/base/sensor.py @@ -31,8 +31,9 @@ class Sensor(): which case the sensor can also apply an ``inverse`` and and ``offset`` to the values read from the device registry. - Parameter - --------- + Parameters + ---------- + name: str The name of the sensor @@ -203,8 +204,9 @@ class SensorXYZ(): ``Z`` values that are floats where the sensor applies an ``inverse`` and and ``offset`` to the values read from the device registry. - Parameter - --------- + Parameters + ---------- + name: str The name of the sensor diff --git a/roboglia/dynamixel/bus.py b/roboglia/dynamixel/bus.py index e2829d7..4501f0e 100644 --- a/roboglia/dynamixel/bus.py +++ b/roboglia/dynamixel/bus.py @@ -170,7 +170,7 @@ def scan(self, range=range(254)): ---------- range: range the range of devices to be cheked if they - exist on the bus. The method will call :py:method:`~ping` + exist on the bus. The method will call :py:meth:`~ping` for each ID in the list. By default the list is [0, 253]. Returns: @@ -251,8 +251,9 @@ def write(self, reg, value): Communication and data errors are logged and no exceptions are raised. - Paramters - --------- + Parameters + ---------- + reg: BaseRegister or subclass The register to write to @@ -308,24 +309,24 @@ class SharedDynamixelBus(SharedBus): """A DynamixelBus that can be used in multithreaded environment. Includes the functionality of a :py:class:`DynamixelBus` in a - :py:class:`SharedBus`. The :py:method:`~write` and :py:method:`~read` - methods are wrapped around in :py:method:`~can_use` and - :py:method:`~stop_using` to provide the exclusive access. + :py:class:`SharedBus`. The :py:meth:`~write` and :py:meth:`~read` + methods are wrapped around in :py:meth:`~can_use` and + :py:meth:`~stop_using` to provide the exclusive access. - In addition, two methods :py:method:`~naked_write` and - :py:method:`~naked_read` are provided so that classes that want sequence + In addition, two methods :py:meth:`~naked_write` and + :py:meth:`~naked_read` are provided so that classes that want sequence of read / writes can do that more efficiently without accessing the lock every time. They simply invoke the *unsafe* methods - :py:method:DynamixelBus.`write` and :py:method:DynamixelBus.`read` from + :py:meth:DynamixelBus.`write` and :py:meth:DynamixelBus.`read` from the :py:class:`DynamixelBus` class. .. see also: :py:class:`SharedBus` class. .. warning:: - If you are using :py:method:`~naked_write` and :py:method:`~naked_read` - you **must** ensure that you wrap them in :py:method:`~can_use` and - :py:method:`~stop_using` in the calling code. + If you are using :py:meth:`~naked_write` and :py:meth:`~naked_read` + you **must** ensure that you wrap them in :py:meth:`~can_use` and + :py:meth:`~stop_using` in the calling code. """ def __init__(self, **kwargs): @@ -492,7 +493,7 @@ def readRx(self, port, dxl_id, length): then trim it to the ``min`` and ``max`` limits of the register. When passing back the data, for registers that are more than 1 byte a *low endian* conversion is executed (see - :py:meth:`DynamixelRegister.register_low_endian). + :py:meth:`DynamixelRegister.register_low_endian`). """ if random.random() < self.__err: return 0, -3001, 0 diff --git a/roboglia/dynamixel/register.py b/roboglia/dynamixel/register.py index 53e57f3..c4db5c3 100644 --- a/roboglia/dynamixel/register.py +++ b/roboglia/dynamixel/register.py @@ -32,13 +32,21 @@ class DynamixelAXBaudRateRegister(BaseRegister): | Code | Baud rate | +======+===========+ | 1 | 1000000| + +------+-----------+ | 3 | 500000| + +------+-----------+ | 4 | 400000| + +------+-----------+ | 7 | 250000| + +------+-----------+ | 9 | 200000| + +------+-----------+ | 16 | 115200| + +------+-----------+ | 34 | 57600| + +------+-----------+ | 103 | 19200| + +------+-----------+ | 207 | 9600| +------+-----------+ """ diff --git a/roboglia/i2c/bus.py b/roboglia/i2c/bus.py index 5df1609..5680111 100644 --- a/roboglia/i2c/bus.py +++ b/roboglia/i2c/bus.py @@ -31,11 +31,11 @@ class I2CBus(BaseBus): In addition there is an extra parameter `mock`. - At this mement the ``I2CBus`` supports devices with byte and word + At this moment the ``I2CBus`` supports devices with byte and word registers and permits defining composed regsiters with ``size`` > 1 that are treated as a single register. - .. example:: A gyroscope sensor might have registers for the z, y and z + .. note:: A gyroscope sensor might have registers for the z, y and z axes reading that are stored as pairs of registers like this:: gyro_x_l #0x28 @@ -193,8 +193,9 @@ def read_block_data(self, dev, address, length): Does not raise any exceptions, but logs any errors. - Paramters - --------- + Parameters + ---------- + dev: BaseDevice or subclass The device for which the block read is performed diff --git a/roboglia/i2c/device.py b/roboglia/i2c/device.py index f426f04..e29e2fb 100644 --- a/roboglia/i2c/device.py +++ b/roboglia/i2c/device.py @@ -24,9 +24,9 @@ class I2CDevice(BaseDevice): """Implements a representation of an I2C device. - It only adds an override for the :py:method:`~get_model_path` in order + It only adds an override for the :py:meth:`~get_model_path` in order to localize the device definitions in the ``device`` directory of the - ``i2c`` module and the method :py:method:`~open` that will attempt to + ``i2c`` module and the method :py:meth:`~open` that will attempt to read all the registers not marked as ``sync``. """ def __init__(self, **kwargs): diff --git a/roboglia/move/__init__.py b/roboglia/move/__init__.py index 07c6ae6..f347c81 100644 --- a/roboglia/move/__init__.py +++ b/roboglia/move/__init__.py @@ -1,2 +1,6 @@ from .thread import StepLoop # noqa: 401 + from .moves import Script # noqa: 401 +from .moves import Scene # noqa: 401 +from .moves import Sequence # noqa: 401 +from .moves import Frame # noqa: 401