HS4 4 Bay Diskless Network Attached Storage
“
Product Information
Specifications:
- Product Name: Synology Plugin for HomeSeer HS4
- Functionality: Communicate with a Synology device, read
metrics, control applications, and Wake on LAN - Developer: Bernold
- Compatibility: HomeSeer HS4, .NET Framework 4.7.1 or higher, at
least one Synology device
Product Usage Instructions
Installation/Configuration:
Add/Modify a Synology Device:
- Choose Add a new device or select an existing one to modify.
Click Continue. - Enter the desired device name in the plugin. Click
Continue. - Input the host address (IP address or DNS name). Do not include
protocol or port. Click Continue. - Select http or https. Click Continue.
- Enter the port number (default suggestions: 5000 or 5001).
Click Continue. - Provide a valid active username on your Synology.
Add/Modify Chat Webhook:
- After adding a device, add chat webhooks for Chat Trigger and
Send Chat Message Action. - In Synology Chat application as an admin user, open user
profile, select Integration, and set up Incoming/Outgoing/Slash
Command or Chatbot. - Add the webhook URL to the plugin (e.g.,
http://192.168.1.23/SynologyPlugin/chatwebhook).
Remove a Device:
To cleanly remove a Synology device and delete its HS4 device
and features, use the Remove a Device page. The plugin will check
for device usage in events before deletion.
Remove a Chat Webhook:
To remove a chat webhook from a device, use the Remove a Chat
Webhook page. Check for webhook usage in events before removal.
Frequently Asked Questions (FAQ):
Q: What are the requirements to use the Synology Plugin for
HomeSeer HS4?
A: You will need HomeSeer HS4, .NET Framework 4.7.1 or higher,
at least one Synology device, and an active account on the Synology
device.
Q: How can I add multiple Synology devices using the
plugin?
A: Simply repeat the Add/Modify a Device process for each
additional Synology device.
“`
Synology Plugin for HomeSeer HS4 Manual
Introduction
Thank you for using the Synology Plugin for HS4! This plugin can be used to communicate with a Synology device: read metrics, control applications and Wake on LAN.
This is my seventh plugin for HS4. My other plugins are the Somfy Local 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.
The plugin uses Synology APIs that were mostly reverse engineered by myself, which unfortunately means I can’t guarantee everything keeps working, but I will always do my best to find alternative ways to fix things.
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 Synology device. – An account on that Synology device that can be used by the plugin.
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 Synology Plugin. · Choose Install. · In Plugins > Manage use the toggle to enable the plugin.
2. Configure: · Go to Plugins > Synology Plugin > General Settings. · Follow the steps: o Choose Continue at the introduction step. o Set the polling frequency. This depends on: How important you find it to know a status. How much CPU percentage you want to allow this plugin. Etc. Note: In DSM the default update frequency is often 10 seconds. o Choose Save Settings.
Add/Modify a Synology Device
1. Go to Plugins > Synology Plugin > Add/Modify a Device. · Follow the steps: o Choose Continue at the introduction step.
o Choose Add a new device (or an existing one if you want to modify it). Choose Continue.
o Enter how you would like the device to be named in the plugin. Then Choose Continue.
o Enter the host address. This can be its IP address (either IPv4 or IPv6) or a DNS name. Do not add a protocol or port. Choose Continue.
o Choose whether you want to use http or https. Choose Continue. o Enter the port number. The plugin will suggest 5000 or 5001, but you may have
set it to use a different port. Choose Continue. o Enter a valid user name that is active on your Synology.
Tip: You may want to first create a separate user with a name indicating its use with HS4 or this plugin. The user has to be added to the Admins group, but you can deny access to all shares and applications. Choose Continue. o Enter the password for your that account. Choose Continue. o Now please ask yourself if everything filled in so far is correct. If not, please go back to modify. If you’re using Multi Factor Authentication (MFA) with a One Time Password (OTP) generate it and fill it in. If you do not, leave it blank. Make sure the OTP is still valid for at least a few seconds when you choose Confirm. The plugin will login on your Synology. If successful, it will let you know which (sets of) features are available. Select which sets you want the plugin to create features for. If you’re modifying and deselect a set, its features will be deleted. Choose Save.
Note that features will be created during polling, so if you have polling set to manual you may want to make sure that is done.
The plugin supports more than one device Simply repeat the Add/Modify a Device 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.
Remove a Device
To cleanly remove a Synology device and delete its HS4 device and features, you can use the Remove a Device page.
1. Go to Plugins > Synology Plugin > Remove a Device. · Follow the steps: o Choose Continue at the introduction step. o Choose the Synology device that you want removed. Choose Continue. o Confirm if you want to remove the device. Choose Remove Device.
The plugin will check if the device is used in events. If so, it will warn you and cancel the removal. If not, the HS4 device and features will be deleted, polling will no longer be done and the Synology device will be removed from the settings.
Add/Modify Chat Webhook
After you have added a device, you can add chat webhooks to it. These webhooks can be used with this plugin’s Chat Trigger and Send Chat Message Action.
To setup a new webhook on your Synology, open the Synology Chat application as an admin user. Then open your user profile (top right corner) and select Integration. Then you can select Incoming/Outgoing/Slash Command or Chatbot. Set up the wanted webhook(s) and then use the information to add it to the plugin. When asked for a URL, enter the url to your HS4, followed by /SynologyPlugin/chatwebhook (for example http://192.168.1.23/SynologyPlugin/chatwebhook).
1. Go to Plugins > Synology Plugin > Add/Modify Chat Webhook. · Follow the steps: o Choose Continue at the introduction step. o Choose the Synology device that the webhook applies to. Choose Continue. o Choose Add a new webhook to <name of device> (or an existing one if you want to modify it). Choose Continue. o Enter how you would like the chat webhook to be named in the plugin. Then Choose Continue. Tip: You may want to include the type of webhook, channel name and/or a trigger word. o Select the type of webhook. Choose Continue. o Based on the selection of the type, next step will ask you for either Webhook URL or Token. Copy this from the settings from the Synology Chat Integration. Choose Continue. o Confirm and choose Save.
Remove a Chat Webhook
To cleanly remove a chat webhook from a device, you can use the Remove a Chat Webhook page. After removal you can no longer use it in triggers and actions.
1. Go to Plugins > Synology Plugin > Remove a Chat Webhook. · Follow the steps: o Choose Continue at the introduction step. o Choose the Synology device that the webhook applies to. Choose Continue. o Choose the Chat Webhook to remove. Choose Continue. o Confirm if you want the Chat Webhook to be removed. Choose Remove Webhook.
The plugin will check if the chat webhook is used in events. If so, it will warn you and cancel the removal. If not, the chat webhook will be deleted from the settings.
Devices and Features
Depending on your device, installed applications and which sets of features you selected during setup, quite some devices and features could be created. Here is an overview:
<Device Name> This is the (root) device.
Uptime Days This feature shows how many days your Synology device has been running.
Uptime Hours This feature shows how many hour your Synology device has been running on top of the Uptime Days.
Uptime Minutes This feature shows how many hour your Synology device has been running on top of the Uptime Days and Uptime Hours.
Uptime Seconds This feature shows how many hour your Synology device has been running on top of the Uptime Days, Uptime Hours and Uptime Minutes.
Firmware Version This feature shows the currently installed firmware version of your Synology device.
System Temperature This feature shows the system temperature of your Synology device, either in Celsius or Fahrenheit (depending on your HS4 settings during startup of the plugin).
Disk x Temperature This (series of) feature(s) shows the temperature per disk, either in Celsius or Fahrenheit (depending on your HS4 settings during startup of the plugin).
Volume x Used This (series of) feature(s) shows the percentage of volume usage.
CPU Load features This series of features show the CPU load percentage:
· CPU Load Average 1 Minute · CPU Load Average 5 Minutes · CPU Load Average 15 Minutes · CPU System Load · CPU User Load · CPU Other Load
These match the CPU tab in Resource Monitor.
Disk x Read Speed This (series of) feature(s) shows the read speed per disk in KB/s.
Disk x Write Speed This (series of) feature(s) shows the write speed per disk in KB/s.
Disk x Utilization This (series of) feature(s) shows the utilization percentage per disk.
Memory Resource features This series of features shows the memory usage:
· Memory Reserved in MB · Memory Used in GB · Memory Buffer in MB · Memory Cached in GB · Memory Available in GB
These match the Memory tab in Resource Monitor.
Network resource features This series of features shows the network usage per connection:
· Network LANx Receive Speed in KB/s · Network LANx Transmit Speed in KB/s
These match the Network tab in Resource Monitor
Certificate <certificate name> Days Left This feature shows the number of days left of the validity of the certificate mentioned.
Buttons: · Renew (123)
The known type of certificates at the moment are (Let me know if you have another type!):
· Synology Inc., the type of your standard certificate. · Let’s Encrypt (added via DSM) · Active Backup for Business, which comes with it.
Backup Task Status for <backup task name> This feature shows the status of the (Hyper Backup) backup task and contains buttons to change the status.
Statuses: · · ·
Unknown (Let me know when you get this, to see if the status can be added!) None (Backup task is not running) Running
Buttons: · ·
Cancel (0) Start (100)
You may want to hide these features for other users, so they can’t mess with your backups. Or remove the buttons. You can still control the feature by setting its value to the values mention above.
Backup Last End Time for <backup task name> Shows the last time this backup task ended (or N/A if it never ran before).
Backup Last Result for <backup task name> Shows the result of the last time the task ran.
Statuses: · · · · ·
Unknown (Let me know when you get this, to see if the status can be added!) None (for backups that have never been running yet) Failed Canceled (if the backup task was canceled) Done (completed successfully)
Backup Progress for <backup task name> Shows the progress percentage when the backup task is running (or N/A when it is not).
Note: Backup Task features are only added after a second polling (first one discovers the VM, second one reads its properties).
Image <image name:tags> Update Availability This feature show the update availability of the (Docker) image in Container Manager and contains a button to Update the image (Which updates the containers using it with the tags).
Buttons: · Update (123)
You may want to hide these features for other users, so they can’t mess with your images. Or remove the buttons. You can still control the feature by setting its value to the values mention above.
Container Status for <container name> This feature shows the status of the (Docker) container in Container Manager and contains buttons to change the status.
Statuses: · · · ·
Unknown (Let me know when you get this, to see if the status can be added!) Created (When the container has been created, but has never been run) Exited (Container is stopped) Running
Buttons: · · · ·
Stop (0) Force Stop (10) Restart (20) Start (100)
You may want to hide these features for other users, so they can’t mess with your containers. Or remove the buttons. You can still control the feature by setting its value to the values mention above.
Note that container features get automatically deleted (and recreated) when you rename the container. This may break events, so be careful.
Container <container name> Running Since When running this feature shows since when (long date format) the container has been running. If not, it will show N/A.
Note that container features get automatically deleted (and recreated) when you rename the container. This may break events, so be careful.
VM Status for <VM name> This feature shows the status of the VM in Virtual Machine Manager and contains buttons to change the status.
Statuses: · · · · · ·
Unknown (Let me know when you get this, to see if the status can be added!) Booting Crashed Creating HA Standby Importing
· Inaccessible · Moving · Preparing · Running
· Shutdown · Shutting Down · Storage Migrating · Suspended · Undefined
Buttons: · · · · · · ·
Shutdown (0) Force Shutdown (10) Reset (20) Suspend (30) Resume (70) Power On (100) Create Snapshot (200)
You may want to hide these features for other users, so they can’t mess with your VMs. Or remove the buttons. You can still control the feature by setting its value to the values mention above.
<VM name> vCPU Usage This feature shows the CPU usage percentage of the VM.
<VM name> Disk x Usage This (series of) feature(s) shows the disk usage percentage of the VM.
<VM name> Disk x Read Throughput This (series of) feature(s) shows the disk read throughput of the VM in KB/s.
<VM name> Disk x Write Throughput This (series of) feature(s) shows the disk write throughput of the VM in KB/s.
<VM name> LANx Status This (series of) feature(s) shows the network status of the VM.
<VM name> LANx Receive Speed This (series of) feature(s) shows the network receive speed of the VM in KB/s.
<VM name> LANx Transmit Speed This (series of) feature(s) shows the network transmit speed of the VM in KB/s.
Note: VM features are only added after a second polling (first one discovers the VM, second one reads its properties).
Chat Trigger
If you’re using this plugin with the Synology Chat application, you can use the Synology Plugin Chat Trigger to trigger events when a message was posted that:
· Comes from a certain chat webhook (Chatbot, Outgoing, Slash Command). · Comes from a certain chat channel number. · Has an interactive message attachment (buttons) with a certain callback ID, name and/or
value (Chatbot only). · Is coming from a certain user. · Contains (a) certain word(s) or matches a regex (Chatbot, Outgoing only). · Contains a trigger word (Outgoing only).
Before you can use chat webhooks in this trigger, you have to add them to the settings on the Add/Modify Chat Webhook page. After that just select the trigger and start filling in its conditions.
Chat Channel Number To look up a chat channel number, just open Synology Chat from a browser, select the channel you want to look up and check the URL bar. The URL should end with the channel number.
Interactive Message Attachment The Callback ID, Name and Value match what you entered on the Generate Interactive Attachment String page.
Matching words When a message is coming from a Chatbot or Outgoing webhook, you can filter on words:
· Any message · Match entire string (case sensitive or not) · Starting with string (case sensitive or not) · Ending with string (case sensitive or not) · Matching any word of string (case sensitive or not) · Matching all words in string (case sensitive or not) · Matching regex string
Trigger word Outgoing chat webhooks can be configured from the Integration settings to only send when a message starts with certain words, called trigger word.
Chat Message Action
To send a chat message from an event, you can use the action Synology Chat Send Message.
Before you can use chat webhooks (Chatbot, Incoming) in this action, you have to add them to the settings on the Add/Modify Chat Webhook page. After that just select the action and start filling in its parameters.
Parameters can be: · The message to be send, which is obviously mandatory. If you want to include a hyperlink in your message you can put it between <> to show as a link. If you want your own text to show, instead of the link add | and your text behind the link. Example: Click the link to go to the <https://www.homeseer.com|HomeSeer page>! · The user to send it to (Chatbot only), mandatory for Chatbot. · URL to attach a file. Note this has to be from a fast responding server, or it will timeout. · Interactive Attachment, or in plain English: Buttons (Chatbot only). To generate a properly formatted Interactive Attachment, you can use the Generate Interactive Attachment String page.
Wake on LAN (WoL) Action
The Wake on LAN action allows you to wake up your Synology device from an event. It does this by sending the WoL magic packet to the LAN1 MAC Address of the device, which was read when you added the device. The packet will be send to port 40000. In case you wonder why this port instead of port 0, 7, or 9: WoL doesn’t care about the port, but 40000 looks better in WireShark 🙂
Scripting
Poll
For manual polling which updates features – 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(“Synology Plugin”, “”, “Poll”, New Object() {})
SetBackupStatus To change the status of a Backup Task you can use PluginFunction SetBackupStatus()
1 DeviceName1
string Has to match the name you gave your Synology device in the plugin.
2 BackupTaskName1 string Has to match the name of the backup task in Hyper Backup.
3 Command
string The following commands are available:
backup To start the backup task
cancel To cancel the running backup task
hs.PluginFunction(“Synology Plugin”, “”, “SetBackupStatus”, New Object() {“MySynology”, “Backup HomeSeer folder”, “backup”})
SetContainerStatus To change the status of a Container you can use PluginFunction SetContainerStatus()
1 DeviceName1 2 ContainerName1 3 Command
string string string
Has to match the name you gave your Synology device in the plugin.
Has to match the name of the container in Container Manager.
The following commands are available: restart To restart the container signal To force stop the container start To start the container stop To stop the container
Example:
hs.PluginFunction(“Synology Plugin”, “”, “SetContainerStatus”, New Object() {“MySynology”, “node-red”, “restart”})
SetVMStatus To change the status of a VM you can use PluginFunction SetVMStatus()
Parameters 1 DeviceName1 2 VMName1 3 Command
string string string
Has to match the name you gave your Synology device in the plugin.
Has to match the name of the VM in Virtual Machine Manager.
The following commands are available: createsnapshot Creates a snapshot of the VM poweroff To force shutdown the VM poweron To start the VM reboot To restart the VM resume Resumes a suspended VM shutdown To shutdown the VM suspend Suspends the VM
Example:
hs.PluginFunction(“Synology Plugin”, “”, “SetVMStatus”, New Object() {“MySynology”, “HomeSeer VM”, “createsnapshot”})
1 Names in this PluginFunction are case-sensitive.
Console Commands
This plugin can be partially (not stand alone) used from the console.
SendChatMessage This command allows you to send a Chat message to a ChatBot or Incoming webhook. For this, the plugin does not have to be connected to HS4. To be able to use this functionality, you will first have to Add a Chat Webhook while the plugin is connected to HS4.
Here is how to use it:
Parameters
1 DeviceName23
string Has to match the name you gave your Synology device in the plugin.
2 WebhookName23 string Has to match the name of the Chat Webhook.
3 Message2
string The message you want to send, without replacement variables.
4 File URL4
string The URL for an attachment (optional), from a fast source.
5 Attachments4
string A string from Generate Interactive Attachment string (for buttons).
Replace double quotes with %22 if needed.
6 ChatUserName
string The name of the chat user (ChatBot only).
If you have spaces in any parameter, enclose it in double quotes.
Examples:
HSPI_SynologyPlugin.exe SendChatMessage mySynology “HomeSeer Chatbot” “The HomeSeer PC just restarted.” “” “” bernold
HSPI_SynologyPlugin.exe SendChatMessage mySynology “General Incoming Webhook” “Are you sure HS4 is running again?” “” ” {%22callback_id%22:%22isitupquestion%22,%22text%22:%22attachment%22,%22acti ons%22:[{%22type%22:%22button%22,%22name%22:%22Yes%22,%22value%22:%22Yes%22 ,%22text%22:%22Yes%22,%22style%22:%22green%22},{%22type%22:%22button%22,%22 name%22:%22No%22,%22value%22:%22No%22,%22text%22:%22No%22,%22style%22:%22re d%22}]}”
2 This parameter is mandatory. 3 This parameter is case-sensitive. 4 This parameter is optional. To skip it use 2 double quotes with nothing in between.
View Setup JSON
If you feel this plugin is lacking functionality, please let me know. Especially when you’re missing status info or commands. Most of what is used is reverse engineered and therefore not documented. 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 > Synology Plugin > View Setup JSON · Follow the steps: o Choose Continue at the introduction step. o Select the correct gateway from the dropdown. Choose Continue. o Select the format. If it holds private information, please manually redact. Choose Show Data. o Copy all text in the textarea and send it to me. On the forum you may want to put it 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 you are missing.
Thanks for your help!
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: SynologyPlugin.ini and SynologyPlugin.ini.bak · From the html > images folder: folder SynologyPlugin and its files · From the Bin folder > folder SynologyPlugin and its files · From the Docs folder > Synology 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
Version 1.0.5.0
1.0.4.0
1.0.3.0 1.0.2.0 1.0.1.0 1.0.0.0
Remark Added Multi Factor Authentication (MFA) with One Time Password (OTP) Added certificate features (days left, renewal button). Added Container Manager (Docker) Image features (update availability, Update button). Added more details to error logging. Added console command SendChatMessage to send chat messages without HS4. Now allowing spaces in device name field (Add/Modify Device page). Fixed potential SSL Certificate error. Fixed SSL error when using a certifcate other than the self-signed certificate. Fixed self-signed certificate effective date checking. Fixed Container features being automatically being deleted when their image is updated, optimized setting container Status. Fixed feature checkboxes on Add/Modify Device page not being set when modifying and there is more than 1 device in the settings. Fixed polling errors in the Log while modifying a device. Removed tight timeout settings. Added PluginFunction SetBackupStatus(). Added PluginFunction SetContainerStatus(). Added PluginFunction SetVMStatus(). Created workaround for buggy documented API calls to make Virtual DSM VMs work. Added status to Backup Last Result feature. Added 10 statuses to VM Status feature. VM buttons Power On, Shutdown and Force Shutdown now use documented API calls instead of reverse engineered. Fixed removing VM Status feature when feature set is unchecked. Fixed potential Backup Task/VM features being deleted due to error while polling. Fixed Backup Task Status not containing name (since 1.0.3.0). Added page for removing Synology devices. Added page for removing Chat webhooks. Optimized code: polling now only calls each Synology device once (instead of 1-3). Expanded View JSON with backup tasks and VMs. Added error logging for commands from buttons. Added error logging during polling. Fixed commands from buttons working when polling is set to manual. Added Hyper Backup features. Added automatic removal of features for containers, VMs (and backup tasks) that were removed from your Synology. Fixed modifying IPV6 address in Add/Modify Device page. Fixed deleting features after removing a feature set from Add/Modify Device page. Now skipping modifying device/features when name and/or host did not change from Add/Modify Device page. Added more validity checks and debug logging to Add/Modify Device page. Fixed chat webhook not always saving. Initial release
Documents / Resources
 | Synology HS4 4 Bay Diskless Network Attached Storage [pdf] User Guide HS4 4 Bay Diskless Network Attached Storage, HS4, 4 Bay Diskless Network Attached Storage, Diskless Network Attached Storage, Network Attached Storage, Attached Storage, Storage |