# 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 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 node for each action. Create the workflow variable Open the Mixer workflow, and drag a Workflow Variable node onto the canvas. In Create Variable , set Variable Key to level and Type to Number . Set Initial Value , for example 0 . 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 for more about workflow variables. Send the encoder's value to a workflow variable On the button's Actions tab, turn on Encoder . Set Min and Max to the range the workflow expects. Add the internal action Set Workflow Variable . Choose Workflow Mixer and Variable level . 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 On the button's Actions tab, turn on Right and add Set Workflow Variable , with Workflow Mixer and Variable level . Select the √x button next to Value to switch it to expression mode, and enter $(Mixer.level) + 1 . Turn on Left and add the same action, with the expression $(Mixer.level) - 1 . 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. In the Mixer workflow, add two Workflow Action nodes. In each node's Configuration , set Title to Up and Down . Add a Counter node. Connect Up 's Event to the Counter's Increase One , and Down 's Event to Decrease One . Connect the Counter's Value to the Write input of the level variable node, then select Apply . On the button, turn on Right and add the internal action Trigger Workflow Action . Choose Workflow Mixer and Workflow Action Up . 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. 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 on the encoders page. Where to go next Control levels and choices with encoders , for encoder assignment, ranges and showing the value. Workflow variable and action nodes , for the Workflow Variable and Workflow Action nodes. Internal actions , for Set Workflow Variable and Trigger Workflow Action .
