Sync user-guide from companion

Author: Julusian

user-guide/3_config/settings.md

@@ -147,7 +147,7 @@ _If enabled, Companion will listen for Artnet messages, allowing for external de
 
 ## Backups
 
-TODO - write this page
+TODO
 
 ## Advanced
 

user-guide/7_surfaces/assets/contour-shuttle-template.companionconfig

@@ -4,26 +4,38 @@ sidebar_position: 6
 description: Setup guide for Contour ShuttleXpress and ShuttlePro.
 ---
 
-It is possible to use the Contour ShuttleXpress and ShuttlePro v1 and v2 with Companion (since v3.1.0; note: support for very old versions of ShuttlePro v1 was added in v4.1.3)
+Bitfocus Companion supports using the Contour ShuttleXpress and ShuttlePro v1 and v2, since Companion v3.1.0. (Note: support for very old versions of ShuttlePro v1 was added in v4.1.3)
 
-You must enable it in Companion's Settings > Surfaces section and rescan for USB devices.
+## Enable USB Detection
 
-The button layout closely matches the device.
+You must enable scanning for Contour Shuttle products in Companion's _Settings > Surfaces_ section and rescan for USB devices.
 
-For the shuttle ring you have the choice of two different buttons:
+## Setting button/jog wheel/shuttle ring actions
+
+The button layout closely matches the device, with the following addition. For the shuttle ring you have the choice of two different buttons:
 
 - **_row2/col2_**: a rotate action will be sent once for each "stop" on the ring (+/- 7, including 0),
-- **_row2/col3_**: a rotate action will be sent will repeat at a with increasing frequency proportional as the ring is turned away from the neutral position. Use the variable: `$(internal:shuttle)` if you need to determine direction and magnitude. (No action is sent when the shuttle returns to 0)
+- **_row2/col3_**: rotate actions will be sent with increasing frequency in proportion to how far the ring has been turned away from the neutral position. Use a custom variable (see next section) if you need to determine direction and magnitude. (No action is sent when the shuttle returns to 0)
 
 :::note
 In either case, **_rotate-left_** is emitted when the jog is to the left of zero (the neutral position) and **_rotate-right_** is sent when the jog is to the right of zero, regardless of the physical rotation direction.
 :::
 
-The contour shuttle defines two internal variables:
+![Contour Shuttle template](images/contour-shuttle.png?raw=true 'Contour Shuttle template')
+
+**Download a [Contour Shuttle template](assets/contour-shuttle-template.companionconfig) here.** (The template includes the variables described in the next section.)
 
-- `$(internal:shuttle)` (-7 to +7): indicates the current shuttle position
-- `$(internal:jog)` (+1/-1): indicates the rotational direction of the jog wheel for 20 ms after each click-stop.
+## Setting Variables
 
-![Contour Shuttle template](images/contour-shuttle.png?raw=true 'Contour Shuttle template')
+The contour shuttle can set the values of two custom variables of your choosing to indicate shuttle position and jog motion. To enable this feature you must first define custom variables. For example, got to the Custom Variables tab and add the following two variables: `$(custom:contourShuttleJog)` and `$(custom:contourShuttleRing)`...
+
+![Define Contour Shuttle Variables](images/contour-shuttle-custom-variables.png?raw=true 'Define Contour Shuttle Variables')
+
+Once the variables have been defined, go to the **_Configured Surfaces_** page and select the variables in the right-hand _Settings_ panel:
+
+![Set Contour Shuttle Variables](images/contour-shuttle-set-custom-variables.png?raw=true 'Set Contour Shuttle Variables')
+
+Now the variables will be set by the Contour Shuttle. Using the example names defined above:
 
-[Contour Shuttle template](assets/contour-shuttle-template.companionconfig)
+- `$(custom:contourShuttleJog)` (+1/-1): indicates the rotational direction of the jog wheel for 20 ms after each click-stop.
+- `$(custom:contourShuttleRing)` (-7 to +7): indicates the current shuttle position

user-guide/7_surfaces/contour_shuttle.md

@@ -9,7 +9,7 @@ It is possible to use the Loupedeck Live, Loupedeck Live S, Loupedeck CT and Raz
 Your Loupedeck must be running firmware v0.2.0 or later, and the Loupedeck software must not be running.
 Enable support for it in Companion's settings and rescan for USB devices.
 
-The layout closely matches the device, but the tall touch strips are not yet mapped.
+The layout closely matches the device. Touching and swiping on the tall touch strips is mapped to user-defined custom variables. Values vary from 0 to 256. See the [Contour Shuttle](contour_shuttle.md#setting-variables) section for examples and more detailed instructions.
 
 ![Loupedeck Live template](images/loupedeck-live.png?raw=true 'Loupedeck Live template')
 

user-guide/7_surfaces/images/contour-shuttle-custom-variables.png

@@ -8,4 +8,4 @@ Many [XKeys](https://xkeys.com/xkeys.html) products can be used with Companion.
 
 Since Companion v3.2, XKeys devices default to their physical (native) layout, which is often larger than Companion's default grid. Prior to 4.0 it was possible to opt into the old layout; this has now been removed.
 
-There is limited support for T-bars and shuttle/jog wheels; their values are exposed via a few hardcoded internal variables.
+There is limited support for T-bars and shuttle/jog wheels; their values are exposed via custom variables that can be associated with the device in the _Surface_ settings. See the [Contour Shuttle](contour_shuttle#setting-variables) section for examples and more detailed instructions.