API¶
Overview¶
This document outlines the main API used to interface with Tinymovr. This API comprises a series of read/write endpoints. The endpoints are defined taking into account the capabilities and constraints of the CAN bus, the main communication bus used by Tinymovr.
The Tinymovr API allows full hardware control from within Python scripts, using a high-level interface to hardware. At the same time, it is possible to interface directly with the CAN bus endpoints, for instance in an embedded application. In both cases, the API Reference provides all the necessary information.
Tinymovr API is part of Tinymovr Studio. For help installing Studio, please take a look at Studio Installation.
Use with Python¶
Here below is an example using the API from Python scripts and controlling hardware:
import can
from tinymovr import Tinymovr
from tinymovr.iface.can_bus import CAN
bus = can.Bus(bustype="slcan", channel="your_com_port", bitrate=1000000)
iface = CAN(bus)
tm = Tinymovr(node_id=1, iface=iface)
tm.calibrate()
The above code block will instantiate a Tinymovr with CAN bus id of 1 and calibrate it. Following the above, you can issue commands such as:
tm.position_control()
tm.set_pos_setpoint(0)
tm.velocity_control()
tm.set_vel_setpoint(80000)
Shortcuts¶
A few commands exist in Tinymovr studio which are shortcuts to Tinymovr endpoints with specific argument values. These are mostly shortcuts to changes of states and modes that are easier to read and remember. They are briefly presented below.
idle()¶
Switch to idle mode and disable the inverter.
Shortcut for tmx.set_state(0, 0)
calibrate()¶
Start calibration sequence. This command presents a safety notice that needs to be accepted by the user before proceeding.
Shortcut for tmx.set_state(1, 0)
position_control()¶
Switch to closed loop control (enable the inverter) and to position control mode.
Shortcut for tmx.set_state(2, 2)
velocity_control()¶
Switch to closed loop control (enable the inverter) and to velocity control mode.
Shortcut for tmx.set_state(2, 1)
current_control()¶
Switch to closed loop control (enable the inverter) and to current control mode.
Shortcut for tmx.set_state(2, 0)
API Reference¶
Note
Where “float32” is mentioned, an IEEE 754, 32-bit floating point representation is assumed.
state¶
0x03
Retrieves an object containing the controller state, control mode and error flags. The object is pretty-printed if inside the Tinymovr Studio iPython environment.
This command has been revised as of firmware 0.8.2 and studio 0.3.3 to report multiple error flags if available. The above and newer versions can display up to five error flags simultaneously, and with the order that they were registered by the firmware error handler.
Tinymovr Studio 0.3.3 and newer is backwards compatible with the legacy error reporting system, as such newer Studio versions can be used with older firmware. However, newer firmware (0.8.2 and later) is not compatible with older Studio versions. Make sure that you run the latest version of Studio before upgrading your firmware.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
|
Legacy Error Flag |
uint8 |
0 |
|
Control State |
uint8 |
1 |
|
Control Mode |
uint8 |
2 |
|
1st Error Flag |
uint8 |
3 |
|
2nd Error Flag |
uint8 |
4 |
|
3rd Error Flag |
uint8 |
5 |
|
4th Error Flag |
uint8 |
6 |
|
5th Error Flag |
uint8 |
7 |
Example¶
Legacy system
>>>tmx.state
{"error": 0, "state": 0, "mode": 0}
New system
>>>tmx.state
State: Idle Mode: Position
Errors:
Invalid State (1): Attempt to transition to invalid state
>>>tmx.state.mode
0
set_state()¶
0x07
Sets the controller state and control mode.
Note
Results of calibration are not automatically saved to Non-Volatile Memory (NVM). You need to issue a save_config
command after calibration is finished to save calibration data to NVM.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
|
Control State |
uint8 |
1 |
|
Control Mode |
uint8 |
2 |
Example¶
>>>tmx.set_state(state=0, mode=0)
can_config¶
0x05
Retrieves the CAN configuration.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
|
CAN Bus ID |
uint8 |
0 |
|
Baud Rate |
uint16 |
1 |
Example¶
>>>tmx.can_config
{"id": 1, "baud_rate": 250}
set_can_config()¶
0x06
Sets the CAN configuration.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
|
CAN Bus ID |
uint8 |
0 |
|
Baud Rate |
uint16 |
1 |
Example¶
>>>tmx.set_can_config(id=1, baud_rate=250)
encoder_estimates¶
0x09
Retrieves the position and velocity encoder estimates.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Estimate |
float32 |
0 |
ticks |
|
Velocity Estimate |
float32 |
4 |
ticks/second |
Example¶
>>>tmx.encoder_estimates
{"position": 1000.0, "velocity": 0.0}
setpoints¶
0x0A
Retrieves the position and velocity setpoints of the controller.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Setpoint |
float32 |
0 |
tick |
|
Velocity Setpoint |
float32 |
4 |
tick/second |
Example¶
>>>tmx.setpoints
{"position": 1000.0, "velocity": 0.0}
encoder_config¶
0x0B
Retrieves the encoder configuration.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Encoder Type |
uint8 |
0 |
|
|
Encoder Bandwidth |
float32 |
1 |
radians/second |
Example¶
>>>tmx.encoder_config
{"type": 0, "bandwidth": 1500.0}
set_pos_setpoint()¶
0x0C
Sets the position setpoint, and optionally velocity and current feed-forward values. Due to the fact that data types of feed-forward values are limited by type, multiples of the root units are used.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Setpoint |
float32 |
0 |
tick |
|
Velocity Setpoint |
int16 |
4 |
decatick/second |
|
Current Setpoint |
int16 |
6 |
centiampere |
Example¶
>>>tmx.set_pos_setpoint(1000.0)
>>>tmx.set_pos_setpoint(position=1000.0, velocity=10000.0, current=0.0)
set_vel_setpoint()¶
0x0D
Sets the velocity setpoint, and optionally current feed-forward value.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity Setpoint |
float32 |
0 |
ticks/second |
|
Current Setpoint |
float32 |
4 |
ampere |
Example¶
>>>tmx.set_vel_setpoint(10000.0)
>>>tmx.set_vel_setpoint(velocity=10000.0, current=0.0)
set_cur_setpoint()¶
0x0E
Sets the current (Iq) setpoint.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Current Setpoint |
float32 |
0 |
amperes |
Example¶
>>>tmx.set_cur_setpoint(0.5)
limits¶
0x15
Retrieves the velocity and current limits of the controller.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity Limit |
float32 |
0 |
tick/second |
|
Current Limit |
float32 |
4 |
ampere |
Example¶
>>>tmx.limits
{"velocity": 300000.0, "current": 10.0}
set_limits()¶
0x0F
Sets the velocity and current limits of the controller.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity Limit |
float32 |
0 |
tick/second |
|
Current Limit |
float32 |
4 |
ampere |
Example¶
>>>tmx.set_limits(velocity=200000.0, current=15.0)
gains¶
0x18
Retrieves the position and velocity gains of the controller.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Gain |
float32 |
0 |
1/second |
|
Velocity Gain |
float32 |
4 |
ampere*second/tick |
Example¶
>>>tmx.gains
{"position": 35.0, "velocity": 0.000012}
set_gains()¶
0x19
Sets the position and velocity gains of the controller.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Gain |
float32 |
0 |
1/second |
|
Velocity Gain |
float32 |
4 |
ampere*second/tick |
Example¶
>>>tmx.set_gains(position=25.0, velocity=0.00001)
offset_dir¶
0x02
Retrieves the user defined rotor position offset and rotor direction values.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Offset |
float32 |
0 |
tick |
|
Direction |
int8 |
4 |
Example¶
>>>tmx.offset_dir
{"offset": 0.0, "direction": 1}
set_offset_dir()¶
0x08
Sets the user defined rotor position offset and rotor direction values.
Note
The direction
field only accepts -1 or 1 as values. All other values are ignored.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Offset |
float32 |
0 |
tick |
|
Direction |
int8 |
4 |
Example¶
>>>tmx.set_gains(offset=2500, direction=-1)
vel_integrator_params¶
0x18
Retrieves the velocity integrator gain and deadband parameters.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity Integrator Gain |
float32 |
0 |
ampere*second/tick |
|
Velocity Integrator Deadband |
float32 |
4 |
tick |
Example¶
>>>tmx.vel_integrator_params
{"gain": 0.0001, deadband: 200}
set_vel_integrator_params()¶
0x19
Sets the velocity integrator gain and deadband parameters.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity Integrator Gain |
float32 |
0 |
ampere*second/tick |
|
Velocity Integrator Deadband |
float32 |
4 |
tick |
Example¶
>>>tmx.set_vel_integrator_params(gain=0.0001, deadband=300)
Iq¶
0x14
Retrieves the current (Iq) setpoint and estimate.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Iq Setpoint |
float32 |
0 |
ampere |
|
Iq Estimate |
float32 |
4 |
ampere |
Example¶
>>>tmx.Iq
{"setpoint": 1.0, "estimate": 0.9}
Iphase¶
0x10
Retrieves the measured phase currents.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
A Phase Current |
int16 |
0 |
ampere |
|
B Phase Current |
int16 |
0 |
ampere |
|
C Phase Current |
int16 |
0 |
ampere |
Example¶
>>>tmx.Iphase
{"A": 1.0, "B": -0.6, "C": -0.4}
set_encoder_config¶
0x11
Sets the encoder configuration.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Encoder Type |
uint8 |
0 |
|
|
Encoder Bandwidth |
float32 |
1 |
radians/second |
Example¶
>>>tmx.set_encoder_config(0, 1500)
plan_t_limit¶
0x20
Generate and execute a time-limited trajectory.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Target Position |
float |
0 |
tick |
|
Total Trajectory Time |
uint16 |
4 |
millisecond |
|
Acceleration Phase Percent |
uint8 |
6 |
(none, values 0-255) |
|
Deceleration Phase Percent |
uint8 |
7 |
(none, values 0-255) |
Example¶
>>>tmx.plan_t_limit(100000, 3000, 50, 50)
plan_v_limit¶
0x21
Generate and execute an acceleration- and velocity-limited trajectory.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Target Position |
float |
0 |
tick |
|
Max Velocity |
float |
4 |
tick/second |
Example¶
>>>tmx.plan_v_limit(100000, 50000)
set_max_plan_acc_dec¶
0x22
Set maximum acceleration and deceleration values for trajectory generation.
Note
This command only sets values, it does not execute a trajectory. For trajecotry execution with set values, make a call to plan_v_limit
.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Max Acceleration |
float |
0 |
tick/(second^2) |
|
Max Deceleration |
float |
4 |
tick/(second^2) |
Example¶
>>>tmx.set_max_plan_acc_dec(50000, 50000)
device_info¶
0x1A
Retrieves device-related information.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Device ID |
uint32 |
0 |
|
|
FW Major Ver. |
uint8 |
4 |
|
|
FW Minor Ver. |
uint8 |
5 |
|
|
FW Patch Ver. |
uint8 |
6 |
|
|
MCU Temp |
uint8 |
7 |
°C |
Example¶
>>>tmx.device_info
{"device_id": 99999, "fw_major": 0, "fw_minor": 7, "fw_patch": 1, "temp": 45}
motor_config¶
0x1E
Retrieves motor config (flags, pole pairs, calibration current).
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Calibrated, Gimbal |
uint8 |
0 |
|
|
Motor Pole Pairs |
uint8 |
1 |
|
|
Calibration Current |
float |
2 |
ampere |
Example¶
>>>tmx.motor_config
{"flags": 1, "pole_pairs": 11, "I_cal": 5.0}
set_motor_config¶
0x1F
Sets motor config (flags, pole pairs, calibration current).
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Gimbal |
uint8 |
0 |
|
|
Motor Pole Pairs |
uint8 |
1 |
|
|
Calibration Current |
float |
2 |
ampere |
Example¶
High-current motor: .. code-block:: python
>>>tmx.set_motor_config(0, 14, 5)
Gimbal motor: .. code-block:: python
>>>tmx.set_motor_config(1, 14, 0.5)
timings¶
0x1B
Retrieves MCU timings in each control cycle.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
|
Total MCU Cycles |
uint32 |
0 |
|
Busy MCU Cycles |
uint32 |
4 |
Example¶
>>>tmx.timings
{"total": 7500, "busy": 1000}
estop()¶
0x02
Emergency stop: Idles the MCU immediately.
Arguments¶
No arguments.
Example¶
>>>tmx.estop()
reset()¶
0x16
Resets the MCU.
Arguments¶
No arguments.
Example¶
>>>tmx.reset()
save_config()¶
0x1C
Saves board configuration to Non-Volatile Memory.
Note
Saving config only works when Tinymovr is in idle mode, otherwise the command is ignored.
Arguments¶
No arguments.
Example¶
>>>tmx.save_config()
erase_config()¶
0x1D
Erases the configuration stored in NVM and resets the MCU.
Note
Erasing config only works when Tinymovr is in idle mode, otherwise the command is ignored.
Arguments¶
No arguments.
Example¶
>>>tmx.erase_config()
get_set_pos_vel()¶
0x25
Gets and sets Position and Velocity feedforward in one go.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Setpoint |
float32 |
0 |
ticks |
|
Velocity Setpoint |
float32 |
4 |
ticks/second |
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Estimate |
float32 |
0 |
ticks |
|
Velocity Estimate |
float32 |
4 |
ticks/second |
Example¶
>>>tmx.get_set_pos_vel(1000.0, 0)
{"position":0.0, "velocity": 0.0}
get_set_pos_vel_Iq()¶
0x26
Get and set Position, Velocity feedforward and Iq feedforward in one go. Due to the fact that data types of feed-forward values are limited by type, multiples of the root units are used.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Setpoint |
float32 |
0 |
tick |
|
Velocity Setpoint |
int16 |
4 |
decatick/second |
|
Current Setpoint |
int16 |
6 |
centiampere |
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Position Estimate |
float32 |
0 |
tick |
|
Velocity Estimate |
int16 |
4 |
decatick/second |
|
Current Estimate |
int16 |
6 |
centiampere |
Example¶
>>>tmx.get_set_pos_vel_Iq(1000.0, 0, 0)
{"position":0.0, "velocity": 0.0, "current": 0.0}
motor_RL¶
0x27
Retrieves motor resistance and inductance values.
Return Values¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Phase Resistance |
float32 |
0 |
ohm |
|
Phase Inductance |
float32 |
4 |
henry |
Example¶
>>>tmx.motor_RL
{"R": 0.2, "L": 0.00005}
set_motor_RL¶
0x28
Sets attached motor resistance and inductance values.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Phase Resistance |
float32 |
0 |
ohm |
|
Phase Inductance |
float32 |
4 |
henry |
Example¶
>>>tmx.set_motor_RL(0.5, 0.0001)
set_watchdog¶
0x2A
Enables/disables the CAN timeout watchdog, and sets the timeout length in seconds. This watchdog sets the control state to idle after a period of inactivity on the CAN bus. Maximum of 536s.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Enable/disable |
uint8 |
0 |
state |
|
Watchdog timeout |
float32 |
1 |
second |
Example¶
>>>tmx.set_watchdog(1, 5)
>>>tmx.set_watchdog(0)
set_vel_inc¶
0x2B
Sets the maxiumum increment by which the velocity can change each control loop, making it ramp between velocities to reduce voltage spikes. Default of 100. Setting this to 0 disables velocity ramping.
Arguments¶
Member |
Description |
Data Type |
Data Offset |
Default Unit |
|
Velocity increment |
float32 |
0 |
ticks |
Example¶
>>>tmx.set_vel_inc(100)
Error Codes¶
Tinymovr uses error codes to indicate faults in operation. These are listed below. Note that using Tinymovr studio, the error codes are already presented with an explanation.
0: NO_ERROR
¶
No error present.
1: INVALID_STATE
¶
An invalid state has been requested. This can be triggered when attempting to transition to a state whose controller state constraints are not satisfied. E.g. switching to closed loop control without calibrating.
2: ILLEGAL_VALUE
¶
This is a legacy error code that is not in use.
3: VBUS_UNDERVOLTAGE
¶
The bus voltage has dropped below the undervoltage threshold. In a current-limited power supply, this may also indicate excessive current demand from the power supply.
4: OVERCURRENT
¶
The phase current has exceeded the overcurrent threshold. The overcurrent threshold is 1,5 times the user-defined current limit, and in any case no more than 50A.
5: PWM_LIMIT_EXCEEDED
¶
This is a legacy error code that is not in use.
6: PHASE_RESISTANCE_OUT_OF_RANGE
¶
The phase resistance measured during calibration is out of range. The defined range is 5mΩ to 1Ω.
7: PHASE_INDUCTANCE_OUT_OF_RANGE
¶
The phase inductance measured during calibration is out of range. The defined range is 2μH to 5mH.
8: INVALID_POLE_PAIRS
¶
The pole pair detection algorithm did not converge near an integer number during calibration.
9: ENCODER_READING_UNSTABLE
¶
Encoder reading variation is over maximum allowed threshold. This is usually the casse if the magnet is misaligned, too far away from the encoder IC, or missing.