Studio Usage¶
Overview¶
Tinymovr Studio is an IPython application that enables communication with multiple Tinymovr instances, allowing configuration and control.
Launching the command line app¶
tinymovr
Discovery¶
Tinymovr Studio uses a polling mechanism to discover Tinymovr nodes in the CAN network. Upon launching the app, by default the first ten nodes are scanned. The ones that are present are available through the variable handle ‘tmx’, where x the device index. To specify the scan range, take a look at Command-line options.
Alternative Adapters/Firmwares¶
By default Tinymovr Studio searches for slcan-compatible CAN bus adapters, which appear as USB Virtual COM Port devices. To specify an alternative device, use the –bustype and –chan command line arguments.
For instance, to work with adapters using the CANine firmware, launch Tinymovr Studio as follows:
tinymovr --bustype=canine —chan=0xC1B0
Note that you need to have completed setting up CANine before issuing the above command to work with CANine.
Compatibility¶
Tinymovr Studio includes by default a version check to determine compatibility of firmware with studio version. This is performed each time a node is discovered, and prior to initializing the tinymovr object. Compatibility is determined through comparison of versions with minimun requirements embedded in both firmware and studio. If you wish to disable version check (e.g. for backwards compatibility), you can use the --no-version-check command line argument. Please note that unexpected things can happen if you combine incompatible firmware and studio versions.
Issuing Commands¶
You can read variables and issue commands using the respective Tinymovr handle, e.g.:
tmx.device_info
or
tmx.set_vel_setpoint(0)
Where x is the device ID. Full tab completion is available.
Multiple Instances¶
In order for multiple Tinymovr instances to coexist in the same network, they need to have unique IDs. The default ID is 1. To assign different IDs to each board, follow the method below:
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.
Issue the id change
tm1.set_can_config(x)
where x is the desired ID. Valid IDs are from 1-64, but the Studio app currently discovers IDs up to 8.
Relaunch Studio
The board will be discovered with the new ID. Save configuration.
tmx.save_config()
Power down or reset the board. Tinymovr is now ready to use with the new ID.
Command-line options¶
Tinymovr Studio supports the following command line options.
--ids=<ids>¶
The –ids option specifies a set of CAN node IDs to scan.
Example:
tinymovr --ids=1,3,5,7-9
All syntax options supported by Pynumparser are available.
--bustype=<bustype>¶
The –bustype option specifies a CAN bus type to use.
Example:
tinymovr --bustype=robotell
All interfaces offered by python-can are supported.
--chan=<chan>¶
The –chan options specifies a channel to use, optionally together with the –bustype option.
Example:
tinymovr --bustype=robotell --chan=COM3
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.
--no-version-check¶
Disables the firmware-studio version compatibility check that is performed by default when discovering a Tinymovr node.
Units¶
Tinymovr Studio introduced physical units and quantities since v0.3.0. Units are introduced through the Pint package. Using units you will see all values that you query associated with a unit, which forms a physical quantity.
With units, you can do the following:
In [1]: tm1.encoder_estimates
Out[1]: {'position': 0.0 <Unit('tick')>, 'velocity': 0.0 <Unit('tick / second')>}
You can also set quantities in any (defined) unit you wish. For instance:
In [1]: tm1.set_pos_setpoint(2.0 * ureg('rad'))
The above will set the rotor position to 2 radians from the initial position. Similarly for velocity:
In [1]: tm1.set_vel_setpoint(2.0 * ureg('rad/s'))
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:
from tinymovr.units 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:
tm.set_pos_setpoint(2*PI * rad, 0 * rad/s, 1500 * mA)
Take a look at the API Reference for default units used in each command.
For more information on units and their usage, take a look at Pint’s documentation
Plotting¶
Tinymovr Studio features a capable and fast plotter to visualize your setup in real time. The plotter is accessible from within the IPython terminal that hosts Tinymovr Studio.
Example: Plotting Encoder Estimates¶
Let us imagine that we want to plot the position and velocity estimates of our encoder. The following will do the trick:
plot(lambda: [tm1.encoder_estimates])
A plot window will show up on screen. Notice that both values (position and velocity) are plotted. This is because we passed the endpoint itself as an argument. The plotter is smart enough to know to expand the returned dictionary, and assign values to the correct keys.
Also note that there are two y-axes in the plot, one on the left and one on the right. Each of these corresponds to one value being plotted, and will adjust to that value’s range. You can have as many values as you wish, the plotter will add so-called ‘parasite’ axes on the right side of the plot for each value. However with more than three or four it doesn’t really look pretty…
Plotting values from multiple endpoints¶
It is possible to plot multiple endpoints from the same or multiple devices with the same syntax:
plot(lambda: [tm1.encoder_estimates, tm1.setpoints])
In the above example, estimates are plotted together with setpoints for position and velocity.
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:
tinymovr --bustype=socketcan --chan=CAN0
Tinymovr in-silico¶
Tinymovr studio implements a simplistic simulation of the actual controller, in order to facilitate validation of basic commands etc. To use the simulation mode, run Studio as follows:
tinymovr --bustype=insilico --chan=test
Basic commands such as state, encoder_estimates, set_pos_setpoint work, more to be implemented soon.