tinymovr · yconst · Aug 19, 2024 · Oct 10, 2023 · Oct 21, 2023 · Oct 28, 2023
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -20,3 +20,8 @@ sphinx:
 python:
   install:
   - requirements: docs/requirements.txt
+
+# Build PDF & ePub
+formats:
+  - epub
+  - pdf
diff --git a/.vscode/c_cpp_properties.json b/.vscode/c_cpp_properties.json
@@ -8,7 +8,8 @@
             "defines": [
                 "_DEBUG",
                 "UNICODE",
-                "_UNICODE"
+                "_UNICODE",
+                "__CC_ARM"
             ],
             "cStandard": "c11",
             "cppStandard": "c++17",

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,7 +3,32 @@
     "files.associations": {
         "random": "c",
         "limits": "c",
-        "common.h": "c"
+        "common.h": "c",
+        "__hash_table": "c",
+        "__tuple": "c",
+        "array": "c",
+        "type_traits": "c",
+        "ratio": "c",
+        "tuple": "c",
+        "variant": "c",
+        "chrono": "c",
+        "compare": "c",
+        "cstddef": "c",
+        "__locale": "c",
+        "__bit_reference": "c",
+        "__node_handle": "c",
+        "atomic": "c",
+        "bitset": "c",
+        "__memory": "c",
+        "locale": "c",
+        "optional": "c",
+        "system_error": "c",
+        "vector": "c",
+        "motor.h": "c",
+        "trajectory_planner.h": "c",
+        "xf1.h": "c",
+        "controller.h": "c",
+        "observer.h": "c"
     },
     "python.testing.unittestArgs": [
         "-v",

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -96,9 +96,10 @@
                 "R50",
                 "R51",
                 "R52",
+                "R53",
                 "M51"
             ],
-            "default": "R52"
+            "default": "R53"
         }
     ]
 }
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 ![FW Check Build](https://github.com/yconst/tinymovr/workflows/Tinymovr%20Firmware%20Check%2FBuild/badge.svg)
 ![Studio Lint Test](https://github.com/yconst/tinymovr/workflows/Tinymovr%20Studio%20Lint%2FTest/badge.svg)
 ![Docs Build](https://github.com/yconst/tinymovr/workflows/Tinymovr%20Docs%20Build/badge.svg)
-[![Discord](https://img.shields.io/discord/742400176664084535)](https://discord.gg/CzcCaXbU)
+[![Discord](https://img.shields.io/discord/742400176664084535)](https://discord.gg/UnmfuVzKuQ)
 
 [Tinymovr is an affordable motor controller](https://tinymovr.com) with integrated encoder and CAN bus for precise control of 3-phase brushless motors (PMSMs). 
 

diff --git a/avlos_config.yaml b/avlos_config.yaml
@@ -5,15 +5,17 @@ generators:
   generator_c:
     enabled: true
     paths:
+      output_enums: ./firmware/src/tm_enums.h
       output_header: ./firmware/src/can/can_endpoints.h
       output_impl: ./firmware/src/can/can_endpoints.c
     header_includes:
     - src/common.h
+    - src/tm_enums.h
     impl_includes:
     - <string.h>
     - src/adc/adc.h
     - src/system/system.h
-    - src/encoder/encoder.h
+    - src/sensor/sensors.h
     - src/observer/observer.h
     - src/motor/motor.h
     - src/scheduler/scheduler.h

diff --git a/docs/hardware/errata.rst b/docs/hardware/errata.rst
@@ -3,7 +3,7 @@ Hardware Errata
 
 .. _alpha-erratum-1:
 
-Tinymovr Alpha CAN Bus Connector Erratum
+Tinymovr Alpha CAN Bus Connector
 ****************************************
 
 The CANine v1 Adapter that came with Tinymovr alpha had the DF-13 pins reversed and as such is not compatible with regular DF-13 cables. Alpha users are advised to use the alternative pin header on the board and the included DF-13 to 2.54mm pin converter cable to communicate with Tinymovr, as shown in the diagram below:
@@ -16,7 +16,7 @@ Note above that the red wire should stay disconnected and to the left side of th
 
 .. _alpha-erratum-2:
 
-Tinymovr Alpha USB Micro Connector Erratum
+Tinymovr Alpha USB Micro Connector
 ******************************************
 
 The USB Micro connector used in the v1 adapter was unfortunately not very robust. In order to ensure that there is a good contact between the board and the USB cable, please ensure the male connector of the cable is firmly seated in the female connector of the board.
@@ -33,6 +33,17 @@ Tinymovr R5 UART Silkscreen Reversed
 
 The silkscreen next to the UART port on the rear of Tinymovr R5 has the order of pins reversed. The correct pins are provided in the figure below.
 
+This does not affect R5.2 and above.
+
 .. image:: erratum_R51.png
   :width: 600
-  :alt: Tinymovr R5 reversed silkscreen on UART port
+  :alt: Tinymovr R5 reversed silkscreen on UART port
+
+.. _r52-erratum-1:
+
+Tinymovr R5.2 FLEX2 Port as SPI
+************************************
+
+Even though Tinymovr R5.2 has the FLEX2 port which can function as SPI, due to a hardware incompatibility this port does not implement SPI correctly. As such, external sensors are only supported on the M5.x series at the moment.
+
+Tinymovr R5.3 and above does not have this issue and supports external SPI sensors normally.
diff --git a/docs/hardware/gimbal.rst b/docs/hardware/gimbal.rst
@@ -1,3 +1,5 @@
+.. _gimbal-motors:
+
 *************
 Gimbal Motors
 *************
@@ -28,6 +30,9 @@ To achieve closed-loop current control, motor controllers such as Tinymovr use c
 
 The gimbal mode of Tinymovr disables closed-loop current control. The commanded currents are converted to voltages using basic resistance and inductance formulas. 
 
+
+.. _enabling-gimbal-mode:
+
 Enabling Gimbal Mode
 --------------------
 

diff --git a/docs/hardware/guide.rst b/docs/hardware/guide.rst
@@ -36,6 +36,26 @@ Most gimbal motors can be used with Tinymovr M5. Gimbal motors are essentially o
 
    * Motors with trapezoidal back-EMF can also be controlled, but control will be sub-optimal. The trapezoidal back-EMF will appear as residual in the dq frame, as a result it will be much harder for the current controller to regulate phase currents. The tangible result is that the motor may exhibit increased noise and vibration while running.
 
+Limitations
+***********
+
+Tinymovr controllers are designed with certain limitations in terms of motor internal resistance and inductance, to ensure optimal closed loop current control performance.
+
+.. list-table:: Motor Limits
+   :header-rows: 1
+
+   * - Controller Version
+     - Phase Resistance (ohms)
+     - Phase Inductance (henries)
+   * - Tinymovr R5.x and R3.x
+     - 0.01 to 1.0
+     - 5e-6 to 1e-3
+   * - Tinymovr M5.x
+     - 0.5 to 20.0
+     - 1e-5 to 1e-2
+
+Note that motors with parameters outside this range will result in calibration failing. Ensure that the motors you select adhere to these parameters for the best operational experience. You can still use motors outside this range with open loop current control, through :ref:`enabling-gimbal-mode`.
+
 
 Mechanical Setup
 ################
@@ -73,9 +93,9 @@ Sensor Magnet and Mounting Tips
 
 * Ensure the sensor magnet is firmly attached to the motor shaft, otherwise it may slip out of sync. Use strong adhesive to secure.
 
-* It is possible to have the magnet on the rear side of the PCB, i.e. opposite of the magnet sensor IC, but the gap needs to be reduced to account for the PCB thickness. This has been verified by MPS in `this forum post <https://forum.monolithicpower.com/t/mounting-ma702-and-magnet-on-opposite-sides-of-pcb/1609>`_, quoted below: 
+* It is possible to have the magnet on the rear side of the PCB, i.e. opposite of the magnet sensor IC, but the gap needs to be reduced to account for the PCB thickness. This has been verified by MPS in a forum post [1]_, quoted below: 
   *[...] this type of arrangement is possible, what really matters in the end is that there is enough magnetic field reaching the sensor.
-  Of course the minimum distance is imposed by the thickness of the PCB, so it puts some constraints on the design, that you have to take into account when chosing the magnet (you can use our online simulation tool for that). But as long as the PCB is not acting as a magnetic shield (due to copper plane), then it is fine.*
+  Of course the minimum distance is imposed by the thickness of the PCB, so it puts some constraints on the design, that you have to take into account when choosing the magnet (you can use our online simulation tool for that). But as long as the PCB is not acting as a magnetic shield (due to copper plane), then it is fine.*
 
 * Calibration needs to be performed without any loads on the motor. If the motor is coupled to a load, the sensor offset angle may not be determined correctly, leading to a sub-optimal setup.
 
@@ -118,7 +138,7 @@ Connect the CAN bus header to one of the two CAN sockets on the board. It is not
 
 * Tinymovr M5.x: you will need to provide an external 120Ω termination resistor.
 
-In small setups with few nodes and short wires, it is better to enable just a single termination resistor, either on one Tinymovr board or on the CAN adapter. In setups with many nodes and long cables, you may need to enable termination resistors in both terminal nodes.
+In small setups with few nodes and short wires, it is better to enable just a single termination resistor, either on one Tinymovr board or on the CAN adapter. In setups with many nodes and long cables, you may need to enable termination resistors in both terminal nodes. A typical CAN driver has an “open-drain” output structure, meaning that the dominant edge is actively driven and the recessive edge is not. Therefore, properly terminating the bus is very important because it ensures that the recessive edge decays properly, and in time for the next bit's sample point [2]_.
 
 .. warning::
    The UART pins in Tinymovr R5.1 have the silkscreen reversed. If you are planning to use UART with R5.1, consult :ref:`r51-erratum-1`. 
@@ -148,4 +168,8 @@ Multiple nodes can be connected in a single CAN Bus network by means of daisy-ch
 
 .. image:: daisy_chain.png
   :width: 800
-  :alt: Connecting multiple nodes by daisy-chaining
+  :alt: Connecting multiple nodes by daisy-chaining
+
+
+.. [1] MPS forum post on mounting MA702 and magnet on opposite sides of PCB: https://forum.monolithicpower.com/t/mounting-ma702-and-magnet-on-opposite-sides-of-pcb/1609
+.. [2] Split Termination, Texas Instruments. Available at `https://www.ti.com/document-viewer/lit/html/SSZTB40#:~:text=for%20each%20termination.-,Split%20Termination,typically%20between%201%2D100nF`.
diff --git a/docs/protocol/integrating.rst b/docs/protocol/integrating.rst
@@ -22,12 +22,11 @@ Here below is an example using the API from Python scripts and controlling hardw
 .. code-block:: python
 
     import can
-    from tinymovr.tee import init_tee
+    from tinymovr.bus_router import init_router
     from tinymovr.config import get_bus_config, create_device
 
-    params = get_bus_config(["canine", "slcan_disco"])
-    params["bitrate"] = bitrate
-    init_tee(can.Bus(**params))
+    params = get_bus_config(["canine", "slcan_disco"], bitrate=1000000)
+    init_router(can.Bus, params)
     tm = create_device(node_id=1)
 
     tm.controller.calibrate()
@@ -42,6 +41,97 @@ The above code block will instantiate a Tinymovr with CAN bus id of 1 and calibr
     tm.controller.velocity_mode()
     tm.controller.velocity.setpoint = 80000
 
+BusRouter API
+#############
+
+The `BusRouter` class in the Tinymovr library is designed to facilitate message distribution and communication on the CAN bus by distributing incoming messages based on the result of a filter callback.
+
+API Overview
+------------
+
+.. class:: BusRouter
+
+   Initializes and manages the routing of CAN bus messages between various clients. It integrates a simple forwarding mechanism for sending messages to simplify interfacing with CAN bus objects.
+
+   .. method:: __init__(bus_manager, timeout, logger)
+
+      Constructor for the BusRouter. Initializes the bus manager, timeout, and logger.
+
+      .. note::
+        This constructor should not be used directly. Instead, use the :func:`init_router` function.
+
+      :param bus_manager: Instance of BusManager to handle low-level bus interactions.
+      :param timeout: Timeout in seconds for receiving messages.
+      :param logger: Logger instance for logging information.
+
+   .. method:: run()
+
+      Main thread function that continuously listens for incoming frames and dispatches them to the appropriate clients based on filter results.
+
+   .. method:: add_client(filter_cb, recv_cb)
+
+      Registers a new client to receive messages that meet specific conditions.
+
+      :param filter_cb: Callback function that determines if the incoming frame should be passed to the client.
+      :param recv_cb: Callback function that handles the received frame.
+
+   .. method:: stop()
+
+      Stops the router's main running thread, effectively stopping the routing of messages.
+
+   .. method:: shutdown()
+
+      Performs a complete shutdown by stopping the router and closing all bus manager activities.
+
+   .. method:: send(frame)
+
+      Sends a frame via the bus manager.
+
+      :param frame: The CAN frame to be sent.
+
+Bus Router Management Functions
+-------------------------------
+
+These helper functions manage the lifecycle of the `BusRouter` instance.
+
+.. function:: init_router(bus_class, bus_params, logger, timeout=0.1)
+
+   Initializes a bus router using a python-can bus instance. This function creates a singleton instance of `BusRouter`.
+
+   :param bus_class: The bus class from python-can to be used.
+   :param bus_params: Parameters for the bus initialization.
+   :param logger: Logger instance for logging activities.
+   :param timeout: Timeout in seconds for receiving messages.
+   :return: An instance of `BusRouter`.
+
+.. function:: destroy_router()
+
+   Destroys the existing bus router and stops its associated thread.
+
+.. function:: get_router()
+
+   Returns the current instance of the bus router if it exists.
+
+Deprecations
+------------
+
+The following functions are deprecated and will be removed in future versions:
+
+.. function:: init_tee()
+
+   .. deprecated:: 2.1
+    Use :func:`init_router` instead.
+
+.. function:: destroy_tee()
+
+   .. deprecated:: 2.1
+    Use :func:`destroy_router` instead.
+
+.. function:: get_tee()
+
+   .. deprecated:: 2.1
+    Use :func:`get_router` instead.
+
 Error Codes
 ###########
-Original file line number
+Diff line change
@@ Expand Up / @@ -96,9 +96,10 @@ @@
                     "R50",
                     "R51",
                     "R52",
+                    "R53",
                     "M51"
                 ],
-                "default": "R52"
+                "default": "R53"
             }
         ]
     }