Tinymovr 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

bus = can.Bus(bustype="cantact", channel="COM1", 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)

API Reference

Note

Where “float32” is mentioned, an IEEE 754, 32-bit floating point representation is assumed.

state

endpoint: 0x03
type: Read-only

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

errors

Legacy Error Flag

uint8

0

state

Control State

uint8

1

mode

Control Mode

uint8

2

errors

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()

endpoint: 0x07
type: Write-only

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

state

Control State

uint8

1

mode

Control Mode

uint8

2

Example

>>>tmx.set_state(state=0, mode=0)

can_config

endpoint: 0x05
type: Read-only

Retrieves the CAN configuration.

Return Values

Member

Description

Data Type

Data Offset

id

CAN Bus ID

uint8

0

baud_rate

Baud Rate

uint16

1

Example

>>>tmx.can_config
{"id": 1, "baud_rate": 250}

set_can_config()

endpoint: 0x06
type: Write-only

Sets the CAN configuration.

Arguments

Member

Description

Data Type

Data Offset

id

CAN Bus ID

uint8

0

baud_rate

Baud Rate

uint16

1

Example

>>>tmx.set_can_config(id=1, baud_rate=250)

encoder_estimates

endpoint: 0x09
type: Read-only

Retrieves the position and velocity encoder estimates.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

position

Position Estimate

float32

0

ticks

velocity

Velocity Estimate

float32

4

ticks/second

Example

>>>tmx.encoder_estimates
{"position": 1000.0, "velocity": 0.0}

setpoints

endpoint: 0x0A
type: Read-only

Retrieves the position and velocity setpoints of the controller.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

position

Position Setpoint

float32

0

tick

velocity

Velocity Setpoint

float32

4

tick/second

Example

>>>tmx.setpoints
{"position": 1000.0, "velocity": 0.0}

set_pos_setpoint()

endpoint: 0x0C
type: Write-only

Sets the position setpoint, and optionally velocity and current feed-forward values. Due to the fact that data types of feed-forward values are range-limited, multiples of the root units are used.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

position

Position Setpoint

float32

0

tick

velocity

Velocity Setpoint

int16

4

decatick/second

current

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()

endpoint: 0x0D
type: Write-only

Sets the velocity setpoint, and optionally current feed-forward value.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

velocity

Velocity Setpoint

float32

0

ticks/second

current

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()

endpoint: 0x0E
type: Write-only

Sets the current (Iq) setpoint.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

current

Current Setpoint

float32

0

amperes

Example

>>>tmx.set_cur_setpoint(0.5)

limits

endpoint: 0x15
type: Read-only

Retrieves the velocity and current limits of the controller.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

velocity

Velocity Limit

float32

0

tick/second

current

Current Limit

float32

4

ampere

Example

>>>tmx.limits
{"velocity": 300000.0, "current": 10.0}

set_limits()

endpoint: 0x0F
type: Write-only

Sets the velocity and current limits of the controller.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

velocity

Velocity Limit

float32

0

tick/second

current

Current Limit

float32

4

ampere

Example

>>>tmx.set_limits(velocity=200000.0, current=15.0)

gains

endpoint: 0x18
type: Read-only

Retrieves the position and velocity gains of the controller.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

position

Position Gain

float32

0

1/second

velocity

Velocity Gain

float32

4

ampere*second/tick

Example

>>>tmx.gains
{"position": 35.0, "velocity": 0.000012}

set_gains()

endpoint: 0x19
type: Write-only

Sets the position and velocity gains of the controller.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

position

Position Gain

float32

0

1/second

velocity

Velocity Gain

float32

4

ampere*second/tick

Example

>>>tmx.set_gains(position=25.0, velocity=0.00001)

integrator_gains

endpoint: 0x18
type: Read-only

Retrieves the velocity integrator gain of the controller.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

velocity

Velocity Integrator Gain

float32

0

ampere*second/tick

Example

>>>tmx.integrator_gains
{"velocity": 0.0001}

set_integrator_gains()

endpoint: 0x19
type: Write-only

Sets the velocity integrator gain of the controller.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

velocity

Velocity Integrator Gain

float32

0

ampere*second/tick

Example

>>>tmx.set_integrator_gains(velocity=0.0001)

Iq

endpoint: 0x14
type: Read-only

Retrieves the current (Iq) setpoint and estimate.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

setpoint

Iq Setpoint

float32

0

ampere

estimate

Iq Estimate

float32

4

ampere

Example

>>>tmx.Iq
{"setpoint": 1.0, "estimate": 0.9}

Iphase

endpoint: 0x10
type: Read-only

Retrieves the measured phase currents.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

A

A Phase Current

int16

0

ampere

B

B Phase Current

int16

0

ampere

C

C Phase Current

int16

0

ampere

Example

>>>tmx.Iphase
{"A": 1.0, "B": -0.6, "C": -0.4}

device_info

endpoint: 0x1A
type: Read-only

Retrieves device-related information.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

device_id

Device ID

uint32

0

fw_major

FW Major Ver.

uint8

4

fw_minor

FW Minor Ver.

uint8

5

fw_patch

FW Patch Ver.

uint8

6

temp

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

endpoint: 0x1E
type: Read-only

Retrieves attached motor config.

Return Values

Member

Description

Data Type

Data Offset

Default Unit

flags

Calibrated, Gimbal

uint8

0

R

Phase Resistance

uint16

1

milliohm

pole_pairs

Motor Pole Pairs

uint8

3

L

Phase Inductance

uint16

4

microhenry

Example

>>>tmx.motor_config
{"flags": 1, "R": 200, "pole_pairs": 11, "L": 100}

set_motor_config

endpoint: 0x1F
type: Write-only

Sets attached motor properties.

Arguments

Member

Description

Data Type

Data Offset

Default Unit

flags

Gimbal

uint8

0

R

Phase Resistance

uint16

1

milliohm

L

Phase Inductance

uint16

3

microhenry

Example

>>>tmx.set_motor_config(1, 5000, 2000)

timings

endpoint: 0x1B
type: Read-only

Retrieves MCU timings in each control cycle.

Return Values

Member

Description

Data Type

Data Offset

total

Total MCU Cycles

uint32

0

busy

Busy MCU Cycles

uint32

4

Example

>>>tmx.timings
{"total": 7500, "busy": 1000}

estop()

endpoint: 0x02
type: Write-only

Emergency stop: Idles the MCU immediately.

Arguments

No arguments.

Example

>>>tmx.estop()

reset()

endpoint: 0x16
type: Write-only

Resets the MCU.

Arguments

No arguments.

Example

>>>tmx.reset()

save_config()

endpoint: 0x1C
type: Write-only

Saves board configuration to Non-Volatile Memory.

Note

Saving config to NVM only works when Tinymovr is in idle mode, otherwise the command is ignored.

Arguments

No arguments.

Example

>>>tmx.save_config()

erase_config()

endpoint: 0x1D
type: Write-only

Erases board configuration and resets the MCU.

Arguments

No arguments.

Example

>>>tmx.erase_config()