Merge pull request #312 from tinymovr/studio/custom_spec_param

Allow specifying custom spec files as studio cli params

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#   - requirements: docs/requirements.txt

docs/develop/guide.rst

@@ -12,7 +12,7 @@ This document provides a guide for setting up a development environment for deve
 Hardware Connections
 ####################
 
-For proper debugging capabilities you will need a Segger J-Link adapter. Unfortunately original J-Link adapters are quite expensive. A more affordable option is the J-Link EDU adapter at around $60 or the J-Link EDU mini adapter at around $20. In addition, there are J-Link clones that can be purchased for very low prices on ebay or Aliexpress. However, reliability of these clones is not guaranteed.
+For proper debugging capabilities you will need a Segger J-Link adapter. Unfortunately original J-Link adapters are quite expensive. A more affordable option is the J-Link EDU adapter at around $60 or the J-Link EDU mini adapter at around $20. In addition, there are J-Link clones that can be purchased for very low prices on ebay or Aliexpress. However, reliability of these clones is not guaranteed, and we do not provide support when using these clones.
 
 With the board and J-Link adapter powered off, connect the J-Link to Tinymovr as shown below:
 
@@ -42,7 +42,7 @@ Connection with SWD adapter (e.g. isolator) for R5:
 
 (diagrams made with `Wireviz <https://github.com/formatc1702/WireViz>`_)
 
-As of Tinymovr 1.0.1, it is no longer necessary to patch the `JLinkDevices.xml` file with the PAC additions, in order for JLinkGDBServer to work properly. Relevant files are included in the repo.
+As of Tinymovr 1.0.1, it is no longer necessary to patch the ``JLinkDevices.xml`` file with the PAC additions, in order for JLinkGDBServer to work properly. Relevant files are included in the repo.
 
 
 .. _develop-preparation:
@@ -64,7 +64,7 @@ The file comes in a zipped installer exe (!), which all it does is extract the c
 
     cp -r <pac55xx_sdk_location> <tinymovr_location>/firmware/pac55xx_sdk/
 
-In any case, the target directory should be named `pac55xx_sdk`. The above copy command ensures this.
+In any case, the target directory should be named ``pac55xx_sdk``. The above copy command ensures this.
 
 Now you have the required PAC SDK almost ready. There is a small patch that you will need to apply in the pac55xx_sdk directory. It is suggested to use the `Python patch package <https://pypi.org/project/patch/>`_, which is cross-platform. If you do not have the package, install using pip:
 
@@ -100,7 +100,7 @@ We take great pride in creating this in-house, cross-platform development soluti
 Configuring
 ***********
 
-You'll need to configure the path to the JLink debug server in `.vscode/launch.json`. The configuration blocks look like this:
+You'll need to configure the path to the JLink debug server in ``.vscode/launch.json``. The configuration blocks look like this:
 
 .. code-block:: javascript
   
@@ -135,7 +135,7 @@ Select the board revision against which you are compiling from the list. The bui
 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:
+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
 
@@ -157,7 +157,7 @@ Flashing and Debugging
 
 Before debugging, make sure the J-Link drivers and software is installed. The drivers and software, together with instructions, can be found in the `Qorvo website <https://www.qorvo.com/products/p/PAC5527#evaluation-tools>`_, under the download 'Segger J-Link Support'. This download includes a nacessary patch to enable J-Link to work with Qorvo devices. Instructions on how to apply the patch are included in the download.
 
-The Tinymovr repo includes all VSCode settings configured, except for the JLink `serverpath` variable in `launch.json`, which you'll need to update to reflect your system. Note that there are multiple instances in the file, you'll need to update all of them.
+The Tinymovr repo includes all VSCode settings configured, except for the JLink ``serverpath`` variable in ``launch.json``, which you'll need to update to reflect your system. Note that there are multiple instances in the file, you'll need to update all of them.
 
 We offer various VSCode launch configurations to suit different development and debugging tasks, including remote Tinymovr flashing debugging using a remote JLink server. These are are briefly outlined below.
 
@@ -216,7 +216,7 @@ Eclipse is no longer supported. Consider :ref:`develop-setting-up-vscode` instea
 Setup Studio for Development
 ############################
 
-Tinymovr Studio is a Python application and as such can be easily set up to facilitate development. The approach is to use `pip` to install Tinymovr in develop mode, from a local copy of the (`git repo <https://github.com/tinymovr/Tinymovr>`_). This allows any changes you make to the local code to be immediately available when you run the executable (`tinymovr`, `tinymovr_cli`, or `tinymovr_dfu`).
+Tinymovr Studio is a Python application and as such can be easily set up to facilitate development. The approach is to use ``pip`` to install Tinymovr in develop mode, from a local copy of the (``git repo <https://github.com/tinymovr/Tinymovr>``_). This allows any changes you make to the local code to be immediately available when you run the executable (``tinymovr``, ``tinymovr_cli``, or ``tinymovr_dfu``).
 
 .. note::
    We recommend installing Tinymovr in a virtual environment. `Here is a quick tutorial on how to setup a virtual environment using Conda <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments>`_.
@@ -234,7 +234,28 @@ or to enable GUI support:
 
     pip3 install -e .[GUI]
 
-This will install the Tinymovr Studio in develop mode. Now, `tinymovr`, `tinymovr_cli` and `tinymovr_dfu` will use the local Tinymovr Studio code.
+This will install the Tinymovr Studio in develop mode. Now, ``tinymovr``, ``tinymovr_cl`i`` and ``tinymovr_dfu`` will use the local Tinymovr Studio code.
 
 Happy coding!
 
+
+Custom Device Definitions
+#########################
+
+Tinymovr uses YAML files for device specification (the spec). Device spec files reside in ``{tinymovr_package_dir}/studio/Python/tinymovr/specs/``. This is where files covering Tinymovr firmware 1.3.x to 1.6.x are situated by default. 
+
+You can add custom device spec files in this directory to tell Tinymovr Studio GUI, CLI and library how to communicate with custom devices. For instance, assuming that you have installed Tinymovr Studio using ``pip3``, you will need to find the directory of the tinymovr package first using the command below:
+
+Windows
+
+.. code-block:: console
+
+    python -c "import os, tinymovr; print(os.path.dirname(tinymovr.__file__))"
+
+Macos and Linux
+
+.. code-block:: console
+
+    python3 -c "import os, tinymovr; print(os.path.dirname(tinymovr.__file__))"
+
+Then, paste your custom spec file to ``{tinymovr_package_dir}/studio/Python/tinymovr/specs/``. Tinymovr should correctly discover your custom device.

docs/features/features.rst

@@ -30,7 +30,7 @@ Before using the planner, the desired acceleration, deceleration and max velocit
     tm1.traj_planner.max_decel = {max_deceleration} # ticks/sec^2
     tm1.traj_planner.max_vel = {mac_velocity} # ticks/sec
 
-Once you set the desired acceleration and deceleration parameters, they do not need to be re-set. The parameters can be saved in NVRAM using `tmx.save_config()`.
+Once you set the desired acceleration and deceleration parameters, they do not need to be re-set. The parameters can be saved in NVRAM using ``tmx.save_config()``.
 
 Once the parameters are set, you can execute a plan to a target position:
 
@@ -70,7 +70,7 @@ Now the time-limited trajectory is executed as follows:
 Multi-axis Synchronization
 ********************************************
 
-Time-limited trajectories are useful for synchronizing the acceleration, cruise and deceleration phases for multiple axes. For instance, to synchronize three axes with different setpoints, you would configure the same `t_acc`, `t_cruise`, `t_dec` values. This guarantees that the trajectory phases are synchronized. Then you would issue the `move_to_tlimit` commands to each of the three different controllers in sequence:
+Time-limited trajectories are useful for synchronizing the acceleration, cruise and deceleration phases for multiple axes. For instance, to synchronize three axes with different setpoints, you would configure the same ``t_acc``, ``t_cruise``, ``t_dec`` values. This guarantees that the trajectory phases are synchronized. Then you would issue the ``move_to_tlimit`` commands to each of the three different controllers in sequence:
 
 .. code-block:: python
 
@@ -95,14 +95,14 @@ Because the homing planner relies on mechanical resistance of the structure, it
 
 There are six parameters in total that control the homing behavior:
 
-* `tmx.homing.velocity`: The velocity at which the motor performs homing
-* `tmx.homing.max_homing_t`: The maximum time the motor is allowed to travel before aborting homing
-* `tmx.homing.retract_dist`: The retraction distance the motor travels after the endstop has been found
-* `tmx.homing.stall_detect.velocity`: The velocity below which (and together with `stall_detect.delta_pos`) stall detection mode is triggered
-* `tmx.homing.stall_detect.delta_pos`: The position error above which (and together with `stall_detect.velocity`) stall detection mode is triggered
-* `tmx.homing.stall_detect.t`: The time to remain in stall detection mode before the motor is considered stalled
+* ``tmx.homing.velocity``: The velocity at which the motor performs homing
+* ``tmx.homing.max_homing_t``: The maximum time the motor is allowed to travel before aborting homing
+* ``tmx.homing.retract_dist``: The retraction distance the motor travels after the endstop has been found
+* ``tmx.homing.stall_detect.velocity``: The velocity below which (and together with ``stall_detect.delta_pos``) stall detection mode is triggered
+* ``tmx.homing.stall_detect.delta_pos``: The position error above which (and together with ``stall_detect.velocity``) stall detection mode is triggered
+* ``tmx.homing.stall_detect.t``: The time to remain in stall detection mode before the motor is considered stalled
 
-In addition to the above, the phase current while the motor is stopped, until `stall_detect.t` time passes is the maximum allowed phase current, as defined in `tmx.controller.current.Iq_limit`. It is advisable to set this value so that mechanical damage or fatigue is avoided.
+In addition to the above, the phase current while the motor is stopped, until ``stall_detect.t`` time passes is the maximum allowed phase current, as defined in ``tmx.controller.current.Iq_limit``. It is advisable to set this value so that mechanical damage or fatigue is avoided.
 
 Operation
 *********
@@ -125,7 +125,7 @@ FOC decouples the torque-producing and magnetizing currents by aligning the stat
 
 Two parameters control flux braking:
 
-1. `tmx.controller.current.max_Ibus_regen`: The maximum current (in amperes) allowed to be fed back to the power source before flux braking activates. By adjusting this value, you can control the regenerative braking threshold and determine when flux braking should take effect.
+1. ``tmx.controller.current.max_Ibus_regen``: The maximum current (in amperes) allowed to be fed back to the power source before flux braking activates. By adjusting this value, you can control the regenerative braking threshold and determine when flux braking should take effect.
 
-2. `tmx.controller.current.max_Ibrake`: The maximum current (in amperes) allowed to be dumped to the motor windings during flux braking. By setting this value to zero, you can deactivate flux braking. Adjusting this parameter allows you to manage the braking torque and the heat generated during the braking process.
+2. ``tmx.controller.current.max_Ibrake``: The maximum current (in amperes) allowed to be dumped to the motor windings during flux braking. By setting this value to zero, you can deactivate flux braking. Adjusting this parameter allows you to manage the braking torque and the heat generated during the braking process.
 

docs/hardware/guide.rst

@@ -137,4 +137,15 @@ Connecting Power
 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) / 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.
+   Each Tinymovr board has a capacitance of around 500μF (R3.x) / 240μ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.
+
+.. _daisy-chain:
+
+Connecting Multiple Nodes (Daisy-Chaining)
+##########################################
+
+Multiple nodes can be connected in a single CAN Bus network by means of daisy-chaining. Tinymovr R5 and Tinymovr M5 offer two CAN Bus ports for this purpose, which makes it easy to daisy-chain units. Note that for networks with long cable lengths, you may need termination on both ends. On one end this can be achieved with the onboard termination resistor of CANine, but on the other end you will have to provide your own.
+
+.. image:: daisy_chain.png
+  :width: 800
+  :alt: Connecting multiple nodes by daisy-chaining

docs/sensors/sensors.rst

@@ -100,7 +100,7 @@ At this point, you are ready to perform motor/sensor calibration. This will meas
 
 .. code-block:: python
 
-    tmx.calibrate()
+    tmx.controller.calibrate()
 
 After calibration finishes, you should be able to control the motor:
 
@@ -115,6 +115,6 @@ Once you have determined that the motor behaves as expected, set to idle and per
 
 .. code-block:: python
 
-    tmx.idle()
+    tmx.controller.idle()
     tmx.save_config()
 

docs/upgrade/upgrade.rst

@@ -72,6 +72,24 @@ Flashing the Firmware
 
    Ensure your CAN interface is connected and configured correctly with Tinymovr.
 
+2. **Enter DFU Mode**:
+
+   Launch the Tinymovr CLI:
+
+   .. code-block:: bash
+
+      tinymovr_cli
+
+   Once inside teh CLI, type the following to enter DFU Mode:
+
+   .. code-block:: python
+
+      tmx.enter_dfu()
+
+   Then exit the CLI by typing ``exit``.
+
+   If you are getting an exception after this command, it means that either your Tinymovr does not come with the DFU bootloader, so you will have to :ref:`upgrade-using-activeflashlight`, or your board is already in DFU mode.
+
 2. **Run the Script**:
 
    With the firmware .bin file you downloaded, execute the DFU script:

studio/Python/tests/test_base_function.py

@@ -22,15 +22,17 @@ def test_position_control(self):
         Test position control
         """
         self.check_state(0)
+        self.tm.motor.I_cal = 5
+        self.tm.controller.current.Iq_limit = 5
         self.try_calibrate()
         self.tm.controller.position_mode()
         self.check_state(2)
 
         for i in range(5):
-            self.tm.controller.position.setpoint = i * 10000 * ticks
+            self.tm.controller.position.setpoint = i * 3000 * ticks
             time.sleep(0.25)
             self.assertAlmostEqual(
-                i * 10000 * ticks, self.tm.encoder.position_estimate, delta=1000 * ticks
+                i * 3000 * ticks, self.tm.encoder.position_estimate, delta=1000 * ticks
             )
 
 

studio/Python/tests/test_dfu.py

@@ -22,8 +22,7 @@
 from tinymovr import init_tee, destroy_tee
 from tinymovr.config import (
     get_bus_config,
-    create_device,
-    definitions
+    create_device
 )
 
 import unittest

studio/Python/tinymovr/cli.py

@@ -1,16 +1,18 @@
 """Tinymovr Studio CLI
 
 Usage:
-    tinymovr_cli [--bus=<bus>] [--chan=<chan>] [--bitrate=<bitrate>]
+    tinymovr_cli [--bus=<bus>] [--chan=<chan>] [--spec=<spec>] [--bitrate=<bitrate>]
     tinymovr_cli -h | --help
     tinymovr_cli --version
 
 Options:
     --bus=<bus>  One or more interfaces to use, first available is used [default: canine,slcan_disco].
     --chan=<chan>  The bus device "channel".
+    --spec=<spec> A custom device spec to be added to the list of discoverable spec.
     --bitrate=<bitrate>  CAN bitrate [default: 1000000].
 """
 
+import yaml
 import can
 import pkg_resources
 import IPython
@@ -20,7 +22,7 @@
 from tinymovr import init_tee, destroy_tee
 from tinymovr.discovery import Discovery
 from tinymovr.constants import app_name
-from tinymovr.config import get_bus_config, configure_logging
+from tinymovr.config import get_bus_config, configure_logging, add_spec
 
 """
 Tinymovr CLI Module
@@ -49,6 +51,12 @@ def spawn():
 
     logger = configure_logging()
 
+    spec_file = arguments["--spec"]
+    if spec_file:
+        with open(spec_file, 'r') as file:
+            spec_data = yaml.safe_load(file)
+            add_spec(spec_data, logger)
+
     buses = arguments["--bus"].rsplit(sep=",")
     channel = arguments["--chan"]
     bitrate = int(arguments["--bitrate"])

studio/Python/tinymovr/config/__init__.py

@@ -1,8 +1,7 @@
 from tinymovr.config.config import (
     get_bus_config,
     configure_logging,
-    definitions,
     create_device,
     create_device_with_hash_msg,
-    ProtocolVersionError,
+    add_spec,
 )