PLCBUS.pm

NAME

PLCBUS - use the PLCBUS with misterhouse

DESCRIPTION

Enables the use of PLCBUS modules with misterhouse. To send/receive data from the bus a PLCBUS2-T 1141 device is required.

All testing was done with the USB variant but there should be no difference.

This module depends on a separate server process 'plcbussrv' to connect to the PLCBUS. You can get the tool from https://github.com/tobser/plcbussrv, see README.md for installation instructions. The server process is automatically started by this module

mh.private.ini

    plcbus_serial_port=/dev/plcbus
    plcbus_phase_mode=3
    plcbus_user_code=0xAB
    plcbus_command_file=/tmp/plcbuscommands
    plcbussrv_port=4567
    debug=plcbus:2|plcbus_module:2
    plcbus_logfile=1

plcbus_serial_port

Filename of your 1141

plcbus_phase_mode

Set to 1 or 3, default is 1

plcbus_user_code

The PLCBUS user code. All all modules including the 3-Phasecouple must be setup with the same user code otherwise they will not react to commands if not set the default of 0xff is used

plcbus_command_file

Can be used to execute arbitrary PLCBUS commands not available through the web interface. See SETTING UP A NEW PLCBUS MODULE on how to use it.

For a list of available commands take a look at %cmd_to_hex at the beginning of PLCBUS.pm

plcbussrv_port

TCP port to use for the plcbussrv server process. Default is '4567'

plcbus_logfile

if set to '1' a seperate logfile "$main::config_parms{data_dir}/logs/plcbus.log" with all plcbus logging is created. This may help to keep the global mh logfile clean while still being able to debug plcbus. All logmessages are written regardless of your 'debug=' setting.

if set to '0' or omitted, no logfile is created.

SAMPLE .MHT FILE

    Format = A
    # PLCBUS_TYPE,   address,  name,                groups                       default|scenes
    PLCBUS_Scene,    O2,       TestScene
    PLCBUS_2026G,    B2,       StandardLamp,        Property|livingroom(10;10),  O2:30@2|B2:100@0
    PLCBUS_2263DAU,  B4,       StaircaseLightning,  Property|staircase(5;20),    O2:70@4|B4:85@1
    PLCBUS_2026G,    B5,       TvLamp,              Property|livingroom(20;20),

CATEGORY PLCBUS

The module automatically creates the "PLCBUS"-Category which contains all PLCBUS voice commands.

VOICE COMMANDS

Voice commands for the user code and for all home address are created. Those are worded as found in the documentation for the serial interface of the 1141. This may and probably will change in future.

PLCBUS ITEMS

For now all devices can only go into on/off state You can use the Voice_Cmds of the PLCBUS Category execute specific PLCBUS commands e.g. 'status_req' to retrieve the current state of the module. 'status_req' will also change the on/off state of the module if an answer is received. Other commands such as to get the signal strength do not change the state of the item. You have to check the misterhouse log for the result of those commands.

There are 3 special voice command states '1_phase', '3-phase' and 'use_mh_ini_phase_mode' to use a specific phase mode for one unit. This command is stored per unit, and is also restored between misterhouse restarts. But won't survive a reboot. Another way to permanently override the phase setting is to add the item either to the group onephase or threephase to override the mh.ini setting 'use_mh_ini_phase_mode' deletes the setting and the phase mode specified in mh.ini is used. Phase to use is determined in the following order: * use value set from voice command * if not set check if its part of a phase specific group * the the mh ini setting is used * if mh.ini setting is not set the default 1 Phase is used

SETTING UP A NEW PLCBUS MODULE

You may want to enable full debug output in for PLCBUS in your private mh.ini file to see what's actually going on:

    debug=plcbus:2|plcbus_module:2

Let's say we purchased a new PLCBUS_2026G plug in module. First we need to decide for an address for our new module, e.g. C7 and create a new entry in our mht file:

    PLCBUS_2026G,    C7,       newTestLamp, PLCBUS_C

Now reload or restart misterhouse. Misterhouse should now create the new device and start the plcbussrv server, which you should have installed already. If not see the DESCRIPTION for a link.

If all went as expected you should find your new device in the PLCBUS_C group:

http://misterhouse/ia7/#path=/objects&parents=PLCBUS_C&_collection_key=0,1,17,$PLCBUS_C

Now we have to tell the module about its new address. All modules I used so far are brought into setup mode by pressing the setup button for 5s. The LED starts blinking as soon as the module changes into setup mode. The 3-Phasecoupler is an exception, its LED turns of as soon as it changed to setup mode.

As soon as the LED start to blink you have to send a 'on' command to the module. Either by changing its state via the web interface to 'on' or by using the PCLBUS command file (see mh.private.ini setting)

    echo c,7,on > /tmp/plcbuscommands

If the module stops blinking and the attached light turns off, the module now knows its own address and should react to your commands. To change the brightness level and fade rate try the following command

    echo c,7,presetdim,60,7 > /tmp/plcbuscommands

For less information on available commands see the documentation for the 1141 RS-232 Interface. You can get it in the download section of the PLCBUS forum http://www.plc-bus.info/downloads.php?cat=2 (you need to be logged in)

Now start playing with your new toys. But not too much, cause your 1141 and/or your phase couple may get annoyed :-(

SCENE DEFINITION

All modules that shall belong to a scene address have to be turned on and be in their desired brightness state. All others have to be in off state, otherwise they will belong to your new scene.

To setup a new scene, add a PLCBUS_Scene item to your mht file and configure your pclbus devices to be a part of the the scene. A scene member definition consists of the scene address, the brightness level and faderate for the scene. The format is 'SceneAddress:Brightness@Faderate', multiple sceneadresses are seperated with '|'. If a scene definition contains the address of the item itself, this is used as the default setting for the item.

    Format = A
    # PLCBUS_TYPE,   address,  name,                groups                       default|scenes
    PLCBUS_Scene,    O2,       TestScene
    PLCBUS_2026G,    B2,       StandardLamp,        Property|livingroom(10;10),  O2:30@2|B2:100@0
    PLCBUS_2263DAU,  B4,       StaircaseLightning,  Property|staircase(5;20),    O2:70@4|B4:85@1

StandardLamp TestScene O2 with a brightnesslevel of 30 and a faderate of 2s. Its defaulte setting is 100% brightness, no fade.

SETTING UP A SCENE

To program a scene all the members of the scene have to be in the desired state. Scene items provide you with the needed commands to achieve this.

Before you start make sure there is nothing changing the states of your lights.

Program Scene

To program the scene you have to set the following states on the scene object

1. prepare_program: this tries to turn every plcbus item off; then sends presetdim command to all members of the scene. You have to wait for all lights to complete the configured brightness
2. program: this command sends the actual scene address to all devices in 'on' state. The lights will blink if the where not already member of the scene
3. set_members_default: This will send presetdim with the default levels to all members of a scene, otherwise the next 'on' command will use the levels of the programed scene.

Delete Scene

1. prepare_delete:: turns all off; then sends scene 'on' command; wait for all members to turn on
2. delete: deletes the scene address from the modules; Lights will blink if the receive the delete command.

If a scene is turned on, all members will enter the 'on' state. If any of the scene members is turned off, the scene will also change to 'off'.

AUTHOR

Tobias Sachs diespambox@gmx.net

PLCBUS.pm