CLI Basic System Setup

From OpenMotics
Jump to: navigation, search

Principles

This document describes the CLI steps to activate switches and lights and to setup a basic home automation system. Please note that the same can be accomplished by using the graphical OpenMotics cloud interface, for more information, please consult the System cloud setup and Switch Setup pages.

This document will describe following CLI actions:

  • Test inputs
  • Test outputs
  • Link inputs with outputs
  • Set timers
  • Switch all lights off with 1 button

For the more advanced features, please consult Thermostat Setup and CLI Advanced Setup.

To see all available CLI instructions, please consult the CLI Reference Guide


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 master (be careful that the RS232 jumpers J1 and J2 are removed) or an active Gateway in the OpenMotics Cloud (Jumper J1 and J2 must be set). See the RS232 page for more information.
  • 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 (on twisted pair). Please be careful that the RS485 termination jumper on the different modules is only set for the first and last module on the bus.
  • The following limitations apply:
    • 30 input modules (up to 240 inputs)
    • 30 output modules (up to 240 outputs)
    • These are the input modules that exist:
      • 8 ports input module
      • 8 ports temperature module
      • Oled module
    • These are the output modules that exist:
      • 8 ports dim control module (0-10V)
      • 8 ports Output (Relay) module

The Master controller can fully operate in stand-alone without the Gateway controller software running.

Terminal Emulator

The master controller has a RS485 Bus connection to communicate with the different modules and has a RS232 connection to communicate with the Gateway controller or with a terminal emulator.

The CLI can be accessed in 2 ways:

  • Terminal emulator connected with Direct TTL RS232 connection (Master CLI TTL connection) on the Gateway (Jumper J1 and J2 removed), see RS232 page for connection details.
  • Terminal emulator embedded in the OpenMotics Cloud by using the Maintenance function (Jumper J1 and J2 set).

This CLI can be accessed by using the Maintenance function in the OpenMotics cloud or by using a RS232 TTL cable (Baud rate 115200, 8 databits, no parity, 1 stop bit, no flow control) that is connected directly on the Gateway.


The master Controller can be put in 2 modes: API or CLI mode:

  • In CLI mode, the user has a Command Line Interface that can be used to program the master controller and to execute individual instruction in readable text (see CLI reference guide).
  • In API mode, the Gateway controller will sent instructions over RS232 to the Master Controller in non-readable text to execute instructions. The Master API instruction set can be obtained on request.

The master can be easily changed from API to CLI mode and vice versa (see point 7 of Notes).

Notes

  1. In CLI mode, characters sent through RS232 can be echoed (“echo on” or “echo off”). In API mode they are never echoed.
  2. Instructions are case sensitive.
  3. As opposed to API mode, CLI mode has a variable instruction length.
  4. Every instruction must be followed by a Carriage return (<CR>, DEC 13).
  5. Every successful instruction will return the requested information (or perform requested action) followed by OK, otherwise ERROR is returned (wrong format, wrong parameters,…). All error codes are listed in the Error Codes section.
  6. An instruction will only be executed if the Master has responded with “OK”
  7. To go from CLI to API mode type exit. To go from API to CLI mode type STRCM (capitals), followed by random characters until “ERROR 17” or “OK” appears.
  8. If terminal emulation is not working, check following points:
    • Direct RS232 connection:
      • Check if the right cable (Must be a TTL RS232 cable) is used and hardware wise correctly connected to the Master CLI TTL (Not RS232) connection of the Gateway.
      • Check in your terminal emulation program (putty or others) that the right COM port is used and that the right baudrate (115200) settings are applied
      • If the Master Controller is in API mode, the Master will not react on any CLI instruction. Try to use the STRCMxxxxxxxxxxxxxxxxxxx to change towards CLI mode.
      • Check if the Jumpers J1 and J2 are removed from the Gateway
    • Maintenance Mode:
      • Check if your Gateway is connected to the internet. If so, the VPN, Cloud and Alive led should be on (one of those 3 leds will be flashing). If this is not the case, check connectivity.
      • Make sure your gateway is registered on the OpenMotics cloud and you have a valid account
      • Make sure that jumper J1 and J2 are set on the Gateway.

Limitations

The maximum number of inputs that can exist is 240 so inputs 0-239 are valid input numbers. The maximum number of outputs that can exist is 240 so outputs 0-239 are valid output numbers. Outputs on a dimmer module can be dimmed. The valid dimmer values that can be used are between 0 (light at 0%) and 63 (light at 100%).

Adding Modules

All the connected slave modules work in 2 modes: Normal mode and initialization mode. In normal mode, the master will communicate with the modules previously detected on the RS485 bus. When putting the modules in initialization mode, the master will learn and detect new modules (by pressing the init button the slave modules) on the bus and add them in the master device list. The network address generation is fully automatic and no jumpers need to be set (and no bus conflicts can exist).

Put Bus in Init Mode and add modules

  • Put the Bus in discovery mode

module discover start

With this instruction, you will put the Bus in initialization mode so modules can be added.

Please execute folowing steps:

Step1: Put the bus in discovery mode

Note: If one or more Output Modules will be used to control roller shutters it must be put in the correct mode before entering the command below. For more info on how to put the Output Module in Roller Shutter Mode please refer to the Hardware Installation Guide.

Step2: Please check that the status led of all slave modules is orange (except for the Power Modules). If this is not the case, the RS485 A or B lines are reversed or not connected. Please also check the RS485 jumpers (only the first and the last module on the bus can have the RS485 jumper set). After Checking, redo module discover start

Step3: Press the init button on every output modules one per one. If the master indicates a bus conflict, press the init button again until the output module is added.

Note: When the Bus is in Init mode, output modules will not work in other words, if a switch is linked to an output and that switch is activated, the output will not toggle.

Exit the Init Mode and put the Bus in Normal Mode

  • Exit Discovery mode

module discover stop

This instruction will put the modules back in normal mode

Test Outputs

In this phase, please test all individual output (in this example , we will switch on light 3 at max light density->63) that you have on your system. When you have 1 Output (Dim or Relay) module installed, output 0 to 7 is active, when you have 2 output modules installed, output 0 to 15 is active etc

  • Instruction example to switch ON an Output:

output on 3 63

will switch ON output 3 at dimmer value 63 (dimmer value from 0 to 63)

  • Instruction example to switch OFF a light:

output off 3

will switch output 3 off

  • Instruction example to switch off all outputs and lights

output all off

  • If an output is not working, you can easily find this output back by using following instruction:

output indicate 3

This instruction will make the output led of output 3 flash during 30 seconds but will not change the output state.

  • Instruction example to give an output a name

output name write 3 Kitchen

In this example, output 3 will be named Kitchen

  • Instruction example to set the output type

output type write 21 0

This instruction will change the tested output type to “output” (0) or “light” (>0). It is important to set the output type correctly; this will avoid ventilators or heating valves to be switched off when for example the “all lights off basic action” is used. The standard output type for all outputs is “light”. In the above example, we will change the output type for output 21 to output.

  • To read the output type, use following instruction:

output type read 21

Execute following steps for every output:

  1. Switch ON output on and OFF output off to test the output
  2. Give the output a name output name write
  3. Set the correct output type if it's not a light output type write

Test Inputs/Switches

  • To see when an input is activated, put the system in Input Debug Mode

input debug on

When a switch is pressed, the console will indicate which switch is pressed and which output is linked. When output 0-239 is indicated, those outputs will be toggled when the switch is pressed. When output 240 is indicated, then the switch will perform ta special functions as indicated in the input page of this switch (see CLI Advanced Setup). When output 255 is indicated, no function is linked to this switch.

  • To switch off the input debug mode

input debug off

  • If an input needs to be found, following instruction can be used (in this example, we try to find input 22)

input indicate 22

The led of this input will flash during 30 seconds.

  • To give an input a name (Max 8 characters):

input name write 3 Kitch1

  • To write the inverted status of an input

input invert write 3 0

Standard switches used are NO (Normally Open), however, when NC switches are used, the switch type must be changed. Standard is the system configured for NO. The above example changes switch 3 to NC(1).

Execute following steps for every input when Input debug is enabled:

  1. Test every single switch and see if the input appears on the console
  2. Optionally, change the input inverted status
  3. Optionally, give the input a name

Link an Input with an Output

When an input (0-239) is linked to an output (0-239), the input will toggle (or dim) the output.

  • To link an input with an output

input link write 8 3

In the above example, input 8 is linked to output 3

  • To read the linked output:

input link read 8

Execute the following steps to link an input with an output:

  1. Activate the input debug mode by using input debug on
  2. Press the input you want to link and check which input number appears
  3. Link to input to the appropriate output
  4. Test the programmed switch by using it. When a switch is linked to a dimmer output, the dimmer function is automatically added to that switch (short press -> toggle on or off, long press -> dim up or down)

Configure a timer on an output

  • To program a timer (from 1 to 65534 seconds, tomer value = 0 -> No timer configured):

output timer write 3 240

In the above example, we've programmed a timer value of 4 minutes for output 3

  • To read the programmed timer value:

output timer read 3