docs: Add Rotary API docs.

Signed-off-by: lbuque <[email protected]>

docs/en/hardware/index.rst

@@ -5,3 +5,4 @@ Hardware
     :maxdepth: 1
 
     power.rst
+    rotary.rst

docs/en/hardware/rotary.rst

@@ -0,0 +1,138 @@
+Rotary
+======
+
+.. include:: ../refs/hardware.rotary.ref
+
+
+Rotary is used to control the rotary encoder integrated inside the host. Below
+is the detailed Rotary support for the host:
+
+.. table::
+    :widths: auto
+    :align: center
+
+    +-----------------+--------+
+    | Controller      | Rotary |
+    +=================+========+
+    | Dial            | |S|    |
+    +-----------------+--------+
+    | DinMeter        | |S|    |
+    +-----------------+--------+
+
+.. |S| unicode:: U+2714
+
+
+Micropython Example::
+
+    import os, sys, io
+    import M5
+    from M5 import *
+    from hardware import *
+
+    label0 = None
+    rotary = None
+
+    def btnA_wasClicked_event(state):
+        global label0, rotary
+        rotary.reset_rotary_value()
+        label0.setText(str(rotary.get_rotary_value()))
+
+    def setup():
+        global label0, rotary
+
+        M5.begin()
+        Widgets.fillScreen(0x222222)
+        label0 = Widgets.Label("0", 96, 80, 1.0, 0xffa000, 0x222222, Widgets.FONTS.DejaVu72)
+
+        BtnA.setCallback(type=BtnA.CB_TYPE.WAS_CLICKED, cb=btnA_wasClicked_event)
+
+        rotary = Rotary()
+
+    def loop():
+        global label0, rotary
+        M5.update()
+        if rotary.get_rotary_status():
+            label0.setText(str(rotary.get_rotary_value()))
+
+    if __name__ == '__main__':
+        try:
+            setup()
+            while True:
+            loop()
+        except (Exception, KeyboardInterrupt) as e:
+            try:
+            from utility import print_error_msg
+            print_error_msg(e)
+            except ImportError:
+            print("please update to latest firmware")
+
+
+UIFLOW2 Example:
+
+    |example.svg|
+
+
+class Rotary
+------------
+
+Constructors
+------------
+
+.. class:: Rotary()
+
+    Creates a Rotary object.
+
+    UIFLOW2:
+
+        |init.svg|
+
+Methods
+-------
+
+.. method:: Rotary.get_rotary_status() -> bool
+
+    Gets the rotation status of the Rotary object.
+
+    UIFLOW2:
+
+        |get_rotary_status.svg|
+
+
+.. method:: Rotary.get_rotary_value() -> int
+
+    .. note:: Cannot be used simultaneously with :meth:`Rotary.get_rotary_increments()`.
+
+    Gets the rotation value of the Rotary object.
+
+    UIFLOW2:
+
+        |get_rotary_value.svg|
+
+
+.. method:: Rotary.get_rotary_increments() -> int
+
+    .. note:: Cannot be used simultaneously with :meth:`Rotary.get_rotary_increments()`.
+
+    Gets the rotation value of the Rotary object.
+
+    UIFLOW2:
+
+        |get_rotary_increments.svg|
+
+
+.. method:: Rotary.reset_rotary_value() -> None
+
+    Resets the rotation value of the Rotary object.
+
+    UIFLOW2:
+
+        |reset_rotary_value.svg|
+
+
+.. method:: Rotary.set_rotary_value() -> None
+
+    Sets the rotation value of the Rotary object.
+
+    UIFLOW2:
+
+        |set_rotary_value.svg|

docs/en/refs/hardware.rotary.ref

@@ -0,0 +1,13 @@
+.. |example.svg| image:: ../../_static/hardware/rotary/example.svg
+
+.. |init.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/init.svg
+
+.. |get_rotary_status.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_status.svg
+
+.. |get_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_value.svg
+
+.. |reset_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/reset_rotary_value.svg
+
+.. |set_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/set_rotary_value.svg
+
+.. |get_rotary_increments.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_increments.svg

docs/zh_CN/hardware/index.rst

@@ -9,3 +9,4 @@ Hardware
     speaker.rst
     imu.rst
     power.rst
+    rotary.rst

docs/zh_CN/hardware/rotary.rst

@@ -0,0 +1,137 @@
+Rotary
+======
+
+.. include:: ../refs/hardware.rotary.ref
+
+
+Rotary 用于控制主机内部集成的旋转编码器。以下是主机的 Rotary 支持详细：
+
+.. table::
+    :widths: auto
+    :align: center
+
+    +-----------------+--------+
+    | Controller      | Rotary |
+    +=================+========+
+    | Dial            | |S|    |
+    +-----------------+--------+
+    | DinMeter        | |S|    |
+    +-----------------+--------+
+
+.. |S| unicode:: U+2714
+
+
+Micropython Example::
+
+    import os, sys, io
+    import M5
+    from M5 import *
+    from hardware import *
+
+    label0 = None
+    rotary = None
+
+    def btnA_wasClicked_event(state):
+        global label0, rotary
+        rotary.reset_rotary_value()
+        label0.setText(str(rotary.get_rotary_value()))
+
+    def setup():
+        global label0, rotary
+
+        M5.begin()
+        Widgets.fillScreen(0x222222)
+        label0 = Widgets.Label("0", 96, 80, 1.0, 0xffa000, 0x222222, Widgets.FONTS.DejaVu72)
+
+        BtnA.setCallback(type=BtnA.CB_TYPE.WAS_CLICKED, cb=btnA_wasClicked_event)
+
+        rotary = Rotary()
+
+    def loop():
+        global label0, rotary
+        M5.update()
+        if rotary.get_rotary_status():
+            label0.setText(str(rotary.get_rotary_value()))
+
+    if __name__ == '__main__':
+        try:
+            setup()
+            while True:
+            loop()
+        except (Exception, KeyboardInterrupt) as e:
+            try:
+            from utility import print_error_msg
+            print_error_msg(e)
+            except ImportError:
+            print("please update to latest firmware")
+
+
+UIFLOW2 Example:
+
+    |example.svg|
+
+
+class Rotary
+------------
+
+Constructors
+------------
+
+.. class:: Rotary()
+
+    创建一个 Rotary 对象.
+
+    UIFLOW2:
+
+        |init.svg|
+
+Methods
+-------
+
+.. method:: Rotary.get_rotary_status() -> bool
+
+    获取 Rotary 对象的旋转状态。
+
+    UIFLOW2:
+
+        |get_rotary_status.svg|
+
+
+.. method:: Rotary.get_rotary_value() -> int
+
+    .. note:: 不能和 :meth:`Rotary.get_rotary_increments()` 同时使用
+
+    获取 Rotary 对象的旋转值。
+
+    UIFLOW2:
+
+        |get_rotary_value.svg|
+
+
+.. method:: Rotary.get_rotary_increments() -> int
+
+    .. note:: 不能和 :meth:`Rotary.get_rotary_status()` 同时使用
+
+    获取 Rotary 对象的旋转增量。可用于判断旋转方向。
+
+    UIFLOW2:
+
+        |get_rotary_increments.svg|
+
+
+.. method:: Rotary.reset_rotary_value() -> None
+
+    重置 Rotary 对象的旋转值。
+
+    UIFLOW2:
+
+        |reset_rotary_value.svg|
+
+
+.. method:: Rotary.set_rotary_value() -> None
+
+    设置 Rotary 对象的旋转值。
+
+    UIFLOW2:
+
+        |set_rotary_value.svg|

docs/zh_CN/refs/hardware.rotary.ref

@@ -0,0 +1,13 @@
+.. |example.svg| image:: ../../_static/hardware/rotary/example.svg
+
+.. |init.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/init.svg
+
+.. |get_rotary_status.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_status.svg
+
+.. |get_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_value.svg
+
+.. |reset_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/reset_rotary_value.svg
+
+.. |set_rotary_value.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/set_rotary_value.svg
+
+.. |get_rotary_increments.svg| image:: https://m5stack.oss-cn-shenzhen.aliyuncs.com/mpy_docs/hardware/rotary/get_rotary_increments.svg