CAROUSEL(9)

📦
version 2.9.4 · 4 versions
, in ubuntu resolute, ubuntu stonking

okay so bestie, welcome to the CAROUSEL(9) manual page — it's a HAL Component and it's literally here to make toolchanger carousels make sense. no cap, it's giving ✨very useful✨. let's get into it 🎀

💖 NAME

carousel — orient a toolchanger carousel using various encoding schemes 🌸

✨ SYNOPSIS

loadrt carousel pockets=N[,N] encoding=ssss[,sss] num_sense=N[,N]
dir=N[,N]
  • pockets — the number of pockets in each toolchanger. use up to 8 numbers separated by commas to create multiple carousel components. multi-carousel slay 💅
  • encoding — the position encoding. your options are gray, binary, bcd, index, edge, counts or single. Default = 'gray'
  • num_sense — the number of position sense pins. Default = 4.
  • dir — set to 1 for unidirectional or 2 for bidirectional operation. Default = bidirectional
  • parity — set to 1 for odd parity, 0 for even parity checking. Default = 0 (even)

🦋 DESCRIPTION

okay so this component is here to help you operate various types of carousel-type toolchangers. it's the bestie your toolchanger didn't know it needed 🫶

You can configure it to work with binary, binary-coded decimal (BCD) or gray-coded position feedback (that's the 'binary', 'bcd' and 'gray' modes). Or, alternatively, it can work with an individual sensor for each tool position ('single' mode), or with a sensor at each tool position and a separate index ('index' mode). Systems using a stepper motor or quadrature encoder are also supported ('counts' mode). And edge? it's a special case of index mode for tool changers with pockets on both the rising and falling edges of the position sensor. (Seen on at least one Denford Orac.) 🔥

Both unidirectional and bidirectional systems are supported — and yeah, that includes the ones that reverse against a stop when in position. iconic behaviour fr fr.

The number of carousel component instances created depends on the number of entries in the pockets modparam. For example:

loadrt carousel pockets=10,10,8

Would create 3 carousel instances with 10, 10 and 8 pockets. The other parameters are optional — if they're absent, then defaults will be used. Any missing entry will assume the previous value. lowkey convenient 💅

When the enable pin is set to true, the component will immediately set the "active" pin to true and then (for a bidirectional instance) calculate the shortest path to the requested pocket number. The appropriate motor direction output pins will then be set. Bit outputs for forward and reverse are provided as well as a three-state velocity output for driving a DC motor PWM or a velocity-mode stepgen. she's efficient, your honour ✨

The component will monitor the carousel position and, when the correct position is reached, set the motor-control pins to 0, set "active" to 0 and set "ready" to 1. mission accomplished 🎀

In 'index', 'edge' or 'counts' mode there is a need to find the initial home position of the carousel. The first time that the "enable" pin is set; the carousel will rotate forwards searching for a home signal. In 'index' and 'edge' mode this is when both the index and pulse inputs are true. In 'counts' mode only the index input needs to be set to set home. Additionally in 'counts' mode the usual index-enable logic of the encoder counters is supported.

With some carousel designs the carousel will not stop immediately. To allow for this, set the align-dc pin to a low velocity to be used for a final latching move, and set the decel-time to a suitable value. Once the decel-time has expired the carousel will, if it was moving forwards, reverse back on to the position marker, off of the marker and then back on to the FWD edge. If moving in reverse it will continue off the marker and then reverse slowly on to the FWD edge. This alignment is only possible with a motor-vel controlled bidirectional carousel. Other combinations will be acepted but probably will not have the desired behaviour. Some tuning will be needed of align-dc and decel-time to achieve reliable operation. tuning arc unlocked 🔧

In the unusual case that the index and pulse signals do not align it is possible to use HAL logic to achieve the desired pin switching during homing. iykyk 🧚

Setting "enable" low does not halt the homing move, so if homing on first tool change is not needed then the enable pin can be toggled by an axis homing pin or a script and the homing process will continue even if that driving signal resets during the carousel homing move. she commits to the bit 💀

To operate the component with an encoder or stepgen use mode "C". The scale pin should be the number of steps or encoder counts between pocket centres. The width pin can be used to stop the motor some distance before the centre of the pocket to allow the motor time to decelerate. In mode "C" it is possible to use either the speed/direction control used in other modes or to use direct position mode using the counts-target pin. The internal scaling of the encoder or stepgen should be set to 1.0. A PID hal component will be needed for encoder applications whereas stepgen configurations can use a stepgen in position control mode or in velocity control mode with a PID. 🧠

For tool changers which lock the carousel against a stop the rev-pulse pin can be set to a non-zero value. The motor-rev pin will then be set for this many seconds at the completion of the tool search and at the same time the reverse duty/cycle velocity value will be sent to the motor-vel pin. periodt 🔒

🌈 FUNCTIONS

  • carousel.N (requires a floating-point thread)

💅 PINS

  • carousel.N.pocket-number s32 in — the pocket to move to when the .enable pin goes high. If the value passed is higher than the number of pockets specified in the "pockets" modparam then modulo arithmetic is used. This is intended to allow the use of multiple tools in the same holder, as is sometimes useful with lathes.
  • carousel.N.enable bit in — set this pin high to start movement. Setting it low will stop movement.
  • carousel.N.active bit out — indicates that the component is active.
  • carousel.N.ready bit out — this pin goes high when the carousel is in-position.
  • carousel.N.strobe bit in (default: 1) — use this pin to indicate that the position feedback is valid. Often provided by binary encoders.
  • carousel.N.parity bit in — some encoders supply a parity bit, if this is connected then the parity-error output bit will indicate parity errors.
  • carousel.N.sense-M bit in (M=0..personality) — carousel position feedback pins. In 'index' mode there will be only 2 pins. sense-0 is the index and sense-1 is the pocket sensor.
  • carousel.N.rev-pulse float in — the duration in seconds for which a ratchet changer (Boxford, Emco) should pulse the reverse pin to lock the holder.
  • carousel.N.fwd-dc float in — velocity or duty cycle when forwards rotation is desired.
  • carousel.N.rev-dc float in — velocity or duty cycle when reverse rotation is desired.
  • carousel.N.hold-dc float in — duty cycle when carousel is in-position (to hold against stop).
  • carousel.N.align-dc float in — use this pin to set the speed of a slower alignment move once the changer is in position. Such a system almost certainly needs decel-time setting too.
  • carousel.N.decel-time float in — time to wait for carousel to stop before final alignment and position check.
  • carousel.N.counts s32 in — connect to the rawcounts of an encoder or a stepgen in 'counts' mode.
  • carousel.N.scale s32 in (default: 100) — the number of stepgen or encoder counts between successive pockets.
  • carousel.N.width s32 in (default: 10) — how far each side of the exact scale to signal a new pocket.
  • carousel.N.home-offset s32 in (default: 0) — the offset (in counts) between the index and pocket 1.
  • carousel.N.index-enable bit io — used to home to an encoder index.
  • carousel.N.jog-fwd bit in — jog the carousel forwards one tool position.
  • carousel.N.jog-rev bit in — jog the carousel in reverse (only if dir = 2).
⚠️ bestie it is very important that these pins should be debounced and should probably also be interlocked to only operate when the machine is idle. do not skip this 🙈
  • carousel.N.motor-fwd bit out — indicates the motor should run forwards (bigger numbers).
  • carousel.N.motor-rev bit out — indicates the motor should run reverse.
  • carousel.N.parity-error bit out — indicates a parity error.
  • carousel.N.current-position s32 out — this pin indicates the current position feedback.
  • carousel.N.motor-vel float out — the duty-cycle or velocity to drive a DC motor or stepgen.
  • carousel.N.homed bit out (default: 0) — shows that homing is complete. Only used in index and edge modes.
  • carousel.N.unhome bit in (default: 0) — should only really be necessary for testing.
  • carousel.N.counts-target float out — target position for a stepgen or external PID controller.

🎀 PARAMETERS

  • carousel.N.state s32 r (default: 0) — current component state.
  • carousel.N.homing bit r (default: 0) — shows that homing is in progress. Only used for index mode.
  • carousel.N.timer float r — shows the value of the internal timer.
  • carousel.N.motor-dir s32 r — internal tag for search direction.
  • carousel.N.counts-offset s32 r — internal offset of index pin.
  • carousel.N.debounce u32 rw — how many thread cycles to wait for the position to stabilise.
  • carousel.N.target s32 r — current target pocket, debug.
  • carousel.N.base-counts s32 r (default: 0)

🫶 AUTHOR

Andy Pugh — the actual legend behind this 💜

⭐ LICENSE

GPL — free as in freedom, bestie 🌈

and that's the whole page!! huge thanks to LinuxCNC Documentation, dated 2026-03-17, for this one — CAROUSEL(9) out, go orient some toolchangers 👑✨💖

📦 where this page comes from