Switchable Kinematics (switchkins)

1. Введение

A number of kinematics modules support the switching of kinematics calculations. These modules support a default kinematics method (type0), a second built-in method (type1), and (optionally) a user-provided kinematics method (type2). Identity kinematics are typically used for the type1 method.

The switchkins functionality can be used for machines where post-homing joint control is needed during setup or to avoid movement near singularities from G-code. Such machines use specific kinematics calculations for most operations but can be switched to identity kinematics for control of individual joints after homing.

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. Switchable Kinematic Modules

The following kinematics modules support switchable kinematics:

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. назначения идентифицирующей буквы

При использовании типа кинематики identity параметр модуля координаты можно использовать для назначения букв сочленениям в произвольном порядке из набора разрешенных букв координат. Примеры:

[KINS]
JOINTS = 6

# conventional identity ordering: joint0==x, joint1==y, ...
KINEMATICS = genhexkins coordinates=xyzabc

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

Note	Если параметр coordinates= опущен, по умолчанию буква-сочленение присваиваемых идентификаторов будут joint0==x,joint1=y,…

Назначения сочленений, предусмотренные для кинематики identity при использовании параметра координат, идентичны тем, которые предусмотрены для модуля trivkins. Однако дублирование букв осей для назначения нескольких сочленений букве координат обычно не применимо для последовательной или параллельной кинематики (например, genserkins, pumakins, genhexkins и т. д.), где нет простой взаимосвязи между сочленениями и координатами.

Дублирование букв координат осей поддерживается в модулях кинематики xyzac-trt-kins, xyzbc-trt-kins и 5axiskins (bridgemill). Типичным применением дублирующихся координат являются портальные станки, в которых для поперечной оси используются два двигателя (сочленения).

2.2. Обратная совместимость

Переключаемая кинематика инициализируется с помощью motion.switchkins-type==0, реализующего одноименный метод кинематики. Если контакт типа motion.switchkins не подключен (как в устаревших конфигурациях), доступен только тип кинематики по умолчанию.

3. HAL Контакты

Переключение кинематики контролируется входным контактом HAL модуля движения motion.switchkins-type. Значение вывода с плавающей запятой усекается до целого числа и используется для выбора одного из предоставленных типов кинематики. Нулевое значение запуска выбирает тип кинематики по умолчанию type0.

Note	Входной контакт типа motion.switchkins имеет тип числа с плавающей запятой, чтобы облегчить подключение к выходным контактам модуля движения, таким как motion.analog-out-0n, которые управляются стандартными M-кодами (обычно M68EnL0).

Выходные контакты HAL предназначены для информирования ГИП о текущем типе кинематики. Эти контакты также можно подключить к цифровым входам, которые считываются программами G-кода для включения или отключения поведения программы в соответствии с активным типом кинематики.

3.1. Сводная информация о контактах HAL

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. Использование

4.1. HAL Connections

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 ;update analog-out-03 to select kinstype 1
M66 E0 L0 ;sync interp-motion
...
...       ;user G-code
...
M68 E3 Q0 ;update analog-out-03 to select kinstype 0
M66 E0 L0 ;sync interp-motion
...

Note	Команда M66 wait-on-input обновляет переменную #5399. Если текущее значение этой переменной необходимо для последующих целей, его следует скопировать в дополнительную переменную перед вызовом M66.

Эти последовательности команд G-кода обычно реализуются в подпрограммах G-кода как переназначенные M-коды или с помощью обычных сценариев M-кода.

Предлагаемые коды (используемые в конфигурациях sim):

Обычные пользовательские M-коды:

M128 Выбор kinstype 0 (кинематика по умолчанию при запуске)
M129 Выбирает kinstype 1 (обычно идентичная кинематика)
M130 Выбирает kinstype 2 (кинематика, предоставляемая пользователем)

Переназначенные М-коды:

M428 Выбор kinstype 0 (кинематика по умолчанию при запуске)
M429 Выберите kinstype 1 (обычно идентичная кинематика)
M430 Выбор kinstype 2 (кинематика, предоставляемая пользователем)

Note	Обычные пользовательские М-коды (в диапазоне от M100 до M199) находятся в модальной группе 10. Переназначенные M-коды (в диапазоне от M200 до M999) могут указывать модальную группу. Дополнительную информацию см. в документации по переназначению.

4.4. Настройки ограничений INI-файла

При планировании траектории LinuxCNC используются ограничения на положение (мин, максимум), скорость и ускорение для каждой применимой буквы координат, указанной в INI-файле конфигурации. Пример буквы L (в наборе XYZABCUVW):

[AXIS_L]
MIN_LIMIT =
MAX_LIMIT =
MAX_VELOCITY =
MIN_ACCELERATION =

Указанные ограничения файла INI применяются к типу кинематики по умолчанию типа 0, который активируется при запуске. Эти ограничения могут не применяться при переключении на альтернативную кинематику. Однако, поскольку при переключении кинематики требуется синхронизация движения интерпретатора, контакты INI-HAL можно использовать для установки пределов для ожидающего типа кинематики.

Note	Контакты INI-HAL обычно не распознаются во время работы программы G-кода, если не выдана команда синхронизации (queue-buster). Дополнительную информацию см. на странице руководства milltask ($ man milltask).

Соответствующие контакты INI-HAL для номера сочленения (N):

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

Соответствующие контакты INI-HAL для координаты оси (L):

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

Note

В общем, не существует фиксированных сопоставлений между номерами сочленений и буквами координат осей. Для некоторых модулей кинематики могут существовать специальные сопоставления, особенно для тех, которые реализуют идентичную кинематику (trivkins). Дополнительную информацию смотрите на странице руководства kins ($ man kins).

Предоставленный пользователем M-код может изменить любые или все пределы координат оси перед изменением контакта типа motion.switchkins и синхронизацией интерпретатора и движущихся частей LinuxCNC. Например, скрипт bash, вызывающий halcmd, может быть hardcoded для установки любого количества контактов HAL:

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

Подобные скрипты могут быть вызваны как пользовательский M-код и использованы перед M-кодом переключения kins, который обновляет контакт HAL типа motion.switchkins-type и вызывает принудительную синхронизацию interp-motion. Обычно для каждого kinstype (0,1,2) используются отдельные скрипты.

Когда identity kinematics предоставляется в качестве средства управления отдельными сочленениями, может быть удобно устанавливать или восстанавливать пределы, указанные в системном INI-файле. Например, робот стартует со сложной (non-identity) кинематикой (type0) после возврата в исходное положение. Система настроена так, что ее можно переключить на identity kinematics (type1) для манипулирования отдельными сочленениями с помощью обычных букв из набора XYZABCUVW. Настройки INI-файла ([AXIS_L]) не применимы при работе с identity (type1) kinematics. Для решения этого варианта использования пользовательские скрипты M-кода могут быть разработаны следующим образом:

M129 (Switch to identity type1)

прочитать и разобрать INI-файл
HAL: setp ограничительные контакты INI-HAL для каждой буквы оси ([AXIS_L]) в соответствии с настройкой ([JOINT_N]) identity-referenced номера сочленения INI файла
HAL: setp motion.switchkins-type 1
MDI: выполните синхронизирующий G-код (M66E0L0)

M128 (restore robot default kinematics type 0)

прочитать и разобрать INI-файл
HAL: setp ограничительные контакты INI-HAL для каждой буквы оси ([AXIS_L]) в соответствии с соответствующей настройкой INI-файла ([AXIS_L])
HAL: setp motion.switchkins-type 0
MDI: выполните синхронизирующий G-код (M66E0L0)

Note	Конфигурации моделирования vismach для робота Puma демонстрируют сценарии M-кода (M128, M129, M130) для этого примера использования.

4.5. Соображения смещения системы координат

Как и настройки предельных значений INI-файла, смещения системы координат (G92, G10L2, G10L20, G43 и т. д.) обычно применимы только для type 0 типа kinematics при запуске по умолчанию. При переключении типов кинематики может быть важно либо сбросить все смещения перед переключением, либо обновить смещения в соответствии с требованиями конкретной системы.

4.6. Внешние соображения смещения

External offsets (set to an axis (L) via axis.L.eoffset-request) are preserved during kinematics switches. When an offset is active on an axis before the switch (visible in axis.L.eoffset), the trajectory planner maintains that same offset after the switch, similar to how it maintains the commanded position from a G-code. This ensures consistent machine behavior regardless of the active kinematics.

If maintaining the offset will be an issue due to axis limit changes or other concerns, be sure to clear and possibly disable the eoffset before making a kinematics switch.

5. Конфигурации моделирования

Конфигурации моделирования (не требующие аппаратного обеспечения) снабжены иллюстративными дисплеями vismach в подкаталогах configs/sim/axis/vismach/ .

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. Условия пользовательской кинематики

Пользовательскую кинематику можно закодировать и протестировать в сборках Run-In-Place (RIP). В раздаче имеется файл шаблона src/emc/kinematics/userkfuncs.c. Этот файл можно скопировать/переименовать в пользовательский каталог и отредактировать для предоставления пользовательской кинематики с kinstype==2.

Пользовательский файл кинематики можно скомпилировать из исходных расположений вне дерева для реализаций rt-preempt или путем замены файла шаблона в дереве (src/emc/kinematics/userkfuncs.c) для систем rtai.

Preempt-rt make пример:

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

7. Предупреждения

Неожиданное поведение может возникнуть, если программа G-кода случайно запускается с несовместимым типом кинематики. Нежелательное поведение можно обойти в программах G-кода следующим образом:

Подключение соответствующих контактов HAL kinstype.is.N к контактам цифрового входа (например, motion.digital-in-0m).
Чтение контакта цифрового входа (M66 E0 Pm) в начале программы G-кода
Прерывание (M2) программы G-кода с сообщением (DEBUG, problem_message), если kinstype не подходит.

При интерактивном использовании возможностей медленной подачи или команд MDI оператору требуется соблюдать осторожность. В ГИП должны быть индикаторы для отображения текущего типа кинематики.

Note

Переключаемая кинематика может привести к существенным эксплуатационным изменениям, требующим тщательного проектирования, тестирования и подготовки к развертыванию. Управление смещениями координат, компенсацией инструмента и ограничениями файлов INI может потребовать сложных и нестандартных рабочих протоколов.

8. Примечания к коду

Кинематические модули, обеспечивающие функциональность switchkins, связаны с объектом switchkins.o (switchkins.c), который предоставляет main программу модуля (rtapi_app_main()) и связанные с ней функции. Эта main программа считывает (необязательные) параметры командной строки модуля (coordinates, sparm) и передает их в функцию switchkinsSetup(), предоставляемую модулем.

Функция switchkinsSetup() идентифицирует kinstype специфичные процедуры настройки и функции для прямого и обратного расчета для каждого kinstype (0,1,2) и устанавливает ряд настроек конфигурации.

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.