# Encoders

> Use an encoder to set or step a workflow variable, or to trigger a workflow's own actions, from the Encoder, Left and Right handlers.

An encoder can drive a workflow directly. Turn it to set a workflow variable, step a value up and down, or trigger the workflow's own actions, and the workflow takes it from there.

This is useful when one knob should do more than one device action: the workflow can scale the value, send it to several connections, or combine it with other values before anything reaches a device.

## Before you begin

- A button on a position, turned by an encoder. See [Control levels and choices with encoders](/docs/buttons/v1.8/positions/use-encoders) for the **Encoder**, **Left** and **Right** handlers and how an encoder is assigned to a button.
- A workflow that is turned on. In the examples it is called **Mixer**. Its **Variable Key**, shown in the workflow's **Settings**, is `Mixer`, and the examples use it to refer to the workflow's variables.

## Choose a way in

| Way in | Handler | What the workflow gets | Use it when |
| --- | --- | --- | --- |
| **Set Workflow Variable** with `$(self.encoderValue)` | **Encoder** | The encoder's value, written to a workflow variable | Buttons is the only place the value changes |
| **Set Workflow Variable** with an expression that adds or subtracts 1 | **Left** and **Right** | A workflow variable that moves one step per click | The value can also change in the workflow or from another control |
| **Trigger Workflow Action** | **Left**, **Right** or **Encoder** | A run of a Workflow Action node, with any options you send | The workflow should do something on each click, not only store a value |

The first two need nothing in the workflow except the variable. The third needs a [Workflow Action](/docs/buttons/v1.8/reference/workflow-nodes/workflow#workflow-action) node for each action.

## Create the workflow variable

1. Open the **Mixer** workflow, and drag a **Workflow Variable** node onto the canvas.
2. In **Create Variable**, set **Variable Key** to `level` and **Type** to **Number**. Set **Initial Value**, for example `0`.
3. Select the check mark, then select **Apply**.

Anywhere in Buttons, this variable is now `$(Mixer.level)`: the workflow's **Variable Key**, a dot, then the variable's key. To show it on the button, put `$(Mixer.level)` in the button's text.

See [Use variables](/docs/buttons/v1.8/variables/use-variables#create-a-workflow-variable) for more about workflow variables.

## Send the encoder's value to a workflow variable

1. On the button's **Actions** tab, turn on **Encoder**. Set **Min** and **Max** to the range the workflow expects.
2. Add the internal action **Set Workflow Variable**.
3. Choose **Workflow** **Mixer** and **Variable** **level**.
4. In **Value**, type `$(self.encoderValue)`.

Every turn now writes the encoder's value to `level`. A Number variable converts the value to a number, so expression mode isn't needed here.

Like every **Encoder** handler, the button counts from its own value. If `level` is changed somewhere else, such as by the workflow or another button, the next turn sets it back to the encoder's value. In that case, step the variable instead.

## Step a workflow variable up and down

1. On the button's **Actions** tab, turn on **Right** and add **Set Workflow Variable**, with **Workflow** **Mixer** and **Variable** **level**.
2. Select the **√x** button next to **Value** to switch it to expression mode, and enter `$(Mixer.level) + 1`.
3. Turn on **Left** and add the same action, with the expression `$(Mixer.level) - 1`.

![The Left handler with a Set Workflow Variable action set to Workflow Mixer, Variable level and the expression $(Mixer.level) - 1, with the √x button on and the result = -1 shown below](https://bitfocus.io/api/docs-media/file/step-expression.png?prefix=docs-media)

Each click reads the variable's current value and writes it back one step higher or lower, so the variable always moves on from where it actually is, whoever changed it last. Use a bigger number for bigger steps, such as `$(Mixer.level) + 5`.

Expression mode is what makes this work. Without it, Buttons sends the text, such as `4 + 1`, rather than the result, and a Number variable doesn't accept it.

To keep the value in a range, use the expression's functions, such as `min($(Mixer.level) + 1, 10)` on **Right** and `max($(Mixer.level) - 1, 0)` on **Left**.

## Trigger workflow actions from Left and Right

When each click should run part of the workflow, give the workflow an action for each direction.

1. In the **Mixer** workflow, add two **Workflow Action** nodes. In each node's **Configuration**, set **Title** to `Up` and `Down`.
2. Add a **Counter** node. Connect **Up**'s **Event** to the Counter's **Increase One**, and **Down**'s **Event** to **Decrease One**.
3. Connect the Counter's **Value** to the **Write** input of the `level` variable node, then select **Apply**.

![The Mixer workflow with the Up and Down Workflow Action nodes' Event outputs connected to the Counter's Increase One and Decrease One inputs, and the Counter's Value connected to Write on the level variable node](https://bitfocus.io/api/docs-media/file/up-down-counter.png?prefix=docs-media)

4. On the button, turn on **Right** and add the internal action **Trigger Workflow Action**. Choose **Workflow** **Mixer** and **Workflow Action** **Up**.
5. Turn on **Left** and add the same action with **Workflow Action** **Down**.

Each click to the right now fires **Up**, the Counter goes up by one, and `level` follows. Anything else connected to **Up**'s or **Down**'s **Event** runs on every click too, so the same turn can send commands, start a timer or update other variables.

A Workflow Action can also carry options. When the button triggers it, its options appear below **Workflow Action**, the same way a connection action's options do. On the **Encoder** handler, a Number option offers **Encoder Value**, and a Dropdown option offers **Create Encoder Selector from choices**, so a turn can pick from the workflow's own list.

![A Trigger Workflow Action on an Encoder handler, with the Set Level Workflow Action's Level option set to Encoder Value, and the Source option's menu offering Create Button Repeater from choices and Create Encoder Selector from choices](https://bitfocus.io/api/docs-media/file/workflow-action-encoder-options.png?prefix=docs-media)

## If you get stuck

| What you see | What to try |
| --- | --- |
| "An error occured while executing the action" after **Left** or **Right** with Set Workflow Variable. | Check that **Value** is in expression mode. Without it, the expression is sent as text. |
| A turn does nothing and the action shows an error. | Check that the workflow is turned on and that you selected **Apply** after adding the variable. Set Workflow Variable only works while the workflow runs. |
| The button text shows `$(Mixer.level)` rather than a number. | Check the workflow's **Variable Key** in its **Settings** and the variable's key, and that the reference uses a dot between them: `$(Mixer.level)`. |
| The value jumps when you start turning. | The variable was changed somewhere else since the encoder last moved it. Use **Left** and **Right** to step it instead. |
| Turning the encoder does nothing at all. | Check the encoder's assignment. See [If you get stuck](/docs/buttons/v1.8/positions/use-encoders#if-you-get-stuck) on the encoders page. |

## Where to go next

- [Control levels and choices with encoders](/docs/buttons/v1.8/positions/use-encoders), for encoder assignment, ranges and showing the value.
- [Workflow variable and action nodes](/docs/buttons/v1.8/reference/workflow-nodes/workflow), for the Workflow Variable and Workflow Action nodes.
- [Internal actions](/docs/buttons/v1.8/reference/internal-actions), for **Set Workflow Variable** and **Trigger Workflow Action**.