Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
631 lines (386 sloc) 16 KB

Note: for the latest version, please visit the Documentation on the Wiki

QUICK API REFERENCE - v0.1.0

Constructors

Properties

Methods

Events

Machina Data Types


Constructors

Robot

Robot(string name, string make)

Creates a new instance of a Robot object with given name and brand ("ABB", "KUKA", "UR" or "HUMAN").

Robot bot = new Robot();

Properties

Version

static string

Represents current version number.

Console.WriteLine(Robot.Version);  // "0.1.0"

Methods

Mode

bool Mode(ControlMode mode)

bool Mode(string mode)

Sets the control mode the robot will operate under: "offline" (default), "execute" or "stream." Check the Walkthrough section for more information about what this means.

Robot arm = new Robot();

// Sets the robot instance to work in 'stream' mode
bot.Mode("stream");

--

Connect

bool Connect()

Scans the network for robotic devices, real or virtual, and performs all necessary operations to connect to it. Necessary for 'online' modes such as 'execute' and 'stream.'

Robot bot = new Robot();
bot.Mode("stream");

// Connects to a real or virtual controller
bot.Connect();

Disconnect

bool Disconnect()

Performs all necessary operations to safely disconnect from connected devices. Necessary for 'online' modes such as 'execute' and 'stream.'

Robot bot = new Robot();
bot.Mode("stream");
bot.Connect();

// ... do awesome stuff

// Disconnect from the controller before closing the client
bot.Disconnect();

NOTE: it is extremely important to disconnect from devices upon client closure to ensure proper disposal of all COM objects. Failure to do so may prevent the client from further successful connections and the need to restart the controller.

--

Start

bool Start()

Runs the program loaded in the device or resumes a stopped execution.

Robot bot = new Robot();
bot.Mode("stream");
bot.Connect();

// Start running the streaming program and listen for actions
bot.Start();

NOTE: works only in 'execute' and 'stream' modes.

Stop

bool Stop()

Stops the currently running program. Program execution can be resumed with Start()

Robot bot = new Robot();
bot.Mode("stream");
bot.Connect();
bot.Start();

// ... do stuff

// Stop program execution
bot.Stop();

// ... do more stuff in between

bot.Start();  // resume execution

NOTE: works only in 'execute' and 'stream' modes.

--

Export

List <string> Export()

bool Export(string filepath)

Converts all pending actions into device-specific code, and returns it as a string representation or saves it to a text file. All actions issued to the Robot instance so far will be flushed from the buffer.

Robot bot = new Robot();
bot.Mode("offline");

// ... issue a bunch of actions

// Create a program file with all issued actions so far (and flush them from the buffer)
bot.Export(@"C:\roboticProgram.mod");
Robot bot = new Robot();
bot.Mode("offline");

// ... issue a bunch of actions

List<string> code = bot.Export();

NOTE: works only in 'offline' mode.

Execute

void Execute()

Converts all pending actions into device-specific code, uploads it to the connected controller and starts execution of this program. All actions issued to the Robot instance so far will be flushed from the buffer.

Robot bot = new Robot();
bot.Mode("execute");

// ... issue a bunch of actions

// Upload all pending actions as a program to the controller and run it!
bot.Execute();

NOTE: works only in 'execute' mode.

--

Motion

MotionType Motion()

void Motion(MotionType type)

void Motion(string type)

Gets or sets the current type of motion to be applied to future translation actions. This can be "linear" (default) for straight line movements in Euclidean space, or "joint" for linear transitions between joint angles (linear movement in robot configuration space).

// Change to "joint" movement
bot.Motion("joint");
bot.Move(100, 0, 0);  // will perform a relative joint movement

// Revert back to "linear" movement
bot.Motion("linear");
bot.Move(-100, 0, 0);  // will perform a relative linear movement

NOTE: "joint" movement is easier and gentler to the mechanics of a robotic arm, but trajectories are often less intuitive, resulting in unexpected interferences and collisions. Use extreme caution when executing "joint" translations.

Coordinates

ReferenceCS Coordinates()

void Coordinates(ReferenceCS refcs)

void Coordinates(string type)

Gets or sets the coordinate system that will be used for future relative actions. This can be "global" or "world" (default) to refer to the system's global reference coordinates, or "local" to refer to the device's local reference frame. For example, for a robotic arm, the "global" coordinate system will be the robot's base, and the "local" one will be the coordinates of the end effector, after all translation and rotation transformations.

bot.Move(100, 0);         // moves 100 mm in global (default) X direction
bot.Rotate(1, 0, 0, 45);  // rotates 45 degs around global X axis

// Sets relative actions to use the device's local reference frame
bot.Coordinates("local");
bot.Move(100, 0, 0);      // move 100 mm in local X direction
bot.Rotate(1, 0, 0, 45);  // rotates 45 degs around local X axis

Speed

int Speed()

void Speed(int speedInc)

Gets the current speed value, or increases the speed value in mm/s at which future transformation actions will run. Default value is 20.

bot.SpeedTo(100);
bot.Move(100, 0);  // will move at 100 mm/s

bot.Speed(-75);
bot.Move(100, 0);  // will move at 25 mm/s

SpeedTo

void SpeedTo(int speed)

Sets the absolute speed value in mm/s at which future transformation actions will run. Default value is 20.

bot.SpeedTo(100);
bot.Move(100, 0);  // will move at 100 mm/s

bot.Speed(-75);
bot.Move(100, 0);  // will move at 25 mm/s

Zone

int Zone()

void Zone(int zoneInc)

Gets the current zone value, or increases the zone radius in mm at which the device will start transitioning to its next target transformation. You can think of this as a 'proximity precision' parameter to blend movement along consecutive waypoints. Default value is 5 mm.

// Set a 10 mm proximity radius to targets
bot.ZoneTo(10);
bot.MoveTo(200, 200, 10);

// The corners of this square movement will look 'rounded' with a 4 mm radius
bot.Zone(-6);
bot.Move(50, 0);
bot.Move(0, 50);
bot.Move(-50, 0);
bot.Move(0, -50);

ZoneTo

void ZoneTo(int zone)

Sets the absolute zone radius in mm at which the device will start transitioning to its next target transformation. You can think of this as a 'proximity precision' parameter to blend movement along consecutive waypoints. Default value is 5 mm.

// Set a 10 mm proximity radius to targets
bot.ZoneTo(10);
bot.MoveTo(200, 200, 10);

// The corners of this square movement will look 'rounded' with a 4 mm radius
bot.Zone(-6);
bot.Move(50, 0);
bot.Move(0, 50);
bot.Move(-50, 0);
bot.Move(0, -50);

PushSettings

void PushSettings()

Stores current state settings to a buffer, so that temporary changes can be made, and settings can be reverted to the stored state later with PopSettings().

bot.PushSettings();  // store current settings
bot.Speed(200);
bot.Zone(10);
bot.Move(100, 0);    // will move at 200 mm/s with 10 mm zone
bot.PopSettings();   // revert to previously stored settings

bot.Move(100, 0);    // will move at the speed and zone values before .PushSettings()

NOTE: State settings include motion type, reference coordinate system, speed and zone.

PopSettings

void PopSettings()

Reverts current settings to the state stored by the last call to PushSettings().

bot.PushSettings();  // store current settings
bot.Speed(200);
bot.Zone(10);
bot.Move(100, 0);    // will move at 200 mm/s with 10 mm zone
bot.PopSettings();   // revert to previously stored settings

bot.Move(100, 0);    // will move at the speed and zone settings before .PushSettings()

NOTE: State settings include motion type, reference coordinate system, speed and zone.

--

Move

bool Move(Point direction)

bool Move(double incX, double incY)

bool Move(double incX, double incY, double incZ)

Moves the device along a specified vector relative to its current position.

bot.MoveTo(300, 0, 500);  // device moves to global coordinates [300, 0, 500]
bot.Move(0, 0, 100);      // device is now at [300, 0, 600]

NOTE: the direction of this relative movement is defined by the current reference coordinate system.

MoveTo

bool MoveTo(Point position)

bool MoveTo(double x, double y, double z)

Moves the device to an absolute position in global coordinates.

bot.MoveTo(300, 0, 500);  // device moves to global coordinates [300, 0, 500]
bot.Move(0, 0, 100);      // device is now at [300, 0, 600]

Rotate

bool Rotate(Rotation rotation)

bool Rotate(Point vector, double angDegs)

bool Rotate(double rotVecX, double rotVecY, double rotVecZ, double angDegs)

Rotates the device a specified angle in degrees along the specified vector.

bot.Rotate(0, 0, 1, 45);  // rotates the device 45 degrees around Z axis

NOTE: the orientation of this relative rotation is defined by the current reference coordinate system.

RotateTo

bool RotateTo(Rotation rotation)

bool RotateTo(CoordinateSystem cs)

bool RotateTo(Point vecX, Point vecY)

bool RotateTo(double x0, double x1, double x2, double y0, double y1, double y2)

Rotates the devices to an absolute orientation, usually defined by the two main X and Y axes.

bot.RotateTo(-1, 0, 0, 0, 1, 0);  // rotates to a coordinate system with flipped Z axis

Transform

bool Transform(Point position, Rotation rotation)

bool Transform(Rotation rotation, Point position)

Performs a compound relative rotation + translation transformation in a single action. Note that when performing relative transformations, the R+T versus T+R order matters. The overloads are designed to take this order into account.

// Move the device 100 mm in X and then rotate 90 degs around Z axis
bot.Transform(new Point(100, 0, 0), new Rotation(0, 0, 1, 90));

NOTE: the direction and orientation of this relative transformation is defined by the current reference coordinate system.

TransformTo

bool TransformTo(Point position, Rotation rotation)

bool TransformTo(Rotation rotation, Point position)

Performs a compound absolute rotation + translation transformation, or in other words, sets both a new absolute position and orientation for the device in the same action.

// The device moves to [300, 0, 500] and is rotated 180 degs in the Y axis from the global reference CS
bot.TransformTo(new Point(300, 0, 500), new Rotation(0, 1, 0, 180));

NOTE: R+T order isn't relevant for absolute transformations, the overloads are here just for orthogonality.

Joints

bool Joints(Joints incJoints)

bool Joints(double incJ1, double incJ2, double incJ3, double incJ4, double incJ5, double incJ6)

Increase the rotation angle in degrees of the joints in mechanical devices, specially robotic arms.

bot.Joints(-15, 0, 0, 0, 0, 0);  // rotate joint 1 (base) -15 degs
bot.Joints(0, 0, 0, 0, 0, 180);  // rotate joint 6 (end effector) 180 degs

JointsTo

bool JointsTo(Joints joints)

bool JointsTo(double j1, double j2, double j3, double j4, double j5, double j6)

Sets the rotation angle in degrees of the joints in mechanical devices, specially robotic arms.

bot.JointsTo(0, 0, 0, 0, 0, 0);   // sets the robot to move to home position
bot.JointsTo(0, 0, 0, 0, 90, 0);  // set joint 5 to rotate 90 degs

Wait

bool Wait(long timeMillis)

Pause program execution for specified milliseconds.

bot.MoveTo(300, 200, 400);
bot.Wait(1500);    // wait 1.5 s before executing next action
bot.Move(0, 0, 100);

Message

bool Message(string message)

Displays a text message on the device. This will depend on the device's configuration. For example, for ABB robots it will display it on the FlexPendant's log window.

bot.MoveTo(300, 200, 400);
bot.Message("Moving up!");
bot.Move(0, 0, 100);

Comment

bool Comment(string comment)

Adds a commented line into the robot instructions set. This is useful in offline mode when compiling programs in device-specific language, to add comments, annotations and reminders.

bot.Comment("Here we move the robot to home position");
bot.JointsTo(0, 0, 0, 0, 90, 0);

If this code was compiled in RAPID language for ABB robots, it would look like this:

  ! Here we move the robot to home position
  MoveAbsJ [[0,0,0,0,90,0],[0,9E9,9E9,9E9,9E9,9E9]],vel100,z5,Tool0\WObj:=WObj0;

Events

BufferEmpty

event BufferEmptyHandler BufferEmpty

This event rises whenever the client has released all pending actions to the controller, and there are no more instructions to be issued. Think of this as an event that signals a 'demand' to issue new orders to the connected device. This is useful when developing time-sensitive apps whose actions depend on the state of the environment, like motion controllers, interactive installations and so on...

// Subscribe to BufferEmptyEvents
bot.BufferEmpty += new BufferEmptyHandler(IssueNewMovement);

void IssueNewMovement(object sender, EventArgs args) {
    // Handle the event by moving to the most current target
    bot.MoveTo(currentTarget);
}

NOTE: works only in 'stream' mode.

Machina Data Types

Point

Point()

Point(double x, double y, double z)

Point(Point p)

Represents a location or a vector in three dimensional space. This class features several helper methods and operator overloads to perform vector algebra.

Rotation

Rotation()

Rotation(double w, double x, double y, double z)

Rotation(Rotation r)

Rotation(CoordinateSystem cs)

Rotation(Point vec, double angDegs)

Rotation(Point vecX, Point vecY)

Rotation(double x0, double x1, double x2, double y0, double y1, double y2)

Represents an rotation in three-dimensional space defined by its quaternion representation. This class features several helper methods and operator overloads to perform quaternion algebra.

Joints

Joints()

Joints(Joints j)

Joints(double j1, double j2, double j3, double j4, double j5, double j6)

A six-dimensional vector useful as a representation of the rotational values at the joints of a robotic manipulator.

CoordinateSystem

CoordinateSystem()

CoordinateSystem(Point vecX, Point vecY)

CoordinateSystem(double x0, double x1, double x2, double y0, double y1, double y2)

Represents a Coordinate System composed of a triplet of orthogonal XYZ unit vectors following right-hand rule orientations. Useful for spatial and rotational orientation.

You can’t perform that action at this time.