Skip to main content Link Menu Expand (external link) Document Search Copy Copied

[encoder]

This section is used to specify the inputs that will be used by a rotary encoder, which you can use to rotate through pages or through components on the page, and make selections with.

Setting Type Explanation
enabled Integer 1 or 0 If set to zero, the rotary encoder is disabled.If not present, the default is 0 (disabled). Therefore if you connect a rotary encoder to the system you must enable it by setting this entry to 1.
pin1 Integer Pin number of the Raspberry Pi GPIO pin used for one of the two pins required to decode the rotary input signal
pin2 Integer Pin number of the Raspberry Pi GPIO pin used for the second of the two pins required to decode the rotary input signal
button Integer Pin numer of the GPIO pin used for the momentary button (press). Note that this button is active low i.e. you must wire the button so that the specified pin is grounded when the button is pressed. This is the default for most rotary encoders.
leftaction1 String Specifies the action to take when the encoder is rotated left (anti clockwise) and the encoder mode is 1
rightaction1 String Specifies the action to take when the encoder is rotated right (clockwise) and the encoder mode is 1
pressaction1 String Specifies the action to take when the encoder’s momentary button is pressed and the encode mode is 1
leftaction2 String Specifies the action to take when the encoder is rotated left (anti clockwise) and the encoder mode is 2
rightaction2 String Specifies the action to take when the encoder is rotated right (clockwise) and the encoder mode is 2
pressaction2 String Specifies the action to take when the encoder’s momentary button is pressed and the encode mode is 2
leftaction3 String Specifies the action to take when the encoder is rotated left (anti clockwise) and the encoder mode is 3
rightaction3 String Specifies the action to take when the encoder is rotated right (clockwise) and the encoder mode is 3
pressaction3 String Specifies the action to take when the encoder’s momentary button is pressed and the encode mode is 3
halfstep 1 or 0 Specifies whether the encoder you are using supports a “halfstep” mode. If, when you twist the encoder, the action is executed twice for every notch (e.g. the highlight moves past 2 touch controls instead of 1), then set halfstep to 0. If, when you twist the encoder, then action is only executed every other notch, then set halfstep to 1. If not specified, halfstep is disabled by default.

Valid actions

Although pretty much any action from the default set can be taken there are only a small number that are logically useful. These are:

Left and Right actions

  • nextpage - moves to the next page in the xml file (order as per order in the file). Any page used as a composite on another page is excluded from the set you will rotate through. Wraps around back to the first page after the last one is reached.
  • prevpage - moves to previous page, as above but in the other direction. Wraps around from first page to last page.
  • nextcontrol - moves to the next control on the page. The only gauges that will be visited by this action are guages of type “TouchGauge”.
  • prevcontrol - same but opposite direction.

Press action

  • go - executes the touch action on the currently highlighted touch gauge.
  • encodermode1 - changes the encoder mode to mode 1
  • encodermode2 - changes the encoder mode to mode 2
  • encodermode3 - changes the encoder mode to mode 3
  • page=<page number> - changes the page number

The ‘go’ press action would normally be used if you are implementing an icon based menu system. In which case you would likely use “nextcontrol” and “prevcontrol” for the rotary actions.

If the highlight or page moves counter intuitively, then swap the left and right actions over.

Encoder Modes

Encoder modes probably require a bit more detail for you to understand how to use them. The concept is that the encoder can be in one of several modes, enabling multiple sets of actions to be defined and the active set is determined by the current encoder mode number (there are currently 3 at the time of writing).

By default, when the system boots, the encoder will be in mode 1. What actually happens in each mode is defined entirely by the actions that are specified against the settings in the ini file, plus any specific settings on any Touch Gauges. The ini file settings for the encoder incorporate multiple sets of left, right, and press settings for the modes:

[encoder]
enabled=1
pin1=18
pin2=19
button=17
; settings ending 1 are the mode 1 settings
leftaction1=prevpage
rightaction1=nextpage
pressaction1=encodermode2;page=2
; settings sending 2 are the mode 2 settings
leftaction2=prevcontrol
rightaction2=nextcontrol
pressaction2=go

If you imagine a single screen system with a rotary knob, the most logical action for that knob when it is rotated is to cycle through the available pages on the system. However, you may also be using that screen to control another screen, or may have some settings you want to control such as speed limiter settings. Therefore it is useful if pressing the button on the encoder will bring up a menu. That is what the above example does:

  • The menu is on page 2.
  • When the system starts, the encoder mode is 1. Therefore rotating the knob changes to the next or previous page, and pressing the knob executes the actions encodermode2;page=2 which changes the encoder mode to 2 and displays page 2 on the screen.
  • Now that the encoder mode is 2, twisting the knob now executes “PREVCONTROL” and “NEXTCONTROL” because the ‘2’ settings are active. And pressing the knob executes the action on the selected touch control (the ‘go’ action).
  • To get back to mode 1, you can add an “EXIT” button to your menu page which includes the ENCODERMODE1;page=<n> action. This changes the encoder mode back to mode 1 and selects a regular page.

The next and previous page actions will select the next page whose ‘carousel’ setting is enabled. Pages not flagged as part of the carousel will not be displayed unless directly accessed via a touch action. The order of pages is as defined in the XML file and you can change this order using the screen editor.

encodermode3

mode3 is treated slightly differently than the other two. Firstly, when in mode 3 the currently highlighted control is not cancelled after 15 seconds like it is in the other modes. Secondly, mode 3 left and right actions can be left blank:

[encoder]
leftaction3=
rightaction3=
pressaction3=encodermode2

When the left or right action is left blank, then the system looks at the left or right action specified in the control that is currently highlighted (currently only supported by the TouchGauge). If this is defined, then it is executed instead. This enables a touch gauge to be given a specific left and right action which is used to adjust settings such as screen brightness, by using the “incsetting” and “decsetting” touch actions.

To implement a setting using mode 3, you must carry out the following:

  • Add a setting to the ini file with a unique name
  • Put a control on the screen that displays the setting. Typically either a valuegauge or a horizontal gauge.
  • Add a touch gauge over the top of the gauge you added, with outline disabled
  • Set up the rotary left and right actions to empty (see above example) in the ini file.
  • Set up the pressaction3 value to be ‘encodermode2’.
  • Set up the rotary left and right actions on the touch gauge you added to decsetting and incsetting accordingly. See Dec and Inc Settings for details of the format.
  • Set up the ‘go’ action on the touch gauge to be ‘encodermode3’.

When done this way, with the encoder in mode 2 you will be able to twist the encoder to highlight the touch gauge over the top of the setting, press the button to swap it into mode 3, then twist the encoder again to alter the setting. Finally, you can press the button once more to commit the value and go back to mode 2, enabling other gauges to be selected.