Merge pull request #266 from tinymovr/develop

Version 1.5.0
tinymovr · Jun 3, 2023 · e0ba7d5 · e0ba7d5
2 parents e20c235 + 751a4e3
commit e0ba7d5
Show file tree

Hide file tree

Showing 45 changed files with 166 additions and 5,829 deletions.
diff --git a/.github/workflows/firmware.yml b/.github/workflows/firmware.yml
@@ -7,7 +7,7 @@ jobs:
     runs-on: 'ubuntu-22.04'
     strategy:
       matrix:
-        board-revision: [R32, R33, R5, M5]
+        board-revision: [R32, R33, R50, R51, R52, M5]
     steps:
     - uses: actions/checkout@v2
     - uses: carlosperate/arm-none-eabi-gcc-action@v1

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -93,10 +93,12 @@
             "options": [
                 "R32",
                 "R33",
-                "R5",
+                "R50",
+                "R51",
+                "R52",
                 "M5"
             ],
-            "default": "R5"
+            "default": "R52"
         }
     ]
 }
diff --git a/docs/control/theory.rst b/docs/control/theory.rst
@@ -36,12 +36,12 @@ As the motor phases are connected, current measurement in each of the three phas
 Reference Frames
 ****************
 
-Next, the 3-phase measurements are transformed to the rotating frame of the rotor which is termed dq. The relevant transformation is known as the dq0 transform. The resulting quantities are the direct (d) current and quadrature (q) current. Motor torque is attributed to the quadrature component, while the direct component is minimized.
+Next, the 3-phase measurements are transformed to the rotating frame of the rotor which is termed dq. The relevant transformation is known as the dq0 transform. The resulting quantities are the direct (d) current and quadrature (q) current. Motor torque is attributed to the quadrature component, while the direct component is minimized (except in the case of :ref:`flux-braking-feature`).
 
 Current Regulation and Motor Parameter Identification
 *****************************************************
 
-Because the d and q quantities represent DC signals in the rotational frame, it is possible to apply PI regulation to control current.  For optimal regulation, the PI current regulation requires correct identification of proportional and integral gains. Tinymovr uses the method proposed in [1] to calculate the gains from the resistance and inductance motor parameters. The parameters are measured automatically by the firmware during the calibration procedure. 
+Because the d and q quantities represent DC signals in the rotational frame, it is possible to apply PI regulation to control current. For optimal regulation, the PI current regulation requires correct identification of proportional and integral gains. Tinymovr uses the method proposed in [1] to calculate the gains from the resistance and inductance motor parameters. The parameters are measured automatically by the firmware during the calibration procedure. 
 
 Thus the whole process is automated, and you don't need to worry about it.
 

diff --git a/docs/develop/guide.rst b/docs/develop/guide.rst
@@ -89,7 +89,9 @@ If you are in Windows you will also need to install GNU make. This is rather eas
 Using VSCode
 ############
 
-VSCode-based Tinymovr development is a cross-platform solution (Linux, Macos and Windows supported) for building, flashing and debugging firmware. As of November 2021, it is the official approach to Tinymovr development.
+Our development environment for Tinymovr utilizes VSCode and is designed with cross-platform compatibility in mind. We support all major operating systems: Linux, MacOS, and Windows. This method allows for a unified approach to building, flashing, and debugging firmware.
+
+We take great pride in creating this in-house, cross-platform development solution, as an alternative to the official Windows-only solution, providing enhanced flexibility and simplifiyng the process of developing for Tinymovr across multiple platforms.
 
 
 Building
@@ -107,7 +109,26 @@ Tinymovr implements board revision selection using an input menu with a few pred
   :width: 800
   :alt: Board revision selector
 
-Select the board revision against which you are compiling (R32, R33 or R5) from the list. The build process will start, it usually takes less than half a minute. After it finishes, you should end up with a ``build/`` directory inside ``firmware/`` and there you should see the files ``tinymovr_fw.elf``, ``tinymovr_fw.hex`` and ``tinymovr_fw.bin``.
+Select the board revision against which you are compiling from the list. The build process will start, it usually takes less than half a minute. After it finishes, you should end up with a ``build/`` directory inside ``firmware/`` and there you should see the files ``tinymovr_fw.elf``, ``tinymovr_fw.hex`` and ``tinymovr_fw.bin``.
+
+More about Hardware Revisions
+-----------------------------
+
+Tinymovr passes the `BOARD_REV_XX` argument regarding the board revision to the compiler. This is used in the firmware to configure the hardware accordingly. Invoking a make command with the REV argument is as follows:
+
+.. code-block:: console
+
+    make debug REV=R5
+
+
+Currently the following hardware revision values are supported:
+
+- R32
+- R33
+- R50
+- R51
+- R52
+- M5
 
 
 Flashing and Debugging

diff --git a/docs/encoders/encoders.rst b/docs/encoders/encoders.rst
@@ -20,12 +20,12 @@ The onboard sensor is enabled by default, so no special configuration is necessa
 
 .. code-block:: python
 
-    tm1.encoder.type = 1
-    tm1.encoder.bandwidth = 1500
+    tm1.encoder.type = 0
+    tm1.encoder.bandwidth = 300
     tm1.save_config()
     tm1.reset() # encoder change is applied after reset
 
-The value of 1500 in bandwidth is the default value configured for the onboard sensor, which works well for most configurations.
+The value of 300Hz in bandwidth is the default value configured based on the charasteristics of the onboard sensor.
 
 Hall Effect Sensor
 ******************
@@ -68,7 +68,7 @@ As a first step you need to configure the sensor type and observer bandwidth.
     tm1.encoder.type = 1
     tm1.encoder.bandwidth = 100
 
-This sets the encoder type to Hall effect sensor, and the encoder bandwidth to 100. 
+This sets the encoder type to Hall effect sensor, and the encoder bandwidth to 100Hz. 
 
 Next, you need to set the motor configuration:
 

diff --git a/docs/hardware/connectors.png b/docs/hardware/connectors.png
diff --git a/docs/hardware/connectors_m5.png b/docs/hardware/connectors_m5.png
diff --git a/docs/hardware/connectors_r5.png b/docs/hardware/connectors_r5.png
diff --git a/docs/hardware/connectors_r52.png b/docs/hardware/connectors_r52.png
diff --git a/docs/hardware/dimensions.png b/docs/hardware/dimensions.png
diff --git a/docs/hardware/dimensions_m5.png b/docs/hardware/dimensions_m5.png
diff --git a/docs/hardware/dimensions_r5 b/docs/hardware/dimensions_r5
diff --git a/docs/hardware/dimensions_r5.png b/docs/hardware/dimensions_r5.png
diff --git a/docs/hardware/dimensions_r52.png b/docs/hardware/dimensions_r52.png
diff --git a/docs/hardware/gimbal.rst b/docs/hardware/gimbal.rst
@@ -2,14 +2,19 @@
 Gimbal Motors
 *************
 
+.. _gimbal-introduction:
+
 Introduction
 ------------
 
-Since firmware v0.8.4 and studio v0.3.4, Tinymovr can drive gimbal-style brushless motors.
+Tinymovr can drive gimbal-style brushless motors in open loop current control, by disabling current sensing. 
+
+.. warning::
+   * This mode is not recommended for Tinymovr M5, which is a specialized gimbal driver and can do closed loop current control with gimbal motors.
 
 What is a gimbal motor anyway?
 
-A gimbal motor is a 3-phase brushless motor whose stator is wound with many turns, and as such exhibits much larger resistance and inductance compared to the high-current brushless motors used to provide lift to drones, rc planes etc. Gimbal motors are used in... well... camera gimbals mainly, because they offer smooth motion and require small currents to produce torque compared to the 'regular' brushless motors. This in turn can help minimize the size of the motor driver and associated wires etc. Note that we refer to reduction of current through the stator windings and not the power converted to heat as a result of Joule heating of stator windings, which is still the same for the same amount of torque.
+A gimbal motor is a 3-phase brushless motor whose stator is wound with many turns, and as such exhibits much larger resistance and inductance compared to the high-current brushless motors used to provide lift to drones, rc planes etc. Gimbal motors are used in... well... camera gimbals mainly. Similar motors can be found in light robotic joints. Such motors offer smooth motion and require small currents to produce torque compared to the 'high current' brushless motors. This in turn can help minimize the size of the motor driver and associated wires etc. Note that we refer to reduction of current through the stator windings and not the power converted to heat as a result of Joule heating of stator windings, which is still the same for the same amount of torque.
 
 To achieve closed-loop current control, motor controllers such as Tinymovr use current measurement resistors in each phase (usually in series with the low-side mosfet) to estimate the current in the motor windings. These resistors have low resistance (in the range of a few milliOhms at most), to limit power dissipation in the resistor and allow operation in wide current ranges (up to several tens of Amps, even hundreds). The drawback is that current measurements exhibit noise of 100s of mA, and as such do not offer accurate measurements of small currents.
 
@@ -19,8 +24,6 @@ Enabling Gimbal Mode
 --------------------
 
 .. warning::
-   * Although tested, gimbal mode is still experimental. Please ensure all safety precautions, and use at your own risk!
-
    * DO NOT perform calibration on a gimbal motor without setting gimbal mode first! There is a risk of damaging the motor and board.
 
    * Using arbitrary resistance and inductance settings can damage your motor and board.

diff --git a/docs/hardware/guide.rst b/docs/hardware/guide.rst
@@ -18,15 +18,27 @@ Note that the Tinymovr Servo Kit includes all of the above in a ready to use kit
 Supported Motor Types
 #####################
 
-Most three-phase pancake-style outrunners can be used with Tinymovr. While there is a lot of variation between motors of even the same size and external appearance, as a general rule-of-thumb motors ranging from 40mm outer diameter to 110mm should work fine with Tinymovr.
+Tinymovr R5.x and R3.x
+**********************
+
+Most three-phase pancake-style outrunners can be used with Tinymovr R5. While there is a lot of variation between motors of even the same size and external appearance, as a general rule-of-thumb motors ranging from 40mm outer diameter to 110mm should work fine with Tinymovr.
+
+For a good quality and affordable option, take a look at our own `Tinymovr Motors <https://tinymovr.com/5208_motor>`_.
+
+Tinymovr M5.x
+*************
+
+Most gimbal motors can be used with Tinymovr M5. Gimbal motors are essentially outrunners with high resistance (they have more turns). You can read more about gimbal motors in :ref:`gimbal-introduction`. Note that, to control gimbal motors with Tinymovr M5, you do not have to (in fact, should not) use Gimbal mode. Tinymovr M5 is capable of accurately sensing current at a lower scale, which is compatible with gimbal motors.
+
 
 Additional details:
 
-Tinymovr expects a motor with sinusoidal back-EMF. Most brushless outrunners have inusoidal back-EMF. If uncertain and you have access to an oscilloscope, you can hook up the motor phases to the scope channels and check out the back-EMF for yourself. 
+Tinymovr expects a motor with sinusoidal back-EMF. Most brushless outrunners (including gimbal motors) have sinusoidal back-EMF. If uncertain and you have access to an oscilloscope, you can hook up the motor phases to the scope channels and check out the back-EMF for yourself. 
 
 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.
 
 
+
 Mechanical Setup
 ################
 
@@ -46,8 +58,6 @@ The most important aspect of a correct setup is to ensure the controller is prop
 
 A `3D printable encoder magnet jig <https://github.com/yconst/Tinymovr/blob/master/hardware/misc/magnet_jig.stl>`_ is available, suitable for 6mm disc magnets and 14, 19, 25 and 30mm motor hole diameters.
 
-For a 3D printable motor mount design, check out the `Tinymovr alpha dev kit mount <https://github.com/yconst/Tinymovr/tree/master/hardware/motor-stand>`_ (suitable for 40xx motors).
-
 .. note::
    For safety reasons, you should always ensure the motor & controller assembly are secured to a stable surface before operation. The motor rotor may experience high acceleration that may cause damage or injury if not secured properly.
 
@@ -96,7 +106,11 @@ Connecting Motor
 
 Connect the three motor phases to the three terminals on Tinymovr. The order of connection is not important, and motor direction will be determined during motor/encoder calibration.
 
-For Tinymovr R3.x, the motor leads can be connected by soldering on the PCB. For Tinymovr R5, the leads can be connected by soldering on the PCB, or you can solder a screw terminal block and secure the motor leads on the block.
+* Tinymovr R3.x: The motor leads can be connected by soldering on the PCB. 
+
+* Tinymovr R5.x: The leads can be connected by soldering on the PCB, or you can solder a screw terminal block and secure the motor leads on the block.
+
+* Tinymovr M5.x: The leads can be connected by soldering on the PCB.
 
 .. _connecting-data:
 
@@ -109,6 +123,8 @@ Connect the CAN bus header to one of the two CAN sockets on the board. It is not
 
 * Tinymovr R5.x: you will need to provide an external 120Ω termination resistor.
 
+* 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.
 
 .. warning::
@@ -123,7 +139,9 @@ Connecting Power
 
 * Tinymovr R5.x can be powered from a 12-38V (3S-9S) power source.
 
+* Tinymovr M5.x can be powered from a 12-38V (3S-9S) power source.
+
 With the power source off/disconnected, connect the power leads observing correct polarity. Turn on/connect the power source. Upon successful power-up, the onboard LED should light up.
 
 .. note::
-   Each Tinymovr board has a capacitance of around 500μF (R3.x) / 160μF (R5). Such capacitance can introduce significant inrush current upon power-on, especially if several boards are connected to the same power supply. To prevent damage to components from overcurrent, the use of an inrush current limiter or a current-limited power supply is advised.
+   Each Tinymovr board has a capacitance of around 500μF (R3.x) / 200μF (R5) / 50μF (M5). Such capacitance can introduce significant inrush current upon power-on, especially if several boards are connected to the same power supply. To prevent damage to components from overcurrent, the use of an inrush current limiter or a current-limited power supply is advised. We offer a `Power Distribution and protection device <https://tinymovr.com/products/dianome>`_ which is suitable for this task.
diff --git a/docs/hardware/overview.rst b/docs/hardware/overview.rst
@@ -10,15 +10,15 @@ R5.x
 
 Tinymovr R5.x is the latest Tinymovr revision. It features increased connectivity in a reduced footprint.
 
-Board Dimensions
-################
+Board Dimensions (R5.0, R5.1)
+#############################
 
 .. image:: dimensions_r5.png
   :width: 800
   :alt: Tinymovr R5 dimensions
 
-Connectivity
-############
+Connectivity (R5.0, R5.1)
+#########################
 
 .. image:: connectors_r5.png
   :width: 800
@@ -27,20 +27,55 @@ Connectivity
 .. 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`. This only affects R5.1 boards.
 
+Board Dimensions (R5.2)
+#######################
+
+.. image:: dimensions_r52.png
+  :width: 800
+  :alt: Tinymovr R5.2 dimensions
+
+Connectivity (R5.2)
+###################
+
+.. image:: connectors_r52.png
+  :width: 800
+  :alt: Tinymovr R5.2 connectors and pinouts
+
+
+M5.x
+****
+
+Tinymovr M5.x is is our specialized driver for gimbal motors and light robotic joints. It features a very compact footprint and 5A max drive.
+
+Board Dimensions (M5.1)
+#######################
+
+.. image:: dimensions_m5.png
+  :width: 800
+  :alt: Tinymovr M5 dimensions
+
+Connectivity (M5.1)
+###################
+
+.. image:: connectors_m5.png
+  :width: 800
+  :alt: Tinymovr M5 connectors and pinouts
+
+
 R3.x
 ****************
 
 R3.x is the previous Tinymovr revision, with CAN and UART connectivity.
 
-Board Dimensions
-################
+Board Dimensions (R3.x)
+#######################
 
 .. image:: dimensions.png
   :width: 800
   :alt: Tinymovr R3.x dimensions
 
-Connectivity
-############
+Connectivity (R3.x)
+###################
 
 .. image:: connectors.png
   :width: 800

diff --git a/docs/interfaces/interfaces.rst b/docs/interfaces/interfaces.rst
@@ -32,6 +32,9 @@ As an alternative to CAN Bus, Tinymovr offers UART-based (serial) communication.
 .. warning::
    The UART port on Tinymovr is NOT 5V tolerant. Applying 5V voltage will immediately damage the onboard PAC5527 controller. Please use only 3.3V for UART communication.
 
+.. warning::
+   The UART port on Tinymovr offers a 3.3v output for driving very light loads (30mA absolute max). Tinymovr cannot be powered by this pin. In addition, most UART adapters offer 5V power, which is incompatible with Tinymovr. **In short: If in doubt, leave this pin disconnected**.
+
 Protocol Description
 ####################
 

diff --git a/docs/protocol/reference.rst b/docs/protocol/reference.rst
@@ -375,7 +375,7 @@ controller.current.bandwidth
 
 ID: 30
 Type: float
-Units: radian / second
+Units: hertz
 
 The current controller bandwidth.
 
@@ -668,7 +668,7 @@ encoder.bandwidth
 
 ID: 55
 Type: float
-Units: radian / second
+Units: hertz
 
 The encoder observer bandwidth.
 

diff --git a/docs/upgrade/connectors.png b/docs/upgrade/connectors.png
diff --git a/docs/upgrade/connectors_m5.png b/docs/upgrade/connectors_m5.png
diff --git a/docs/upgrade/connectors_r5.png b/docs/upgrade/connectors_r5.png
diff --git a/docs/upgrade/connectors_r52.png b/docs/upgrade/connectors_r52.png
diff --git a/docs/upgrade/upgrade.rst b/docs/upgrade/upgrade.rst
@@ -13,14 +13,44 @@ For this method you will need a USB to UART adapter or similar device to connect
 .. warning::
    The UART port on Tinymovr is NOT 5V tolerant. Applying 5V voltage will immediately damage the onboard PAC5527 controller. Please use only 3.3V for UART communication.
 
+.. warning::
+   The UART port on Tinymovr offers a 3.3v output for driving very light loads (30mA absolute max). Tinymovr cannot be powered by this pin. In addition, most UART adapters offer 5V power, which is incompatible with Tinymovr. **In short: If in doubt, leave this pin disconnected**.
+
+Connectivity
+############
+
+R5.2
+====
+
+.. image:: connectors_r52.png
+  :width: 800
+  :alt: Tinymovr R5.2 connectors and pinouts
+
+R5.0, R5.1
+==========
+
 .. image:: connectors_r5.png
   :width: 800
-  :alt: Tinymovr R5 connectors and pinouts
+  :alt: Tinymovr R5.0 and R5.1 connectors and pinouts
+
+M5.1
+====
+
+.. image:: connectors_m5.png
+  :width: 800
+  :alt: Tinymovr M5 connectors and pinouts
+
+R3.x
+====
 
 .. image:: connectors.png
    :width: 800
    :alt: Tinymovr R3.x connectors and pinouts
 
+
+Procedure
+#########
+
 Qorvo provides an application to interface with the bootloader environment using UART and enable firmware upgrades. It is available through the `Qorvo website <https://www.qorvo.com/products/p/PAC5527#evaluation-tools>`_ as an archive named "PAC55xx ActiveFlashLight Bootloader". Please download and extract the archive and follow these steps:
 
 1. Inside the "resources" folder run the ActiveFlashLight application
@@ -41,3 +71,7 @@ Upgrading using J-Link
 
 Please see :ref:`setting-up-vscode`.
 
+.. warning::
+   Depending on the hardware revision and the batch, either a vertical or a sideways JST-SH connector is used for SWD. In any case, the pin order shown in the above figures is correct. Please consider this when connecting your SWD adapter.
+
+