Schaltbare Kinematik (switchkins)

1. Einführung

Eine Reihe von Kinematikmodulen unterstützt die Umschaltung von Kinematikberechnungen. Diese Module unterstützen eine Standard-Kinematikmethode (Typ0), eine zweite eingebaute Methode (Typ1) und (optional) eine vom Benutzer bereitgestellte Kinematikmethode (Typ2). Für die Typ1-Methode wird in der Regel die Identitätskinematik verwendet.

Die Switchkins-Funktionalität kann für Maschinen verwendet werden, bei denen eine Steuerung der Gelenke nach der Referenzfahrt während des Einrichtens erforderlich ist oder um Bewegungen in der Nähe von Singularitäten aus dem G-Code zu vermeiden. Solche Maschinen verwenden für die meisten Vorgänge spezifische Kinematikberechnungen, können aber für die Steuerung einzelner Gelenke nach der Referenzfahrt auf Identitätskinematik umgestellt werden.

The kinematics type is selected with G12.1 P- and G13.1, from a G-code program or by interactive MDI commands. Buttons on a virtual panel (PyVCP, GladeVCP, etc.) or on hardware controls select a kinematics type through the halui provisions for activating MDI commands.

Changing the kinematics type requires the interpreter and motion parts of LinuxCNC to be synchronized, which G12.1 and G13.1 do themselves.

A deprecated HAL pin, motion.switchkins-type, selects a kinematics type as well. It is described under Usage below, because existing configurations use it.

2. Schaltbare Kinematik-Module

Die folgenden Kinematikmodule unterstützen umschaltbare Kinematiken:

xyzac-trt-kins (type0:xyzac-trt-kins type1:identity)
xyzbc-trt-kins (type0:xyzbc-trt-kins type1:identity)
genhexkins (type0:genhexkins type1:identity)
genserkins (type0:genserkins type1:identity) (puma560 example)
pumakins (type0:pumakins type1:identity)
three21kins (type0:three21kins type1:identity)
scarakins (type0:scarakins type1:identity)
5axiskins (type0:5axiskins type1:identity) (bridgemill)

Every module listed above uses its own kinematics for type0 and identity kinematics for type1. Each accepts the module string parameter sparm to swap the two, so that the machine starts in identity kinematics and the module kinematics are selected on demand:

[KINS]
KINEMATICS = xyzac-trt-kins sparm=identityfirst
# ...

Starting in identity kinematics leaves a way out of poses the module kinematics cannot solve. A module kinematics failure (near a singularity, for instance) reports an error and disables the machine; type0 is then reached without running the failing kinematics again.

Note	The sparm setting exchanges type0 and type1, so any G-code or HAL logic that selects a kinematics type by number must match.

Kinematics that solve the forward direction iteratively, genhexkins among them, need a pose to start from. While another type is running they take the estimate the caller supplies, which motion seeds from the [TRAJ]HOME world home, so they are ready to be switched to.

2.1. Identitätsbrief-Zuweisungen

Bei Verwendung eines identischen Kinematiktyps kann der Modulparameter Koordinaten verwendet werden, um den Gelenken Buchstaben in beliebiger Reihenfolge aus der Menge der zulässigen Koordinatenbuchstaben zuzuweisen. Beispiele:

[KINS]
JOINTS = 6

# konventionelle Identitätsanordnung: joint0==x, joint1==y, ...
KINEMATICS = genhexkins coordinates=xyzabc

# custom identity ordering: joint0==c, joint1==b, ...
KINEMATICS = genhexkins coordinates=cbazyx

Note	Wenn der Parameter coordinates= weggelassen wird, lauten die Standard-Zuordnungen der Gelenkbuchstaben joint0==x,joint1=y,….

Die Gelenkzuweisungen für Identitäts-Kinematiken bei Verwendung des Koordinatenparameters sind identisch mit denen für das Modul trivkins. Die Duplizierung von Achsenbuchstaben zur Zuweisung mehrerer Gelenke für einen Koordinatenbuchstaben ist jedoch im Allgemeinen nicht für serielle oder parallele Kinematiken (wie genserkins, pumakins, genhexkins usw.) geeignet, bei denen es keine einfache Beziehung zwischen Gelenken und Koordinaten gibt.

Die Duplizierung von Achskoordinatenbuchstaben wird in den Kinematikmodulen xyzac-trt-kins, xyzbc-trt-kins und 5axiskins (bridgemill) unterstützt. Typische Anwendungen für doppelte Koordinaten sind Gantry-Maschinen, bei denen zwei Motoren (Gelenke) für die Querachse verwendet werden.

2.2. Rückwärtskompatibilität

Schaltbare Kinematiken werden mit motion.switchkins-type==0 initialisiert und implementieren ihre gleichnamige Kinematikmethode. Wenn der motion.switchkins-type-Pin nicht angeschlossen ist - wie in Legacy-Konfigurationen - ist nur der Standard-Kinematik-Typ verfügbar.

3. HAL-Pins

Die Umschaltung der Kinematik wird durch den Motion-Modul-Eingang HAL pin motion.switchkins-type gesteuert. Der Fließkommawert des Pins wird in eine Ganzzahl umgewandelt und zur Auswahl eines der angebotenen Kinematik-Typen verwendet. Der Startwert Null wählt den Standard-Kinematiktyp Typ0.

Note	Der Eingangspin motion.switchkins-type ist ein Fließkomma-Eingangspin, um den Anschluss an die Ausgangspins des Motion-Moduls wie motion.analog-out-0n zu erleichtern, die von Standard M-Codes (typischerweise M68EnL0) gesteuert werden können.

Es sind Ausgangs-HAL-Pins vorgesehen, um GUIs über den aktuellen Kinematik-Typ zu informieren. Diese Pins können auch mit digitalen Eingängen verbunden werden, die von G-Code-Programmen gelesen werden, um das Programmverhalten entsprechend dem aktiven Kinematik-Typ zu aktivieren oder zu deaktivieren.

3.1. HAL Pin Zusammenfassung

motion.switchkins-type Input (float)
motion.kins-type Output (float)
kinstype.is-0 Output (bit)
kinstype.is-1 Output (bit)
kinstype.is-2 Output (bit)

A module providing more than three kinematics types has one kinstype.is-N pin per type.

4. Anwendung

4.1. HAL-Verbindungen

G12.1 and G13.1 ask motion for a kinstype directly and need no HAL connection at all.

A kinstype can also be selected by writing the pin motion.switchkins-type, which is sourced from an analog output pin like motion.analog-out-03 so that it can be set by M68 commands:

net :kinstype-select <= motion.analog-out-03
net :kinstype-select => motion.switchkins-type

Warning

Selecting the kinstype from HAL is deprecated and motion says so, once, the first time the pin is used to change it. The interpreter does not see the pin, so a program is read, its limits checked and its path looked ahead in whatever kinematics the interpreter last knew about, which is not necessarily the one that will run it. Use G12.1 and G13.1. The pin is in a grace period: it keeps working for now, but is meant to be removed in the future.

4.2. G-code commands

G12.1 P- selects a kinstype and G13.1 cancels back to identity kinematics. Which kinstype is identity is declared by the module (see Code Notes), not fixed to a number:

...
G12.1 P1  ;select kinstype 1
...
...       ;user G-code
...
G13.1     ;back to identity kinematics
...

These codes ask motion for the kinstype directly and synchronize task and motion themselves, so no HAL connection and no separate sync command are needed. The G-code words and the motion.switchkins-type pin are both acted on when they change, so whichever asked most recently is the one in force. motion.kins-type reports what is currently selected.

The pin is deprecated, see the warning under HAL Connections.

The kinstype in force is readable in G-code as #<_kins_type>, which lets a subroutine restore whatever its caller had selected:

#<saved> = #<_kins_type>
G12.1 P2
( ... )
G12.1 P#<saved>

Selection is not cancelled by the end of a program or by an abort, so that the kinstype continues to match the position readout. A program that should leave the machine in identity kinematics ends with G13.1.

A module that declares no identity kinstype refuses G13.1 with an error and can still be driven by number with G12.1; see Code Notes for how a module declares its types.

See the G-code documentation for G12.1 and G13.1 for the full description.

4.3. M-code commands

Warning

This is the deprecated route described under HAL Connections above. It is documented because existing configurations use it. New ones should use G12.1 and G13.1.

Writing motion.switchkins-type through an analog output pin needs the HAL connection shown above. Kinstype selection is then managed using G-code sequences like:

...
M68 E3 Q1 ;analog-out-03 aktualisieren, um Kinstype 1 auszuwählen
M66 E0 L0 ;Sync Interp-Bewegung
...
... ;Benutzer G-Code
...
M68 E3 Q0 ;analog-out-03 aktualisieren, um Kinstype 0 zu wählen
M66 E0 L0 ;Sync Interp-Bewegung
...

Note	Ein M66-Befehl wait-on-input aktualisiert die Variable #5399. Wenn der aktuelle Wert dieser Variablen für spätere Zwecke benötigt wird, sollte er vor dem Aufruf von M66 in eine zusätzliche Variable kopiert werden.

Diese G-Code-Befehlssequenzen werden in der Regel in G-Code-Unterprogrammen als remapped M-codes oder mit herkömmlichen M-code-Skripten implementiert.

Vorgeschlagene Codes (wie in den Sim-Konfigurationen verwendet) sind:

Herkömmliche Benutzer-M-Codes:

M128 Kintyp 0 auswählen (Standardkinematik beim Start)
M129 Kintyp 1 auswählen (typischerweise Identitätskinematik)
M130 Kinstype 2 auswählen (benutzerdefinierte Kinematik)

Neu zugeordnete M-Codes:

M428 Kintyp 0 auswählen (Standardkinematik beim Start)
M429 Kinstype 1 auswählen (typischerweise Identitätskinematik)
M430 Kinstype 2 auswählen (benutzerdefinierte Kinematik)

Note	Herkömmliche Benutzer-M-Codes (im Bereich M100-M199) gehören zur Modalgruppe 10. Neu zugeordnete M-Codes (im Bereich M200 bis M999) können eine Modalgruppe angeben. Weitere Informationen finden Sie in der Remap-Dokumentation.

4.4. INI-Datei Limit Einstellungen

LinuxCNC Bahnplanung verwendet Grenzen für die Position (min, max), Geschwindigkeit und Beschleunigung für jede anwendbare Koordinaten-Buchstaben in der Konfiguration INI-Datei angegeben. Beispiel für den Buchstaben L (im Satz XYZABCUVW):

[AXIS_L]
MIN_LIMIT =
MAX_LIMIT =
MAX_VELOCITY =
MIN_ACCELERATION =

Die angegebenen INI-Datei-Grenzwerte gelten für die Standardkinematik vom Typ 0, die beim Start aktiviert wird. Beim Umschalten auf eine andere Kinematik sind diese Grenzen möglicherweise nicht anwendbar. Da jedoch beim Umschalten der Kinematik eine Synchronisierung zwischen Interpreter und Bewegung erforderlich ist, können INI-HAL-Pins verwendet werden, um Grenzwerte für einen anstehenden Kinematik-Typ festzulegen.

Note	INI-HAL-Pins werden während eines G-Code-Programms normalerweise nicht erkannt, es sei denn, es wird einw Synchronisations (der sogenannte Queue-Buster, engl. für "wartende Befehle Zerstörer") ausgegeben. Weitere Informationen hierzu finden Sie in der milltask-Manpage ($ man milltask).

Die für eine gemeinsame Nummer (N) relevanten INI-HAL-Pins sind:

ini.N.min_limit
ini.N.max_limit
ini.N.max_acceleration
ini.N.max_velocity

Die für eine Achsenkoordinate (L) relevanten INI-HAL Pins sind:

ini.L.min_limit
ini.L.max_limit
ini.L.max_velocity
ini.L.max_acceleration

Note

Im Allgemeinen gibt es keine festen Zuordnungen zwischen Gelenknummern und Achsenkoordinatenbuchstaben. Für einige Kinematikmodule, insbesondere solche, die Identitätskinematik implementieren (trivkins), kann es spezifische Zuordnungen geben. Weitere Informationen finden Sie in der kins man page ($ man kins).

Ein vom Benutzer bereitgestellter M-code kann eine oder alle der Achsenkoordinaten Grenzen vor der Änderung der motion.switchkins-type Pin und die Synchronisierung der Interpreter und Motion-Teile von LinuxCNC ändern. Als Beispiel kann ein Bash-Skript, das halcmd aufruft, "hardcoded" werden, um eine beliebige Anzahl von HAL-Pins zu setzen:

#!/bin/bash
halcmd -f <<EOF
setp ini.x.min_limit -100
setp ini.x.max_limit  100
# ... repeat for other limit parameters
EOF

Skripte wie dieses können als Benutzer-M-Code aufgerufen und vor dem Kinstype-Switching-Mcode verwendet werden, der den motion.switchkins-type HAL Pin aktualisiert und einen interp-motion-Sync erzwingt. Normalerweise würden für jeden kinstype (0,1,2) separate Skripte verwendet werden.

Wenn Identitätskinematiken als Mittel zur Steuerung einzelner Gelenke vorgesehen sind, kann es sinnvoll sein, die in der System-INI-Datei angegebenen Grenzwerte festzulegen oder wiederherzustellen. Ein Beispiel: Ein Roboter startet nach der Referenzfahrt mit einer komplexen (nicht identischen) Kinematik (Typ 0). Das System ist so konfiguriert, dass es auf eine Identitätskinematik (Typ1) umgeschaltet werden kann, um einzelne Gelenke mit den herkömmlichen Buchstaben aus dem Satz XYZABCUVW zu manipulieren. Die Einstellungen in der INI-Datei ([AXIS_L]) sind beim Betrieb mit Identitätskinematik (Typ1) nicht anwendbar. Um diesem Anwendungsfall gerecht zu werden, können die Benutzer-M-code-Skripte wie folgt gestaltet werden:

M129 (Switch to identity type1)

INI-Datei lesen und auswerten ("parsen")
hal: setzt die INI-HAL Grenzstifte für jeden Achsenbuchstaben ([AXIS_L]) entsprechend der identitätsbezogenen Gelenknummer INI-Datei ([JOINT_N])
HAL: setp motion.switchkins-type 1
MDI: Ausführen eines Synchronisations-G-Codes (M66E0L0)

M128 (restore robot default kinematics type 0)

INI-Datei lesen und auswerten ("parsen")
HAl: Setzen der INI-HAL Limit Pins für jeden Achsenbuchstaben ([AXIS_L]) entsprechend der entsprechenden INI-Datei Einstellung ([AXIS_L])
HAL: setp motion.switchkins-type 0
MDI: Ausführen eines Synchronisations-G-Codes (M66E0L0)

Note	Die Vismach-Simulationskonfigurationen für einen Puma-Roboter demonstrieren die M-Code-Skripte (M128, M129, M130) für diesen Beispielanwendungsfall.

4.5. Koordinatensystem-Offsets Berücksichtungen

Wie die Limit Einstellungen in der INI-Datei gelten auch die Koordinatensystem-Offsets (G92, G10L2, G10L20, G43 usw.) im Allgemeinen nur für die Standard-Startkinematik vom Typ 0. Beim Wechsel des Kinematik-Typs kann es wichtig sein, entweder alle Offsets vor dem Wechsel zurückzusetzen oder die Offsets entsprechend den systemspezifischen Anforderungen zu aktualisieren.

4.6. Externe Offsets Berücksichtungen

Externe Offsets (gesetzt auf eine Achse (L) über axis.L.eoffset-request) bleiben bei Kinematikwechseln erhalten. Wenn ein Offset auf einer Achse vor dem Wechsel aktiv ist (sichtbar in axis.L.eoffset), behält der Trajektorienplaner dieses Offset nach dem Wechsel bei, ähnlich wie er die befohlene Position aus einem G-Code beibehält. Dies gewährleistet ein konsistentes Maschinenverhalten unabhängig von der aktiven Kinematik.

Wenn das Beibehalten des Offsets aufgrund von Achsgrenzenänderungen oder anderen Faktoren problematisch sein könnte, stellen Sie sicher, dass das eoffset vor dem Kinematikwechsel gelöscht und gegebenenfalls deaktiviert wird.

5. Simulationskonfigurationen

Simulationskonfigurationen (die keine Hardware erfordern) werden mit illustrativen Vismach-Anzeigen in Unterverzeichnissen von configs/sim/axis/vismach/ bereitgestellt.

5axis/table-rotary-tilting/xyzac-trt.ini (xyzac-trt-kins)
5axis/table-rotary-tilting/xyzbc-trt.ini (xyzac-trt-kins)
5axis/bridgemill/5axis.ini (5axiskins)
scara/scara.ini (scarakins)
puma/puma560.ini (genserkins)
puma/puma.ini (pumakins)
hexapod-sim/hexapod.ini (genhexkins)

6. Kinematische Bestimmungen des Benutzers

Benutzerdefinierte Kinematiken können auf Run-In-Place ("RIP") Builds kodiert und getestet werden. Eine Vorlagendatei src/emc/kinematics/userkfuncs.c ist in der Distribution enthalten. Diese Datei kann in ein Benutzerverzeichnis kopiert/umbenannt und bearbeitet werden, um benutzerdefinierte Kinematik mit kinstype==2 bereitzustellen.

Die benutzerdefinierte Kinematikdatei kann bei rt-preempt-Implementierungen aus den Out-of-Tree-Quellen kompiliert werden oder bei rtai-Systemen durch Ersetzen der In-Tree-Vorlagendatei (src/emc/kinematics/userkfuncs.c).

Preempt-rt make Beispiel:

$ userkfuncs=/home/myname/kins/mykins.c make && sudo make setuid

7. Warnungen

Unerwartetes Verhalten kann auftreten, wenn ein G-Code-Programm versehentlich mit einem inkompatiblen Kinematik-Typ gestartet wird. Unerwünschtes Verhalten kann in G-Code-Programmen umgangen werden, indem:

Anschluss geeigneter kinstype.is.N HAL-Pins an digitale Eingangspins (wie motion.digital-in-0m).
Auslesen des digitalen Eingangspins (M66 E0 Pm) beim Start des G-Code-Programms
Abbruch (M2) des G-Code-Programms mit einer Meldung (DEBUG, problem_message), wenn der Kintyp nicht geeignet ist.

Bei der interaktiven Verwendung von Jogging-Einrichtungen oder MDI-Befehlen ist Vorsicht geboten. Leitfäden sollten Anzeigen enthalten, die den aktuellen Kinematik-Typ anzeigen.

Note

Die Umstellung auf eine andere Kinematik kann erhebliche betriebliche Veränderungen mit sich bringen, die eine sorgfältige Planung, Prüfung und Schulung für den Einsatz erfordern. Die Verwaltung von Koordinatenversatz, Werkzeugkompensation und INI-Datei Limits kann komplizierte und nicht standardisierte Betriebsprotokolle erfordern.

8. Code Anmerkungen

Kinematikmodule, die switchkins-Funktionen bereitstellen, sind mit dem Objekt switchkins.o (switchkins.c) verknüpft, welches das Hauptprogramm des Moduls (rtapi_app_main()) und zugehörige Funktionen bereitstellt. Dieses Hauptprogramm liest die (optionalen) Kommandozeilenparameter des Moduls (Koordinaten, sparm) und übergibt sie an die vom Modul bereitgestellte Funktion switchkinsSetup().

Die Funktion switchkinsSetup() identifiziert die kinstype-spezifischen Setup-Routinen und die Funktionen für die Vorwärts- und Rückwärtsberechnung für jeden Kinstype (0,1,2) und setzt eine Reihe von Konfigurationseinstellungen.

A module can provide further kinstypes by calling switchkinsRegister() from within switchkinsSetup(), once per kinstype:

int switchkinsRegister(int ktype, KS kset, KF kfwd, KI kinv);

ktype runs from 0 to SWITCHKINS_MAX_TYPES-1 (defined in kinematics.h). A kinstype has to come from one route or the other, so registering one that switchkinsSetup() has already filled in is an error, and so is leaving a gap below the highest kinstype provided. Either mistake fails the module load and says which kinstype is at fault.

Each kinstype gets its own kinstype.is-N pin, so a module providing the usual three keeps the pin names it always had.

A module should also declare what each kinstype IS, again from within switchkinsSetup():

int switchkinsDeclare(int ktype, int flags);

with flags from kinematics.h:

KINSTYPE_IDENTITY no transform: the joints are the world
KINSTYPE_PRIMARY the module’s working transform

G-code reads these declarations: G13.1 cancels to the kinstype declared KINSTYPE_IDENTITY, whatever its number, so a module whose identity kinematics is not kinstype 0 still gets a working G13.1. At most one kinstype may be declared identity, and declaring a kinstype the module does not provide fails the module load. A module that declares nothing keeps working exactly as before for G12.1 P-, but G13.1 is an error, since the number of the identity kinematics is then a guess.

After calling switchkinsSetup(), rtapi_app_main() checks the supplied parameters, creates a HAL component, and then invokes the setup routine identified for each kinstype.

Each kinstype setup routine can (optionally) create HAL pins and set them to default values. A setup routine is called once per kinstype it is registered for, so a routine used for two kinstypes must not create the same pin twice. When all setup routines finish, rtapi_app_main() issues hal_ready() for the component to complete creation of the module.

8.1. Outline

The two routes in one switchkinsSetup(), with the kinematics itself left out. Types 0 to 2 are filled in through the pointer arguments as they always were, and a fourth is registered:

int switchkinsSetup(kparms* kp,
                    KS* kset0, KS* kset1, KS* kset2,
                    KF* kfwd0, KF* kfwd1, KF* kfwd2,
                    KI* kinv0, KI* kinv1, KI* kinv2
                   )
{
    kp->kinsname             = "mykins"; // must agree with the filename
    kp->halprefix            = "mykins"; // hal pin names
    kp->required_coordinates = "xyzab";
    kp->max_joints           = strlen(kp->required_coordinates);
    // remaining kparms fields

    *kset0 = identityKinematicsSetup;    // kinstype 0 is the startup default
    *kfwd0 = identityKinematicsForward;
    *kinv0 = identityKinematicsInverse;

    *kset1 = myKinematicsSetup;
    *kfwd1 = myKinematicsForward;
    *kinv1 = myKinematicsInverse;

    *kset2 = userkKinematicsSetup;
    *kfwd2 = userkKinematicsForward;
    *kinv2 = userkKinematicsInverse;

    // any further kinstype comes from switchkinsRegister(), and the
    // numbering carries on from the three above with no gaps
    if (switchkinsRegister(3, myOtherKinematicsSetup,
                              myOtherKinematicsForward,
                              myOtherKinematicsInverse)) { return -1; }

    return 0;
} // switchkinsSetup()

A module wanting fewer than three kinstypes leaves the unused pointer arguments alone and starts registering at the first free number.

For the surrounding shape, the in-tree switchkinsSetup() routines are in src/emc/kinematics: 5axiskins.c, xyzac-trt-kins.c, genserkins.c, scarakins.c and the others listed at the top of this document. None of them registers a fourth kinstype yet, so the call above has no in-tree example to copy.