Tinymovr

************
Studio Usage
************

.. |cli| raw:: html

   <span style="padding:3px 10px;margin: 10px auto; background:#85dff1; border-radius: 12px; font-family: sans-serif; font-size: 14px;">CLI</span>

.. |gui| raw:: html

   <span style="padding:3px 10px;margin: 10px auto; background:#85f1df; border-radius: 12px; font-family: sans-serif; font-size: 14px;">GUI</span>


Tinymovr Studio is a cross-platform GUI application, CLI application, and Python library that offers easy access to all of Tinymovr's functionality.

This documentation page includes examples both for the |gui| as well as the |cli| apps. 


Launching Studio
################

|gui|

.. code-block:: console

    tinymovr

.. image:: gui_plot.png
  :width: 680
  :alt: Tinymovr Studio GUI with plot

|cli|

.. code-block:: console

    tinymovr_cli

.. image:: cli.png
  :width: 680
  :alt: Tinymovr Studio CLI

Alternative Adapters/Firmwares
##############################

By default Tinymovr Studio searches for either slcan-compatible CAN bus adapters or adapters using the `CANine firmware <https://github.com/tinymovr/CANine>`_ [1]_. To specify an alternative device, use the `--bus` command line argument. 

For instance, to work with SocketCAN-compatible adapters in linux, launch Tinymovr Studio as follows:

|gui|

.. code-block:: console

    tinymovr --bus=socketcan


|cli|

.. code-block:: console

    tinymovr_cli --bus=socketcan


.. [1] Note that you need to have completed `setting up CANine <https://canine.readthedocs.io/en/latest/canine.html#canine-firmware>`_ before working with CANine.

Compatibility
#############

Tinymovr Studio includes by default a checksum comparison to determine protocol compatibility between firmware and studio version. This is performed each time a node is discovered, and prior to initializing the tinymovr object. If you see a compatibility-related message, please upgrade to the latest studio and firmware versions. 

Custom Device Specs
###################

You can specify a custom device spec (YAML file) as a command line argument:

|gui|

.. code-block:: console

    tinymovr --spec=/path/to/myspec.yaml

|cli|

.. code-block:: console

    tinymovr_cli --spec=/path/to/myspec.yaml

This is useful, for instance, if you have altered the default Tinymovr spec files. Using this parameter with a project developed using `Avlos <https://github.com/tinymovr/avlos>`_, you can even use Tinymovr Studio to control your own custom devices!


Issuing Commands in CLI
#######################

|cli|

You can read/write variables and issue commands using the respective Tinymovr handle, e.g.:

.. code-block:: python

    tm1.encoder

or

.. code-block:: python

    tm1.controller.pos_setpoint = 10000

Replace "tm1" with the correct device ID if necessary. Full tab completion is available.


.. _multiple-instances:

Multiple Instances
##################

In order for multiple Tinymovr instances to coexist in the same CAN network, they need to have unique IDs. The default ID is 1. To assign different IDs to each board, follow the method below:

1. Connect a single Tinymovr to the bus and launch Studio. The board will be assigned the default ID, 1, and will be accessible as tm1.

2. |gui| Change the ID

.. image:: change_id.png
  :width: 400
  :alt: Change CAN bus node ID using the GUI

The board will be discovered with the new ID. Studio GUI will rescan, discover the new node, and remove the old instance.

2. |cli| Change the ID

.. code-block:: python

    tm1.comms.can.id = x

where x is the desired ID. You can assign IDs in the range 1-1024.

The board will be discovered with the new ID. Relaunch Studio CLI to remove the old board instance. 

3. |gui| Save configuration.

.. image:: save_config.png
  :width: 400
  :alt: Save configuration using the GUI

3. |cli| Save configuration.

.. code-block:: python

    tm1.save_config()

4. Power down or reset the board. Tinymovr is now ready to use with the new ID.


.. _can-id-persistence:

CAN Node ID Persistence
########################

When you call ``save_config()``, the CAN node ID is stored redundantly in a dedicated metadata header in flash, separate from the main configuration payload. This metadata has its own integrity check (magic marker and checksum), which makes it verifiable independently of the rest of the configuration.

This design ensures that **the CAN node ID survives firmware updates**. When new firmware is flashed, the main configuration is invalidated (because the firmware version changes), but the metadata header remains intact. On the next boot, the device reads the node ID from the metadata before checking the firmware version, so it keeps its assigned bus address.

The diagram below shows how the boot process handles this:

.. mermaid::

   flowchart TD
       A["nvm_load_config()"] --> B["Scan flash slots, find latest"]
       B --> C{"Valid metadata?"}
       C -- No --> D["Return false, ID stays default 1"]
       C -- Yes --> E{"node_id copies match and >= 1?"}
       E -- Yes --> F["Restore CAN ID from metadata"]
       E -- No --> G["Skip ID restore"]
       F --> H["Read config payload, validate checksum"]
       G --> H
       H --> I{"Firmware version matches?"}
       I -- Yes --> J["Restore full config, return true"]
       I -- No --> K["Return false -- but CAN ID is already set"]

In practice, this means:

- **Normal boot** -- Full configuration is restored, including the CAN ID.
- **After a firmware update** -- The metadata is still valid, so the CAN ID is restored. The full configuration fails the version check, so other parameters revert to defaults, but the device remains addressable on the bus.
- **Corrupted flash** -- Metadata validation fails and the device falls back to the default ID (1).
- **Fresh device** -- No saved configuration exists; the default ID (1) is used.

.. note::
   After a firmware update you will need to re-calibrate and restore your configuration (or import from a previously exported JSON file), but you do **not** need to reassign the CAN node ID. See :ref:`can-id-preservation` for more details.


.. _export-import-config:

Exporting & Importing Configuration
####################################

Tinymovr Studio allows you to export the current device configuration to a JSON file and import it back later. This is useful for backing up tuning parameters, replicating a setup across multiple boards, or restoring configuration after a firmware update.

The exported file includes controller gains, trajectory planner limits, sensor settings, motor parameters, homing configuration, and other settable attributes. Note that CAN bus parameters (ID and baud rate) are intentionally excluded from export, as importing mismatched values could disrupt communication.

.. note::
   Export/import transfers configuration values over CAN but does **not** persist them to flash. After importing, call ``save_config()`` if you want the values to survive a power cycle.


|gui|

Use the **File** menu:

- **File > Export Config...** -- Exports the device configuration to a JSON file. If multiple devices are connected, a picker dialog lets you choose which one.
- **File > Import Config...** -- Imports a JSON configuration file into the device.


|cli|

In the CLI, use ``export_config()`` and ``import_config()`` from the ``tinymovr.config`` module:

.. code-block:: python

    import json
    from avlos.json_codec import AvlosEncoder
    from tinymovr.config import export_config, import_config

    # Export to a JSON file
    config = export_config(tm1)
    with open("my_config.json", "w") as f:
        json.dump(config, f, cls=AvlosEncoder)

    # Import from a JSON file
    with open("my_config.json", "r") as f:
        config = json.load(f)
    import_config(tm1, config)

    # Optionally persist to flash
    tm1.save_config()


.. _command-line-options:

Command-line options
####################

Tinymovr Studio supports the following command line options.


``--bus=<bus>``
=======================

The --bus option specifies a CAN bus type to use.

Example:

|gui|

.. code-block:: console

    tinymovr --bus=canine

|cli|

.. code-block:: console

    tinymovr_cli --bus=canine

All interfaces offered by python-can are supported.


``--chan=<chan>``
=================

The --chan options specifies a channel to use, optionally together with the --bus option. 

Example:

|gui|

.. code-block:: console

    tinymovr --bus=socketcan --chan=CAN0

|cli|

.. code-block:: console

    tinymovr_cli --bus=socketcan --chan=CAN0

By default, Tinymovr Studio will use slcan as the interface, and will search for CANAble/CANtact-type devices with slcan firmware. Such is the CANine adapter supplied with Tinymovr Servo Kits.


``--bitrate=<chan>``
====================

Specifies a bitrate in baud.

Example:

|gui|

.. code-block:: console

    tinymovr --bus=socketcan --bitrate=1000000

|cli|

.. code-block:: console

    tinymovr_cli --bus=socketcan --bitrate=1000000

By default, Tinymovr Studio will use 1000000 as bitrate.
We tested with 1000000, 500000 and 250000 baud.



Units
#####

Tinymovr Studio introduced physical units and quantities since v0.3.0. Units are introduced through the `Pint <https://pypi.org/project/Pint/>`_ package. Using units you will see all values that you query associated with a unit, which forms a physical quantity.

|gui|

In the GUI, units are displayed by default in any quantity that supports them. For instance:

.. image:: gui_command.png
  :width: 400
  :alt: Change CAN bus node ID using the GUI

You can set any quantity supporting units by specifying the desired compatible unit next to the quantity you want to set. For instance, to set the position setpoint:

|cli|

In the CLI, units are displayed whenever a quantity that supports them is printed:

.. code-block:: python

    In [1]: tm1.encoder.pos_estimate
    Out[1]: 0.0 <Unit('tick')>

You can also set quantities in any (defined) unit you wish. For instance:

.. code-block:: python

    In [1]: tm1.controller.pos_setpoint = 2.0 * rad

The above will set the rotor position to 2 radians from the initial position. Similarly for velocity:

.. code-block:: python

    In [1]: tm1.controller.vel_setpoint = 3.0 * rad / second

Will set velocity to 3 radians/second. If not unit is used in setting a value, the default units will be assumed, in the above cases ticks and ticks/second.

The ureg object is the unit registry, and it is that which holds all unit definitions. You can use it to do all sorts of cool stuff such as doing conversions, defining your own shortcuts or even new units.

For instance, to define a few frequently used shortcuts in a program:

.. code-block:: python

    from avlos import get_registry
    ureg = get_registry()
    mA = ureg.milliampere
    rad = ureg.radian
    s = ureg.second

Then you can use the defined shortcuts to intuitively set values, such as a position setpoint with velocity and current feed-forwards:

.. code-block:: python

    tm1.controller.pos_setpoint = 2*PI * rad
    tm1.controller.vel_setpoint = PI * rad/second
    tm1.controller.cur_setpoint = 1.5 * ampere

Take a look at the :ref:`api-reference` for default units used in each command.

For more information on units and their usage, take a look at `Pint's documentation <https://pint.readthedocs.io/en/stable/>`_


Socketcan & Linux
#################

You can use a socketcan-enabled CAN adapter with Tinymovr Studio. The CANine adapter supplied with Tinymovr Servo Kits supports Socketcan natively with the alternative Candlelight Firmware. To connect to a Socketcan device, run Studio as follows:

|gui|

.. code-block:: console

    tinymovr --bus=socketcan --chan=CAN0

|cli|

.. code-block:: console

    tinymovr_cli --bus=socketcan --chan=CAN0