Tutorial 3 — dimming

Part 2 — Tutorials. Continues the project from Tutorial 2.

---

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:

1. Design workspace tab → Controls ribbon tab → drag a dimmer/light icon onto the plan.

2. Click it → Connect → double-click the DA3-22M output 1 → name it Living room light.

3. 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.

---

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:00.2 (a step every 0.2 s)

3. ✓ to save.

Repeat for the other direction:

1. + → 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.

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.

Full details in Appendix B.

---

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 — one button, many lights.