CLI Advanced Setup

From OpenMotics
Jump to: navigation, search

General

This document describes the steps to activate switches and lights in an advanced home automation system by using Basic Actions.

Before starting with this document, please make sure you are familiar with the basic functions as described in the CLI Basic System Setup section.

To get the basic Home automation features activated, you need minimum following requirements:

  • An installed Gateway with the latest firmware
  • An RS232 TTL direct connection with the Gateway or an active cloud connection (so the maintenance feature can be used)
  • At least one input module and one output module (or dimmer module)
  • All modules must be connected to +12V power supply and the A and B RS485 Bus lines must be wired correctly. Please be careful that the RS485 termination jumper on the different modules are only set for the first and the last module on the bus.

Most of the programming functions can also be done by using the graphical user interface, please see Switch Setup for some examples.

Principles

The full system is based on Basic Actions. A Basic action consists of 2 bytes:

  • Action Type: The Action Type will define which action that will be executed
  • Action Number: The action number will define on which output for example the action will be executed.

For a full list of available Basic Actions, please consult the Action Types list.

Example of a Basic Action (BA):

  • BA 161 15
  • 161 is the Action Type to switch on an output.
  • 15 is the action number
  • 15 -> Output 15
  • So this Basic Actions will switch on output 15.

Basic actions are used through the whole system. Time based functions or environmental parameters can for example trigger a Basic action, or when a switch is pressed, multiple basic actions can be executed. Simple Actions, Scheduled actions, group actions, simple decisions (IF THEN ELSE), thermostat actions, etc. are all Basic Actions. A Group Action for example is a list of Basic Actions and thus can include other group actions for example. All basic actions can be combined creating huge possibilities and complex functions.

The most used basic actions are created at the input page of a switch. Every switch has its own input page that can contain up to 15 basic actions that can be executed when the switch is pressed. Every input can be linked to 1 output. The valid output numbers are from 0 to 239. When output number 240 is programmed, the system will execute all the basic actions that are defined at input level of that switch.

Basic action.jpg

Some Examples

Please have CLI Reference Guide open in a second tab so the used commands can be checked.

Please have Action Types open to check your Basic actions (BA)

Switching OFF all outputs

If you link a switch with an output, the input link (which indicates the output) can only be between 0 and 239 (because we have maximum 240 outputs). However, if we program as input link 241, all outputs will be switched off.

input link write 6 241

Disadvantage of this approach is that all outputs will be switched off, including other outputs then lights like pumps, valves of the heating etc. In most cases, this is not the best approach.

Switching OFF all Lights

What we want to accomplish is that all lights will be switched off by using 1 switch but only the lights, not the other outputs.

  • Step1:

In the system, all outputs are standard configured as lights. The non-lights outputs should be changed to a standard output so the system knows which output is a light and which output is a standard output. Because all outputs are standard configured as light outputs, we only need to change the non-light outputs. In our example, output 45 is driving the ventilation and cannot be switched off by our switch 6, this is done by following instruction:

output type write 45 0

The “0” indicates that output 45 is a standard output (not a light).

  • Step2:

To switch off all lights, we can easily do this by using a Basic Action. By looking at the Action Types list, we can see that action type 163 is exactly what we need. We need to tell the system that the Basic actions (max 15 for each input) of input 6 must be used. We do this by putting 240 as input link so the system knows that the Basic actions of that input needs to be executed.

input link write 6 240
  • Step3:

Now, we only have to add our Basic Action for that particular switch (in our example it's switch 6)

input action write 6 0 163 0

Switch 6 Action Line 0 BA type 163 BA Action 0

This programs our Basic action for switch 6 at action line 0 (we have 0-14 Basic actions we can program for each input) with action type 163 and action number 0 (which is in the case of switching all lights off irrelevant but must be <240). We don’t need more to accomplish our example.

By using the instruction

input link read 6

you can see the programmed input link as well the programmed Basic actions. Basic actions with action type 255 are not used or empty basic actions.

Note 1: We can easily test a basic action. A good practice is to test a Basic Action before implementing it. For the above example, we can test our ‘all lights out function’ by using following instruction:

basic action activate 163 0

Note 2: We can imagine, with kids for example, that using one switch to switch off all lights with a single push could create some funny situations. To avoid this, we could easily create a switch that must be pushed for 3 seconds for example before all lights are switched off. See example "Switch with multiple functions.

Toggle multiple lights/outputs with 1 Button

Example: Switch 7 must toggle all lights in the living room (output 23, 24, 25 and 26). In this example, we have again 2 solutions to accomplish this function:

We add the basic actions in our input page to toggle every individual light (action type 162). However, we don’t want if 2 lights are already on, we toggle 2 off and the 2 others on. To solve this, we will use the Toggle Follow Function (action type 174) that will follow the first light in the list (first light on, all lights on, first lights off, all lights off). These are the instructions that are needed:

  • Step1:
input link write 7 240
  • Step2:
input action write 7 0 174 0
input action write 7 1 162 23
input action write 7 2 162 24
input action write 7 3 162 25
input action write 7 4 162 26

Toggle light/output groups with 1 Button

In the system, we can link lights to groups (or floor levels) and switch on/off/toggle a complete group. Every light can only be part of 1 group. First we will link all lights to group 10:

  • Step1:
floor level write 23 10
floor level write 24 10
floor level write 25 10
floor level write 26 10
  • Step2:

As you can see in the Action Action Types list, we have a Basic Action that can toggle a group or floor level (action type 173). To finish our function, following instructions are needed:

input link write 7 240
input action write 7 0 173 10

Note: As you can see, we didn't use the Toggle Follow Function. When complete groups or floor levels are toggled, the system will check if 1 or more lights are on and will switch off those lights. If all lights are off, then the lights of the group will be switched on.

Button with Multiple functions

Example: Switch 27 must toggle light 9 but when pressed longer than 3 seconds, all lights must be switched off except for light 10 that must remain on for about 2 minutes and then switched off

The above solution must be accomplished by using the basic actions at input page level. The answer of all our questions can be found back again in the Action Types list. We must give our switch 27 multiple functions:

  1. If we press normally, it should toggle light 9
  2. If we press longer than 3 seconds, it must switch off all lights and switch on light 10 for about 2 minutes

So let's start programming our system to have the above example working.

  • Step1:

Let’s program that our switch that will toggle (action type 162) output 9

input link write 27 240
input action write 27 0 162 9
  • Step2:

That was simple. Now we need to add a function that activates multiple actions when pressing input 27 for longer than 3 seconds, this will be done by using action type 208. Action type 208 will activate a group action after 3 seconds. Let’s assume for example that group action 20 is empty.

input action write 27 1 208 20
  • Step3:

Now, we only have to program our group action 20 to switch off all lights (Action Type 163) and switch on output 10 for about 2 minutes (action type 195). A good practice is to always check is a group is free by using instruction group list and in this case group read 20 (all BA should be on 255). Another good practice is also to give your group action a name.

group name write 20 All lights off
group write 20 0 163 0
group write 20 1 195 10

Important Note: When you group multiple actions in for example a group action, it is a good practice to test those actions.

For example, we want to test group action 20 that we've programmed:

basic action activate 2 20			; will execute group action 20

If an action that you've tested doesn't give the expected result, you can always do the test again and check what’s happening on system level. Before executing the action again you can enable the debug mode:

debug on

To switch off debug mode:

debug off

Store/shutter/curtain with 2 buttons

In this example, we'll discuss how to program a store to go up and down and protect that both outputs (Up and Down motor connection) are not switched on together. This example in reality won't be used because an Output module can be put in Roller/Shutter mode which has the output protection built-in. This is however a good example what can be done.

As an example, we take a store that is connected to 2 Relay outputs:

  • Output 0 to move the store up
  • Output 1 to move the store down

We must program it so never both outputs 0 and 1 can be enabled at the same time which could destroy the store (when the output module is NOT put in Roller/Shutter mode)!

We will program 2 switches to move the stores up and down:

  • Switch 11 will move the store up
  • Switch 10 will move the store down

With the switches, we want to activate and stop the stores. So when the store is moving, pushing on 1 of the buttons must stop the store.


  • Step1:

First, let’s give the outputs a name, program them as outputs and set their timer value (120 seconds).

output name write 0 Store Up
output name write 1 Store Down
output type write 0 0
output type write 1 0
output timer write 0 120
output timer write 1 120
  • Step2:

Program the group actions (in this example group 0, 1 and 2 -> first check if these group action are empty before start using them) to Move the store up, down and stop the store

group name write 0 Move Store Up
group write 0 0 160 1			; Switch off output 1
group write 0 1 235 1			; Delay all next instructions with 1 second to avoid Relay 0 and 1 to be ON at the same time
group write 0 2 161 0			; Switch On output 0
group write 0 3 235 255			; Stop Delaying all next instructions
group name write 1 Move Store Dwn
group write 1 0 160 0			; Switch off output 0
group write 1 1 235 1			; Delay all next instructions with 1 second to avoid Relay 0 and 1 to be ON at the same time
group write 1 2 161 1			; Switch On output 1
group write 1 3 235 255			; Stop Delaying all next instructions
group name write 2 Stop Store
group write 2 0 160 0			; Switch off output 0
group write 2 1 160 1			; Switch off output 1


  • Step3:

Let’s now program the switches so these can move and stop the stores

input link write 11 240
input action write 11 0 240 0		; IF
input action write 11 1 244 0		; Is Output 0 Off?
input action write 11 2 240 1		; AND
input action write 11 3 244 1		; Is Output 1 Off?
input action write 11 4 240 10		; THEN
input action write 11 5 2 0		; execute group 0 (Move Store Up)
input action write 11 6 240 20		; ELSE
input action write 11 7 2 2		; execute group 2 (Stop store)
input action write 11 8 240 255		; ENDIF
input link write 10 240
input action write 10 0 0 240		; IF
input action write 10 1 244 0		; Is Output 0 Off?
input action write 10 2 240 1		; AND
input action write 10 3 244 1		; Is Output 1 Off?
input action write 10 4 240 10		; THEN
input action write 10 5 2 1		; execute group 1 (Move Store Dwn)
input action write 10 6 240 20		; ELSE
input action write 10 7 2 2		; execute group 2 (Stop store)
input action write 10 8 240 255		; ENDIF

Activate ventilator depending on Humidity

When a temperature sensor with humidity is connected to the system, it's simple to configure actions linked to the humidity level.

  • Step1:

Let's first create a group which checks the humidity and drives our ventilator (in our example this is output 5). Group 8 is free so let's now program group 8. To check the connected humidity sensors and their value, use instruction humidity list. Please note that the IF THEN ELSE programming must be done with system values (which are not the same as the real values). For the calculation between normal and system value, please consult the System Value page.

group name write 8 Check humidity
group write 8 0 240 0     	; IF
group write 8 1 247 32   	; value Humidity sensor 0
group write 8 2 249 140   	; >140 (=70% humidity see System Value)
group write 8 3 240 10   	; THEN
group write 8 4 161 5   	; Output 5 ON
group write 8 5 240 255   	; ENDIF
group write 8 6 240 0   	; IF
group write 8 7 247 32   	; value Humidity sensor 0
group write 8 8 250 100   	; <100 (=50% humidity see System Value)
group write 8 9 240 10   	; THEN
group write 8 10 160 5   	; Output 5 OFF
group write 8 11 240 255   	; ENDIF

As you can see in the above example, we applied an hysteresis (on>70% and off<50%) to avoid the ventilator to switch on and off. We can test the group with instruction basic action activate 2 8.

  • Step2:

We've to decide how our group 8 is triggered. This can be linked at an input but better is that this group is checked every minute. For this, we will use a scheduled action which can be programmed on a certain hour and day. We will use schedule action 5. To check the used scheduled actions, please use instruction schedule list and instruction schedule read 5 (to check of our schedule action of our example is empty -> all 255)

schedule name write 5 humidity check
schedule write 5 24 0 255 2 8

5 -> schedule action 5, 24 -> 24h, 0 -> 0m (when programmed time is 24:00, routine when will be executed every minute if the day is valid), 255 -> Every day of the week and do not remove the schedule action out of the queue, 2 -> execute group action, 8 -> group action 8

  • Step3:

Now the scheduled action is created, it's not yet active. The scheduled action must be in the scheduled action queue to get checked and executed. With the instruction schedule queue list you can check the scheduled actions active in the queue and with the instruction schedule queue add x and schedule queue delete x scheduled actions can be added and removed from the queue.

To make sure a scheduled action is always in the queue, also after a power reset, we will put the scheduled actions and the schedule queue at startup. The system has a startup list of Basic actions that can be executed during startup. To check the list of startup actions, you can use the instruction startup list. In this example, our startup list is empty so we will start at line 0.

startup write 0 3 5

Now we only have to execute the startup action by using instruction startup activate or by resetting the master controller using instruction reset (connection in maintenance mode will be lost). Also check if the programmed action is in the scheduled action queue by using instruction schedule queue list

Button short press -> Toggle light, long press -> All lights off

Button 38 is the button of my bedroom. When i apply a short press, light 35 must be toggled, when i apply a long press (around 3 seconds) all lights must be switched off. However, i only want 1 of both to be executed (or toggle light or all lights off) in other words, when i arrive home again much too late and my wife is sleeping, i still want to switch off all lights without toggling the light of the bedroom and my wife seeing that i'm late and maybe had a few beers :)

The solution is that we ask the system to evaluate what needs to be done at button release. So at button release or when the press time is achieve, the system needs to execute the right actions.

  • Step1:

Create a group action (if that does not exist yet) to switch off all lights (group 25 in our example).

group name write 25 All Lights OFF
group write 25 0 163 0			; All lights off
  • Step2:

Create the necessary actions at switch level (in our example switch 38)

input link write 38 240 		; switch 38 must executed his action list
input action write 38 0 208 25 		; When switch 38 is pressed for more than 3 seconds, execute group 25
input action write 38 1 236 0 		; Only execute following Basic actions at button release
input action write 38 2 162 35 		; Toggle output 35 (at button release)
input action write 38 0 236 255 	; Stop executing Basic actions at button release

Create Group action to delay switching ON/OFF lights

As you all know by reading the previous examples, you can use group actions in different levels in the Openmotics system (linked to a switch, linked to scheduled action, linked to startup actions etc) so we'll program the delayed switched ON/OFF in a group action.

Let's program following example: When executing this group action, light 5 must go ON immediately, After 5 seconds Light 6 and 7 after must go ON and after 20 seconds, Light 5, 6 and 7 must go OFF.

  • Step1:

Create a group action (if that does not exist yet) to switch off all lights (group 30 in our example).

group name write 30 Delayed lights
group write 30 0 161 5			; Switch ON light 5 immediately
group write 30 1 235 5                 ; Delay all following instruction with 5 seconds
group write 30 2 161 6                 ; Switch ON light 6
group write 30 3 161 7                 ; Switch ON light 7
group write 30 4 235 255               ; Ends 5 seconds of delay queue
group write 30 5 235 20                ; Delay all following instruction with 20 seconds
group write 30 6 160 5                 ; Switch OFF light 5
group write 30 7 160 6                 ; Switch OFF light 6
group write 30 8 160 7                 ; Switch OFF light 7
group write 30 9 235 255               ; Ends 20 seconds of delay queue
  • Step2:

Test the group action by using following action:

Create Scheduled action that open the curtains in the morning and closes them in the evening

In this example, we would like to execute group action 20 (which will open the curtains) in the morning at 7.15am and closes the curtains at 7.55pm by execution group action 21. We assume in this example that group action 20 and 21 are created and working.

First we have to create the Scheduled Action and we have to put this scheduled action in the scheduled action queue, we will do this by adding this to the startup actions. Every time when the processor starts, it will add this Scheduled Action to the scheduled action queue.

  • Step1:

Create 2 scheduled actions (one for the morning and one for the evening):

schedule list                          ; Check for non used scheduled actions (for example up to 4 they are used)
schedule write 5 7 15 255 2 20 	; Execute group action 20 at 7h15 every day and don't delete from the queue after execution (255)
schedule write 6 19 55 255 2 21 	; Execute group action 21 at 19h55 every day and don't delete from the queue after execution (255)
schedule list                          ; You will see the created actions now but with an "empty" tag, this means these are valid actions but without a name
schedule name write 5 Open morning     ; Create name for scheduled action 5
schedule name write 6 Close evening    ; Create name for scheduled action 6
schedule list                          ; Now you will the see your list with the appropriate names
schedule read 5                        ; With this instruction, you can read the content of a scheduled action, in this case number 5
  • Step2:

Put the scheduled actions in the scheduled action queue at startup:

startup list                           ; Check the startup that already exist (in this example, no startup actions are defined yet)
startup write 0 3 5                    ; Add scheduled action 5 to the startup queue

Note:

If you want to erase a created scheduled action, please use following instruction:

schedule write 5 255 255 255 255 255   ; Delete scheduled action 5
schedule list                          ; you'll see that schedule action 5 is gone
startup write 1 3 6                    ; Add scheduled action 6 to the startup queue
  • Step3:

Reset your system and check if they are in the queue:

reset                                  ; reset the system to add the scheduled actions in the queue by starting up
schedule queue list                    ; check if the 2 scheduled actions are in the scheduled queue.
  • Step4:

Check your time:

time read                              ; You will get back the time and the day of the week (1=Monday)

If the time is not correct, please adapt the time zone in the Openmotics portal (Settings-Environment) since the time is automatically adapted and synchronized with the internet time. Using the instruction "time write" will correct the time but when maintenance session is closed, this time will be overwritten by the internet time and the chosen timezone.

Create actions that allows curtains to open/close at a certain position with the use of reed switches

Note: We're not using Large Installation mode, however, this example could be easily modified with the Basic Actions (see Action Types) used in Large Installation for roller/shutters.

In this example, we have a large projector screen with curtains. Depending on the movie format, we want to put the curtains in 4 possible positions:

  • Fully open
  • Open 4:3 format
  • Open 16:9 format
  • Fully close

The fully open or close position is simple, the motors have their own stop so we just have to activate the motors to go open or close. To know to 4:3 and 16:9 stop, we've installed a reed switch at each individual position. Those reed switches are each connected to an input of an input module.

  • Step1:

Please make sure that your output module is in Roller/Shutter Mode so the 2 motor directions can't be activated at the same time, see Roller/Shutter mode. If your module was already activated (but in the wrong mode), remove the output modules and perform the module discovery again.

  • Step2:

Test your motor in both directions and measure the time between fully open (in our example output 2) and fully close (in our example output 3).

input debug on			        ; Test also your reed switches at position 4:3 and 16:9, by opening and closing, check on the console if you see the reed switch activation
output on 2                            ; Open
output off 2                           ; Stop the motor from opening
output on 3                            ; Close
output off 3                           ; Stop the motor from closing
input debug off
  • Step3:

Create 6 group actions to open/close the curtains at the 3 possible positions (4:3, 16:9, fully open/close). We'll use the freely assignable validation bits to let the input actions (from the reed switches) know if they'll have to stop the motor or not. In our example, reed switch 4:3 is connected to input 5, reed switch 16:9 is connected to input 6. For simplicity, we'll use validation bit 5 and 6 to be linked to input 5 and 6.

group name write 10 Fully open         ; We use group 10 in our example which is not yet in use and give it a name
group write 10 0 238 5			; Set freely assigned bit 5 at 0 in other words, don't stop at position 4:3
group write 10 1 238 6			; Set freely assigned bit 6 at 0 in other words, don't stop at position 16:9
group write 10 2 160 3                 ; Stop output 3 (not really needed since your module is in shutter mode but better safe than sorry)
group write 10 3 195 2                 ; Activate output 2 (which is the open connection in our example) for 2 minutes and 30 seconds
group name write 11 Open 43            ; We use group 11 in our example which is not yet in use and give it a name
group write 11 0 237 5			; Set freely assigned bit 5 at 1 in other words, stop at position 4:3
group write 11 1 238 6			; Set freely assigned bit 6 at 0 in other words, don't stop at position 16:9
group write 11 2 160 3                 ; Stop output 3 (not really needed since your module is in shutter mode but better safe than sorry)
group write 11 3 195 2                 ; Activate output 2 (which is the open connection in our example) for 2 minutes and 30 seconds
group name write 12 Open 169           ; We use group 12 in our example which is not yet in use and give it a name
group write 12 0 238 5			; Set freely assigned bit 5 at 0 in other words, don't stop at position 4:3
group write 12 1 237 6			; Set freely assigned bit 6 at 1 in other words, stop at position 16:9
group write 12 2 160 3                 ; Stop output 3 (not really needed since your module is in shutter mode but better safe than sorry)
group write 12 3 195 2                 ; Activate output 2 (which is the open connection in our example) for 2 minutes and 30 seconds
group name write 13 Fully close        ; We use group 13 in our example which is not yet in use and give it a name
group write 13 0 238 5			; Set freely assigned bit 5 at 0 in other words, don't stop at position 4:3
group write 13 1 238 6			; Set freely assigned bit 6 at 0 in other words, don't stop at position 16:9
group write 13 2 160 2                 ; Stop output 2 (not really needed since your module is in shutter mode but better safe than sorry)
group write 13 3 195 3                 ; Activate output 3 (which is the close connection in our example) for 2 minutes and 30 seconds
group name write 14 Close 43           ; We use group 14 in our example which is not yet in use and give it a name
group write 14 0 237 5			; Set freely assigned bit 5 at 1 in other words, stop at position 4:3
group write 14 1 238 6			; Set freely assigned bit 6 at 0 in other words, don't stop at position 16:9
group write 14 2 160 2                 ; Stop output 2 (not really needed since your module is in shutter mode but better safe than sorry)
group write 14 3 195 3                 ; Activate output 3 (which is the close connection in our example) for 2 minutes and 30 seconds
group name write 15 Close 169          ; We use group 15 in our example which is not yet in use and give it a name
group write 15 0 238 5			; Set freely assigned bit 5 at 0 in other words, don't stop at position 4:3
group write 15 1 237 6			; Set freely assigned bit 6 at 1 in other words, stop at position 16:9
group write 15 2 160 2                 ; Stop output 2 (not really needed since your module is in shutter mode but better safe than sorry)
group write 15 3 195 3                 ; Activate output 3 (which is the close connection in our example) for 2 minutes and 30 seconds
  • Step4:

Now we still have to program our inputs (reed switches) so they'll stop the motor when needed. So when input 5 is activated and freely assigned bit 5 is set to 1, stop the motor. The same applies to input 6.

input link write 5 240 		; switch 5 must execute his action list
input action write 5 0 240 0 		; IF
input action write 5 1 245 5 		; Freely assigned bit 5 = 1
input action write 5 2 240 10 		; THEN
input action write 5 3 160 2		; Stop motor open
input action write 5 4 160 3		; Stop motor close
input action write 5 5 240 255 	; ENDIF
input link write 6 240 		; switch 6 must execute his action list
input action write 6 0 240 0 		; IF
input action write 6 1 245 6 		; Freely assigned bit 6 = 1
input action write 6 2 240 10 		; THEN
input action write 6 3 160 2		; Stop motor open
input action write 6 4 160 3		; Stop motor close
input action write 6 5 240 255 	; ENDIF

All programming is done :) Time for testing !

  • Step5:

Let's test our setup now.

basic action activate 2 13             ; Launch group action 13 to test the fully close position
basic action activate 2 10             ; Launch group action 10 to test the fully open position
basic action activate 2 11             ; Launch group action 11 to test the 4:3 position
basic action activate 2 12             ; Launch group action 12 to test the 16:9 position
basic action activate 2 14             ; Launch group action 14 to test the 4:3 position
basic action activate 2 15             ; Launch group action 15 to test the 16:9 position
  • Step6:

Link your group actions to any switche or an action on the portal depending how you want to activate your curtains.