code_notes.lyx

CNC 的开放码,EMC2 V2.2.8版

#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\language english
\inputencoding default
\fontscheme bookman
\graphics default
\float_placement !htbp
\paperfontsize default
\spacing single 
\papersize letterpaper
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 0.8in
\bottommargin 0.8in
\secnumdepth 1
\tocdepth 5
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Chapter

Introduction
\layout Section

Intended audience
\layout Standard

This document is a collection of notes about the internals of EMC2.
 It is primarily of interest to developers, however much of the information
 here may also be of interest to system integrators and others who are simply
 curious about how EMC2 works.
 Much of this information is now outdated and has never been reviewed for
 accuracy.
\layout Section

Organisation
\layout Standard

There will be a chapter for each of the major components of EMC2, as well
 as chapter(s) covering how they work together.
 This document is very much a work in progress, and it's layout may change
 in the future.
\layout Chapter

Overview of EMC2
\layout Section

Terms and definitions
\layout Description

AXIS An axis is one of the six degrees of freedom that define a tool position
 in three dimensional Cartesian space.
 Those axes are X, Y, Z, A, B, and C, where X, Y, and Z are linear coordinates
 that determine where the tip of the tool is, and A, B, and C are angular
 coordinates that determine the tool orientation.
 Unfortunately 
\begin_inset Quotes eld
\end_inset 

axis
\begin_inset Quotes erd
\end_inset 

 is also sometimes used to mean a degree of freedom of the machine itself,
 such as the saddle, table, or quill of a Bridgeport type milling machine.
 On a Bridgeport this causes no confusion, since movement of the table directly
 corresponds to movement along the X axis.
 However, the shoulder and elbow joints of a robot arm and the linear actuators
 of a hexapod do not correspond to movement along any Cartesian axis, and
 in general it is important to make the distinction between the Cartesian
 axes and the machine degrees of freedom.
 In this document, the latter will be called 
\begin_inset Quotes eld
\end_inset 

joints
\begin_inset Quotes erd
\end_inset 

, not axes.
 (The GUIs and some other parts of the code may not always follow this distincti
on, but the internals of the motion controller do.)
\layout Description

JOINT A joint is one of the movable parts of the machine.
 Joints are distinct from axes, although the two terms are sometimes (mis)used
 to mean the same thing.
 In EMC2, a joint is a physical thing that can be moved, not a coordinate
 in space.
 For example, the quill, knee, saddle, and table of a Bridgeport mill are
 all joints.
 The shoulder, elbow, and wrist of a robot arm are joints, as are the linear
 actuators of a hexapod.
 Every joint has a motor or actuator of some type associated with it.
 Joints do not necessarily correspond to the X, Y, and Z axes, although
 for machines with trivial kinematics that may be the case.
 Even on those machines, joint position and axis position are fundamentally
 different things.
 In this document, the terms 
\begin_inset Quotes eld
\end_inset 

joint
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

axis
\begin_inset Quotes erd
\end_inset 

 are used carefully to respect their distinct meanings.
 Unfortunately that isn't necessarily true everywhere else.
 In particular, GUIs for machines with trivial kinematics may gloss over
 or completely hide the distinction between joints and axes.
 In addition, the ini file uses the term 
\begin_inset Quotes eld
\end_inset 

axis
\begin_inset Quotes erd
\end_inset 

 for data that would more accurately be described as joint data, such as
 input and output scaling, etc.
\layout Description

POSE A pose is a fully specified position in 3-D Cartesian space.
 In the EMC2 motion controller, when we refer to a pose we mean an EmcPose
 structure, containing three linear coordinates and three angular ones.
\layout Chapter

Motion Controller
\layout Section

Introduction
\layout Standard

The motion controller receives commands from user space modules via a shared
 memory buffer, and executes those commands in realtime.
 The status of the controller is made available to the user space modules
 through the same shared memory area.
 The motion controller interacts with the motors and other hardware using
 the HAL (Hardware Abstraction Layer).
 This document assumes that the reader has a basic understanding of the
 HAL, and uses terms like hal pins, hal signals, etc, without explaining
 them.
 For basic information about the HAL, read the 
\begin_inset Quotes eld
\end_inset 

Introduction to HAL
\begin_inset Quotes erd
\end_inset 

 document (available as CVS/documents/lyx/Hal_Introduction.lyx, or CVS/emc2/docs/
Hal_Introduction.pdf, or http://linuxcnc.org/Hal_Introduction.pdf).
 Another chapter of this document will eventually go into the internals
 of the HAL itself, but in this chapter, we only use the HAL API as defined
 in emc2/src/hal/hal.h.
\layout Section

Block diagrams and Data Flow
\layout Standard

Figure 
\begin_inset LatexCommand \ref{fig:motion-joint-controller-block-diag}

\end_inset 

 is a block diagram of a joint controller.
 There is one joint controller per joint.
 The joint controllers work at a lower level than the kinematics, a level
 where all joints are completely independent.
 All the data for a joint is in a single joint structure.
 Some members of that structure are visible in the block diagram, such as
 coarse_pos, pos_cmd, and motor_pos_fb.
\layout Standard


\begin_inset Float figure
wide false
collapsed false

\layout Standard
\align center 

\begin_inset Graphics
	filename emc2-motion-joint-controller-block-diag.ps
	width 7in
	height 7in
	keepAspectRatio
	clip

\end_inset 


\layout Caption


\begin_inset LatexCommand \label{fig:motion-joint-controller-block-diag}

\end_inset 

Joint Controller Block Diagram
\end_inset 


\layout Standard

Figure 
\begin_inset LatexCommand \ref{fig:motion-joint-controller-block-diag}

\end_inset 

 shows five of the seven sets of position information that form the main
 data flow through the motion controller.
 The seven forms of position data are as follows:
\layout Enumerate

emcmotStatus->carte_pos_cmd - This is the desired position, in Cartesian
 coordinates.
 It is updated at the traj rate, not the servo rate.
 In coord mode, it is determined by the traj planner.
 In teleop mode, it is determined by the traj planner? In free mode, it
 is either copied from actualPos, or generated by applying forward kins
 to (2) or (3).
\layout Enumerate

emcmotStatus->joints[n].coarse_pos - This is the desired position, in joint
 coordinates, but before interpolation.
 It is updated at the traj rate, not the servo rate.
 In coord mode, it is generated by applying inverse kins to (1) In teleop
 mode, it is generated by applying inverse kins to (1) In free mode, it
 is copied from (3), I think.
\layout Enumerate

emcmotStatus->joints[n].pos_cmd - This is the desired position, in joint
 coords, after interpolation.
 A new set of these coords is generated every servo period.
 In coord mode, it is generated from (2) by the interpolator.
 In teleop mode, it is generated from (2) by the interpolator.
 In free mode, it is generated by the free mode traj planner.
\layout Enumerate

emcmotStatus->joints[n].motor_pos_cmd - This is the desired position, in
 motor coords.
 Motor coords are generated by adding backlash compensation, lead screw
 error compensation, and offset (for homing) to (3).
 It is generated the same way regardless of the mode, and is the output
 to the PID loop or other position loop.
\layout Enumerate

emcmotStatus->joints[n].motor_pos_fb - This is the actual position, in motor
 coords.
 It is the input from encoders or other feedback device (or from virtual
 encoders on open loop machines).
 It is "generated" by reading the feedback device.
\layout Enumerate

emcmotStatus->joints[n].pos_fb - This is the actual position, in joint coordinate
s.
 It is generated by subtracting offset, lead screw error compensation, and
 backlash compensation from (5).
 It is generated the same way regardless of the operating mode.
\layout Enumerate

emcmotStatus->carte_pos_fb - This is the actual position, in Cartesian coordinat
es.
 It is updated at the traj rate, not the servo rate.
 Ideally, actualPos would always be calculated by applying forward kinematics
 to (6).
 However, forward kinematics may not be available, or they may be unusable
 because one or more axes aren't homed.
 In that case, the options are: A) fake it by copying (1), or B) admit that
 we don't really know the Cartesian coordinates, and simply don't update
 actualPos.
 Whatever approach is used, I can see no reason not to do it the same way
 regardless of the operating mode.
 I would propose the following: If there are forward kins, use them, unless
 they don't work because of unhomed axes or other problems, in which case
 do (B).
 If no forward kins, do (A), since otherwise actualPos would _never_ get
 updated.
 
\layout Section

Commands
\layout Standard

This section simply lists all of the commands that can be sent to the motion
 module, along with detailed explanations of what they do.
 The command names are defined in a large typedef enum in emc2/src/emc/motion/mo
tion.h, called cmd_code_t.
 (Note that in the code, each command name starts with 
\begin_inset Quotes eld
\end_inset 

EMCMOT_
\begin_inset Quotes erd
\end_inset 

, which is omitted here.)
\layout Standard

The commands are implemented by a large switch statement in the function
 emcmotCommandHandler(), which is called at the servo rate.
 More on that function later.
\layout Standard

There are approximately 44 commands - this list is still under construction.
\layout Subsection

ABORT
\layout Standard

The ABORT command simply stops all motion.
 It can be issued at any time, and will always be accepted.
 It does not disable the motion controller or change any state information,
 it simply cancels any motion that is currently in progress.
\begin_inset Foot
collapsed false

\layout Standard

It seems that the higher level code (TASK and above) also use ABORT to clear
 faults.
 Whenever there is a persistent fault (such as being outside the hardware
 limit switches), the higher level code sends a constant stream of ABORTs
 to the motion controller trying to make the fault go away.
 Thousands of 'em....
 That means that the motion controller should avoid persistent faults.
 This needs looked into.
\end_inset 


\layout Subsubsection

Requirements
\layout Standard

None.
 The command is alway accepted and acted on immediately.
\layout Subsubsection

Results
\layout Standard

In free mode, the free mode trajectory planners are disabled.
 That results in each joint stopping as fast as it's accel (decel) limit
 allows.
 The stop is not coordinated.
 In teleop mode, the commanded Cartesian velocity is set to zero.
 I don't know exactly what kind of stop results (coordinated, uncoordinated,
 etc), but will figure it out eventually.
 In coord mode, the coord mode trajectory planner is told to abort the current
 move.
 Again, I don't know the exact result of this, but will document it when
 I figure it out.
\layout Subsection

FREE
\layout Standard

The FREE command puts the motion controller in free mode.
 Free mode means that each joint is independent of all the other joints.
 Cartesian coordinates, poses, and kinematics are ignored when in free mode.
 In essence, each joint has it's own simple trajectory planner, and each
 joint completely ignores the other joints.
 Some commands (like JOG) only work in free mode.
 Other commands, including anything that deals with Cartesian coordinates,
 do not work at all in free mode.
\layout Subsubsection

Requirements
\layout Standard

The command handler applies no requirements to the FREE command, it will
 always be accepted.
 However, if any joint is in motion (GET_MOTION_INPOS_FLAG() == FALSE),
 then the command will be ignored.
 This behaviour is controlled by code that is now located in the function
 
\begin_inset Quotes eld
\end_inset 

set_operating_mode()
\begin_inset Quotes erd
\end_inset 

 in control.c, that code needs to be cleaned up.
 I believe the command should not be silently ignored, instead the command
 handler should determine whether it can be executed and return an error
 if it cannot.
\layout Subsubsection

Results
\layout Standard

If the machine is already in free mode, nothing.
 Otherwise, the machine is placed in free mode.
 Each joint's free mode trajectory planner is initialised to the current
 location of the joint, but the planners are not enabled and the joints
 are stationary.
\layout Subsection

TELEOP
\layout Standard

The TELEOP command places the machine in teleoperating mode.
 In teleop mode, movement of the machine is based on Cartesian coordinates
 using kinematics, rather than on individual joints as in free mode.
 However the trajectory planner per se is not used, instead movement is
 controlled by a velocity vector.
 Movement in teleop mode is much like jogging, except that it is done in
 Cartesian space instead of joint space.
 On a machine with trivial kinematics, there is little difference between
 teleop mode and free mode, and GUIs for those machines might never even
 issue this command.
 However for non-trivial machines like robots and hexapods, teleop mode
 is used for most user commanded jog type movements.
\layout Subsubsection

Requirements
\layout Standard

The command handler will reject the TELEOP command with an error message
 if the kinematics cannot be activated because the one or more axes have
 not been homed.
 In addition, if any joint is in motion (GET_MOTION_INPOS_FLAG() == FALSE),
 then the command will be ignored (with no error message).
 This behaviour is controlled by code that is now located in the function
 
\begin_inset Quotes eld
\end_inset 

set_operating_mode()
\begin_inset Quotes erd
\end_inset 

 in control.c.
 I believe the command should not be silently ignored, instead the command
 handler should determine whether it can be executed and return an error
 if it cannot.
\layout Subsubsection

Results
\layout Standard

If the machine is already in teleop mode, nothing.