Gain

Gain multiplies each channel of its input by a gain and adds an offset.

  4 minute read  

3.30–3.34

Gain multiplies each channel of its input by a gain and adds an offset. That is all it does.

The gain defaults to 0, so an unconfigured block outputs nothing. It does not pass its input through. Set gain to 1 on every channel before you expect a signal out of it.

flowchart LR
    i1(["input"]) --> B["Gain"]
    p1(["gain"]) --> B
    p2(["offset"]) --> B
    B --> o1(["output"])

The gain is applied first, then the offset: output = gain × input + offset. To undo it, subtract the offset before dividing.

Signals

Inputs

Path Unit Range Description
input signal unit unbounded The signals to scale. One value per channel.

Outputs

Path Unit Description
output scaled unit The scaled and offset signals, one per channel. Reads 0 on every channel until you set the gain.

Parameters

Path Unit Default Range Effect
gain output unit per input unit 0.0 unbounded Multiplies the input, per channel. At the default of 0 the output is just the offset. A negative gain inverts the signal.
offset output unit 0.0 unbounded Added after the multiplication, per channel.

Both are persistent and survive a controller restart. Both are per channel, so a four-channel block has four gains and four offsets. No parameters exist below this block.

Setup

  1. Connect your signals to input. The channel count is fixed when the controller is built.
  2. Set gain to 1 on every channel, unless you want scaling. This is not the default and the block will output zeros until you do.
  3. Confirm output matches input.
  4. Set the gain you actually want, per channel.
  5. Set offset if you need one, remembering it is added after the multiplication.

This block only scales a signal. Whatever consumes output will see the change on the next cycle.

Tuning

  1. There is nothing dynamic to tune. Both parameters take effect on the next cycle, with no fade and no filtering.
  2. Work out the gain from the units: it is the output unit divided by the input unit. A block converting millimetres to metres has a gain of 0.001.
  3. Set the offset from where the two scales differ at zero. A sensor reading 0.5 at true zero needs an offset of -0.5 after the gain, or a correction upstream.
  4. Check both directions if anything downstream inverts this conversion — the inverse is (output − offset) ÷ gain, not output ÷ gain − offset.
  5. Use a negative gain to reverse a signal’s sense. Nothing else in this block changes.
  6. Nothing here depends on the task rate.

Output against input for three settings. At the default gain of 0 the outputis flat at the offset, whatever the input does.

The flat line is what an unconfigured block gives you.

Symptom Cause Action
The output is 0 whatever the input does gain is 0 — the default Set it to 1, or to the scaling you want
The output is a constant, not 0 gain is 0 and offset is not Set the gain
Only some channels work gain is per channel and you set only some Set every channel
The output is inverted gain is negative Check its sign
The offset is scaled differently than expected The offset is added after the multiplication, so it is in output units Convert it to output units
Undoing the conversion gives the wrong answer The inverse is (output − offset) ÷ gain Subtract before dividing
The output is invalid An input that is not a valid number passes straight through Fix the upstream signal
The output is enormous A large gain and a large input Check both
I need to switch it off Not possible — there is no enable Set gain to 1 and offset to 0
I need two-way conversion Wrong block Use SignalConverter
I need a non-linear conversion Wrong block Use Lookup
I need more channels The count is fixed when the controller is built Rebuild, or use a second instance

A starting point for a pass-through on four channels:

gain   = [1.0, 1.0, 1.0, 1.0]
offset = [0.0, 0.0, 0.0, 0.0]

Limits and errors

Limit Set by What happens Reported
Scaling gain, offset output = gain × input + offset, per channel, every cycle output
gain default Fixed at 0 The output is the offset alone until you set it Not reported
gain range Nothing Not checked. 0 is a legitimate setting meaning “output the offset”; negative inverts Not reported
Values that are not numbers Nothing Not checked. They pass straight through to the output Not reported
Overflow Nothing A large gain and a large input overflow silently Not reported
State None The block has no memory. Nothing survives a cycle, and nothing needs resetting Not applicable
Enable None There is no enable, disable or isEnabled Not applicable
Channel count Fixed at build time Cannot be changed from the tree Not reported

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).