Luup Somfy Walkthrough

Revision as of 00:56, 29 June 2009

The documentation (see: [1]) explains that you talk to the controller using RS232 9600 Baud, 8 Data Bits, 1 Stop Bit, No Parity. The interface supports up to 16 blinds. The communication is one-way only; there are no response codes or incoming data from the blinds when they change manually. Here is the relevant section from the manual.

RS232 Operation
1. Set RS232 communication settings to: 9600 Baud, 8 Data Bits, 1 Stop Bit, No Parity
2. Use the ASCII protocol command string syntax: <!> <2 digit channel number> <Directional Command>
3. The directional commands must be capital letters and are as follows:
  U: UP
  D: DOWN
  S: STOP
4. Examples: Motor 2 Up: !02U
  Motor 5 Down: !05D
  Motor 1 Stop: !01S

Step 1: SSH into Vera

Since this device is so simple it may not be necessary to debug anything. But we'll do this anyway. You need to give Vera a root password, which is the administrator password to login directly. Do this by either: a) from a command prompt in Windows, Linux or Mac type telnet [ip address of vera] and when you see the root@HomeControl:~# prompt enter: passwd and type in a password twice. Then type exit. Or b) In Vera's web ui click Advanced, Net & Wi-fi and the 'Advanced Configuration' link, and supply the password there. Note, sometimes Windows Vista doesn't have the telnet utility installed, so you have to use step b.

Once you have a root password set, you will no longer be able to use telnet to login to Vera, you must use ssh. The reason you should use ssh to login for debugging, and not telnet, is because some of the useful key sequences, like Ctrl+C, don't work in telnet.

Once you've setup a root password, from a Mac or Linux console type: ssh [ip of vera] From a Windows PC, download putty.exe here: [2]. You don't need to install putty, just put the .exe on your desktop or in a folder. When you run putty.exe, type in Vera's IP address and click 'open'.

When you see login as:, enter: root and then enter your password. Now from the root@HomeControl:# prompt type:

 cd /var/log/cmh
 tail -f LuaUPnP.log

Do something in Vera's web ui and you'll see the logs go. Whenever the system rotates the logs, meaning purges the log files because Vera's memory is limited for storing logs, your tail will end. Press the 'up' arrow and hit 'enter' to display the tail command again and restart it. Press Ctrl + c when you've confirm the logs are working ok.

In Vera's web ui, choose Advanced, Logs, and check 'Verbose logging'. This option will create large logs that have lots of information we may need for debugging. It will stay checked for 24 hours and then automatically turn itself off so you're not creating unnecessarily large log files.

Step 3a: Add your with the web generator tool

 --coming soon.  for now use step 3b.

Step 3b: Add your device by building the XML files by hand

In Vera's setup UI, go to Devices, Luup plugins, click 'Luup files' and download the files:

D_BinaryLight1.xml since there is no UPnP device specification for blinds, and blinds are essentially binary devices that are either up/down, we can implement the up/down using the same service that a light switch uses, and that way any UPnP control point that can control a light switch, will also be able to control blinds.

S_SwitchPower1.xml because when you open D_BinaryLight1.xml, you'll see that in the 'services' section, this is the filename (SCPDURL) for the SwitchPower service.

D_TestSerial.xml because this is a sample serial device we can use as a template.

I_TestSerial.xml because this is a sample implementation for our serial device.

Open D_TestSerial.xml and re-save it as a different name, such as D_SomfyBlinds.xml. Change the xml field deviceType to "urn:somfy-com:device:blinds:1" or use your own domain name instead of somfy-com. Change friendlyName to "Somfy Blind Controller", manufacturer to "Somfy", manufacturerURL to "somfy.com", modelDescription to "16 port RS232 to Somfy blind interface", modelName to "1810686" (the Somfy part number). modelURL and serialNumber and UPC aren't really important so you can just remove them.

Remove all the tags in 'servicelist' and copy/paste the service for SwitchPower from D_BinaryLight1.xml into the servicelist tag. You can leave out the controlURL and eventSubURL tags because the Luup engine will replace them anyway. The servicelist should now look like this:

   <serviceList>
     <service>
       <serviceType>urn:schemas-upnp-org:service:SwitchPower:1</serviceType>
       <serviceId>urn:upnp-org:serviceId:SwitchPower1</serviceId>
       <SCPDURL>S_SwitchPower1.xml</SCPDURL>
     </service>
   </serviceList>

Change the filename in the implementationFile tag from I_TestSerial.xml to I_SomfyBlinds.xml.

Open I_TestSerial.xml and delete the sample Lua code within the 'actionList' tag. Change the 'protocol' tag in 'settings' from crlf to raw because this device doesn't have any low level particular low level protocol, like terminating blocks of data with a carriage return, etc. Save the file as I_SomfyBlinds.xml.

Back on Vera's setup ui under 'Luup files' you the first 'upload' button to upload D_SomfyBlinds.xml and the 2nd to upload I_SomfyBlinds.xml. Check Restart Luup after upload because the files won't be processed unless we restart the Luup engine, and click 'go'. Now leave your browser tab open at this page so that as we change the implementation file we can just click 'go' without having to select the files again.

In another browser tab go to Vera's device page again and under 'Add device' put the new device filename D_SomfyBlinds.xml in the input box, and choose the room where the blind controller is located, click 'Add device', then click 'save'.

Step 4: Setup the port

Vera talks to serial devices using a serial port proxy that turns the serial port into a network port. This way the serial port can reside anywhere on the network. Here are 3 ways to connect Vera to the Somfy device:

1. Get the UC232R-10 usb->serial adapter here: [3] Connect it to one of Vera's USB ports. In Vera's web ui, click the 'save' button, which, even if the 'save' button is grayed out, causes the Luup engine to re-initialize and scan for new serial ports. Wait 30 seconds.

2. Use any Windows COM port or USB->serial port device. Download Windows_Serial_Proxy and run it as explained there. Wait 30 seconds after running it and it will exit after it has reported the port to the Luup engine.

3. Connect a Global Cache GC-100 to your network. Wait 30 seconds or so for the Luup engine to find it. This should happen automatically.

After you've done 1, 2 or 3, go to Devices, Luup plugins and click "Serial port configuration". The serial port should be on the list. Use the pull-down's to set the serial port options: baud=9600, Data Bits=8, Stop Bits=1, Parity=none. For the 'Use with device', select your Somfy Blind controller. Choose 'Save'.

Step 5: Test the port

First, make note of the device id for your Somfy blinds by clicking '+' next to the device in the device list. Next, go to Devices, Luup Plugins, Test Luup code. In the 'Device number' input box put the device number for the Somfy blinds. This way whatever code we test uses the Lua instance for the Somfy blinds, which will be configured already to use the serial port.

In the 'Code' input box, type: lu_iop_send('!01U') and click 'Go'. That is a command according to the Somfy specs, which should make motor #1 go up. You can try other commands and click 'Go' each time. If everything is working ok, skip to step 6. If it's not working, you will want to do some debugging. Here's some debug things to try:

1. Be sure you checked 'Verbose logging' in Step 1. In your ssh console (ie putty if you're using windows) enter tail -f LuaUPnP.log | grep '^5\|^01' where the | means to send the output through the grep utility, which will filter out only certain lines. The ^ means 'lines that start with'. Line that start with 5 are logs related to Lua, and lines that start with 01 are critical errors. The \| means 'or' for grep. Now go back and click 'go' again in the Test Luup window. Return to the ssh console and you should see a line that starts with 51, which means data sent within Luup, that shows !01U. If you're going to be switching back and forth between the ssh console and web ui to do tests, then before you switch to the web ui, you can either hit 'enter' a few times in the ssh console to add some blank space, or press Ctrl+c and then 'up' followed by 'enter' to restart tail. That way you've created some separation between existing log entries and new ones so you can clearly see what is happening when you click 'go'. If you're not seeing anything, in the Test Luup window add the line lu_log('test somfy') above the lu_iop_send. You should see 'test somfy' get logged when you press 'go'.

2. Assuming you do see the line '51' log entry showing that the Luup engine is trying to send data, you may want to check the serial port itself. You can go back to the 'serial port configuration' and remove the 'Somfy blind' device from the serial port so the Luup engine won't open the port. Make a note of the network ip and port for the serial port. Click 'Save' to save your changes. Now from a command prompt run: telnet [ip] [port]. If you don't have telnet, open another putty session and click the 'telnet' radio box, put in the ip address and port and click 'open'. You should now be able to type the commands in the telnet session: !01U and see the blinds work. If it still doesn't work, try connecting the blinds directly to your PC and using a terminal program, like Hyperterminal, to talk directly to the serial port and confirm the connections are ok.