> For the complete documentation index, see [llms.txt](https://wiki.inels.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.inels.com/inels-bus/inels-design-manager-idm3/tutorial-dimming-with-analog-functions.md).

# Tutorial 3 — dimming

*Part 2 — Tutorials. Continues the project from* [*Tutorial 2*](/inels-bus/inels-design-manager-idm3/tutorial-toggles-impulses-and-delays.md)*.*

***

## What you will build

A living-room dimmer with the behaviour people expect from a real dimmer:

| Press                      | Result                                  |
| -------------------------- | --------------------------------------- |
| Short press                | toggle on/off                           |
| Hold                       | brightness climbs (or falls) smoothly   |
| Release                    | it stops at whatever level it reached   |
| Second button, short press | jump straight to a 50 % "evening" level |

Along the way you will meet the one idea that trips people up about ramps.

***

## Digital versus analog

A relay has two states: on and off. A dimmer has 101 — 0 % through 100 %. That difference runs through everything:

|              | Relay       | Dimmer      |
| ------------ | ----------- | ----------- |
| Called       | **Digital** | **Analog**  |
| States       | ON / OFF    | 0 % – 100 % |
| Functions    | `Digital…`  | `Analog…`   |
| Example unit | SA3-02M     | DA3-22M     |

**Function type must match.** A `Digital` function will not be offered for a dimmer, and an `Analog` one will not be offered for a relay. If the function you want is missing from the dropdown, you almost certainly created it with the wrong **Function type**.

> **When they do meet:** `Analog copy` and `Digital copy` translate between the two — `0 % = OFF`, and anything from `1 %` to `100 % = ON`. Going the other way, `OFF = 0 %` and `ON = 100 %`.

***

## Step 1 — Add the dimmer

1. **Project** ribbon tab → **Device manager**.
2. Select `Internal-Master/BUS1`.
3. **New unit** → **DA3-22M** → **OK**.
4. Set its **Address** to match the physical unit, and **Description** to `Living room dimmer`.
5. Close, and save.

Then place it:

6. **Design** workspace tab → **Controls** ribbon tab → drag a dimmer/light icon onto the plan.
7. Click it → **Connect** → double-click the **DA3-22M output 1** → name it `Living room light`.
8. Place two more button icons, connected to **buttons 3 and 4** of the GSB3-40. Name them `Living room button` and `Evening button`.

Check for yellow dots before continuing.

***

## Step 2 — On, off, and toggle

Start with the simple case. The default project already has these:

| Function        | Effect                                                 |
| --------------- | ------------------------------------------------------ |
| `ANALOG_ON`     | straight to 100 %                                      |
| `ANALOG_OFF`    | straight to 0 %                                        |
| `ANALOG_SWITCH` | toggle — if it is at 100 %, go to 0 %, and the reverse |

1. **Function** workspace tab → **Functions** ribbon tab → **Add connection**.
2. Drag from `Living room button` to `Living room light`. Switch **Add connection** off.
3. **Wire manager** → select the wire → name it `Living room dimmer` → **+**:
   * **Action:** `Short down`
   * **User function:** `ANALOG_SWITCH`
4. **OK**, close, save, upload.

Short-press button 3: the light goes to full, then off, then full.

> **`Analog switch value` is not "restore the last level".** It moves between 0 % and 100 %, nothing else. A dimmer that returns to its previous brightness needs a system integer to remember it — [Tutorial 8](/inels-bus/inels-design-manager-idm3/tutorial-timers-counters-and-conditions.md).

***

## Step 3 — Hold to dim

This is the part that makes it feel like a dimmer, and it needs **two actions working as a pair**:

* **`Long down`** — start the level moving
* **`Long up`** — stop it where it is

Nothing predefined covers the first one, so define it.

### Define the brighten function

1. **Functions** ribbon tab → **Function manager** → **+**
   * **Name:** `ANALOG_LEVEL_UP`
   * **Function type:** `Analog`
   * **Select function:** `Analog increasing level`
2. Two parameters appear:
   * **Analog inc dec step** → `5` (climb in 5 % steps)
   * **Analog inc dec time** → `00:00:01` (a step every 1 s)
3. **✓** to save.

Repeat for the other direction:

4. **+** → **Name:** `ANALOG_LEVEL_DOWN`, **Select function:** `Analog decreasing level`, same two parameter values. **✓**

Those numbers give roughly 4 seconds for a full 0→100 % sweep. Bigger step or shorter time makes it faster; adjust to taste once you have felt it.

### Wire it up

1. **Wire manager** → select `Living room dimmer`.
2. **+** → **Action:** `Long down`, **User function:** `ANALOG_LEVEL_UP` → **OK**
3. **+** → **Action:** `Long up`, **User function:** `ANALOG_STOP_LEVEL_CHANGE` → **OK**
4. Close, save, upload.

Hold button 3: the light climbs. Let go: it holds. Short press: it toggles.

**One wire, three actions, and it now behaves like a proper dimmer.**

> **`ANALOG_STOP_LEVEL_CHANGE` is not optional.** Without it the level keeps climbing to 100 % after you release, because nothing told it to stop. Always pair `Long down` with `Long up`.

### Dimming the other way

Wire button 4 to the same dimmer with `ANALOG_LEVEL_DOWN` on `Long down` and `ANALOG_STOP_LEVEL_CHANGE` on `Long up`. Now one button brightens and its neighbour dims — the usual two-button arrangement.

***

## Step 4 — Jump to a set level

For a scene button you do not want to hold anything. You want one press, one level.

The default project has these ready:

| Function               | Level |
| ---------------------- | ----- |
| `ANALOG_SET_LEVEL_0`   | 0 %   |
| `ANALOG_SET_LEVEL_25`  | 25 %  |
| `ANALOG_SET_LEVEL_50`  | 50 %  |
| `ANALOG_SET_LEVEL_75`  | 75 %  |
| `ANALOG_SET_LEVEL_100` | 100 % |

1. **Add connection** → drag `Evening button` → `Living room light`.
2. **Wire manager** → name it `Living room evening` → **+**:
   * **Action:** `Short down`
   * **User function:** `ANALOG_SET_LEVEL_50`
3. **OK**, close, save, upload.

Press button 4 and the light goes to half, from wherever it was.

Need 40 %? Define your own with **`Analog set level`** and a **Analog value (%)** of `40`.

***

## Step 5 — Ramps, and the thing everyone gets wrong

A **ramp** makes a change gradual instead of instant. `ANALOG_BRIGHTEN` and `ANALOG_DIM` in the default project use a 4-second ramp.

Here is the catch:

> **Ramp length is the time for a full 0 % → 100 % sweep — not the time for the change you asked for.**

So with a 10-second ramp:

| Change      | Actual time |
| ----------- | ----------- |
| 0 % → 100 % | 10 s        |
| 0 % → 50 %  | 5 s         |
| 10 % → 30 % | 2 s         |

That is usually what you want — the rate of change stays constant, so small adjustments feel quick and big ones feel gentle. But if you set a 10-second ramp expecting every change to take ten seconds, you will think it is broken.

Ramp length can be anything from 0 s to 1 hour.

### The ramp functions

| Function                   | What it does               | Parameters           |
| -------------------------- | -------------------------- | -------------------- |
| `Analog switch ON w ramp`  | fade up to 100 %           | delay, ramp length   |
| `Analog switch OFF w ramp` | fade down to 0 %           | delay, ramp length   |
| `Analog set level w ramp`  | fade to a level you choose | value %, ramp length |

Try replacing `ANALOG_SET_LEVEL_50` on your evening wire with a custom `ANALOG_SET_50_RAMP_3S` — **`Analog set level w ramp`**, value `50`, ramp `00:00:03`. The light now eases to half rather than snapping. It is a small thing that makes an installation feel expensive.

***

## Step 6 — Switch on with auto off

`Analog switch ON w auto OFF` goes to 100 % and returns to 0 % by itself after a time you set in **Analog switch OFF over (s)** — the analog equivalent of the staircase impulse from [Tutorial 2](/inels-bus/inels-design-manager-idm3/tutorial-toggles-impulses-and-delays.md).

Useful for a bathroom or a walk-in wardrobe. One parameter, 0 s to 24 h.

***

## The full analog set

Everything a dimmer can be told to do:

| Function                                               | Parameters                 |
| ------------------------------------------------------ | -------------------------- |
| `Analog switch ON`                                     | —                          |
| `Analog switch OFF`                                    | —                          |
| `Analog switch value`                                  | —                          |
| `Analog_DelaySwitchOn` / `OFF` / `value`               | delay                      |
| `Analog switch ON w ramp` / `Analog switch OFF w ramp` | delay, ramp length         |
| `Analog switch ON w auto OFF`                          | switch OFF over            |
| `Analog increasing level` / `decreasing level`         | inc/dec step, inc/dec time |
| `Analog stop changing level`                           | —                          |
| `Analog set level`                                     | value %                    |
| `Analog set level w ramp`                              | value %, ramp length       |
| `Analog copy`                                          | —                          |

Every one also exists as a `GroupAnalog_…` version that acts on a whole group at once — [Tutorial 4](/inels-bus/inels-design-manager-idm3/tutorial-groups-and-scenes.md).

Full details in [Appendix B](/inels-bus/inels-design-manager-idm3/idm3-function-reference.md).

***

## What you learned

* **Digital** is on/off, **Analog** is 0–100 %, and function types must match the consumer
* Hold-to-dim is a **pair**: `Long down` starts the level moving, `Long up` stops it
* Forgetting `Analog stop changing level` means the light runs to full
* **Ramp length is the 0→100 % time**, so partial changes are proportionally quicker
* `ANALOG_SET_LEVEL_*` gives instant scene levels; add a ramp to make them glide

***

## Try this before moving on

1. Make `ANALOG_LEVEL_UP` twice as fast, upload, and feel the difference. Tuning by feel is how this is done in practice.
2. Build a "night light" — `Analog set level w ramp`, value `10`, ramp `00:00:10` — on a long press of the evening button.
3. Wire the dimmer's own **external input** (DA3-22M has them) to the same light, so a conventional wall switch works alongside the glass button.

***

**Next:** [Chapter 8 — Tutorial 4: groups and scenes](/inels-bus/inels-design-manager-idm3/tutorial-groups-and-scenes.md) — one button, many lights.