lib/unit: Roller485 compatible other i2c unit.

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

Author: Tinyu-Zhao

docs/en/refs/unit.roller485.ref

@@ -3,7 +3,7 @@
     :target: https://docs.m5stack.com/en/unit/Unit-Roller485
     :height: 200px
     :width: 200px
-#base
+
 .. |init.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/init.png
 .. |set_motor_output_state.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/set_motor_output_state.png
 .. |get_motor_output_state.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/get_motor_output_state.png
@@ -54,32 +54,34 @@
 .. |set_i2c_address.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/set_i2c_address.png
 .. |get_i2c_address.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/get_i2c_address.png
 
-.. |example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/example.png
+.. |i2c_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/i2c_example.png
+.. |rs485_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/rs485_example.png
+.. |rs485_i2c_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/rs485_i2c_example.png
 
-#i2c
-.. |init2.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/init.png
-.. |read.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/read.png
-.. |write.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/write.png
+.. |roller485_i2c_fire_example.m5f2| raw:: html
 
-.. |example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/example.png
+    <a
+        href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/unit/roller485/roller485_i2c_fire_example.m5f2"
+        target="_blank"
+    >
+        roller485_i2c_fire_example.m5f2
+    </a>
 
-#485
-.. |init3.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/init.png
-.. |read.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/read.png
-.. |create_frame.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/create_frame.png
-.. |write.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/write.png
-.. |send_command.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/send_command.png
-.. |read_response.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/read_response.png
-.. |_crc8.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/_crc8.png
+.. |roller485_485_fire_example.m5f2| raw:: html
 
+    <a
+        href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/unit/roller485/roller485_485_fire_example.m5f2"
+        target="_blank"
+    >
+        roller485_485_fire_example.m5f2
+    </a>
 
-.. |example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/example.png
 
-#485->i2c
-.. |init4.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/init.png
-.. |read_i2c_slave.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/read_i2c_slave.png
-.. |write_i2c_slave.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/write_i2c_slave.png
-.. |read_i2c_slave_register.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/read_i2c_slave_register.png
-.. |write_i2c_slave_register.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/write_i2c_slave_register.png
+.. |roller485_485toi2c_fire_example.m5f2| raw:: html
 
-.. |example.png| image:: https://static-cdn.m5stack.com/mpy_docs/unit/roller485/example.png
+    <a
+        href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/unit/roller485/roller485_485toi2c_fire_example.m5f2"
+        target="_blank"
+    >
+        roller485_485toi2c_fire_example.m5f2
+    </a>

docs/en/units/index.rst

@@ -65,6 +65,7 @@ Unit
     relay.rst
     relay4.rst
     rgb.rst
+    roller485.rst
     scroll.rst
     ssr.rst
     synth.rst

docs/en/units/roller485.rst

@@ -1,39 +1,82 @@
 
-RollerBase
+Roller485
 ==========
 
 .. include:: ../refs/unit.roller485.ref
 
 Support the following products:
 
-|RollerBase|
+|Roller485|
 
-Micropython Example::
+Roller485 I2C Example:
 
-    import os, sys, io
-    import M5
-    from M5 import *
+    .. literalinclude:: ../../../examples/unit/roller485/roller485_i2c_fire_example.py
+        :language: python
+        :linenos:
 
+Roller485 I2C UIFLOW2 Example:
 
+    |i2c_example.png|
 
-UIFLOW2 Example:
+.. only:: builder_html
+
+    |roller485_i2c_fire_example.m5f2|
+
+Roller485 RS485 Example:
 
-    |example.png|
+    .. literalinclude:: ../../../examples/unit/roller485/roller485_485_fire_example.py
+        :language: python
+        :linenos:
+
+Roller485 RS485 UIFLOW2 Example:
+
+    |rs485_example.png|
 
 .. only:: builder_html
 
-class RollerBase
-----------------
+    |roller485_485_fire_example.m5f2|
+
+Roller485 RS485ToI2C Example:
+
+    .. literalinclude:: ../../../examples/unit/roller485/roller485_485toi2c_fire_example.py
+        :language: python
+        :linenos:
+
+Roller485 RS485ToI2C UIFLOW2 Example:
+
+    |rs485_i2c_example.png|
+
+.. only:: builder_html
+
+    |roller485_485toi2c_fire_example.m5f2|
+
+
+class Roller485Unit
+-------------------
 
 Constructors
 ------------
 
-.. class:: RollerBase()
+.. class:: Roller485Unit(bus, address, mode)
+
+    Initialize the Roller485Unit object based on communication mode.
+
+    :param bus: The I2C/RS485 bus instance.
+    :param address: The motor's RS485 address. Defaults to _ROLLER485_RS485_ADDR.
+    :param mode: The Roller485 communication mode.
 
     UIFLOW2:
 
         |init.png|
 
+class RollerBase
+----------------
+
+Constructors
+------------
+
+.. class:: RollerBase()
+
 
 Methods
 -------
@@ -522,7 +565,7 @@ Methods
 
 
 class RollerI2C(RollerBase)
----------------
+---------------------------
 
 Constructors
 ------------
@@ -550,23 +593,16 @@ Methods
     :param length: The number of bytes to read.
     :return: The data read from the device as a bytes object.
 
-    UIFLOW2:
-
-        |read.png|
-
 .. method:: RollerI2C.write(register, bytes) -> None
 
     Write data to a specified register on the I2C device.
 
     :param register: The name of the register to write to.
     :param bytes: The data to write to the register as a bytes object.
 
-    UIFLOW2:
-
-        |write.png|
 
 class Roller485(RollerBase)
----------------
+----------------------------
 
 Constructors
 ------------
@@ -578,11 +614,6 @@ Constructors
     :param bus: The RS485 bus instance.
     :param int address: The motor's RS485 address. Defaults to _ROLLER485_RS485_ADDR.
 
-    UIFLOW2:
-
-        |init1.png|
-
-
 Methods
 -------
 
@@ -593,9 +624,6 @@ Methods
     :param register: The name of the register to read from.
     :param length: The number of bytes to read.
 
-    UIFLOW2:
-
-        |read.png|
 
 .. method:: Roller485.create_frame(cmd, motor_id, *datas) -> None
 
@@ -605,10 +633,6 @@ Methods
     :param motor_id: The ID of the motor.
     :param datas: Additional data bytes to include in the frame.
 
-    UIFLOW2:
-
-        |create_frame.png|
-
 .. method:: Roller485.write(register, bytes) -> bool
 
     Write data to a specified register via RS485.
@@ -617,10 +641,6 @@ Methods
     :param bytes: The data to write to the register as a bytes object.
     :return: The response after writing the data.
 
-    UIFLOW2:
-
-        |write.png|
-
 .. method:: Roller485.send_command(cmd, id, data, buf_len) -> bool
 
     Send a command via RS485.
@@ -630,9 +650,6 @@ Methods
     :param data: The data to send along with the command.
     :param buf_len: The length of the buffer.
 
-    UIFLOW2:
-
-        |send_command.png|
 
 .. method:: Roller485.read_response(cmd, id) -> tuple[Literal[True], Any]
 
@@ -642,91 +659,87 @@ Methods
     :param id: The motor ID.
     :return: A tuple (success, response). Success is True if the response is valid, and response is the data read.
 
-    UIFLOW2:
-
-        |read_response.png|
-
 .. method:: Roller485._crc8(buffer) -> int
 
     Calculate CRC8 checksum.
 
     :param buffer: The data buffer to compute the checksum for.
     :return: The computed CRC8 value.
 
-    UIFLOW2:
-
-        |_crc8.png|
-
 
 class Roller485ToI2CBus(RollerBase)
----------------
+-----------------------------------
 
 Constructors
 ------------
 
-.. class:: Roller485ToI2CBus(bus, address=_ROLLER485_RS485_ADDR, i2c_address=0x64)
+.. class:: Roller485ToI2CBus(bus, address, mode)
 
     Initialize the Roller485ToI2CBus object.
 
     :param bus: The RS485 bus instance.
     :param address: The motor's RS485 address. Defaults to _ROLLER485_RS485_ADDR.
-    :param i2c_address: The I2C address of the slave device. Defaults to 0x64.
-
-    UIFLOW2:
-
-        |init2.png|
-
 
 Methods
 -------
 
-.. method:: Roller485ToI2CBus.read_i2c_slave(length) -> tuple[Literal[True], Any]
+.. method:: Roller485ToI2CBus.readfrom_mem(addr, mem_addr, nbytes) -> bytes
 
-    Read data from the I2C slave device via RS485.
+    Read data from a specific register of the I2C slave device.
 
-    :param length: The number of bytes to read.
-    :return: The data read from the I2C slave.
+    :param addr: The I2C slave address to read from.
+    :param mem_addr: Memory register address.
+    :param nbytes: The number of bytes to read.
+    :return: The data read from the register.
     :throws Exception: If the read operation fails.
 
-    UIFLOW2:
+.. method:: Roller485ToI2CBus.readfrom_mem_into(addr, mem_addr, buf)
 
-        |read_i2c_slave.png|
+    Read data from a specific register of the I2C slave device.
 
-.. method:: Roller485ToI2CBus.write_i2c_slave(byte_list, stop_bit) -> Literal[True]
+    :param addr: The I2C slave address to read from.
+    :param mem_addr: Memory register address.
+    :param buf: Buffer to store the data.
 
-    Write data to the I2C slave device via RS485.
+.. method:: Roller485ToI2CBus.writeto_mem(addr, mem_addr, buf) -> Literal[True]
 
-    :param byte_list: The data bytes to write.
-    :param stop_bit: Whether to send a stop bit after writing.
+    Write data to a specific register of the I2C slave device.
+
+    :param addr: The I2C slave address to write to.
+    :param mem_addr: Memory register address.
+    :param buf: The data bytes to write.
     :return: True if the write operation is successful.
     :throws Exception: If the write operation fails.
 
-    UIFLOW2:
-
-        |write_i2c_slave.png|
-
-.. method:: Roller485ToI2CBus.read_i2c_slave_register(register, length) -> bytes
+.. method:: Roller485ToI2CBus.readfrom(addr, nbytes) -> bytes
 
-    Read data from a specific register of the I2C slave device.
+    Read data from the I2C slave device via RS485.
 
-    :param register: The register address to read from.
-    :param length: The number of bytes to read.
-    :return: The data read from the register.
+    :param addr: The I2C slave address to read from.
+    :param nbytes: The number of bytes to read.
+    :return: The data read from the I2C slave.
     :throws Exception: If the read operation fails.
 
-    UIFLOW2:
+.. method:: Roller485ToI2CBus.readfrom_into(addr, buf)
 
-        |read_i2c_slave_register.png|
+    Read data from the I2C slave device via RS485.
 
-.. method:: Roller485ToI2CBus.write_i2c_slave_register(register, byte_list) -> Literal[True]
+    :param addr: I2C device address.
+    :param buf: Buffer to store the data.
 
-    Write data to a specific register of the I2C slave device.
+.. method:: Roller485ToI2CBus.writeto(addr, buf, stop) -> Literal[True]
 
-    :param register: The register address to write to.
-    :param byte_list: The data bytes to write.
+    Write data to the I2C slave device via RS485.
+
+    :param addr: The I2C slave address to write to.
+    :param buf: The data bytes to write.
+    :param stop: Whether to send a stop bit after writing.
     :return: True if the write operation is successful.
     :throws Exception: If the write operation fails.
 
-    UIFLOW2:
 
-        |write_i2c_slave_register.png|
+.. method:: Roller485ToI2CBus.scan(addr, buf, stop) -> List
+
+    Scan for I2C devices on the bus.
+
+    :return: A list of addresses of the found I2C devices.