Skip to main content

FreshRSS smart home integration, free and open source

FreshRSS integration for Gladys Assistant

Your FreshRSS reader in Gladys: unread counts, new articles, mark as read.

View on GitHubAll integrations

Connect Gladys to FreshRSS, the self-hosted feed aggregator: follow your unread articles per category and per feed, react when a new article arrives, mark articles as read from your scenes, and see the newest unread articles on the dashboard. The integration follows the state of your reader (read / unread, the same in all your FreshRSS apps), not the feeds themselves.

Tested against a real FreshRSS 1.30.4 (the official Docker image) with test feeds. Feedback welcome on the Gladys forum.

Prerequisites​

  • Gladys Assistant 5.1 or later.
  • FreshRSS, at home or on a public server, reachable from the Gladys machine.
  • The API of FreshRSS allowed: as an administrator, open Administration → Authentication and tick Allow API access.
  • An API password for your user: open Profile → API management, enter an API password and save. It is not your login password; FreshRSS shows the API address on the same page.

Configuration​

  1. Open the Configuration tab of the integration.
  2. In FreshRSS address, enter the address you open FreshRSS at, for example 192.168.1.50:8080 (http when no scheme is given) or https://rss.example.org. The API address shown by FreshRSS (…/api/greader.php) works too.
  3. Enter your User name and the API password.
  4. Optional: Read FreshRSS every (5 minutes by default), and Keywords to watch, separated by commas, for the keyword filter of the "New article" trigger.
  5. Click Test the connection: it shows the user, the unread articles, the feeds and the categories.
  6. Open the Discovery tab and add the devices you want.

Devices​

  • FreshRSS: Unread articles (everything) and FreshRSS online (0 while FreshRSS does not answer).
  • One device per category and one device per feed (offered for each of them): their Unread articles.

The values are read every few minutes (the setting above) and right after every change made from Gladys. They are kept in the history, for a chart of your unread pile. To act above a threshold, use the device trigger of Gladys: Unread articles above 50, for instance.

Dashboard widget​

FreshRSS: the number of unread articles, the six newest unread articles (feed, date, summary, links to the article and to the feed in FreshRSS when they are https), a Refresh button that reads FreshRSS again now, and a Mark as read button, with a confirmation, that marks the listed articles as read (only them). Set to a category or a feed device, the widget shows that one only.

Scene triggers​

  • New article: an unread article arrived in FreshRSS. Filters: a category (a category device), a feed (a feed device), a keyword (one of the keywords of the configuration, found in the title, case and accents ignored). Information passed on: title, link, feed, category, author, keyword found, publication date and article id.

Nothing fires at the first read after installing the integration, nor for the articles already there when a feed is added, nor for articles already read in another app. At most 10 articles are announced per read.

Scene actions​

  • Mark FreshRSS articles as read: every unread article of a category or a feed; pick the FreshRSS device to mark everything. Results: articles marked, category or feed.
  • Mark articles as read by id: one or more article ids, typically the article id of the "New article" trigger. Result: articles marked.
  • Read the unread FreshRSS titles: the newest unread articles (1 to 10), of everything or of a category or feed, optionally marked as read afterwards. Results: number read, unread articles in all, titles one per line ("Title — Feed"), title, link and feed of the newest one.

Scene examples​

  • Morning briefing: at 7:30, Read the unread FreshRSS titles (category News, 5 articles, then mark them as read), then send a Telegram message with its Titles result (insert it with the variable picker).
  • Watch a topic: with Gladys in the keywords, New article with the keyword Gladys → send a message with the Title and the Link of the article, then Mark articles as read by id with its Article id.
  • Too much to read: device trigger Unread articles of the FreshRSS device above 100 → Mark FreshRSS articles as read on the category Uncategorized.

Troubleshooting​

  • "The API of FreshRSS is disabled": allow API access in Administration → Authentication (an administrator of FreshRSS has to do it).
  • "FreshRSS refused the user name or the API password": the API password is not the login password; set it again in Profile → API management.
  • "FreshRSS does not answer": check the address and the port from the Gladys machine. Behind a reverse proxy, enter the full address, path included.
  • "FreshRSS redirects to another address": FreshRSS answers on another address, often the same one in https://: enter that one.
  • "This address does not answer like FreshRSS": the address leads to another service, or to a login page (an authentication proxy in front of FreshRSS must let /api/ through).
  • No "New article" event: articles arrive when FreshRSS refreshes its feeds (its cron job, CRON_MIN in the official Docker image; each feed at most once per hour by default), then at the next read of the integration.
  • More details: set the LOG_LEVEL variable of the integration to debug.

Limits​

  • FreshRSS knows categories by their name only: renaming a category in FreshRSS offers a new device, the old one stays without values.
  • The API of FreshRSS does not tell the feeds in error, and cannot ask for a refresh of the feeds: FreshRSS keeps its own schedule.
  • The trigger filters only compare exact values: the keyword filter is one of the configured keywords, written as in the configuration (the first one found in the title).
  • Starred articles, labels and the feeds themselves are not managed from Gladys. At most 100 categories and 200 feeds are offered as devices.
  • The widget links open https addresses only: an article or a FreshRSS on plain http has no link.
  • Not affiliated with FreshRSS.

Configuration settings​

These are the settings FreshRSS asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect FreshRSSsectionNoIn FreshRSS, allow API access (Administration → Authentication), then set an API password for your user (Profile → API management). Enter the address of FreshRSS, your user name and that API password: the integration reads your unread counts, announces the new articles and marks articles as read from your scenes.
FreshRSS addressstringYesThe address you open FreshRSS at, or the API address shown in Profile → API management.
User namestringYes
API passwordsecretYesNot the login password: FreshRSS → Profile → API management → API password.
Read FreshRSS everyselectNoNew articles are announced at the next read, once FreshRSS has fetched them (its own refresh, by its cron job).
Keywords to watch (optional)stringNoSeparated by commas. A new article whose title holds one carries it, for the keyword filter of the trigger.
Language of names and messagesselectNoFeature names are set when a device is added to Gladys.

How to install FreshRSS in Gladys​

  1. In Gladys, open Integrations: FreshRSS appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-freshrss:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-freshrss.

FreshRSS requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

FreshRSS is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on