> 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-your-first-idm3-project.md).

# Tutorial 1: your first iDM3 project

*Part 2 — Tutorials.*

***

## What you will build

A wall button that switches a light. By the end of this chapter it will be running on a real central unit, and pressing the button will turn the light on.

That is deliberately small. The point is not the light — the point is that you will have walked the **entire** path once: project → units → placement → function → wire → upload → test. Every later tutorial is a variation on this path, so it is worth doing carefully now.

Allow about an hour the first time.

***

## What you need

|                            |                                                                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| iDM3 installed             | [Chapter 3](/inels-bus/inels-design-manager-idm3/installing-idm3-and-first-run.md)                                        |
| A central unit             | CU3-08M in this tutorial, powered, on your network                                                                        |
| Its IP address             | Ask whoever commissioned it, or see [Chapter 22](/inels-bus/inels-design-manager-idm3/idm3-central-unit-configuration.md) |
| A button unit              | GSB3-40 here — any BUS button unit works                                                                                  |
| A relay unit               | SA3-02M here — any BUS relay output works                                                                                 |
| The BUS addresses of both  | Hexadecimal, set during installation                                                                                      |
| A light wired to the relay | So you can see it work                                                                                                    |

> **No hardware yet?** Do steps 1 to 6, then skip the upload and use the **Simulation** workspace tab instead. You will see the logic work without a central unit. ([Chapter 26](/inels-bus/inels-design-manager-idm3/idm3-simulation-and-monitor.md))

***

## Step 1 — Create the project

1. Start iDM3.
2. Open the application menu `[☰]` (top-left) and choose **New from default**.
3. Open `[☰]` again and choose **Save as**. Name it `Tutorial` and save.

Saving now means that if anything goes wrong you can reopen a clean starting point.

> **Why "New from default" and not "New"?** The default project arrives with **61 ready-made functions** already defined — `DIGITAL_ON`, `DIGITAL_SWITCH`, `ANALOG_SET_LEVEL_50`, `SHUTTER_PULL_UP/DOWN` and so on. A plain **New** gives you an empty project and you would have to build each one by hand. On real jobs, start from the default. Always.

### Give it a name and a version

1. Go to the **Project** ribbon tab.
2. In the **Informations** group, click **Set**.
3. Fill in **Name:** — for example `Tutorial project`.
4. Leave **Version:** as it is. Tick **Increment version before save** if you want iDM3 to bump the version number every time you save. On real jobs this is genuinely useful: it tells you at a glance whether the CU is running the same build as the file in your hand.
5. Fill in the **Author informations** — your name and email. On a real installation, the next engineer will thank you.
6. Click **OK**.

***

## Step 2 — Add the units

This is where you tell iDM3 what hardware exists. Open **Project → Device manager**.

The device tree has **three levels**, and you must build them in order — top down. This is the single most common place new users get stuck, so here is the structure first:

```
  CU3-08M                          ← level 1: the central unit      "New master"
  └── Internal-Master/BUS1         ← level 2: the bus master        "New slave"
      ├── GSB3-40   (addr 01)      ← level 3: the actual devices    "New unit"
      └── SA3-02M   (addr 02)
```

**The five toolbar buttons only light up when the right thing is selected.** That is not a bug — it is iDM3 stopping you from putting a device somewhere it cannot go:

| Button            | Enabled when                        | Adds                             |
| ----------------- | ----------------------------------- | -------------------------------- |
| **New master**    | the project has no central unit yet | the central unit                 |
| **Change master** | the central unit is selected        | swaps it for a different CU type |
| **New slave**     | the **central unit** is selected    | a bus master module              |
| **New unit**      | a **bus master module** is selected | a real device                    |
| **Remove unit**   | anything removable is selected      | —                                |

### 2a. Add the central unit

1. Click **New master**.
2. In the **Units** window, choose **CU3-08M**.
3. Click **OK**.

The CU appears at the top of the tree. Select it and the right-hand **Parameters** panel shows its **Address** and a **Description** field. Type a description — `Main CU` — because a hex address tells you nothing six months from now.

### 2b. Add the bus master

1. **Select the CU** in the tree. (**New slave** stays greyed out until you do.)
2. Click **New slave**.
3. Choose **Internal-Master/BUS1** — the CU's own built-in bus.
4. Click **OK**.

> Internal master addresses cannot be changed. That is normal — they are fixed in the hardware.

### 2c. Add the button and the relay

1. **Select `Internal-Master/BUS1`** in the tree. (**New unit** needs a bus master selected.)
2. Click **New unit**, choose **GSB3-40**, click **OK**.
3. With `Internal-Master/BUS1` still selected, click **New unit** again, choose **SA3-02M**, **OK**.

Now set their addresses — **these must match the hardware, or nothing will work:**

1. Select the GSB3-40. In **Parameters**, set **Address** to the unit's real hex address.
2. Set **Description** to `Hallway switch`.
3. Select the SA3-02M. Set its **Address** and describe it as `Hallway light`.

> **Addresses must be unique across the whole system.** iDM3 checks this and will refuse a duplicate. If you are unsure of a unit's address, it is printed on the device.

### The limit bars

At the bottom right you will see bar graphs — **Modules limit**, **Units limit**, **Address limit** and **Current source**. They show how full the bus is: how many devices you have against the maximum, and how much current they draw.

Watch them on real projects. When one fills, **New unit** greys out and you need another bus master or a bus power supply. Details in [Chapter 16](/inels-bus/inels-design-manager-idm3/idm3-device-manager-reference.md).

Click **Close** when done, then save (`[☰]` → **Save**).

***

## Step 3 — Put the devices on a floor plan

iDM3 now knows the hardware exists, but you cannot wire anything yet. Wires are drawn between **icons on a floor plan**, so the devices have to be placed first.

1. Switch to the **Design** workspace tab (along the bottom).
2. Go to the **Controls** ribbon tab. It is a gallery of icons you can drag.
3. **Drag** a switch/button icon onto the plan.
4. **Drag** a light/output icon onto the plan.

Both icons now carry a **yellow dot**. That means *"not connected to a real device yet"* — the icon is just a picture until you assign it.

### Assign each icon to a real device

1. Click the button icon. A settings panel appears on the right.
2. Click **Connect**. The **Select device** window lists every available input and output, each with its hex address and description.
3. Find your GSB3-40 and **double-click the input for button 1**.
4. The yellow dot disappears. Set the icon's **Name** to `Hallway button`.
5. Repeat for the light icon: **Connect** → double-click the **SA3-02M output 1** → name it `Hallway light`.

> **The yellow dot is your friend.** Any icon still showing one does nothing at all, however correct the rest of your project looks. When a wire mysteriously has no effect, check for yellow dots first.

Save again.

***

## Step 4 — Find the function you need

Here is the thing that surprises everyone: **you cannot pick "switch the light on" directly on the wire.** A wire uses a named, reusable **user function**, which is defined separately.

The good news is that you do not have to make one. Because you started from the default project, the function you need already exists.

1. Go to the **Functions** ribbon tab.
2. Click **Function manager**.
3. Look down the list on the left. Find **`DIGITAL_ON`**.
4. Click it. The right-hand side shows what it is:
   * **Function type:** `Digital`
   * **Select function:** `Digital switch ON`
   * no parameters

That is exactly what you want. Close the Function manager without changing anything.

### The ones you will use most

| Function                                | What it does                      |
| --------------------------------------- | --------------------------------- |
| `DIGITAL_ON`                            | Switch a relay on                 |
| `DIGITAL_OFF`                           | Switch a relay off                |
| `DIGITAL_SWITCH`                        | **Toggle** a relay                |
| `DIGITAL_IMPULSE_1MIN`                  | On for one minute, then off       |
| `ANALOG_SET_LEVEL_50`                   | Set a dimmer to 50 %              |
| `ANALOG_BRIGHTEN` / `ANALOG_DIM`        | Fade a dimmer up or down over 4 s |
| `DIGITAL_GROUP_ON` / `_OFF` / `_SWITCH` | The same, for a whole group       |

The full list of all 61 is in [Appendix B](/inels-bus/inels-design-manager-idm3/idm3-function-reference.md).

### Making your own

You will need a custom one eventually — a two-minute impulse, say, when only the one-minute and five-minute versions exist. The procedure:

1. In **Function manager**, click **+**. The right-hand side becomes editable.
2. Enter a **Name:**.
3. Choose the **Function type:** — `Digital` for a relay, `Analog` for a dimmer.
4. Choose the **Select function:** — the effect itself.
5. Fill in any parameters it offers.
6. Click **✓** to save it, or **✗** to abandon it.

You will do this for real in [Tutorial 2](/inels-bus/inels-design-manager-idm3/tutorial-toggles-impulses-and-delays.md).

> **Function type must match the consumer.** A relay is `Digital`. A dimmer is `Analog`. Pick the wrong type and your function will not be offered on the wire.

***

## Step 5 — Draw the wire

1. Switch to the **Function** workspace tab (along the bottom).
2. Go to the **Functions** ribbon tab.
3. Click **Add connection**. Connectable icons turn **green**.
4. **Press and hold** the mouse on the `Hallway button` icon, **drag** a line to the `Hallway light` icon, and **release**.

A line appears between them, with an arrow showing the direction: button → light. The button is the **actor**, the light is the **consumer**.

Click **Add connection** again to switch the mode off.

> **Nothing happens when you drag?** You are probably on the wrong workspace tab. Wires are drawn on the **Function** tab, not **Design**.

***

## Step 6 — Tell the wire what to do

The wire exists but is empty. It connects two things and does nothing. Now give it its rule.

1. Still on the **Functions** ribbon tab, click **Wire manager**.
2. Find your wire in the list on the left — it shows the actor and consumer names. Select it.
3. On the right, give it a **Name:** — `Hallway light ON` — and a **Description:** if you like.
4. Under **Functions:**, click **+**. The **Wire function** window opens.
5. Set **Action:** to **`Short down`**.
6. Set **User function:** to **`DIGITAL_ON`** — the one you found in step 4.
7. Leave **Conditions** empty. You want this to fire every time.
8. Click **OK**, then close the Wire manager.

Read back what you just built:

> **When** `Hallway button` gets a **`Short down`** → **do** `DIGITAL_ON` (`Digital switch ON`) **to** `Hallway light`.

That is the shape from [Chapter 2](/inels-bus/inels-design-manager-idm3/how-programming-works-in-idm3.md), now real.

**Save the project** (`[☰]` → **Save**).

***

## Step 7 — Connect to the central unit

1. Open `[☰]` → **Settings**.
2. Under **Connection settings**, enter the CU's **IP address : port**.
3. Click **Ping test** to check the CU answers. Fix the network before going further if it does not.
4. Click **OK**.

Watch the connection state at the bottom-right of the window. It should reach **`Connected`**.

| If you see       | It means                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Disconnected`   | No connection — check the IP address and cabling                                                                    |
| `BadPassword`    | Wrong CU password                                                                                                   |
| `UpdateRequired` | The CU firmware is too old — see [Chapter 25](/inels-bus/inels-design-manager-idm3/idm3-firmware-update-manager.md) |
| `Error`          | See the information console at the bottom for the reason                                                            |

***

## Step 8 — Upload

1. Open `[☰]` → **Save to central unit**. (It is also on the **Project** ribbon tab.)
2. Confirm when prompted.
3. Watch the progress. The information console logs each stage.

iDM3 compiles the project and sends it. If compilation fails, the **Compile error** button on the **Project** ribbon tab lights up — click it to see what is wrong.

> **This is the moment the building changes.** Everything before this only edited a file on your PC. Now the central unit is running your rule.

***

## Step 9 — Test it

**Press button 1 on the GSB3-40. The light comes on.**

That is your first working iNELS3 program.

Press it again — the light stays on. That is correct: you asked for `Digital switch ON`, not "toggle". Making it toggle is the first thing you will do in [Tutorial 2](/inels-bus/inels-design-manager-idm3/tutorial-toggles-impulses-and-delays.md).

### If nothing happens

Work through these in order:

| Check                               | How                                                                                                                              |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Did the upload succeed?             | Read the information console for errors                                                                                          |
| Is the connection live?             | Status shows `Connected`                                                                                                         |
| Any yellow dots left?               | **Design** tab — an unassigned icon does nothing                                                                                 |
| Are the addresses right?            | **Device manager** → compare **Address** against the physical units                                                              |
| Is the wire pointing the right way? | **Wire manager** — actor should be the button, consumer the light                                                                |
| Does the function exist?            | **Wire manager** → your wire → is `DIGITAL_ON` listed under **Functions:**?                                                      |
| Is the light itself wired?          | Use **Monitor** to see whether the relay output is switching — if it is, the fault is in the electrical wiring, not your project |

**Monitor** (**Managers** ribbon tab) is the tool that settles this fastest: it shows live device states from the CU, so you can see whether the output is changing at all. [Chapter 26](/inels-bus/inels-design-manager-idm3/idm3-simulation-and-monitor.md).

***

## What you learned

|                                                 |                                                                     |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| **Three-level device tree**                     | master → slave → unit, built top down, buttons enabled by selection |
| **Addresses matter**                            | they must match the hardware and be unique                          |
| **Icons must be assigned**                      | a yellow dot means it does nothing                                  |
| **Functions are defined once, used many times** | Function manager, then picked on the wire                           |
| **Wires are drawn, then filled in**             | drag to create, Wire manager to give it a rule                      |
| **Save ≠ Save to central unit**                 | one writes a file, the other changes the building                   |

***

## Try this before moving on

Small changes, same project. Each takes a couple of minutes and makes the next chapter easier.

1. Add `DIGITAL_OFF` to the same wire with the action **`Long down`**. Now a short press turns the light on and a long press turns it off — one button, two behaviours.
2. Add a second output to the SA3-02M as another icon, and wire button 2 to it.
3. Open **Wire manager** and look at the wire count — `used / maximum`. That maximum is a real limit on large projects.

***

**Next:** [Chapter 6 — Tutorial 2: beyond on/off](/inels-bus/inels-design-manager-idm3/tutorial-toggles-impulses-and-delays.md) — toggling, delays, and staircase lighting.