somfy HS4 Local Plugin for HomeSeer App User Guide

somfy HS4 Local Plugin for HomeSeer App

Product Information

Specifications

• Compatible with: HomeSeer HS4
• Requirements:
  • Net Framework 4.7.1 or higher
  • Supported gateway connected to local network (e.g., Tahoma Switch, Connexoon)
  • Actuators added to gateway (io Homecontrol, RTS, Zigbee, etc.)

Frequently Asked Questions

• Q: How can I troubleshoot if I encounter connection issues with the gateway?
  • A: If you face connection problems, ensure the gateway is powered on and properly connected to your router. Check for any interference or network issues that may affect the connection.
• Q: Can I control multiple gateways with this plugin?
  • A: Yes, the plugin supports more than one gateway, allowing you to manage multiple actuators through different gateways.

Introduction

Thank you for using the Somfy Local Plugin for HS4! This plugin can be used to control actuators linked to your supported Somfy gateway, without using the Somfy cloud (after initial setup).
This is my sixth plugin for HS4. My other plugins are the MiLight Plugin, OpenTherm Plugin, Volvo Plugin, Updates Plugin and Horizon Remote Plugin. My main motivation to develop these plugins is to get better and better at C# development, and because I want the functionality for my own system.

I have tested this plugin thoroughly, but if you find bugs anyway, please let me know.
Bernold

Requirements

To use this plugin, you will need the following:

• HomeSeer HS4.
• .Net Framework 4.7.1 or higher.
• At least one supported gateway, connected to your local network. For example Tahoma Switch, or Connexoon. If you’re not sure if your gateway supports the local API, please check first or make use of the free trial period of this plugin. Preferably the gateway has a fixed IP on your network.
• Actuators added to it (io Homecontrol, RTS, Zigbee, etc.)
• An account with Somfy, your gateway added to it and Developer Mode enabled (see below).
• Initially, at setup, an active internet connection for both your HS4 system and your Somfy gateway.

Enabling Developer Mode

Before you can use your gateway(s) with this plugin, you will have to enable Developer Mode. This enables the local API.

To do this, login to the Somfy website in your country. If you’re not sure which site to use, go to https://www.somfy.com/ and use the continent/country selectors to take you to the correct site. Then login with the same account as you use with the Somfy app. When logged in, you should see your gateway(s) under My Products. Select the gateway and enable its Developer Mode. It’s been reported that for some countries this option has been left out. Somfy registered it as a bug a long time ago, but has not fixed it yet. If this is the case for you, just contact Somfy Support and ask them to enable Developer Mode manually.

Installation/Configuration

1. Install and activate the plugin like any other plugin. If you’re new to HS4, here is how:
   • Go to your HomeSeer Web Control page.
   • Use the Plugin dropdown and choose Add.
   • Use the (2nd) Search bar, or scroll to Somfy Local Plugin.
   • Choose Install.
   • In Plugins > Installed use the toggle to turn on the plugin.
2. Configure:
   • Go to Plugins > Somfy Local Plugin > General Settings.
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Set the polling frequency. This depends on:
     • If you have actuators that report back their status (not RTS).
     • How important you find it to know an actuator’s status.
     • How many actuators you have.
     • How much CPU percentage you want to allow this plugin.
     • Etc.

Adding Gateways

1. Go to Plugins > Somfy Local Plugin > Add Somfy Gateway.
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Enter the PIN (or Pod number) of your gateway. This should be on its label and looks like: 1234-5678-9012. Then Choose Continue.
   • Choose if you want to use the mDNS host name, or the IP address that you have fixed in your router. Using the IP address has the advantage that it works (and keeps working) over subnets, for example if you have the gateway in a separate IoT subnet. Choose Continue.
   • Next enter the port number. By default it’s 8443, but you may have set it to use a different port. Choose Continue.
   • Enter the email address that is associated with your Somfy account. Choose Continue.
   • Enter the password for your Somfy account. Choose Continue.
   • If you’re sure you have filled in everything correctly, choose Add Gateway. Otherwise go back step by step to check/modify what you entered.
   • The plugin will login with Somfy online and attempt to add token to your gateway to be used locally. If successful, it will save the token with the information you entered, with the exception of your Somfy account email and password.
   • Next, it will poll the gateway and create devices and features for the gateway and actuators.

The plugin supports more than one gateway, in case you can reach all actuators with one. Simply repeat the Add Somfy Gateway page.

Noteworthy:

• Feel free to rename devices and features.
• Please do not delete devices and/or features manually. If you don’t want to see them, hide them instead. For speed purposes this plugin assumes devices/features that it created are there. If not, the plugin will crash.
• If you’re feel you’re missing status information, or command buttons, please see View Setup JSON.
• You now basically don’t need internet access anymore, but your gateway won’t receive updates then either. While writing the plugin a useful update came in, which prevented buggy actuator names. If you can, grant access to the gateway every now and.
• Note that this plugin ignores the self-signed certificate of the gateway.

Modifying Gateways

If you need to modify the network settings of a gateway, use the following:

1. Go to Plugins > Somfy Local Plugin > Modify Gateway.
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Select the gateway from the dropdown. If it’s not there, the plugin does not know it (yet/anymore). Choose Continue. Next steps are the same as in Add Somfy Gateway.
   • Choose if you want to use the mDNS host name, or the IP address that you have fixed in your router. Using the IP address has the advantage that it works (and keeps working) over subnets, for example if you have the gateway in a separate IoT subnet. Choose Continue.
   • Next enter the port number. By default it’s 8443, but you may have set it to use a different port. Choose Continue.
   • If you’re sure you have filled in everything correctly, choose Modify Gateway. Otherwise go back step by step to check/modify what you entered.
   • The plugin will save the new setting with the PIN and token you entered at setup.

If you made a mistake, don’t worry. Just follow the Modify Gateway page again to correct it.

Removing Gateways

If for some reason – maybe you have replaced it – you need to remove a gateway you previously added, you can use this page. Careful: It will remove all devices and features related to the gateway and all its settings. Only thing remaining on the gateway and in the cloud is the created token, as it would require internet access and your credentials.

1. Go to Plugins > Somfy Local Plugin > Remove Gateway.
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Select the gateway from the dropdown. If it’s not there, the plugin does not know it (yet/anymore). Choose Continue.
   • Confirm that your really want to remove the gateway and all its devices and features and choose Continue.

Devices And Features

Depending on your gateway and actuators, quite some devices and features could be created. Here is an overview:

Plugin Commands

This feature currently only has one button:

• Poll Now, to manually poll all added gateways.

Gateway Read Status

This feature will tell you if last polling was successful. If your getting Bad quite often, check you’re the connection between gateway and router. For these features, the Last Change Time Updates on Status Change Only setting is off, so it will update at every poll.
Personal note: During testing, I had to reboot my router sometimes (gateway was not always powered on) to improve reading.

Gateway Protocol Version

This is the version of the gateway. This feature has a button “Update”, which forces the gateway to update and reboot. The exact process is not known. Judging by the time it takes to start and reboot it probably always downloads the latest version, flashes the firmware and then reboots the gateway. So beware, if no update is available it probably still flashes the firmware, which is always a bit risky. If you feel confident though, you could just use this button in an event to reboot the gateway at set times if for instance it freezes on you every once in a while.

Gateway Name

• This is the name of the gateway, which you could change with Somfy’s app via cloud. By default it’s probably named: Box

Gateway Connectivity

• This tells you if the gateway has internet access and could be controlled with Somfy’s apps via cloud.

Gateway LED

• This feature tells you if the gateway’s LED is on and has buttons for you to turn it on/off.

Wifi Signal Strength

• Will tell you how well your gateway is connected to your Wi-Fi Access Point. If it’s low, you may want to consider moving either.

Device Battery Level

• This feature shows the battery level of devices that are running on batteries (if available).
• If a percentage is available, that will be shown. If not, the status can be Very Low, Low, Normal, Full.

Device Name

• This is the name of the device, which you could change with Somfy’s app via cloud.

Device RSSI Level

• The RSSI Level of a device tells you how well the gateway can reach it wirelessly. If it’s low, consider moving your gateway, if possible, or adding an extra gateway.

Device Status

• This feature will tell you if the device is available for the gateway to read/control. If it’s not available, that might be caused by it being defective, it being powered off, or being out of reach wirelessly.

Device Zigbee LQI State

• Instead of the RSSI Level of a device, Zigbee uses the Link Quality Indicator (0-255), which also tells you how well the gateway can reach it wirelessly. You may find both RSSI and LQI for the same device, so you may want to hide one. If it’s low, consider moving your gateway, if possible, or adding an extra gateway.

Actuator Color Temperature

Shows the color temperature of the actuator (a light). Its slider lets you set the color temperature. Please note that the slider is always created from 2000-6500K. Your device may not support these values, but there is no way for the plugin to know what the minimum and maximum value are. You can try to find your min. and max. values by sliding all the way down and up and see what values are actually returned after polling. Then modify the values under Status/Graphics > Edit > modify Start and End. Do not just use the values from the product’s specifications. For example, I have 2200-6500K light, which in reality turned out to be 2020-6329K..

Actuator Light Intensity

• Shows the Light Intensity of the actuator (a light). Its slider lets you set the intensity from 0-100%.

Actuator Low Speed

This feature will show up if the actuator supports low speed mode. If you turn it on, the Actuator Position feature will tell the actuator to move in low speed and is therefore more silent. If it’s off, the Actuator Position feature will tell the actuator to move with regular speed.

Actuator Memorized (my) position

This feature will show up if the actuator supports reading and/or modifying the “my” position.
Note that if the percentage value for this feature is the opposite of what the Somfy (cloud) app says, for example 30% instead of 70%, you can use the Invert Position Percentage(s) settings page to make them the same. The plugin will then substract percentage it read from 100% before showing/sending.

Note: There seems to be an inconsistency in HS4 when it comes to adding buttons to slider features. Under some (unknown) circumstances you will get the following message in the Log when operating such button: “Error while getting feature XXXX: A status control covering all or a portion of the value range YY already exists”. The matter has been reported with HomeSeer and they will take a look at it. Until that time, you can use a workaround that has been implemented for these features. Just use 1000-1100 instead of 0-100. So, 1000 equals 0%, 1001 equals 1%, 1002 equals 2%, 1003 equals 3%, 1004 equals 104%, etc. and 1100 equals 100%.

Personal note: I found that some devices seem to have default “my” settings (or my installer somehow sets them exactly the same every time). For example roller shutters with RS100 Solar IO seem to be set to 85% (for ventilation purposes) and awnings with Sunea IO even seem to be set to 105% (they are probably a bit longer). If you need values above 100% just modify the Status/Graphics control End.

Actuator Motion Commands

This feature can have the following buttons (if supported):

• Open (0)
• Close (100)
• Down (1000)
• Up (1100)
• Stop (2000)
• My (3000)
• Identify (4000) – makes it go back and forth a few times to figure out which is is which if you have many actuators
• Start Identify (4100) – same, but keeps doing it until you Stop Identify
• Stop Identify (4200)

Some commands have the same function. Some just make more sense with a certain type of actuator. Feel free to remove buttons. In case you need to restore a button, use the values mentioned to add each with a New Single Value.

Actuator Moving State

• Tells you if the actuator is currently moving or not.

Actuator Open or Closed

Will tell you if the actuator is Open or Closed (or Unknown). Sometimes this may feel like it’s inverted, but that’s how Somfy intended it to be:

• “Closure 100% means “there is no light coming through. Deployment 100% means “the fabric is totally deployed. Therefore, it is coherent that the two states have the same value for an Awning Valance.”
• If you feel confused, feel free to swap the Status text on the Status/Graphics tab. If you’re getting Unknown, please provide me your data (see View Setup JSON) to add the status.

Actuator Position

The position can show a percentage of where the actuator is. Its slider allows you to set it to a specific position. Feel free to add buttons for presets, by adding New Single Value (for example 50), with Control Use (for example 50%, or Half Way) on the Status/Graphics tab.

Note that if the percentage value for this feature is the opposite of what the Somfy (cloud) app says, for example 30% instead of 70%, you can use the Invert Position Percentage(s) settings page to make them the same. The plugin will then substract percentage it read from 100% before showing/sending.

Note: There seems to be an inconsistency in HS4 when it comes to adding buttons to slider features. Under some (unknown) circumstances you will get the following message in the Log when operating such button: “Error while getting feature XXXX: A status control covering all or a portion of the value range YY already exists”. The matter has been reported with HomeSeer and they will take a look at it. Until that time, you can use a workaround that has been implemented for these features. Just use 1000-1100 instead of 0-100. So, 1000 equals 0%, 1001 equals 1%, 1002 equals 2%, 1003 equals 3%, 1004 equals 104%, etc. and 1100 equals 100%.

Actuator Switch Commands

This feature can have the following buttons (if supported):

• Off (0)
• Toggle (50)
• On (100)

Sensor Door Windows Contact State

Shows the Contact state of the sensor. Current statuses are:

• Closed (0)
• Unknown (50)
• Open (100)

Sensor Luminance State

• Shows the luminance value of the sensor in lux (lx).

Sensor Occupancy State

Shows the occupancy state of the sensor. Current statuses are:

• No Person Inside (0)
• Unknown (50)
• Person Inside (100)

Sensor Sun Energy State

• Shows the Sun Energy State value. The unit of W/m² is an assumption (There is no documentation, but it seems to be right. If you have better information, please let me know).

Sensor Relative Humidity State

• Shows the relative humidity value of the sensor in a percentage. By default the number of decimals is set to 2. If your device is less or more accurate, please modify it under Status/Graphics Options.

Sensor Temperature State

Shows the temperature value of the sensor in Celsius or converts it to Fahrenheit, depending on your HS4 Temps setting under Setup/General. The setting will be checked when the plugin starts. Then when creating the feature, it will set the suffix to either °C or °F. The suffix will not change after the feature was created (for speed purposes), so if you had your setting wrong please modify manually. By default the number of decimals is set to 2. If your device is less or more accurate, please modify it. These settings are under Status/Graphics Options.

Invert Position Percentage

Invert Position Percentage(s)

Some Actuator Position features may show a different value than the Somfy app. It’s been known to happen with (some) shutters and skylights. They will show the opposite percentage, for example 30% instead of 70%. The plugin can’t tell by the data it receives from the gateway, it usually just parses the value. To make these features say the same as the app, the Invert Position Percentage(s) page was added. Here is how it works:

1. Go to Plugins > Somfy Local Plugin > Invert Position Percentage(s)
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Next step will list all your actuators with Actuator Position features. Simply set acheckmark for the actuators you want inverted. Then Save.
   • You’re all done. After next polling, the percentage will show the opposite.
   • Note: The plugin also applies it in the background when you use the feature tochange the position of the actuator to match values it reads and sends.

Scripting

Poll

For manual polling, a function has been made available. It takes no parameters and returns nothing (just updates the features) and can be used as follows:

• hs.PluginFunction(“Somfy Local Plugin”, “”, “Poll”, New Object() {})

View Setup JSON

If you feel this plugin is lacking functionality, please let me know. Especially when you’re missing status info or commands. These are not well documented (Presumably it was in an older API, which is no longer online). There are many possibilities I know of, but sometimes I just need more info on what something really does. Sometimes I need to know what the value range is and/or what unit it is in. To help figure things out, please send me your JSON. Preferably more than once, with the actuator in different states (for example, fully open/closed/on/off and half way, dimmed, etc.).

To get the JSON, you can use the View Setup JSON page:

1. Go to Plugins > Somfy Local Plugin > View Setup JSON
   • Follow the steps:
   • Choose Continue at the introduction step.
   • Select the correct gateway from the dropdown. Choose Continue.
   • Select the format. Please use Redacted to send it to me. Note it does not redact the names of gateway or actuators. If they hold private information, please manually react. Choose Show Data.
   • Copy all text in the text area and send it to me. On the forum you may want to putit between Code tags, or upload it as a text (.txt) file after first pasting it in a text editor (for example Notepad) and saving it. Don’t forget to let me know what actuator it’s about and/or what you are missing.

Thanks for your help!

Uninstall

Uninstall: Completely removing

If you decide that the plugin is not for you, that’s too bad. But here is how to delete every last byte of it, because just uninstalling usually leaves files for any plugin.

1. Uninstall the plugin.
2. Remove its devices and features, for example by enabling Bulk Edit, selecting all relevant devices/features, choosing Bulk Action > Delete and confirming it.
3. Manually delete these files and folders:
   • From the Config folder: SomfyLocalPlugin.ini and SomfyLocalPlugin.ini.bak
   • From the html > images folder: folder SomfyLocalPlugin and its files
   • From the Docs folder > Somfy Local Plugin for HomeSeer HS4 manual.pdf (this file)

Support

If you have a question about this plugin or want to report a bug, please use the dedicated sub-forum on https://forums.homeseer.com/

Changelog

devices.

Added Region settings for North America and Asia/Pacific for getting one time API key (requires different server).

Replaced code preventing creation of double features for split devices (for instance temp/humid sensor with Battery Level twice). Converting once, BREAKING CHANGE (if linked): Removing double features!

Modified timeout to 5000ms (was 1500), added message to Log if it occurs anyway.

1.0.6.0| Added Sensor Sun Energy State feature. Added Memorized Position (my) feature.

Added recreation of devices that have been lost.

Added restart of polling timer after using Modify Gateway page.

Modified Inverted Percentages settings to follow 1.0.5.0 deviceURL change. Fixed Sensor Battery Level feature percentage, expanded it with Battery State. Fixed device conversion to 1.0.5.0 at every start of the plugin.

Removed redundant Log message when a device is added.

1.0.5.0| Fixed device creation when deviceURL contains / in front of #, preventing same kind of features under one device.

Lowered required .Net Framework version from 4.7.2 to 4.7.1. Optimized JSON deserialization.

Applied slider/button workaround to Intensity and Color Temperature features. Removed console debug messages.

1.0.4.0| Fixed not working anymore under Linux. Fixed on/off button creation.

Added Light Intensity. Added Color Temperature. Added Toggle button.

Added Occupancy State. Added Battery Level.

Corrected Log message text formatting.

1.0.3.0| Removed debug message from Invert Position Percentage(s) settings page. Added workaround for adding buttons to slider features (see manual).
1.0.2.0| Added luminance sensors (lux), like Sunis io.

Added low speed option for supported actuators like shutters. Corrected setup log text, removed debug text.

Added gateway update button.

 | Fixed error handling when local token could not be created. Improved setup pages.
---|---
1.0.1.0| Fixed handling of JSON while gateway is (re)booting.
1.0.0.0| Initial release

References

• Somfy.com
• Somfy.com

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>