From 5f9cbdda9b779a18fb591d4e859c89c8cbd0fc30 Mon Sep 17 00:00:00 2001 From: MatteGary Date: Wed, 6 Feb 2019 21:53:41 +0100 Subject: [PATCH] Add documentation for Transmission component (#7816) * First checkin for documentation of the newly implemented Transmission Component * Fix * Fix and add switch platform documentation * :pencil2: Tweaks * :pencil2: Tweaks * :pencil2: Tweak * Fix in documentation * :pencil2: Tweak * :pencil2: Tweak to solve deploy error * Update from monitored_variables to monitored_conditions * Update Category Co-Authored-By: MatteGary * Update redirect Co-Authored-By: MatteGary * Add scan_interval Co-Authored-By: MatteGary * Removed scan interval, removed sensor and switch files * :pencil2: Added scan_interval variable * Update transmission.markdown --- .../_components/sensor.transmission.markdown | 91 ------------- .../_components/switch.transmission.markdown | 52 -------- source/_components/transmission.markdown | 123 ++++++++++++++++++ 3 files changed, 123 insertions(+), 143 deletions(-) delete mode 100644 source/_components/sensor.transmission.markdown delete mode 100644 source/_components/switch.transmission.markdown create mode 100644 source/_components/transmission.markdown diff --git a/source/_components/sensor.transmission.markdown b/source/_components/sensor.transmission.markdown deleted file mode 100644 index a1700cd591c..00000000000 --- a/source/_components/sensor.transmission.markdown +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: page -title: "Transmission Sensor" -description: "Instructions on how to integrate Transmission sensors within Home Assistant." -date: 2015-04-25 9:06 -sidebar: true -comments: false -sharing: true -footer: true -logo: transmission.png -ha_category: Downloading -ha_release: pre 0.7 -ha_iot_class: "Local Polling" ---- - - -The `transmission` platform allows you to monitor your downloads with [Transmission](http://www.transmissionbt.com/) from within Home Assistant and setup automation based on the information. - -## {% linkable_title Setup %} - -To use the monitoring, your transmission client needs to allow remote access. If you are running the graphical transmission client (transmission-gtk) go to **Edit** -> **Preferences** and choose the tab **Remote**. Check **Allow remote access**, enter your username and your password, and uncheck the network restriction as needed. - -

- -

- -If everything is setup correctly, the details will show up in the frontend. - -

- -

- -## {% linkable_title Configuration %} - -To enable this sensor, add the following lines to your `configuration.yaml`: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: transmission - host: IP_ADDRESS - monitored_variables: - - 'current_status' - - 'download_speed' - - 'upload_speed' - - 'active_torrents' - - 'paused_torrents' - - 'total_torrents' -``` - -{% configuration %} -host: - description: This is the IP address of your Transmission daemon, e.g., 192.168.1.32. - required: true - type: string -port: - description: The port your Transmission daemon uses. - required: false - type: integer - default: 9091 -name: - description: The name to use when displaying this Transmission instance in the frontend. - required: false - type: string -username: - description: Your Transmission username, if you use authentication. - required: false - type: string -password: - description: Your Transmission password, if you use authentication. - required: false - type: string -monitored_variables: - description: Conditions to display in the frontend. - required: false - type: map - keys: - current_status: - description: The status of your Transmission daemon. - download_speed: - description: The current download speed. - upload_speed: - description: The current upload speed. - active_torrents: - description: The current number of active torrents. - paused_torrents: - description: The current number of paused torrents. - total_torrents: - description: The total number of torrents present in the client. -{% endconfiguration %} - diff --git a/source/_components/switch.transmission.markdown b/source/_components/switch.transmission.markdown deleted file mode 100644 index 11a69c59823..00000000000 --- a/source/_components/switch.transmission.markdown +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: page -title: "Transmission Switch" -description: "Instructions on how to integrate Transmission within Home Assistant." -date: 2015-06-02 09:00 -sidebar: true -comments: false -sharing: true -footer: true -logo: transmission.png -ha_category: Downloading -ha_release: pre 0.7 -ha_iot_class: "Local Polling" ---- - -The `transmission` switch platform allows you to control your [Transmission](http://www.transmissionbt.com/) client from within Home Assistant. The platform enables you switch to your 'Alternative Speed Limits' (aka 'Turtle mode') setting. - -## {% linkable_title Configuration %} - -To add Transmission to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -switch: - platform: transmission - host: IP_ADDRESS -``` - -{% configuration %} -host: - required: true - type: string - description: This is the IP address of your Transmission daemon, e.g., `192.168.1.32`. -port: - required: false - type: integer - default: 9091 - description: The port your Transmission daemon uses. -name: - required: false - type: string - default: Transmission Turtle Mode - description: The name to use when displaying this Transmission instance. -username: - required: false - type: string - description: Your Transmission username, if you use authentication. -password: - required: false - type: string - description: Your Transmission password, if you use authentication. -{% endconfiguration %} diff --git a/source/_components/transmission.markdown b/source/_components/transmission.markdown new file mode 100644 index 00000000000..ae4b0bfcb86 --- /dev/null +++ b/source/_components/transmission.markdown @@ -0,0 +1,123 @@ +--- +layout: page +title: "Transmission" +description: "Instructions on how to integrate Transmission within Home Assistant." +date: 2018-12-12 22:44 +sidebar: true +comments: false +sharing: true +footer: true +logo: transmission.png +ha_category: + - Downloading + - Switch + - Sensor +ha_release: 0.87 +ha_iot_class: "Local Polling" +redirect_from: + - /components/switch.transmission/ + - /components/sensor.transmission/ +--- + +The `transmission` component allows you to monitor your downloads with [Transmission](http://www.transmissionbt.com/) from within Home Assistant and setup automation based on the information. + +## {% linkable_title Setup %} + +To use the monitoring, your transmission client needs to allow remote access. If you are running the graphical transmission client (transmission-gtk) go to **Edit** -> **Preferences** and choose the tab **Remote**. Check **Allow remote access**, enter your username and your password, and uncheck the network restriction as needed. + +

+ +

+ +If everything is set up correctly, the details will show up in the frontend. + +

+ +

+ +## {% linkable_title Configuration %} + +To enable this sensor, add the following lines to your `configuration.yaml`: + +```yaml +transmission: + host: 192.168.1.1 +``` + +{% configuration %} +host: + description: "This is the IP address of your Transmission daemon, e.g., `192.168.1.1`." + required: true + type: string +port: + description: The port your Transmission daemon uses. + required: false + type: integer + default: 9091 +name: + description: The name to use when displaying this Transmission instance in the frontend. + required: false + type: string +username: + description: Your Transmission username, if you use authentication. + required: false + type: string +password: + description: Your Transmission password, if you use authentication. + required: false + type: string +turtle_mode: + description: If enabled, it creates a switch entity to control the 'Alternative Speed Limits' (aka 'Turtle mode') setting. + required: false + type: boolean +scan_interval: + description: How frequently to query for new data. Defaults to 120 seconds. + required: false + type: integer +monitored_conditions: + type: integer + description: "List of monitored conditions. Possible values are:" + required: false + type: map + keys: + current_status: + description: The status of your Transmission daemon. + download_speed: + description: The current download speed [MB/s]. + upload_speed: + description: The current upload speed [MB/s]. + active_torrents: + description: The current number of active torrents. + paused_torrents: + description: The current number of paused torrents. + total_torrents: + description: The total number of torrents present in the client. + started_torrents: + description: The current number of started torrents (downloading). + completed_torrents: + description: The current number of completed torrents (seeding) +{% endconfiguration %} + +## {% linkable_title Event Automation %} + +The Transmission component is continuously monitoring the status of torrents in the target client. Once a torrent is started or completed, an event is triggered on the Home Assistant Bus, which allows to implement any kind of automation. + +Possible events are: + - transmission_downloaded_torrent + - transmission_started_torrent + +Inside of the event, there is the name of the torrent that is started or completed, as it is seen in the Transmission User Interface. + +Example of configuration of an automation with completed torrents: + +```yaml +- alias: Completed Torrent + trigger: + platform: event + event_type: transmission_downloaded_torrent + action: + service: notify.telegram_notifier + data_template: + title: "Torrent completed!" + message: "{{trigger.event.data.name}}" +```