ASUR2019Drivetrain

Version: v1.0.1

A Python library that facilitates the control of the ASUR 2019 drivetrain.

Table of Contents

• Overview
• Current Features
• Requirements
• Installation
• How to Use
  • Import simpledrivetrain
  • Creating a SimpleDrivetrain object
  • Adding, removing, and accessing drive motors
  • Updating drivetrain orientation
  • Getting motor velocities
• License

Overview

ASUR2019Drivetrain is a stripped-down version of SimpleDrivetrain that allows for easy control of ASUR's 2019 drivetrain. SimpleDrivetrain provides an easy way to define a drivetrain by the location and orientation of its motors, and calculate the desired velocities for each motor given the overall desired translational velocity and rotational velocities for the drivetrain, and ASUR2019Drivetrain restricts the robot motor arrangement to that used in the 2019 MATE and Robosub competitions.

Current Features

• Local-oriented and field-oriented, thrust-aware, translation and rotation in 3-space
• Motor-level PWM scaling from user-defined PWM ranges or custom scaling functions

Requirements

• Python 2.7+/3.x
• Numpy

Installation

Install SimpleDrivetrain by placing the ASUR2019Drivetrain source files in your src directory.

How to Use

Import simpledrivetrain

from simpledrivetrain.simple_drivetrain import SimpleDrivetrain

Creating a SimpleDrivetrain object

drivetrain = SimpleDrivetrain()

Adding, removing, and accessing drive motors

• Motors can be added to the drivetrain by calling the add_new_motor method and supplying:
  • The name of the motor, a unique string identifier
  • The position of the motor relative to the drivetrain's center in the form of a 3D coordinate list e.g. [x, y, z]
  • The motor's positive drive direction in the form of a 3D cartesian direction vector e.g. [x, y, z]
  • Optionally, a boolean value inverted to set whether the motor is inverted
  • Optionally, a 3-tuple pwm_bounds in the form of (FULL_REVERSE, FULL STOP, FULL_FORWARD) to which to scale the motor velocity
  • Optionally, a function pwm_scaling_func which accepts a motor velocity in [-1, 1] and scales it to a desired pwm range

  drivetrain.add_new_motor(name, position, direction, inverted=False, 
                           pwm_bounds=(0, 512, 1024), pwm_scaling_func=None)

• Motors can be removed from the drivetrain by calling the remove_motor_by_name method and supplying the name of the motor to remove

  drivetrain.remove_motor_by_name(name)

  alternatively, a motor can also be removed from the drivetrain by calling the remove_motor_by_index method and supplying the motor's index of addition

  drivetrain.remove_motor_by_index(index)

• Motors can be accessed by calling the get_motor_by_name method and supplying the name of the motor to retrieve

  motor = drivetrain.get_motor_by_name(name)

  alternatively, a motor can also be accessed by calling get_motor_by_index method and supplying the motor's index of addition

  motor = drivetrain.get_motor_by_index(index)

• Motors can also be accessed through the motors instance variable, which stores the motors by order of addition in a list

  motorlist = drivetrain.motors

• Alternatively, motors and orientation can be loaded from an xml file by calling the load_drivetrain_from_file method and supplying the filepath string pointing to the xml file:

  drivetrain.load_drivetrain_from_file(filepath)

  For an example file, see Example SimpleDrivetrain xml FIle.

Updating drivetrain orientation

drivetrain.orientation = (pitch, roll, yaw)    

Getting motor velocities

• Motor velocities scaled in [-1, 1], stored in a list by order of motor addition, can be calculated by calling the get_motor_vels method and supplying:
  • translation, a 3D vector representing the drivetrain's desired overall velocity, e.g. [x, y, z]
  • rotation, a 3D vector representing the drivetrain's desired rotational velocity, e.g. [pitching, rolling, yawing]
  • force_local_oriented, a boolean value which, if set to true, ignores current drivetrain orientation and calculates local-oriented motor values. It is set to false by default.

  drivetrain.get_motor_vels(translation, rotation, force_local_oriented=False)

• Motor velocities scaled according to user-defined, motor-level PWM ranges or scaling functions, stored in a list by order of motor addition, can be calculated by calling the get_motor_vels_scaled method and supplying the same translation, rotation, and force_local_oriented parameters as the get_motor_vels method:

  drivetrain.get_motor_vels_scaled(translation, rotation, force_local_oriented=False)

License

ASUR2019Drivetrain is distributed under the terms of the MIT License.