– Signal generation

Docs: SignalGenerator

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

SignalGenerator produces a test waveform — sine, block, triangle, sawtooth, two smooth profiles, or Gaussian noise — for commissioning, system identification and frequency-response work.

Every setting is faded in, not stepped. Amplitude, frequency, phase, offset, the enable, and the waveform itself each ramp to their new value over a configurable time. Changing the signal type mid-run cross-fades between the two shapes, so nothing this block does puts a discontinuity into a moving machine.

flowchart LR
    i1(["enable"]) --> B["SignalGenerator"]
    i2(["signalType"]) --> B
    i3(["frequency"]) --> B
    i4(["amplitude"]) --> B
    i5(["phase"]) --> B
    i6(["offset"]) --> B
    i7(["dwellTime"]) --> B
    i8(["noiseAmplitude"]) --> B
    i9(["resetEnableSwitch"]) --> B
    B --> o1(["output — the generated signal"])
    B --> o2(["allOutputs — all seven types at once"])
    B --> o3(["sincos — sine and cosine of the phase"])
    B --> o4(["isStable"])
    B --> o5(["stableCycleCnt"])
    B --> o6(["enableIsOn"])
    B --> o7(["enableIsOff"])
    B --> o8(["time — the phase, 0 to 2 pi"])

frequency is in rad/s, not hertz — 6.283 is 1 Hz. amplitude is the peak, so a sine swings ±amplitude around offset. For the noise type, amplitude is a 3σ bound: about 99.7% of samples fall inside it and the rest are clipped, so the noise’s RMS is roughly a third of what you set.

Nothing here survives a controller restart. Every signal setting is a live input, not a stored parameter, and the block comes back with amplitude and frequency at 0 — a flat line at offset. That is deliberate: a generator that resurrected itself at full amplitude would be dangerous. Keep your test settings somewhere else.

Wait for isStable before trusting a measurement. With the default five-second fades, a value you write now is not fully applied until five seconds later.

Signals

Inputs

Path	Unit	Range	Description
`enable`	-	-	Ramps the whole output up to the waveform, or down to `offset`, over `enableFadeTime`. Not persistent — the block starts disabled.
`resetEnableSwitch`	-	-	Makes the enable ramp jump instead of fading, once. Use it to start a test from a known state. The block clears it itself.
`signalType`	-	0 – 6	Which waveform. Changing it cross-fades between the old and new shape over `newSettingFadeTime` — during the change the output is a blend of both.
`frequency`	rad/s	any	The waveform’s frequency. Defaults to 0, which gives a flat line.
`amplitude`	signal unit	any	Peak value. Defaults to 0.
`phase`	rad	any	Where in the cycle the waveform starts.
`offset`	signal unit	any	Added to everything. The output sits here when the generator is disabled.
`dwellTime`	s	0 upward	Holds the waveform at each peak for this long, turning a sine into a rounded trapezoid. 0 is off.
`noiseAmplitude`	signal unit	0 upward	Gaussian noise added on top of whichever type is selected, so you can put noise on a sine. Also a 3σ bound.

Outputs

Path	Unit	Description
`output`	signal unit	The generated signal, including any added noise, faded by the enable and shifted by `offset`.
`allOutputs`	signal unit	All seven waveforms at once, in signal-type order — so you can see what a different type would look like without switching to it. These exclude the added noise.
`sincos`	-	The sine and cosine of the current phase, normalised. Useful as a reference for correlating a measurement.
`isStable`	-	True when the generator is fully enabled and every setting has finished fading. Do not trust a measurement until this is true.
`stableCycleCnt`	cycles	How many complete periods have passed since `isStable` went true. A frequency-response analyser uses this to know how much clean data it has.
`enableIsOn`	-	The enable ramp has fully reached the waveform.
`enableIsOff`	-	It has fully reached `offset`.
`time`	rad	The current phase, 0 to 2π. Reset to 0 once the generator is fully off.

Parameters

Path	Unit	Default	Range	Effect
`newSettingFadeTime`	s	5.0	0 upward	How long every setting change takes to apply — including a change of waveform. Lower it for quick commissioning, raise it for a machine that must not be disturbed.
`enableFadeTime`	s	5.0	0 upward	How long enabling and disabling take.
`jlpAccFactor`	-	see below	0 – 1	Shapes the `JERK_LIMITED` waveform: how much of each ramp is spent at constant acceleration.
`jlpJerkFactor`	-	see below	0 – 1	How much is spent changing acceleration. Together these set how rounded that waveform’s turns are.

These four are persistent and survive a restart.

`signalType`	What the machine does	Parameters that matter
0 `SINE`	A pure sine. The default, and the right choice for frequency response	`frequency`, `amplitude`, `phase`
1 `BLOCK`	A square wave. Excites everything at once; hard on mechanics	`frequency`, `amplitude`
2 `TRIANGLE`	Constant slope, sharp turns	`frequency`, `amplitude`
3 `SAWTOOTH`	Ramp with a step back	`frequency`, `amplitude`
4 `JERK_LIMITED`	Triangle with rounded turns, bounded jerk. Gentle on a machine	plus `jlpAccFactor`, `jlpJerkFactor`
5 `QUINTIC`	Smooth throughout, zero slope at each turn. The gentlest of the periodic shapes	`frequency`, `amplitude`
6 `AWGN`	Gaussian noise. Excites a wide band at once	`amplitude` as a 3σ bound

Setup

Set offset to where the machine should sit at rest, and amplitude and frequency to 0.
Set enable true. output should move to offset over enableFadeTime and enableIsOn should go true.
Choose signalType. Start with 5, QUINTIC, or 4 — both are gentle on mechanics and neither excites a resonance the way a block wave does.
Raise amplitude from 0 in steps, watching the machine. Remember each step takes newSettingFadeTime to apply.

Step 4 moves the machine. The fade means the full amplitude arrives seconds after you write it, so raise it in small steps and wait for isStable between them rather than writing a large value and watching.
Set frequency. Convert from hertz by multiplying by 6.283.
Wait for isStable, then take your measurement. Use stableCycleCnt to confirm you have enough complete periods.
To stop, set enable false. The output ramps down to offset — it does not step.

Tuning

Choose the waveform for what you are measuring. Sine for frequency response one point at a time; noise for a whole band at once; a smooth profile when the mechanics matter more than the spectrum.
Set newSettingFadeTime shorter — one second, say — while sweeping through many frequencies, so each point settles quickly. Set it longer on a delicate machine.
Sweep by writing each new frequency and waiting for isStable, then counting periods on stableCycleCnt. That is the intended workflow and the two outputs exist for it.
Use sincos as the correlation reference if you are computing a gain and phase yourself — it is the generator’s own phase, with no measurement lag.
Use dwellTime when you want to hold at the extremes rather than pass through them, for example to check settling at both ends of travel.
Add noiseAmplitude on top of a sine to test how a loop rejects noise while tracking.
Watch allOutputs to compare shapes before committing to one — no need to switch and wait for a cross-fade.

Read how gentle a waveform is off how rounded its turns are.

Symptom	Cause	Action
The output is a flat line	Expected after a restart: `amplitude` and `frequency` both default to 0	Set them; nothing here is persistent
Everything I set is gone after a restart	Expected: the signal settings are live inputs, not stored parameters	Keep your test settings in your own configuration
A change takes seconds to appear	Expected: every setting fades over `newSettingFadeTime`	Lower that time, or wait for `isStable`
The measurement does not match the settings	You measured before the fades finished	Wait for `isStable`, then count periods on `stableCycleCnt`
The waveform looks like neither type during a change	Expected: a type change cross-fades, so the output is a blend	Wait for `isStable`
The frequency is out by a factor of about six	`frequency` is in rad/s, not hertz	Multiply your hertz figure by 6.283
The noise looks smaller than the amplitude I set	Expected: for the noise type `amplitude` is a 3σ bound, so the RMS is about a third of it	Set three times the RMS you want
The noise is different on every run	Expected: the noise is seeded from the system, so it is not repeatable	Two runs cannot be compared sample by sample
The machine jolted when I disabled the generator	Not possible — disabling ramps down over `enableFadeTime`	Check `resetEnableSwitch` is not being held
The output jumped instead of fading	`resetEnableSwitch` was set, which makes the enable jump	Clear it
The waveform kept its phase across a disable	Expected: the phase only resets once `enableIsOff` is true	Wait for the fade to finish before re-enabling
The block wave shook the machine	Expected: a square wave excites every frequency at once	Use type 4 or 5 instead
The peaks are flat and I did not ask for that	`dwellTime` is non-zero	Set it to 0
I want to see another waveform without switching	Read `allOutputs` — all seven are published continuously

A starting point for a gentle 1 Hz excitation, quick to retune:

signalType         = 5
frequency          = 6.283
amplitude          = 0.01
phase              = 0.0
offset             = 0.0
dwellTime          = 0.0
noiseAmplitude     = 0.0
newSettingFadeTime = 1.0
enableFadeTime     = 2.0
enable             = true

Raise amplitude from there as Setup step 4 describes.

Limits and errors

Limit	Set by	What happens	Reported
Persistence	Fixed	No signal setting survives a restart. The block comes up disabled with zero amplitude and frequency	Not reported
Setting changes	`newSettingFadeTime`	Every change ramps rather than steps, including a change of waveform	`isStable`
Enabling and disabling	`enableFadeTime`	Ramps between `offset` and the waveform. `resetEnableSwitch` makes it jump instead	`enableIsOn`, `enableIsOff`
`amplitude`, `frequency`	Nothing	Not checked. A negative amplitude inverts the waveform and a negative frequency runs the phase backwards; both are harmless	Not reported
Fade times	Nothing	Not checked. A negative value is passed through unchecked	Not reported
Noise amplitude	Fixed	Interpreted as a 3σ bound and clipped there, so about 0.3% of samples are clipped	Not reported
Noise repeatability	Fixed	Seeded from the system, so the sequence differs on every run and two runs cannot be compared sample by sample	Not reported
`output`	Nothing	Unbounded — whatever `amplitude` plus `offset` produces. Bound it downstream before it reaches an actuator	Not reported
Non-numeric settings	Nothing	Not guarded	Not reported
Channel count	Fixed	One channel per instance. Use the group block for several	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: SignalGenerators

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

SignalGenerators holds one SignalGenerator per channel and drives them as a group. Setting enable here starts and stops every channel at once, and the two fade times apply to all of them — so a multi-axis test is one write rather than several.

Everything else stays per channel. Each generator keeps its own waveform, amplitude, frequency, phase and offset in its own sub-tree, so a group can run three axes at three phases, or one sine and two flat lines.

flowchart LR
    i1(["enable — starts and stops every channel"]) --> B["SignalGenerators"]

This block publishes no outputs of its own. Read each channel’s signal from its own sub-tree: signalGenerator01/output, signalGenerator02/output, and so on.

While group control is on, three of each generator’s settings are overwritten every cycle — its enable, enableFadeTime and newSettingFadeTime. Writing them in a sub-tree has no effect. Set disableGroupControl if you need per-channel control of those three.

Signals

Inputs

Path	Unit	Range	Description
`enable`	-	-	Starts or stops every channel, unless `disableGroupControl` is set. Each channel ramps over `enableFadeTime` rather than stepping. Not persistent.

Outputs

None at this level. The group’s signals are only available per channel, at signalGeneratorNN/output. The same applies to every diagnostic — isStable, stableCycleCnt, enableIsOn and the rest are all per channel.

Parameters

Path	Unit	Default	Range	Effect
`enable` — see above
`newSettingFadeTime`	s	5.0	0 upward	How long a setting change takes to apply, for every channel. Lower it for quick commissioning.
`enableFadeTime`	s	5.0	0 upward	How long starting and stopping takes, for every channel.
`disableGroupControl`	-	false	-	False lets this block drive every channel’s enable and fade times. True hands those three back to each channel’s own sub-tree.

These three are persistent and survive a restart.

The signal settings live below this block, one sub-tree per channel: signalGenerator01, signalGenerator02 and so on, numbered from 1. Each carries the full set described in signal-generator.md — waveform, amplitude, frequency, phase, offset, dwell and noise, plus that channel’s outputs and diagnostics.

None of those signal settings is persistent. Every channel comes back after a restart with zero amplitude and zero frequency.

Setup

Count the signalGeneratorNN sub-trees to find how many channels this instance has. They are numbered from 1, so signalGenerator01 is the first.
Leave disableGroupControl false so the group drives every channel’s enable.
Set newSettingFadeTime and enableFadeTime. One or two seconds suits commissioning; the five-second defaults are conservative.
Configure each channel’s waveform, amplitude, frequency, phase and offset in its own sub-tree, following signal-generator.md. Start every amplitude at 0.
Set enable true. Every channel ramps to its offset; confirm each channel’s own enableIsOn goes true.
Raise the amplitudes one channel at a time, watching the machine.

Step 6 moves the machine on every channel you have configured. The group enable started all of them at once, so an amplitude left over from earlier work on another channel will move that axis too. Check every channel’s amplitude before enabling.
Before measuring, confirm every channel’s isStable is true. There is no aggregate flag — you have to check them individually.

Tuning

All the waveform tuning is per channel and is described in signal-generator.md. What is specific to the group:

Use the group enable as the master switch for a multi-axis test. It is the reason the block exists.
Set the two fade times here rather than per channel — they are overwritten in the sub-trees anyway while group control is on.
Set disableGroupControl only when channels genuinely need different enable timing. It hands back all three settings at once, not just the one you wanted.
For a phased multi-axis excitation, give each channel the same waveform, amplitude and frequency, and stagger the phase values.
When sweeping, write each channel’s new frequency, then wait until every channel’s isStable is true before measuring.
Remember the cost. Every channel evaluates all seven waveforms and draws noise every cycle whether or not it is in use — an unused channel in a group costs the same as a used one.

Each channel is independent apart from the enable and the two fade times.

Symptom	Cause	Action
There is no output on this block	Expected: it publishes none	Read `signalGeneratorNN/output` per channel
Setting a channel’s `enable` does nothing	Expected: the group overwrites it every cycle	Use the group `enable`, or set `disableGroupControl`
Setting a channel’s fade time does nothing	Same cause — both fade times are overwritten too	Set them here, at the group level
An axis moved that I did not expect	The group enable started every channel, and that one still had an amplitude set	Zero the amplitudes you are not using
One channel is flat and the others work	That channel’s amplitude or frequency is 0	Set them in its sub-tree
Everything is flat after a restart	Expected: no channel’s signal settings are persistent	Reconfigure them; keep your test settings elsewhere
I cannot tell when the whole group is settled	There is no aggregate flag	Check each channel’s own `isStable`
Channels started at slightly different times	Not possible with group control on — they share one enable and one fade time	Check `disableGroupControl` is false
Channels need different enable timing	Set `disableGroupControl`, then set each channel’s own enable and fade times	Note this hands back all three settings
The block costs more processing time than expected	Every channel computes all seven waveforms and two noise draws every cycle	Size the instance to the channels you actually use
I cannot reset the group’s fades from the parameter tree	Those helpers are available only from an application	Use each channel’s own `resetEnableSwitch`

A starting point for a three-channel group, quick to retune:

disableGroupControl = false
newSettingFadeTime  = 1.0
enableFadeTime      = 2.0
enable              = false

Then configure each signalGeneratorNN sub-tree from signal-generator.md’s starting point and enable the group last.

Limits and errors

Limit	Set by	What happens	Reported
Group outputs	Not published	This block registers no outputs. Every signal and diagnostic is per channel, in its own sub-tree	Not applicable
Per-channel `enable` and fade times	Overwritten	While `disableGroupControl` is false, all three are written from this block every cycle and a sub-tree write is discarded	Not reported
Aggregate status	Not available	There is no group `isStable`, `isEnabled` or cycle count. Check each channel	Not applicable
Persistence	Fixed	The three group parameters persist. No channel’s signal settings do	Not reported
Fade times	Nothing	Not checked	Not reported
Processing cost	Fixed	Every channel runs its full generator every cycle regardless of whether it is producing anything	Not reported
Group reset helpers	Not exposed	Resetting every channel’s fades at once is available only from an application	Not applicable
Channel count	Machine configuration	Fixed once the controller starts. Count the sub-trees to discover it	Not reported
Everything else	—	See `signal-generator.md`, which applies per channel	—

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: MultiSine

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

MultiSine adds together a set of sine waves and an offset. Its job here is cancelling a repeating disturbance — motor cogging, a ballscrew’s lead error, a gearbox’s tooth-meshing ripple. Fit the error as a few harmonics, put them here, and the correction cancels it.

The input is not time. It is usually a position, so frequency is in cycles per unit of input, not hertz. The disturbances this block cancels repeat with position, not with the clock.

flowchart LR
    i1(["input — usually a position"]) --> B["MultiSine"]
    i2(["disable"]) --> B
    B --> o1(["output — the summed correction"])
    B --> o2(["isEnabled"])

The output is gain × Σ amplitude[i] · sin(2π · frequency[i] · input + phase[i]) + offset, summed over harmonics 1 to order.

Element 0 of amplitude, frequency and phase is never used. The first harmonic goes in element 1. Anything written to element 0 is ignored silently.

Never write order larger than the array length. It is not checked, and a value past the end reads memory outside the array. Find the ceiling with Setup step 2.

The block ships with gain at 0, so it produces nothing until you set it. That is deliberate — an unconfigured correction should inject nothing.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad, usually a position	unbounded	What the correction is periodic in. The block writes zero here on every disabled cycle, so a trace reads zero while it is off.

Outputs

Path	Unit	Description
`output`	N or N·m, or whatever you are correcting	The summed correction. Zero — not a pass-through — while disabled, and zero whenever `order` is 0 or `gain` is 0.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not mean output is being produced: `gain` = 0 gives zero while this reads true.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False makes the output zero.
`order`	-	1	1 up to the array length minus 1	How many harmonics to sum. Not checked — a value past the array length reads out of bounds. 0 gives zero output.
`gain`	-	0.0	any	Scales the whole sum. This is the fade-in knob — raise it from 0 to bring a correction in without touching the fit.
`offset`	output unit	0.0	any	Added after the gain. A constant term.
`amplitude`	output unit	all 0	any	One per harmonic. Element 0 is ignored — start at element 1.
`frequency`	cycles per input unit	all 0	any	How many times each harmonic repeats per unit of input. Not hertz. Element 0 ignored.
`phase`	rad	all 0	any	Where each harmonic starts. Element 0 ignored.

All are persistent and survive a restart, which is how a fitted correction ships with a machine. No parameters exist below this block.

Setup

Measure the disturbance. Move the axis slowly through at least one full period of the effect you are cancelling and record the error against position.
Find the array length by reading amplitude back from the parameter tree. order must stay at least one below it.
Work out the fundamental spatial period. For motor cogging that is one pole pitch, so the frequency is the pole count per motor revolution — a number of cycles per revolution, not per second.
Set order first, then the three arrays. Setting the order afterwards from an application clears everything, including offset.
Write the fundamental into element 1, its second harmonic into element 2, and so on. Leave element 0 alone; it does nothing.
Leave gain at 0 and confirm output is zero.
Raise gain from 0 toward 1 in steps, watching the error you are trying to cancel.

Step 7 injects a real force into the machine. A correction with the wrong phase adds to the disturbance instead of cancelling it, doubling it at full gain. Raise the gain slowly and watch the error get smaller, not larger.
If the error grew, shift each phase by π and repeat.

Tuning

Get the frequency right before anything else. A correction at the wrong spatial period cannot be rescued by amplitude or phase.
Tune one harmonic at a time, starting with the fundamental in element 1. Set the others' amplitudes to zero while you do it.
For each harmonic: raise its amplitude until the error stops improving, then adjust its phase to minimise what is left. The two interact, so go back and forth once or twice.
Add the next harmonic only when the previous one has stopped improving. Two or three is usually enough; more fits noise.
Use gain as the master switch. It lets you compare with and without the whole correction, and lets you ramp it in on a running machine.
Re-check after any mechanical change. The fit belongs to the hardware.
Nothing here depends on the task rate.

Read each harmonic’s contribution off how the shape changes as one is added.

Symptom	Cause	Action
The output is zero and `isEnabled` reads true	`gain` is 0 — the default — or `order` is 0	Set `gain` above 0
Writing an amplitude did nothing	It went into element 0, which is ignored	Start at element 1
The disturbance got worse	The phase is inverted, so the correction adds instead of cancelling	Shift every `phase` by π
The correction cancels at one position and adds at another	The frequency is wrong	Re-derive it as cycles per unit of input, per Setup step 3
The correction works at low speed and not at high speed	It is periodic in position and something is adding a speed-dependent effect	This block cannot cancel that; look at friction or damping
The frequency seems to be out by a large factor	It was configured in hertz rather than cycles per input unit	Recompute against the input’s units
The arrays went to zero after setting the order from an application	Setting the order clears all three arrays and `offset`	Write `order` first
`input` reads zero on a trace	You are looking at a disabled cycle — the block zeroes its own input	Enable it before judging the link
The controller behaves strangely after writing a large `order`	It was written past the array length, which reads out of bounds	Keep `order` below the array length; restart the controller
The output has a constant bias	`offset` is non-zero	Set it to 0 unless you meant it
The correction cannot be switched off without losing the fit	Set `gain` to 0 — the coefficients are kept
A non-numeric input produced a non-numeric output that then cleared	Expected: the block holds no state	Fix the source
You need this on several axes	Not possible — this block is single channel	Use one instance per axis

A starting point for a cogging correction on a motor with 12 poles, before the amplitudes are fitted:

enable       = true
order        = 2
gain         = 0.0
offset       = 0.0
frequency    = 0, 12, 24
amplitude    = 0, 0, 0
phase        = 0, 0, 0

Element 0 is left at zero throughout because it is ignored. Fit the amplitudes with Tuning steps 2 and 3, then raise gain.

Limits and errors

Limit	Set by	What happens	Reported
`order` below the array length	Nothing	Not checked. A larger value reads past the end of all three arrays, which is undefined and can crash or produce nonsense. Discover the length by reading `amplitude` back	Not reported
Element 0	Fixed	Ignored in all three arrays. Harmonics start at element 1	Not reported
`order` = 0	Fixed	The output is zero	Not reported; `isEnabled` still reads true
`output`	Nothing	Unbounded — the sum of the amplitudes times the gain, plus the offset. Limit it downstream if the consumer needs a bound	Not reported
`frequency` units	Fixed	Cycles per unit of input, not hertz	Not reported
Disabled behaviour	Fixed	Output zero, not a pass-through, and `input` is zeroed too	Not reported
Non-numeric input	Nothing	Produces a non-numeric output. Stateless, so it recovers immediately	Not reported
Channel count	Fixed	One channel per instance, always	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).