LinuxMCE - User contributions [en]

ZME 06443

2012-04-21T15:03:52Z

Mhorst: Created page with "Category: Hardware {{versioninfo|810Status=According to category, Works without caveats|810UpdatedDate=21st April 2012|810UpdatedBy=mhorst|}} [[Category: Auto..."

[[Category: Hardware]]
{{versioninfo|810Status=According to category, Works without caveats|810UpdatedDate=21st April 2012|810UpdatedBy=[[User:mhorst|mhorst]]|}}
[[Category: Automation]]
[[Category: RF Control]]
[[Category: ZWave]]
[[Category: ZWave_switch]]
[[Category: Works without caveats on 0810]]

[[Image:duwi_zw_ws_05443.jpg|right]]

= Z-Wave wall-mounted switch transmitter, battery powered =

== Info ==
This is exactly the same hardware as the [[Düwi_Popp_ZW_WS_05443]] Z-Wave switch, but with new firmware developed by Z-Wave.Me.

The firmware has many additional features compared to the original Düwi firmware. Most importantly, for LinuxMCE, is that LinuxMCE can receive events from this controller, even when the controller is not associated with any device.

== Installation Notes / Experience ==
The user manual for the switch says I have to hold the Inclusion button for two seconds to add the switch to the existing network. This worked, in combination with pressing the button on the [[Aeon_Labs_Z-Wave_Interface]] in my core. However, I only received events after I also had presse the button on the Aeon Labs stick and pressed the controller three times.

Association of devices to this controller can be performed via the LinuxMCE web-admin panel. However, I had to press the controller's button three times before the new configuration from LinuxMCE became active on the switch itself.

== Links ==
* [http://en.z-wave.me/content/wall-controller]

Düwi Popp ZW WS 05443

2012-04-21T14:51:49Z

Mhorst:

[[Category: Hardware]]
{{versioninfo|710Status=According to category, Works without caveats|710UpdatedDate=26th July 2010|710UpdatedBy=[[User:Valent|Valent]]|810Status=According to category, Works without caveats|810UpdatedDate=26th July 2010|810UpdatedBy=[[User:Valent|Valent]]|}}
[[Category: Automation]]
[[Category: RF Control]]
[[Category: ZWave]]
[[Category: ZWave_switch]]
[[Category: Works without caveats on 0710]]
[[Category: Works without caveats on 0810]]

[[Image:duwi_zw_ws_05443.jpg|right]]

= Z-Wave wall-mounted switch transmitter, battery powered =

== Info ==
Düwi ZW WS 05443 Z-Wave switch that can be placed anywhere.
For wireless switching, resp. control of: all Z-Wave wireless switch inserts and wireless intermediate plugs, existing installations can also be expanded without flush-mounted power point, high flexibility with installation due to extremely flat design, to stick or screw on to various substrates, for installation in existing switch box or clipping-in in multiple combinations.
Voltage supply: 2 x 1.5 V battery (LR8 D425),
Range: up to 100 m free field, Range multiplies through the protected Z-Wave Routing System

Note:
LinuxMCE does not receive events from this controller directly, it can only detect that the controller is pressed by inspecting the state of the device that the controller is associated with.
See also [[ZME_06443]]

== Links ==
* [http://www.duewi.de/download.php?bid=5860&lid=4 Manual (German)]
* [http://pepper1.net/zwavedb/uploads/resources/c47dc5e2d0b4e8bbdfd813398373b833c4db3f4a.pdf Manual (English)]
* [http://www.duewi.de/index.php?productid=37276 Düwi Product page]
* [http://www.duewi.de/download.php?bid=5863&lid=4 Quickstart]

== Where to buy ==
* [http://www.home4u-store.com/interact%C2%B3-funk-wandsender-d%C3%BCwi-05443-p-4567.html Home4U Store - 33€]
* [http://p5.hu/hu/termekek/reszletek/57_popp_z-wave_fali_ado/ P5.hu - 63€ (50€ + 25%)]

Düwi ZW ESJ 05436

2011-04-12T17:17:07Z

Mhorst: /* Links */ Added a link to an english version of the manual

[[Category: Hardware]]
{{versioninfo|710Status=According to category, Works without caveats|710UpdatedDate=26th July 2010|710UpdatedBy=[[User:Valent|Valent]]|810Status=According to category, Works without caveats|810UpdatedDate=26th July 2010|810UpdatedBy=[[User:Valent|Valent]]|}}
[[Category: Automation]]
[[Category: RF Control]]
[[Category: ZWave]]
[[Category: ZWave_wallplug]]
[[Category: Works without caveats on 0710]]
[[Category: Works without caveats on 0810]]

[[Image:duwi_zw_esj_05436.jpg|right]]

= Düwi ZWave Sun Window Blind Insert =

== Info ==
'''Düwi ZW ESJ 05436 Z-Wave has dual function:'''

;Switch/Dimmer:
Serves for the switching or dimming of connected lights either via radio signals or directly over clipped-on radio-rockers.

;Sun blind control:
The Düwi wireless insert of sun blind is for the wireless opening and closing of window blinds, shutters,sun blinds and electronic gates. The wireless sun blind automatically turns off the contact after about 2 minutes (value set at delivery) in order to protect the motor

;Technical specifications:
* Switching capacity
** ohmic 1800W
** 460VA (motors + luminescent lamps)
** 500W incandescent bulbs
* Operating voltage: 230 V~, 50 Hz
* Switching time: 2 minutes (time period is factory set)
* Micro fuse: T 8 A H
* Standby : < 1 W

== Links ==
* [ftp://ftp.zwaveeurope.com/pub/man/en/DUW/DUW_064367_in_en.pdf Installation manual]
* [http://www.duewi.de/index.php?productid=37344 Product page]
* [http://www.duewi.de/download.php?bid=5856&lid=4 Manual]
* [http://www.pepper1.net/zwavedb/uploads/resources/dec54c7d90379524e6ae65cff6cd9c8c50739893.pdf Manual (English)]
* [http://www.duewi.de/download.php?bid=5863&lid=4 Quickstart]

== Where to buy ==
* [http://www.home4u-store.com/interact%C2%B3-funk-einsatz-jalousie-aktor-jalousie-d%C3%BCwi-05436-p-4566.html Home4U Store - 45€]
* [http://www.zwave4u.com/products/en/Window-Control/Duwi-Z-Wave-Window-Blind-Insert.html ZWave4U - 58€]
* [http://p5.hu/hu/termekek/reszletek/55_popp_fali_redonyvezerlo_betet/ P5.hu - 74€ (59€ + 25%)]

Düwi Popp ZW WS 05443

2011-04-03T11:43:52Z

Mhorst: /* Links */

[[Category: Hardware]]
{{versioninfo|710Status=According to category, Works without caveats|710UpdatedDate=26th July 2010|710UpdatedBy=[[User:Valent|Valent]]|810Status=According to category, Works without caveats|810UpdatedDate=26th July 2010|810UpdatedBy=[[User:Valent|Valent]]|}}
[[Category: Automation]]
[[Category: RF Control]]
[[Category: ZWave]]
[[Category: ZWave_switch]]
[[Category: Works without caveats on 0710]]
[[Category: Works without caveats on 0810]]

[[Image:duwi_zw_ws_05443.jpg|right]]

= Z-Wave wall-mounted switch transmitter, battery powered =

== Info ==
Düwi ZW WS 05443 Z-Wave switch that can be placed anywhere.
For wireless switching, resp. control of: all Z-Wave wireless switch inserts and wireless intermediate plugs, existing installations can also be expanded without flush-mounted power point, high flexibility with installation due to extremely flat design, to stick or screw on to various substrates, for installation in existing switch box or clipping-in in multiple combinations.
Voltage supply: 2 x 1.5 V battery (LR8 D425),
Range: up to 100 m free field, Range multiplies through the protected Z-Wave Routing System

== Links ==
* [http://www.duewi.de/download.php?bid=5860&lid=4 Manual (German)]
* [http://pepper1.net/zwavedb/uploads/resources/c47dc5e2d0b4e8bbdfd813398373b833c4db3f4a.pdf Manual (English)]
* [http://www.duewi.de/index.php?productid=37276 Düwi Product page]
* [http://www.duewi.de/download.php?bid=5863&lid=4 Quickstart]

== Where to buy ==
* [http://www.home4u-store.com/interact%C2%B3-funk-wandsender-d%C3%BCwi-05443-p-4567.html Home4U Store - 33€]
* [http://p5.hu/hu/termekek/reszletek/57_popp_z-wave_fali_ado/ P5.hu - 63€ (50€ + 25%)]

Bluetooth Dongle

2011-03-27T11:01:15Z

Mhorst: /* Turning off automatic discovery */

[[Category: Hardware]]
{{Versioninfo}}
[[Category: Tutorials| ]]
[[Category: Bluetooth]]

==What is the purpose?==
If you have Bluetooth in the computer that you will use as a LinuxMCE Media Director, this device [http://wiki.linuxmce.org/index.php/Control_LinuxMCE_using_a_Symbian_Series_60_mobile_phone_with_Bl turns your mobile phone into a remote control] and gives you "follow-me" capabilities--your lighting preferences, media and more can follow you around the house.

==Requirements and Compatibility==
Runs on both Linux, using the Bluez library, and Windows, using the standard Windows/Widcom drivers. Although it should work with all Bluetooth devices, we always use USB Bluetooth dongles with the CSR chipset for both Windows and Linux. The D-Link DBT-120 and TDK are some of the more common models.

==Turning off automatic discovery==
To prevent LinuxMCE from finding bluetooth devices outside of your home the autodetection (of any BT device) can be turned off as followed: [http://forum.linuxmce.org/index.php?topic=3139.msg16493#msg16493]
# Login in Web Admin
# Go to Advanced -> Configuration -> Devices
# Open the CORE
# Open DCERouter and click on Orbiter Plugin
# Check the Ignore check box under "Device data".

Turn it back on again to autodetect new devices you're adding to the network, after which you can turn it off again once they're added.

==Things to Consider When Purchasing an Adapter==
 - A single Class 1 adapter (range 100m, 330 ft) will provide Bluetooth service to your whole house. With this setup, the system will not be able to detect which room you are in (ie: no follow-me functionality), but it will be able to detect when you arrive home. This adapter is best placed on the Core for always-on functionality.

 - A Class 2 adapter (range 10m, 33 ft) is good for Media Directors that are quite far apart (ie: on opposite sides of a large house). If the Bluetooth ranges don't overlap, then the system will be able to distinguish your location by room. If the Bluetooth ranges do overlap, the system may hop you back & forth between rooms rapidly.

 - A Class 3 adapter (range 1m, 3 ft) can be used for a setup with multiple Media Directors that are too close to use Class 2 adapters. The downside is that you must be fairly close to the Media Director to be detected. You might consider using a USB extension cord to move this adapter towards the middle of the room for better detection. A USB extension cord is also useful if two Media Directors are too close to each other (ie: opposite sides of an adjoining wall). Having said all of that, Class 3 adapters are not common for the simple reason that their range makes them practically useless except for true PANs, which is not an LinuxMCE use-case. While it is true that many devices can achieve 3m, many will only achieve the specified 1m, especially with local environment considerations, and this renders it useless for LinuxMCE.[http://forum.linuxmce.org/index.php?topic=8175.msg54219#msg54219]

 - Remember, Bluetooth is two-way communication, so the effective range will be the shorter of the two devices that are communicating. If you put Class 2 adapters on all of your Media Directors, but your Orbiter has a Class 3 adapter, then you will be limited to the Class 3 range.

How to add your own GSD device

2010-04-11T17:31:29Z

Mhorst:

[[Category: Programmer's Guide]]
[[Category: Serial]]
[[Category: Tutorials]]
[[Category: GSD]]

Generic_Serial_Device (also known as [[GSD]]) is a LinuxMCE device that allows an end-user to do simple programming for RS232, serial USB or network connected devices.
This enables them to quickly and easily write drivers for such devices.

Note, however, that a GSD device driver is more limited than a compiled driver. The GSD driver allows only a single communication channel with the device (RS232, serial USB or a TCP connection across a network).
If your device has other communication channels (an UDP connection for example), you will have to write a driver in another language and compile it.

== How to add your own GSD device ==

=== Examples ===

For those of you who like to learn by example, there are some already in the LinuxMCE database.
In the LinuxMCE web admin interface go to Advanced-->Configuration-->Device Templates and pick one of the following device templates:
* Panasonic IP camera: A simple driver that enables the retrieval of video frames from this network enabled camera
* Proliphix NT series thermostat: A more elaborate driver for a network enabled thermostat. This driver also sends events to the LMCE system in case, for example, the ambient temperature changes.

=== Creating a new GSD device ===

The steps to add GSD device are following:

==== Install the necessary packages ====
Be sure that you have installed GSD package -
<pre>dpkg -l 'pluto-generic-serial-device'</pre>
(it should be there).

==== Create a device template ====
Created a device template for your system and specify that it should use GSD. The [[Edit_Device_Template]] page may be of help here.

Some things you should take into account:
* Add your template under the proper category; add it under category lighting interfaces if you want to control lighting devices only. To control all kind of devices (security, climate etc) it's better to use Interface::Specialize.
* Specify a communication type - RS232, Ethernet etc. and do not forget to specify the way to connect to the device, i.e.:
** For an Ethernet device, add the TCP Port (#69) to the device data.
* Specify that your device is controlled via category "Device Category:Core" ("Computers - Core"). Otherwise the driver will not be started on the core.

Furthermore you should add the commands implemented by your device, and the events it can generate. If possible, try to fill in the Plug & Play section to ensure that your device will be automatically detected.
Also, fill in the comment fields provide others with information about your device template.

==== Adding the device ====
If you have added Plug & Play information to your device template, a quick reload of the router, followed by the connection of your device will result in the device being detected and added automatically.

If auto-detection is not possible, however, you will have to add your device manually.
This is done on the GSD page: Wizard --> Devices --> Generic Serial Devices.

After installing the device, and a quick reload of your router you should see GSD process in the console:
<code>ps -elf|grep Generic_Serial_Device</code>

<pre>5 S root 10085 1 0 76 0 - 683 - Jul17 ? 00:00:00 SCREEN -d -m -S LinCon_8000-30 /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
5 S root 10086 10085 0 75 0 - 646 wait Jul17 pts/8 00:00:00 /bin/bash /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
0 S root 31800 10086 0 79 0 - 123146 295621 Jul17 pts/8 00:00:00 ./Generic_Serial_Device -d 30 -r localhost -l /var/log/pluto/30_Generic_Serial_Device.log
</pre>

This tells you that a Generic_Serial_Device driver is running. The line containing "./Generic_Serial_Device" shows you the process is running and that this instance of the driver has been given device id 30, and that the logging will be written to the file "/var/log/pluto/30_Generic_Serial_Device.log". In this log you can find all Ruby errors, connection status and other useful information.

==== Adding the Ruby code ====
From the Device Template page and from the GSD page you can edit the Ruby codes for your device. There you can write the actual code for the methods implemented by your device.

You should implement the commands you selected for your device, and you should also implement the "Ruby Internal Commands". These commands consist of the following 6 functions:
;Private Method Listing:
: This is not really a function in itself, but rather a section in your Ruby script where you may define common functions that are used in the rest of your driver. A good example would be a function to write a line to the device's log file:
<pre>
def log(line)
# This function logs a line to the log file of the device
log = File.open("/var/log/pluto/" + device_.devid_.to_s + "_Generic_Serial_Device.log", "a")
log.puts Time.now.to_s + " (Ruby script):" + line.to_s
log.close
end
</pre>

;Process IDLE: This function is executed each one - two seconds. It may be useful to check for a connection between your device and LinuxMCE, or to poll your device for updates.
:See the Proliphix NT series thermostat driver for an example of polling, where the time between polls is reduced to once every 5 minutes, instead of once every few seconds.

;Process Incoming Data: This function is called when some data comes from your device:
<pre>recv = conn_.Recv(100,500);</pre>
:recv contains now the data received from the physical device (say some switch is OFF). You can parse it to update a status of that switch in LinuxMCE:
<pre>cmd = Command.new(device_.devid_, -1001, 1, 2, 48)
cmd.params_[10] = 0
SendCommand(cmd)</pre>

;Process Receive Command For Child: if your device is a parent device for some other devices, this function is called when a command is send to one of the child devices.
:This function should therefore forward the command to it's children. For example, a GSD device that controls dimmer or switches might receive a some command like: ON, OFF or SET LEVEL for one of it's children. It should then send these commands in the desired format to the physical device:
<pre>
cmdId = cmd.id_ # Command ID: ON, OFF, SET LEVEL
cmdTo = cmd.devidto_ # Device ID in LinuxMCE
devPort = device_.childdevices_[cmdTo].devdata_[12] # 12 contains a port/channel
childType = device_.childdevices_[cmdTo].devtemplid_ # Template ID to know type of device: switch or dimmer

case cmdId
when 192 #192 is ON
command = '<your ON command format>'
when 193 #193 is OFF
command = '<your OFF command format>'
when 184 #184 is Level of dimmer
command = '<your SET LEVEL command format>'
end

conn_.Send(command)
</pre>
: In this example the command includes following parameters: cmdTo - the LinuxMCE ID of the child device - to update the status in LinuxMCE, devPort - Port Number - to know where send actual command, cmdId - command type - ON, OFF, SET LEVEL, level value for SET LEVEL. It might be good idea to push unsuccessful commands into array in the GSD device to run them once again.

:NOTE: From trial and error, I have come to the assumption that ON/OFF and SETLEVEL, internally, have seperate values. Be careful as you can have a device that is OFF with a setlevel of 100%. This results in a pretty UGLY message when to attempt the following: Use cmd[184]=100 to turn a device ON. (but don't actually send a cmd[192].. when you attempt to turn the device OFF, you'll get an ugly message in the GSD device saying that the 'CMD[193] won't be processed because it is useless'. (I'm paraphrasing.. you get the idea...) What makes this worse, is when you use an orbiter to turn a device on, it will send you a cmd[184], not a cmd[192]. You will need to watch for this and send a cmd[192] as needed.

:NOTE FOR ABOVE: I have found a way to force the command through. a bit of history first:
The reason we get the infamous 'won't be processed because it is useless' is because DCE has to deal with NON Discrete codes.
for instance: a device that has a power toggle. IF we turn it on, it turns on.
Now, if we turn it ON again, DCE thinks it's on and because it's a toggle, it won't send the command. That is why we get this message.
I dug pretty deep to find this next piece: params[120]=1
this parameter, when set inside a command, will FORCE DCERouter to send the command regardless of what it thinks the state is.
Hope this helps other GSD programmers. DDamron

;Process Initialize: This function is called when GSD device is starting. It's good point to initialize common variables. It is also a good place get the actual status of your device and notify LinuxMCE of it, since the state might have changed while the GSD driver was down.

;Process Release: This function is called when the GSD device is closing.

Note: LinuxMCE caches your Ruby code, so you should do a quick reload of your router each time when you modify your Ruby code!

=== Other Ruby code examples ===

==== Sending an event ====

To send an event to the LinuxMCE system you can use the following snippet:
<pre>
cmd = Command.new(device_.devid_, -1001, 1, 2, 25)
cmd.params_[30] = 20
SendCommand(cmd)
</pre>

This will send the command from your device (device_.devid_) to the LinuxMCE event handler (-1001), identifying it as a priority 1 message, of the event type (2).
Furthermore the event has id 25, which means it's a "Temperature Changed" event (the device template page shows the ids of the events you have added to the device).

Additional parameters of the event can be set by using the cmd.params_ mapping. The device template page has an edit button for each event that enables you to see the parameters associated with that event, including a description of its use.
In our example it shows that the parameter with index 30 is the current ambient temperature in degrees Celcius.

After the cmd object has been initialized it is send to the LinuxMCE system using the SendCommand function.

Note that the same piece of code can be used to send commands instead of events. The only changes are that the message type will be 1 (command) instead of 2 (event), and that the destination will probably differ from the event handler device -1001.

== Troubleshooting ==

This section contains some tips on troubleshooting your new driver.

=== Viewing the logs ===

The best way to test the new GSD device is to edit the file /etc/pluto.conf and comment out the LogLevels filter, so the logging is verbose. You can do this by typing:

vim /etc/pluto.conf

Then move to the start of the line that starts with LogLevels, press 'i' for Insert mode in vim, type a # character, then press [ESC]:wq
The # at the start of a line means it's commented out, or ignored.

now do a reload router. You can do this from the console with: /usr/pluto/bin/MessageSend dcerouter 0 -1000 7 1

Then go to the log directory:

cd /var/log/pluto

ls

ls will list the contents of the directory: There will be a log file that starts with the device number of the gsd device. To follow it type:

tail -f [filename]

rather than typing in the full filename, you can just type the first letters (ie the device number) and press tab, which does an auto complete.

Now send commands to the device. You can do this through the web site or the console. For example, assuming your GSD device has the device id 57, you can send it an ON command (ON is command #192), you could type: /usr/pluto/bin/MessageSend dcerouter 0 57 1 192

The log will show a bunch of data. The lines that start with 40 and 41 are the serial data that is being sent to/from the device. To filter the tail so it only shows the serial data, type:

tail -f [filename] | grep '^40\|^41'

=== Getting the device to start ===
If your device will not start (anymore) as described in section [[How to add your own GSD device#Adding the device]] there can be several causes.

Check that your device is controlled by the core, as described in [[How to add your own GSD device#Create a device template]]. Otherwise the core assumes another device will start the driver.

If your Ruby code contains an error, LinuxMCE may decide to disable the device. So, check that your device is not disabled: on Wizard-->Devices-->Generic Serial Devices click on "Advanced" for your device and make sure the Disabled box is NOT ticked. If it is, untick it, save, and do a quick reload of the router.

Sometimes a quick reload of the router does not suffice. In that case you can run:
<pre>
/usr/pluto/bin/Start_LocalDevices.sh
</pre>
This should start your device. If not, the output of that script is a good place to look for further clues.

== Sharing your driver ==

Once your driver is working properly, you can share it with the rest of the LinuxMCE community.
The procedure for this is as follows:
* Do an sqlCVS update from the web-admin to ensure that your database is up-to-date (Advanced --> sqlCVS --> Update, select all sections)
* Create a Trac ticked describing your device (http://svn.linuxmce.org)
* Do a check-in of your changes: Use the sqlCVS diff function (Advanced --> sqlCVS --> Diff) to determine the updates to the "dce" and "ir" sections of your database and check them in anonymously. The comment of your check-in should mention the Trac ticket number.
* The developers will verify this and check the driver into the database

== See also ==

<ul>
<li>[[GSD Ruby Interface]]</li>
<li>[[GSD - Ruby codes ]]</li>
<li>[[Generic Serial Device]]</li>
</ul>

Proliphix NT series thermostat

2010-04-11T17:23:54Z

Mhorst: /* Status */ Update status

[[Category: Climate]]

[[Image:Proliphix_nt20e_network_thermostat.jpg|thumb|200px|Proliphix NT20e network thermostat]]

= Overview =

The Proliphix thermostats are IP enabled thermostats with a built in web-server, enabling easy configuration from a standard webbrowser.

The thermostat does not contain batteries. It obtains it's power via Power-over-Ethernet or from the HVAC system itself. The model numbers ending in "h" obtain their power from the HVAC system, while the model numbers ending in "e" obtain their power from the ethernet.
Note that the lower numbered thermostats only support a propietary PoE standard, whereas the higher numbered models also support the IEEE 802.3af standard.

= Status =

A driver has been developed based on the Proliphix Device Protocol Revision 1.11. (See http://forum.linuxmce.org/index.php?topic=9538.0)
This driver has been tested with the following models:
* Proliphix NT-100e

The driver implements the standard LinuxMCE thermostat commands. Which means that from LinuxMCE the following commands can be executed:
* The thermostat's mode can be changed (Off, Heating only, Cooling only, Automatic)
* The fan mode can be changed (Auto or Always On)
* The temperature set-point can be changed

Furthermore the driver reports the standard LinuxMCE thermostat status messages to the system. This means LinuxMCE is aware of the following:
* The thermostat's mode
* The fan mode
* The current heating set-point
* The current ambient temperature (this is the average temperature for models with multiple sensors, reading individual sensor is not supported)

The only additional feature of the driver is that it synchronizes the thermostat's time with the LinuxMCE system time. This way the clock will never be out of sync for more than 10 minutes, and the thermostat will not have to be manually updated when switching to (or from) Daylights Savings Time.

Of course the thermostat's administration page can still be accessed normally to update the schedule and other settings.

NOTE: The driver is in the process of being committed to the LinuxMCE repository, see Trac Ticket #671 (http://svn.linuxmce.org/trac.cgi/ticket/671)

= Links =
* Manufacturer: http://www.proliphix.com/
* Proliphix Device Protocol specification: http://rtc.rubyforge.org/svn/trunk/docs/PDP_API_R1_11.pdf

How to add your own GSD device

2010-04-11T14:55:21Z

Mhorst: /* Sending an event */

[[Category: Programmer's Guide]]
[[Category: Serial]]
[[Category: Tutorials]]
[[Category: GSD]]

Generic_Serial_Device (also known as [[GSD]]) is a LinuxMCE device that allows an end-user to do simple programming for RS232, serial USB or network connected devices.
This enables them to quickly and easily write drivers for such devices.

Note, however, that a GSD device driver is more limited than a compiled driver. The GSD driver allows only a single communication channel with the device (RS232, serial USB or a TCP connection across a network).
If your device has other communication channels (an UDP connection for example), you will have to write a driver in another language and compile it.

== How to add your own GSD device ==

=== Examples ===

For those of you who like to learn by example, there are some already in the LinuxMCE database.
In the LinuxMCE web admin interface go to Advanced-->Configuration-->Device Templates and pick one of the following device templates:
* Panasonic IP camera: A simple driver that enables the retrieval of video frames from this network enabled camera
* Proliphix NT series thermostat: A more elaborate driver for a network enabled thermostat. This driver also sends events to the LMCE system in case, for example, the ambient temperature changes.

=== Creating a new GSD device ===

The steps to add GSD device are following:

==== Install the necessary packages ====
Be sure that you have installed GSD package -
<pre>dpkg -l 'pluto-generic-serial-device'</pre>
(it should be there).

==== Create a device template ====
Created a device template for your system and specify that it should use GSD. The [[Edit_Device_Template]] page may be of help here.

Some things you should take into account:
* Add your template under the proper category; add it under category lighting interfaces if you want to control lighting devices only. To control all kind of devices (security, climate etc) it's better to use Interface::Specialize.
* Specify a communication type - RS232, Ethernet etc. and do not forget to specify the way to connect to the device, i.e.:
** For an Ethernet device, add the TCP Port (#69) to the device data.
* Specify that your device is controlled via category "Device Category:Core" ("Computers - Core"). Otherwise the driver will not be started on the core.

Furthermore you should add the commands implemented by your device, and the events it can generate. If possible, try to fill in the Plug & Play section to ensure that your device will be automatically detected.
Also, fill in the comment fields provide others with information about your device template.

==== Adding the device ====
If you have added Plug & Play information to your device template, a quick reload of the router, followed by the connection of your device will result in the device being detected and added automatically.

If auto-detection is not possible, however, you will have to add your device manually.
This is done on the GSD page: Wizard --> Devices --> Generic Serial Devices.

After installing the device, and a quick reload of your router you should see GSD process in the console:
<code>ps -elf|grep Generic_Serial_Device</code>

<pre>5 S root 10085 1 0 76 0 - 683 - Jul17 ? 00:00:00 SCREEN -d -m -S LinCon_8000-30 /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
5 S root 10086 10085 0 75 0 - 646 wait Jul17 pts/8 00:00:00 /bin/bash /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
0 S root 31800 10086 0 79 0 - 123146 295621 Jul17 pts/8 00:00:00 ./Generic_Serial_Device -d 30 -r localhost -l /var/log/pluto/30_Generic_Serial_Device.log
</pre>

This tells you that a Generic_Serial_Device driver is running. The line containing "./Generic_Serial_Device" shows you the process is running and that this instance of the driver has been given device id 30, and that the logging will be written to the file "/var/log/pluto/30_Generic_Serial_Device.log". In this log you can find all Ruby errors, connection status and other useful information.

==== Adding the Ruby code ====
From the Device Template page and from the GSD page you can edit the Ruby codes for your device. There you can write the actual code for the methods implemented by your device.

You should implement the commands you selected for your device, and you should also implement the "Ruby Internal Commands". These commands consist of the following 6 functions:
;Private Method Listing:
: This is not really a function in itself, but rather a section in your Ruby script where you may define common functions that are used in the rest of your driver. A good example would be a function to write a line to the device's log file:
<pre>
def log(line)
# This function logs a line to the log file of the device
log = File.open("/var/log/pluto/" + device_.devid_.to_s + "_Generic_Serial_Device.log", "a")
log.puts Time.now.to_s + " (Ruby script):" + line.to_s
log.close
end
</pre>

;Process IDLE: This function is executed each one - two seconds. It may be useful to check for a connection between your device and LinuxMCE, or to poll your device for updates.
:See the Proliphix NT series thermostat driver for an example of polling, where the time between polls is reduced to once every 5 minutes, instead of once every few seconds.

;Process Incoming Data: This function is called when some data comes from your device:
<pre>recv = conn_.Recv(100,500);</pre>
:recv contains now the data received from the physical device (say some switch is OFF). You can parse it to update a status of that switch in LinuxMCE:
<pre>cmd = Command.new(device_.devid_, -1001, 1, 2, 48)
cmd.params_[10] = 0
SendCommand(cmd)</pre>

;Process Receive Command For Child: if your device is a parent device for some other devices, this function is called when a command is send to one of the child devices.
:This function should therefore forward the command to it's children. For example, a GSD device that controls dimmer or switches might receive a some command like: ON, OFF or SET LEVEL for one of it's children. It should then send these commands in the desired format to the physical device:
<pre>
cmdId = cmd.id_ # Command ID: ON, OFF, SET LEVEL
cmdTo = cmd.devidto_ # Device ID in LinuxMCE
devPort = device_.childdevices_[cmdTo].devdata_[12] # 12 contains a port/channel
childType = device_.childdevices_[cmdTo].devtemplid_ # Template ID to know type of device: switch or dimmer

case cmdId
when 192 #192 is ON
command = '<your ON command format>'
when 193 #193 is OFF
command = '<your OFF command format>'
when 184 #184 is Level of dimmer
command = '<your SET LEVEL command format>'
end

conn_.Send(command)
</pre>
: In this example the command includes following parameters: cmdTo - the LinuxMCE ID of the child device - to update the status in LinuxMCE, devPort - Port Number - to know where send actual command, cmdId - command type - ON, OFF, SET LEVEL, level value for SET LEVEL. It might be good idea to push unsuccessful commands into array in the GSD device to run them once again.

:NOTE: From trial and error, I have come to the assumption that ON/OFF and SETLEVEL, internally, have seperate values. Be careful as you can have a device that is OFF with a setlevel of 100%. This results in a pretty UGLY message when to attempt the following: Use cmd[184]=100 to turn a device ON. (but don't actually send a cmd[192].. when you attempt to turn the device OFF, you'll get an ugly message in the GSD device saying that the 'CMD[193] won't be processed because it is useless'. (I'm paraphrasing.. you get the idea...) What makes this worse, is when you use an orbiter to turn a device on, it will send you a cmd[184], not a cmd[192]. You will need to watch for this and send a cmd[192] as needed.

:NOTE FOR ABOVE: I have found a way to force the command through. a bit of history first:
The reason we get the infamous 'won't be processed because it is useless' is because DCE has to deal with NON Discrete codes.
for instance: a device that has a power toggle. IF we turn it on, it turns on.
Now, if we turn it ON again, DCE thinks it's on and because it's a toggle, it won't send the command. That is why we get this message.
I dug pretty deep to find this next piece: params[120]=1
this parameter, when set inside a command, will FORCE DCERouter to send the command regardless of what it thinks the state is.
Hope this helps other GSD programmers. DDamron

;Process Initialize: This function is called when GSD device is starting. It's good point to initialize common variables. It is also a good place get the actual status of your device and notify LinuxMCE of it, since the state might have changed while the GSD driver was down.

;Process Release: This function is called when the GSD device is closing.

Note: LinuxMCE caches your Ruby code, so you should do a quick reload of your router each time when you modify your Ruby code!

=== Other Ruby code examples ===

==== Sending an event ====

To send an event to the LinuxMCE system you can use the following snippet:
<pre>
cmd = Command.new(device_.devid_, -1001, 1, 2, 25)
cmd.params_[30] = 20
SendCommand(cmd)
</pre>

This will send the command from your device (device_.devid_) to the LinuxMCE event handler (-1001), identifying it as a priority 1 message, of the event type (2).
Furthermore the event has id 25, which means it's a "Temperature Changed" event (the device template page shows the ids of the events you have added to the device).

Additional parameters of the event can be set by using the cmd.params_ mapping. The device template page has an edit button for each event that enables you to see the parameters associated with that event, including a description of its use.
In our example it shows that the parameter with index 30 is the current ambient temperature in degrees Celcius.

After the cmd object has been initialized it is send to the LinuxMCE system using the SendCommand function.

Note that the same piece of code can be used to send commands instead of events. The only changes are that the message type will be 1 (command) instead of 2 (event), and that the destination will probably differ from the event handler device -1001.

== Troubleshooting ==

This section contains some tips on troubleshooting your new driver.

=== Viewing the logs ===

The best way to test the new GSD device is to edit the file /etc/pluto.conf and comment out the LogLevels filter, so the logging is verbose. You can do this by typing:

vim /etc/pluto.conf

Then move to the start of the line that starts with LogLevels, press 'i' for Insert mode in vim, type a # character, then press [ESC]:wq
The # at the start of a line means it's commented out, or ignored.

now do a reload router. You can do this from the console with: /usr/pluto/bin/MessageSend dcerouter 0 -1000 7 1

Then go to the log directory:

cd /var/log/pluto

ls

ls will list the contents of the directory: There will be a log file that starts with the device number of the gsd device. To follow it type:

tail -f [filename]

rather than typing in the full filename, you can just type the first letters (ie the device number) and press tab, which does an auto complete.

Now send commands to the device. You can do this through the web site or the console. For example, assuming your GSD device has the device id 57, you can send it an ON command (ON is command #192), you could type: /usr/pluto/bin/MessageSend dcerouter 0 57 1 192

The log will show a bunch of data. The lines that start with 40 and 41 are the serial data that is being sent to/from the device. To filter the tail so it only shows the serial data, type:

tail -f [filename] | grep '^40\|^41'

=== Getting the device to start ===
If your device will not start (anymore) as described in section [[How to add your own GSD device#Adding the device]] there can be several causes.

Check that your device is controlled by the core, as described in [[How to add your own GSD device#Create a device template]]. Otherwise the core assumes another device will start the driver.

If your Ruby code contains an error, LinuxMCE may decide to disable the device. So, check that your device is not disabled: on Wizard-->Devices-->Generic Serial Devices click on "Advanced" for your device and make sure the Disabled box is NOT ticked. If it is, untick it, save, and do a quick reload of the router.

Sometimes a quick reload of the router does not suffice. In that case you can run:
<pre>
/usr/pluto/bin/Start_LocalDevices.sh
</pre>
This should start your device. If not, the output of that script is a good place to look for further clues.

== See also ==

<ul>
<li>[[GSD Ruby Interface]]</li>
<li>[[GSD - Ruby codes ]]</li>
<li>[[Generic Serial Device]]</li>
</ul>

Proliphix NT series thermostat

2010-04-11T14:52:27Z

Mhorst: Creation

[[Category: Climate]]

[[Image:Proliphix_nt20e_network_thermostat.jpg|thumb|200px|Proliphix NT20e network thermostat]]

= Overview =

The Proliphix thermostats are IP enabled thermostats with a built in web-server, enabling easy configuration from a standard webbrowser.

The thermostat does not contain batteries. It obtains it's power via Power-over-Ethernet or from the HVAC system itself. The model numbers ending in "h" obtain their power from the HVAC system, while the model numbers ending in "e" obtain their power from the ethernet.
Note that the lower numbered thermostats only support a propietary PoE standard, whereas the higher numbered models also support the IEEE 802.3af standard.

= Status =

A driver has been developed based on the Proliphix Device Protocol Revision 1.11. (See http://forum.linuxmce.org/index.php?topic=9538.0)
This driver has been tested with the following models:
* Proliphix NT-100e

The driver implements the standard LinuxMCE thermostat commands. Which means that from LinuxMCE the following commands can be executed:
* The thermostat's mode can be changed (Off, Heating only, Cooling only, Automatic)
* The fan mode can be changed (Auto or Always On)
* The temperature set-point can be changed

Furthermore the driver reports the standard LinuxMCE thermostat status messages to the system. This means LinuxMCE is aware of the following:
* The thermostat's mode
* The fan mode
* The current heating set-point
* The current ambient temperature (this is the average temperature for models with multiple sensors, reading individual sensor is not supported)

The only additional feature of the driver is that it synchronizes the thermostat's time with the LinuxMCE system time. This way the clock will never be out of sync for more than 10 minutes, and the thermostat will not have to be manually updated when switching to (or from) Daylights Savings Time.

Of course the thermostat's administration page can still be accessed normally to update the schedule and other settings.

NOTE: The driver has not yet been committed to the LinuxMCE repository yet.

= Links =
* Manufacturer: http://www.proliphix.com/
* Proliphix Device Protocol specification: http://rtc.rubyforge.org/svn/trunk/docs/PDP_API_R1_11.pdf

File:Proliphix nt20e network thermostat.jpg

2010-04-11T14:33:36Z

Mhorst: Proliphix NT20e network enabled thermostat

Proliphix NT20e network enabled thermostat

How to add your own GSD device

2010-04-11T14:25:23Z

Mhorst: Updated with my experiences of writing my first GSD driver

[[Category: Programmer's Guide]]
[[Category: Serial]]
[[Category: Tutorials]]
[[Category: GSD]]

Generic_Serial_Device (also known as [[GSD]]) is a LinuxMCE device that allows an end-user to do simple programming for RS232, serial USB or network connected devices.
This enables them to quickly and easily write drivers for such devices.

Note, however, that a GSD device driver is more limited than a compiled driver. The GSD driver allows only a single communication channel with the device (RS232, serial USB or a TCP connection across a network).
If your device has other communication channels (an UDP connection for example), you will have to write a driver in another language and compile it.

== How to add your own GSD device ==

=== Examples ===

For those of you who like to learn by example, there are some already in the LinuxMCE database.
In the LinuxMCE web admin interface go to Advanced-->Configuration-->Device Templates and pick one of the following device templates:
* Panasonic IP camera: A simple driver that enables the retrieval of video frames from this network enabled camera
* Proliphix NT series thermostat: A more elaborate driver for a network enabled thermostat. This driver also sends events to the LMCE system in case, for example, the ambient temperature changes.

=== Creating a new GSD device ===

The steps to add GSD device are following:

==== Install the necessary packages ====
Be sure that you have installed GSD package -
<pre>dpkg -l 'pluto-generic-serial-device'</pre>
(it should be there).

==== Create a device template ====
Created a device template for your system and specify that it should use GSD. The [[Edit_Device_Template]] page may be of help here.

Some things you should take into account:
* Add your template under the proper category; add it under category lighting interfaces if you want to control lighting devices only. To control all kind of devices (security, climate etc) it's better to use Interface::Specialize.
* Specify a communication type - RS232, Ethernet etc. and do not forget to specify the way to connect to the device, i.e.:
** For an Ethernet device, add the TCP Port (#69) to the device data.
* Specify that your device is controlled via category "Device Category:Core" ("Computers - Core"). Otherwise the driver will not be started on the core.

Furthermore you should add the commands implemented by your device, and the events it can generate. If possible, try to fill in the Plug & Play section to ensure that your device will be automatically detected.
Also, fill in the comment fields provide others with information about your device template.

==== Adding the device ====
If you have added Plug & Play information to your device template, a quick reload of the router, followed by the connection of your device will result in the device being detected and added automatically.

If auto-detection is not possible, however, you will have to add your device manually.
This is done on the GSD page: Wizard --> Devices --> Generic Serial Devices.

After installing the device, and a quick reload of your router you should see GSD process in the console:
<code>ps -elf|grep Generic_Serial_Device</code>

<pre>5 S root 10085 1 0 76 0 - 683 - Jul17 ? 00:00:00 SCREEN -d -m -S LinCon_8000-30 /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
5 S root 10086 10085 0 75 0 - 646 wait Jul17 pts/8 00:00:00 /bin/bash /usr/pluto/bin/Spawn_Device.sh 30 localhost Generic_Serial_Device
0 S root 31800 10086 0 79 0 - 123146 295621 Jul17 pts/8 00:00:00 ./Generic_Serial_Device -d 30 -r localhost -l /var/log/pluto/30_Generic_Serial_Device.log
</pre>

This tells you that a Generic_Serial_Device driver is running. The line containing "./Generic_Serial_Device" shows you the process is running and that this instance of the driver has been given device id 30, and that the logging will be written to the file "/var/log/pluto/30_Generic_Serial_Device.log". In this log you can find all Ruby errors, connection status and other useful information.

==== Adding the Ruby code ====
From the Device Template page and from the GSD page you can edit the Ruby codes for your device. There you can write the actual code for the methods implemented by your device.

You should implement the commands you selected for your device, and you should also implement the "Ruby Internal Commands". These commands consist of the following 6 functions:
;Private Method Listing:
: This is not really a function in itself, but rather a section in your Ruby script where you may define common functions that are used in the rest of your driver. A good example would be a function to write a line to the device's log file:
<pre>
def log(line)
# This function logs a line to the log file of the device
log = File.open("/var/log/pluto/" + device_.devid_.to_s + "_Generic_Serial_Device.log", "a")
log.puts Time.now.to_s + " (Ruby script):" + line.to_s
log.close
end
</pre>

;Process IDLE: This function is executed each one - two seconds. It may be useful to check for a connection between your device and LinuxMCE, or to poll your device for updates.
:See the Proliphix NT series thermostat driver for an example of polling, where the time between polls is reduced to once every 5 minutes, instead of once every few seconds.

;Process Incoming Data: This function is called when some data comes from your device:
<pre>recv = conn_.Recv(100,500);</pre>
:recv contains now the data received from the physical device (say some switch is OFF). You can parse it to update a status of that switch in LinuxMCE:
<pre>cmd = Command.new(device_.devid_, -1001, 1, 2, 48)
cmd.params_[10] = 0
SendCommand(cmd)</pre>

;Process Receive Command For Child: if your device is a parent device for some other devices, this function is called when a command is send to one of the child devices.
:This function should therefore forward the command to it's children. For example, a GSD device that controls dimmer or switches might receive a some command like: ON, OFF or SET LEVEL for one of it's children. It should then send these commands in the desired format to the physical device:
<pre>
cmdId = cmd.id_ # Command ID: ON, OFF, SET LEVEL
cmdTo = cmd.devidto_ # Device ID in LinuxMCE
devPort = device_.childdevices_[cmdTo].devdata_[12] # 12 contains a port/channel
childType = device_.childdevices_[cmdTo].devtemplid_ # Template ID to know type of device: switch or dimmer

case cmdId
when 192 #192 is ON
command = '<your ON command format>'
when 193 #193 is OFF
command = '<your OFF command format>'
when 184 #184 is Level of dimmer
command = '<your SET LEVEL command format>'
end

conn_.Send(command)
</pre>
: In this example the command includes following parameters: cmdTo - the LinuxMCE ID of the child device - to update the status in LinuxMCE, devPort - Port Number - to know where send actual command, cmdId - command type - ON, OFF, SET LEVEL, level value for SET LEVEL. It might be good idea to push unsuccessful commands into array in the GSD device to run them once again.

:NOTE: From trial and error, I have come to the assumption that ON/OFF and SETLEVEL, internally, have seperate values. Be careful as you can have a device that is OFF with a setlevel of 100%. This results in a pretty UGLY message when to attempt the following: Use cmd[184]=100 to turn a device ON. (but don't actually send a cmd[192].. when you attempt to turn the device OFF, you'll get an ugly message in the GSD device saying that the 'CMD[193] won't be processed because it is useless'. (I'm paraphrasing.. you get the idea...) What makes this worse, is when you use an orbiter to turn a device on, it will send you a cmd[184], not a cmd[192]. You will need to watch for this and send a cmd[192] as needed.

:NOTE FOR ABOVE: I have found a way to force the command through. a bit of history first:
The reason we get the infamous 'won't be processed because it is useless' is because DCE has to deal with NON Discrete codes.
for instance: a device that has a power toggle. IF we turn it on, it turns on.
Now, if we turn it ON again, DCE thinks it's on and because it's a toggle, it won't send the command. That is why we get this message.
I dug pretty deep to find this next piece: params[120]=1
this parameter, when set inside a command, will FORCE DCERouter to send the command regardless of what it thinks the state is.
Hope this helps other GSD programmers. DDamron

;Process Initialize: This function is called when GSD device is starting. It's good point to initialize common variables. It is also a good place get the actual status of your device and notify LinuxMCE of it, since the state might have changed while the GSD driver was down.

;Process Release: This function is called when the GSD device is closing.

Note: LinuxMCE caches your Ruby code, so you should do a quick reload of your router each time when you modify your Ruby code!

=== Other Ruby code examples ===

==== Sending an event ====

To send an event to the LinuxMCE system you can use the following snippet:
<pre>
cmd = Command.new(device_.devid_, -1001, 1, 2, 25)
cmd.params_[30] = 20
SendCommand(cmd)
</pre>

This will send the command from your device (<pre>device_.devid_</pre>) to the LinuxMCE event handler (<pre>-1001</pre>), identifying it as a priority <pre>1</pre> message, of the event type (<pre>2</pre>).
Furthermore the event has id <pre>25</pre>, which means it's a "Temperature Changed" event (the device template page shows the ids of the events you have added to the device).

Additional parameters of the event can be set by using the <pre>cmd.params_</pre> mapping. The device template page has an edit button for each event that enables you to see the parameters associated with that event, including a description of its use.
In our example it shows that the parameter with index 30 is the current ambient temperature in degrees Celcius.

After the <pre>cmd</pre> object has been initialized it is send to the LinuxMCE system using the <pre>SendCommand</pre> function.

Note that the same piece of code can be used to send commands instead of events. The only changes are that the message type will be 1 (command) instead of 2 (event), and that the destination will probably differ from the event handler device -1001.

== Troubleshooting ==

This section contains some tips on troubleshooting your new driver.

=== Viewing the logs ===

The best way to test the new GSD device is to edit the file /etc/pluto.conf and comment out the LogLevels filter, so the logging is verbose. You can do this by typing:

vim /etc/pluto.conf

Then move to the start of the line that starts with LogLevels, press 'i' for Insert mode in vim, type a # character, then press [ESC]:wq
The # at the start of a line means it's commented out, or ignored.

now do a reload router. You can do this from the console with: /usr/pluto/bin/MessageSend dcerouter 0 -1000 7 1

Then go to the log directory:

cd /var/log/pluto

ls

ls will list the contents of the directory: There will be a log file that starts with the device number of the gsd device. To follow it type:

tail -f [filename]

rather than typing in the full filename, you can just type the first letters (ie the device number) and press tab, which does an auto complete.

Now send commands to the device. You can do this through the web site or the console. For example, assuming your GSD device has the device id 57, you can send it an ON command (ON is command #192), you could type: /usr/pluto/bin/MessageSend dcerouter 0 57 1 192

The log will show a bunch of data. The lines that start with 40 and 41 are the serial data that is being sent to/from the device. To filter the tail so it only shows the serial data, type:

tail -f [filename] | grep '^40\|^41'

=== Getting the device to start ===
If your device will not start (anymore) as described in section [[How to add your own GSD device#Adding the device]] there can be several causes.

Check that your device is controlled by the core, as described in [[How to add your own GSD device#Create a device template]]. Otherwise the core assumes another device will start the driver.

If your Ruby code contains an error, LinuxMCE may decide to disable the device. So, check that your device is not disabled: on Wizard-->Devices-->Generic Serial Devices click on "Advanced" for your device and make sure the Disabled box is NOT ticked. If it is, untick it, save, and do a quick reload of the router.

Sometimes a quick reload of the router does not suffice. In that case you can run:
<pre>
/usr/pluto/bin/Start_LocalDevices.sh
</pre>
This should start your device. If not, the output of that script is a good place to look for further clues.

== See also ==

<ul>
<li>[[GSD Ruby Interface]]</li>
<li>[[GSD - Ruby codes ]]</li>
<li>[[Generic Serial Device]]</li>
</ul>