Set up a mast/elevator controller
Does your robot have a mast with a carriage and an elevator? Let's add a controller for that! Our example will be using the Unity Forklift robot.
What is an elevator?
In this context we are talking about the mast of a forklift, which carries a payload like a pallet on a fork. Throughout the tutorial we may refer to the mechanism that carries and lifts the payload as an elevator, the mast, carriage or simply the lift. Understand that generally we are talking about the same thing.
Our implementation assumes that the elevator is capable of these functions:
- Raising the carriage up and down the mast
- Extending the fork longitudinally (forward)
- Moving the fork laterally (horizontally)
- Tilting the carriage backwards
If your robot does not have any axes of movement from the list above, you can ignore these parts as the controller will work regardless.
Interface
ROS Message
float32 mastVerticalExtension # Target vertical extension height
float32 mastVerticalSpeed # Speed at which the mast extends, 0 = as fast as possible
float32 forkLongitudinalExtension # Target forward extension
float32 forkLongitudinalSpeed # Speed at which the fork extends forward, 0 = as fast as possible
float32 forkTiltTarget # Target tilt angle of the fork
float32 forkTiltSpeed # Speed at which the fork tilt, 0 = as fast as possible
float32 forkLateralExtension # Target lateral movement of the fork
float32 forkLateralSpeed # Speed at which the fork moves laterally, 0 = as fast as possible
C# Interface
using System;
namespace Unity.Simulation.VehicleControllers
{
[Serializable]
public struct MastControlMessage
{
public float mastVerticalExtension; // Target vertical extension height
public float mastVerticalSpeed; // Speed at which the mast extends, 0 = as fast as possible
public float forkLongitudinalExtension; // Target forward extension
public float forkLongitudinalSpeed; // Speed at which the fork extends forward, 0 = as fast as possible
public float forkTiltTarget; // Target tilt angle of the fork
public float forkTiltSpeed; // Speed at which the fork tilt, 0 = as fast as possible
public float forkLateralExtension; // Target lateral movement of the fork
public float forkLateralSpeed; // Speed at which the fork moves laterally, 0 = as fast as possible
}
}
The drive interface accepts four main types of distance (target set points) and speed inputs:
- mastVertical. How far the elevator should move in the vertical direction and how fast it should go.
- forkLongitudinal. How far the fork should move forward and how fast it should go. Forward movement can extend and grab the pallet, which would otherwise need to be done by the whole forklift.
- forkTilt. How much the fork should tilt and how fast it should do it. Tilting is meant to stabilize the package while driving, so that it does not fall out forward.
- forkLateral. How far the fork should move sideways and how fast will it do it. Moving sideways is meant for adjusting the fork to accurately grab the pallet without having to move the whole forklift.
The maximum limits for each axis of movement can be set by using the Authoring script or simply by going to each ArticulationBody and changing the upper and lower limits on the ArticulationDrive.
Warning
Units of measurement
The default units of measurement in Unity are meters, so the extension distances are in meters while speeds are in meters per second. Fork tilt in the message is measured in radians and tilt speed - in radians per second. Keep in mind that the pre-made keyboard adapter will be accepting degrees and degrees per second inputs as those are easier to conceptualize!
Now let's add some C# components!
Add the following components to the root GameObject of your robot:
- MastController
- MastKeyboardAdapter OR MastROSAdapter
- MastAuthoring
Configurable parameters
Controller
Drag the corresponding ArticulationBody references to the fields in the MastController
- Mast Levels - these are ArticulationBodies with prismatic joints that have their degree of freedom in the vertical direction
- Fork Longitudinal / Lateral Articulation - these are also Articulation Bodies with prismatic joints set up to move in the directions presented at the top of this page.
- Fork Tilter Articulation - this is a revolute joint ArticulationBody that moves around the lateral direction of the mast.
In case your elevator consists of multiple sections that move together vertically, you can define them here as separate levels. If your elevator is just a single joint moving up and down, set the levels to 1 and drag that ArticulationBody into the field.
Keyboard Adapter
If you chose to use the Keyboard Adapter, examine the default values and adjust any that do not fit your robot. Keep in mind that distances are measured in meters and velocities are measured in meters per second or degrees and degrees per second in the Tilt field case.
- Mast Vertical / Fork Longitudinal / Fork Lateral Target - this is the distance in meters that the elevator or fork can travel before being stopped.
- Mast Vertical / Fork Longitudinal / Fork Lateral Speed - this is the speed in meters per second that the elevator or fork will travel.
- Fork Tilt Target - The maximum rotation in degrees the fork will try to tilt. This could be also limited by the Authoring script setting the lower/upper limits on the ArticulationBody drives individually.
- Fork Tilt Speed - this is the speed in degrees per second that the elevator fork will rotate in.
- Mast Input Asset - the InputActionAsset which will be used to capture input from the keyboard. If not set already, set it to the "MastInput" asset from the package Mast adapters folder.
Connector adapter
If you are using the Connector adapter, you can set the topic, which the connection will try to use to subscribe to the message.
Authoring
Let's take a look at the Mast Authoring script. It is an optional script that makes it easier to set up all the relevant ArticulationBody parameters of your robot.
All the Damping values mentioned here refer to the Damping property of each ArticulationDrive, rather than the Linear/Angular Damping of the ArticulationBody itself.
- Mast Vertical Stiffness. Strength of the spring that controls the vertical movement of the elevator. Higher values mean a more rigid and precise movement; lower values result in a more loose motion, more springiness added.
- Mast Vertical Damping. How much the velocity changes should be dampened, resulting in a slower acceleration.
- Max Mast Longitudinal Extension. How far the fork should be allowed to extend forward. Measured in meters.
- Mast Longitudinal Stiffness and Damping. Same as Vertical Stiffness and Damping.
- Fork Tilt Upper/Lower Limit. How much the tilter should be able to rotate the fork. Measured in degrees.
- Fork Tilt Stiffness and Damping. Same as Vertical Stiffness and Damping.
- Fork Lateral Upper/Lower Limit. How much the lateral sideways motion should be able to extend. Measured in meters.
- Fork Lateral Stiffness and Damping. Same as Vertical Stiffness and Damping.
Congratulations! Your Forklift mast is all set up! You should be able to control it using the keyboard or using ROS messages.