platypush/platypush
platypush
/
platypush
2
2
Fork 4
Code Issues 44 Pull Requests 1 Packages Projects 4 Releases Wiki Activity
Page: Plugins
Pages
Backends Home Plugins Procedures, event hooks and cronjobs as Python scripts Quickstart Run platypush in a container Run platypush in a virtual environment Writing your own backends Writing your own plugins
13 Plugins
Fabio Manganiello edited this page 2021-03-28 16:55:24 +02:00
Table of Contents

A couple of plugins are available out of the box with Platypush under plugins/. Some of them may require extra Python or system dependencies. This page will show you some of the available plugins and some possible use cases, although the only real limit to how to connect things together is just your own imagination. This is not intended to be a complete reference of all the available plugins with their supported methods and dependencies, please refer to our ReadTheDocs page for a more complete reference.

MPD/Mopidy support

Plugin reference.

MPD is an application that allows to manage and play your music collection through a scalable client/server model. You can have your server running on a machine with a hard drive stuffed with mp3s, and access your collection from anywhere using a big family of compatible command line, graphical, web or mobile clients. Mopidy is an evolution of MPD that allows you to access music content from multiple sources through a wide set of plugins - e.g. Spotify, SoundCloud, Deezer, Pandora, TuneIn, Google Music.

Platypush can be a client for your MPD/Mopidy music server, allowing you to search for music, control your queue and the playback upon requests or events.

Configuration:

music.mpd:
    host: localhost
    port: 6600

It's advised to turn on the MPD/Mopidy backend as well if you want to receive live events on your playback status.

Web interface

If you have enabled the HTTP backend, you can already point your browser to http://hostname:8008 and you would see a new tab named music.mpd in your control panel. You can browse your music from here, modify the current playlist, search for music and control the playback state. If you're using mopidy and you have some plugins configured (Spotify, SoundCloud, TuneIn...), you'll be able to control music from your cloud accounts from here as well. The interface will look like this.

Let's take a look at a couple more use cases.

Start playback via HTTP request

Simple use case to get started, start playing the current track through a cURL command:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"music.mpd.play"}' \
    http://hostname:8008/execute

Search and play songs and albums using the integrated voice assistant

If you have configured already the voice assistant backend, you can configure an event hook to play a song or an album whenever you say play [item] by [artist].

First configure an event hook for it that will invoke a new synchrounous procedure:

event.hook.SearchSongVoiceCommand:
    if:
        type: platypush.message.event.assistant.SpeechRecognizedEvent
        phrase: "play ${title} by ${artist}"
    then:
        -
            action: procedure.search_and_play_song

Then define the search_and_play_song procedure:

procedure.sync.search_and_play_song:
    -
        # Clear the content of the current playlist
        action: music.mpd.clear
    -
        # Disable shuffle mode
        action: music.mpd.random
        args:
            value: 0
    -
        # Perform an mpd search. Note how we re-used the "title" and "artist"
        # context variables parsed from the voice assistant event
        action: music.mpd.search
        args:
            filter:
                - artist
                - ${artist}
                - any
                - ${title}
    -
        # Play the first of the search results above. Note how we re-used the
        # "output" context variable, that contains the output of the previous
        # action (an array in the case of `music.mpd.search`), to get the file id
        # of the first result and pass it to `music.mpd.play`
        action: music.mpd.play
        args:
            resource: ${output[0]['file']}

Redis plugin

Plugin reference

Redis is an in-memory data structure store. It can be used as an in-memory store, as a cache or as a message broker. Obviously, latter case is quite interesting when it comes to Platypush :)

Redis is also used heavily by some of our plugins and backends to communicate and synchronize properly, especially if the components live in different processes (for example, the web server) and need to exchange messages with the main process. Redis is a perfect candidate for the purpose. It has a low latency, and the server is lightweight enough to run even on a Raspberry Pi Zero without issues. It's therefore strongly recommended to enable both the Redis plugin and backend (and install a local Redis server) to take full advantage of Platypush features.

The Redis plugin has a quite simple API to deliver messages:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"redis.send_message", "args": {"queue":"my_queue_name", "msg":"My message"}}' \
    http://hostname:8008/execute

Video and media support

Plugin reference

Platypush comes with support for video media, including YouTube, local media and torrents. It's quite handy to turn a RaspberryPi into a full-blown media server or a Chromecast on steroids, voice controls included.

video.omxplayer:
    media_dirs:
        # Local media content will be search in these directories
        - /mnt/exthd/media/movies
        - /mnt/exthd/media/series

    # Torrents and other remote content will be downloaded to this directory
    download_dir: /mnt/exthd/downloads

    # Torrent bind ports override (default ports: 6881, 6891)
    torrent_ports:
        - 7881
        - 7891

    args:
        # You can specify any extra option passed to the OMXPlayer (https://elinux.org/Omxplayer) executable here
        - -o
        - alsa  # or hdmi
        - --subtitles
        - /home/user/subs
        - -orientation
        - 90
        # ...

Some cURL examples:

Play local media

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"file:///path/video.mp4"}}' \
    http://hostname:8008/execute

Play media by URL

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_60fps_stereo_abl.mp4"}}' \
    http://hostname:8008/execute

Play a YouTube video

Note: it requires youtube-dl installed on your system.

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"https://www.youtube.com/watch?v=XCAQ0MZTJmg"}}' \
    http://hostname:8008/execute

Play a torrent content by Magnet link

Note: it requires python-libtorrent.

This will first download the torrent content to download_dir and then play it (streaming while downloading isn't currently supported, the few tests I've run seem to stress the Raspberry Pi too much).

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"magnet:?magnet_uri"}}' \
    http://hostname:8008/execute

Search and play videos from any source

The OMXPlayer plugin comes with a powerful search feature that allows you to search and play videos from any available source (currently supported: local files, YouTube and torrent sources).

An example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"video.omxplayer.search", "args":{"query":"A Space Odyssey"}}' \
    http://hostname:8008/execute

Output:

{
  "type":"response",
  "response": {
    "output": [
      {
        "url": "file:///mnt/hd/media/movies/A Space Odyssey/2001 - A Space Odyssey.avi",
        "title": "2001 - A Space Odyssey.avi"
      },
            {
        "url": "magnet:?xt=urn:...",
        "title": "2001: A Space Odyssey"
      },
      {
        "url": "https://www.youtube.com/watch?v=oR_e9y-bka0",
        "title": "2001: A SPACE ODYSSEY - Trailer"
      }
    ]
  }
}

You can also pass "queue_results":true if you want to add the search results to the current play queue, or "autoplay":true if you want to automatically play the first search result.

If you enabled the plugin you'll also have a nice video search and control tab added to your web panel.

Philips Hue lights support

Plugin reference

Control your Philips Hue lights with custom requests and events triggered by your devices.

light.hue:
    bridge: bridge_name_or_ip
    # If no lights or groups to actions are specified in
    # the action or in the default configuration, all the
    # available lights will be targeted by the commands

    lights:
        - Hall
        - Living Room Left
        - Living Room Right
        - Garage
    groups:
        - Bedroom
        - Kitchen

If you enabled the plugin, you'll also have a lights control tab on your web panel.

Some cURL examples:

Turn on the kitchen lights

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"light.hue.on", "args": {"groups":"Kitchen"}}' \
    http://hostname:8008/execute

Set the sunset scene on the living room lights

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"light.hue.scene", "args": {"name":"Sunset", "groups":"Living Room"}}' \
    http://hostname:8008/execute

Blink your living room lights for five seconds

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"light.hue.animate", "args": {"animation":"blink", "groups":"Living Room", "transition_seconds":0.5, "duration": 5}}' \
    http://hostname:8008/execute

Switch plugins

You can use Platypush to control a variety of smart plugs and switches in your smart home setup. By enabling any of these plugins (even creating an empty config entry just with disabled: False if no confi is required), you'll also get the associated switch tab in the web panel where you can control your devices through a web interface.

Belkin WeMo Switch

Plugin reference

The WeMo Switch is smart Wi-Fi controlled switch that can automate the control of any electric appliance - fridges, lights, coffee machines...

Example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"switch.wemo.on", "args": {"device":"192.168.1.2"}}' \
    http://hostname:8008/execute

TP-Link smart plugs

Plugin reference

This plugin allows you to interact with TP-Link smart plugs like the HS100.

Example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"switch.tplink.on", "args": {"device":"192.168.1.3"}}' \
    http://hostname:8008/execute

Switchbot

Plugin reference

Switchbot is a quite interesting smart home device as it aims to make non-smart devices "smart". It consists in a box with a small bluetooth-controlled mechanical arm that can apply enough pressure to press any button - you can use it to control through Platypush the buttons on your coffee machine, your dishwasher or your old tv for instance.

Note that, unlike the other plugins, Switchbot requires root privileges as it needs to send a raw bluetooth low-energy message using GATT to communicate with the Switchbot. It means that if you're running Platypush as an unprivileged user (and you should!!), you'll need for now to make a sudo rule for it. I plan to make it better/safer though.

Example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"switch.switchbot.press", "args": {"device":"00:11:22:33:44:55"}}' \
    http://hostname:8008/execute

Text-to-Speech support

If mplayer is installed, you can trigger a machine to say custom phrases in any language through the tts plugin. Quite cool if you want to let your RaspberryPi to automatically read you out loud the news or when you get a notification on your phone.

tts:
    lang: en-gb  # Default language

Example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"tts.say", "args": {"phrase":"Connecting people"}}' \
    http://hostname:8008/execute

HTTP requests plugin

Plugin reference

You can programmatically send HTTP requests in your event hooks and procedures through the http.request plugin.

Example:

event.hook.TellMeTheWeather:
    if:
        type: platypush.message.event.assistant.SpeechRecognizedEvent
        phrase: tell me the weather
    then:
        -
            action: http.request.get
            args:
                url: https://your-weather-provider.com/api/weather
                params:
                    - latlng: 0.0,0.0
                headers:
                    - X-Auth-Token: YOUR_TOKEN

Database plugin

Plugin reference

You can use Platypush to programmatically insert, update, delete or select database records in your requests, procedures or event hooks. SQLAlchemy is used as a backend, therefore Platypush support any engine schema natively supported by SQLAlchemy (SQLite, PostgreSQL, MySQL, Oracle...).

Configuration:

db:
    engine:  sqlite:////home/user/temperature.db  # (Optional) default engine; can still be overridden in your db calls

procedure.sync.log_temperature:
    -
        action: http.request.get
        args:
            url: http://your-local-server/api/sensors/temperature  # Example JSON output: {"temperature":21.0}
    -
        action: db.insert
        # engine: mysql://....  # Optionally, you can override the default engine to point to another db
        table: apartment_stats_temp
        records:
            -
                temperature: ${temperature}

update and delete methods are also available.

If you want to programmatically select from a table via HTTP call (returns a list of dictionaries):

curl -XPOST -H 'Content-type: application/json' \
    -d 'msg={"type":"request","target":"hostname","action":"db.select", "args": {"query":"select * from temperature", "engine":"sqlite:////home/user/temperature.db"}}' \
    http://hostname:8008

{
    "type": "response",
    "response": {
        "output": [{"id": 1, "temperature": "21.0","created_at":"<timestamp>"}],
        "errors": []
    }
}

Variables

Plugin reference

variable is a special plugin that allows to set, get and unset variables that you can reuse for instance within a procedure execution, to store states that will be used by some other pieces of logic, or share data with other programs.

NOTE: this plugin relies on the database plugin to be configured. It will indeed store the variables on a local database to persist them across restart and easily share them with other processes.

Example that sets a variable named AT_HOME:

curl -XPOST -H 'Content-type: application/json' \
    -d 'msg={"type":"request","target":"hostname","action":"variable.set", "args": {"AT_HOME":1}' \
    http://hostname:8008

You can now build some custom logic in a synchronous procedure based on that value:

procedure.sync.turn_lights_on_sunset:
    -
        action: variable.get
        args:
            name: AT_HOME

    - if ${AT_HOME}:
        - action: light.hue.on

And then unset it if you don't need it anymore (will delete the row):

curl -XPOST -H 'Content-type: application/json' \
    -d 'msg={"type":"request","target":"hostname","action":"variable.unset", "args": {"name":"AT_HOME"}' \
    http://hostname:8008

Google Assistant plugin

Plugin reference

If you have the Google Assistant backend configured, then you can use the assistant plugin to programmatically start or stop an interaction with the assistant. For instance, you can start a conversation without saying the "Ok, Google" hotword by pressing a Flic button, if you have the Flic backend configured:

event.hook.FlicButtonStartConversation:
    if:
        type: platypush.message.event.button.flic.FlicButtonEvent
        btn_addr: <button MAC address>
        sequence:
            - ShortPressEvent
    then:
        action: assistant.google.start_conversation

Calendar plugin

Plugin reference

You can use the calendar plugin to get your upcoming events or (TODO) change or create events on multiple data sources - Google Calendar, Facebook events calendar, remote ICal resource etc.

Example configuration:

calendar:
    calendars:
        -
            type: platypush.plugins.google.calendar.GoogleCalendarPlugin
        -
            type: platypush.plugins.calendar.ical.IcalCalendarPlugin
            url: https://www.facebook.com/ical/u.php?uid=USER_ID&key=FB_KEY

Note the use of the Google Calendar plugin type. The Google Calendar plugin belongs to the family of Google plugins, which currently includes Calendar, GMail and Maps (to be expanded). Check the instruction on the Google plugin reference on how to generate OAuth2 tokens for your Google account that these plugins can use.

Sensor plugins

You can query sensors connect through multiple interfaces through Platypush.

MCP3008

Plugin reference

The MCP3008 is a very useful ADC converter that you can use to read data from multiple analog sources and transmit them to a digital device that doesn't support direct GPIO analog input (like the Raspberry Pi). You can use it instead of an Arduino or serial device if you want lower latency, or a more compact or cheaper solution.

An example configuration:

gpio.sensor.mcp3008:
    # In this configuration the MCP3008 is connected in software SPI mode,
    # a better option if you don't have many GPIO pins available although
    # it introduces a bit of latency compared to the hardware SPI mode.
    # Here we specify the GPIO pin numbers where you connect your MCP3008
    # interface. Specify spi_port and spi_device instead if you want to run
    # in hardware SPI mode.
    CLK: 15
    MISO: 22
    MOSI: 17
    CS: 25

    # Reference tension, usually 3.3V or 5V on a Raspberry
    Vdd: 3.3

    # Here you can link names and analog conversion functions to the
    # analog sources connected to your MCP3008 pins.
    channels:
        # Channels are identified by MCP3008 pin number
        0:
            name: temperature

            # The conversion function is a snippet of Python code that you can specify to
            # convert the output voltage of your analog sensor (normalized between 0 and 255)
            # into a human readable value (e.g. meters, Celsius degrees, km/h, % etc.).
            # In this example we used a simple LM35DZ (http://www.ti.com/lit/ds/symlink/lm35.pdf)
            # temperature sensors and specified a function to convert the analog value into
            # a Celsius degrees value.
            # Note that the analog value is denoted as `x` in the function definition.
            conv_function: 'round(x*100.0, 2)'  # T = Vout / (10 [mV/C])
        1:
            name: light
            # Here we used a simple ALS-PT9
            # (http://www.everlight.com/file/ProductFile/201407061531031645.pdf) light sensor,
            # that comes with an internal 10 kΩ resistor. The detected luminosity (in lumen)
            # is proportional to the current (in μA) on the resistor, the conversion function
            # simply uses Ohm's law (I = V/R) to get the lumens from the analog voltage value.
            conv_function: 'round(x*1000.0, 6)'

cURL example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request","target":"hostname","action":"gpio.sensor.mcp3008.get_measurement"}' \
    http://hostname:8008/execute

Output:

{
  "type": "response",
  "response": {
    "output": {
      "temperature": 22.42,
      "light": 50.5
    },
    "errors": []
  }
}

If you want to poll your sensors periodically and get a Platypush event whenever their values change then you may want to enable the MCP3008 backend as well.

Distance

Plugin reference

I've tested this plugin quite successfully with the HC-SR04 ultrasound distance sensor, an inexpensive and accurate options for anyone playing with robotics.

The sensor works like an ultrasound radar - it sends a pulse controlled by the trigger_pin, and detects the returning signal through the echo_pin. Known the average speed of sound in air, it's relatively easy to get the distance of the nearest obstacle. All you have to do is connect the trigger and echo pins to the GPIO interface of your device. Note: take into account that the HC-SR04 works at 5V. If you're interfacing it with a device that works with a lower voltage (the GPIO logic of a Raspberry usually runs at 3.3V) you may want to use a voltage converter or set up your cheap voltage divider with two resistors to prevent damage to your GPIO interface.

Example configuration:

gpio.sensor.distance:
    trigger_pin: 13
    echo_pin: 14

cURL example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request","target":"hostname","action":"gpio.sensor.distance.get_measurement"}' \
    http://hostname:8008/execute

Output (in millimiters):

{
  "type": "response",
  "response": {
    "output": 313.17,
    "errors": []
  }
}

Serial

Plugin reference

Use the serial plugin if you want to read analog data through serial interface (typical use cases: Arduino or compatible devices, serial ports etc.).

It's advised if the serial device returns data in JSON format (if you use Arduino you can use the ArduinoJson library to write JSON to the serial interface).

Example configuration:

serial:
    device: /dev/ACM0
    baud_rate: 9600

If you're using udev to dynamically assign your device names, you might consider configuring udev rules to prevent the "dance" of the device names when they are disconnected and reconnected (and renamed to ACM0, ACM1, ACM2, or USB0, USB1 etc.).

cURL example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"serial.get_measurement"}' \
    http://hostname:8008/execute

Output:

{
    "type": "response",
    "response": {
        "output": {
            "smoke": 0,
            "temperature": 23.90402,
            "humidity": 39.08141
        },
        "errors": []
    }
}

Once you enable the serial or mcp3008 plugin and backend you'll be able to monitor the state of your sensors or analog sources through a new tab on the web panel.

ZeroBorg

Plugin reference

The ZeroBorg is a nice piece of circuitry that pairs quite well with Raspberry Pi and compatible devices. It comes with four outputs that you can use to control motors and servos by applying a current. It also comes with an infrared sensor that you can use to detect inputs from an IR remote, Platypush provides a backend to read events from this sensor as well.

The ZeroBorg plugin also allows you to interact with sensors data to control your motors.

Here's an example configuration I use for my 4WD robot controlled by a Raspberry Pi Zero paired with a ZeroBorg device. MagPi provides detailed instructions on how to build such a robot. Note that the calibration values came after numerous tests to get the robot to move straight. Your values may vary depending on your set up, the load of the connected components, the weight and how it is distributed.

gpio.zeroborg:
    directions:
        up:
            motor_1_power: 0.4821428571428572
            motor_2_power: 0.4821428571428572
            motor_3_power: -0.6707142857142858
            motor_4_power: -0.6707142857142858
        down:
            motor_1_power: -0.4821428571428572
            motor_2_power: -0.4821428571428572
            motor_3_power: 0.825
            motor_4_power: 0.825
        left:
            motor_1_power: -0.1392857142857143
            motor_2_power: -0.1392857142857143
            motor_3_power: -1.0553571428571429
            motor_4_power: -1.0553571428571429
        right:
            motor_1_power: 1.0017857142857143
            motor_2_power: 1.0017857142857143
            motor_3_power: 0.6214285714285713
            motor_4_power: 0.6214285714285713
        auto:
            sensors:
                -
                    plugin: "gpio.sensor.distance",
                    threshold: 400.0,
                    timeout: 2.0,
                    above_threshold_direction: "up",
                    below_threshold_direction: "left"

Note that the special direction auto can contain a configuration that allows your device to move autonomously based on the inputs it gets from some sensors. In this case, I set the sensors configuration (a list) to periodically poll a GPIO-based ultrasound distance sensor plugin. timeout says after how long a poll attempt should fail. The plugin package is specified through plugin (gpio.sensor.distance) in this case, note that the plugin must be configured as well in order to work). The threshold value says around which value your logic should trigger. In this case, threshold=400 (40 cm). When the distance value is above that threshold (above_threshold_direction), then go "up" (no obstacles ahead). Otherwise (below_threshold_direction), turn "left" (avoid the obstacle). Feel free to build a more robust autopilot by adding more sensors :)

Once you enable the plugin, you can also drive the robot through the control tab that will be available in the control panel. It also supports directional keys and spacebar long-press to toggle the automatic pilot (click inside of the tab first to focus it).

cURL example to drive your robot up and stop after 5 seconds:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"gpio.zeroborg.drive", "args": {"direction":"up"}}' \
    http://hostname:8008/execute

sleep 5

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"gpio.zeroborg.stop"}' \
    http://hostname:8008/execute

MIDI plugin

Plugin reference

Some of the musicians who ended up on this page probably know the MIDI protocol. Platypush allows you to register a custom MIDI device that can send messages to the OS MIDI sequencer. It's like tricking your machine to think that Platypush is a MIDI keyboard or drum machine. You can for instance create some instrument tracks in LMMS or FruityLoops, link them to your Platypush MIDI source, and play notes through any kind of events that Platypush can process - you can use a Leap Motion to play notes by just waving your hand, use a proximity sensor, play notes with switches and buttons, and so on, the only limit being your creativity.

An example that sends the C4 (middle C, MIDI note 0x60 or 96 in decimal) at medium velocity (64) for 1 second:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"midi.play_note", "args": {"note":96, "velocity":64, "duration":1}}' \
    http://hostname:8008/execute

You can also send raw MIDI messages through the send_message action.

You can also listen for MIDI events and run actions based on them by using the MIDI backend.

MQTT plugin

Plugin reference

MQTT is a message-queue based protocol to exchange messages across devices. MQTT implementations like Paho MQTT, Mosquitto and Adafruit IO are quite popular for communication across IoT devices. You can interact with an MQTT service through this plugin to build any arbitrary complex message-based logic across your Platypush devices. The asynchronous nature of MQTT makes it a better candidate over the HTTP plugin to deliver messages to other devices if you don't mind much about the response. An HTTP call to the Flask server to turn on the lights, for example, requires the sender to wrap the request into an HTTP message, the receiver to react immediately on that while the sender is synchrounously waiting for an answer, execute the light control action (which might take a while), and then wrap the response into an HTTP message back to the sender. Compare it instead with a message-queue based implementation, where you send the message to a queue where the receiver is listening and as soon as the receiver is available it will pick it up - no need for the sender to hang for the response. Also, the message queue doesn't require the receiver to be directly accessible (through IP/hostname and port) to the sender, as it happens in an HTTP interaction. The sender can send a message to the queue, hosted by an MQTT server, and as long as the receiver (or any receiver) is listening on the same queue, the message will be picked up.

Sending a message over an MQTT backend requires an MQTT host server and port (default: 1883), the message to be sent (anything that implements __str__), and the topic to send the message to - see it like a channel where one or multiple devices might be listening.

Example:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"mqtt.send_message", "args": {"topic":"my_topic", "server":"my_mqtt_server", "port":1883, "message":"It worked"}}' \
    http://hostname:8008/execute

You can (or should) of course also use the MQTT backend. By doing so you can send messages across that Platypush devices containing action requests, events or responses. You can create routing rules for messages, or propagate the events you receive on a device over another one - for example I've configured a rule for all of my devices with connected sensors to route their SensorDataChangeEvent events over MQTT to a hub device, where I can monitor from a single web panel the values of all my sensors around the house. Another good use case for MQTT is to send messages from your Android devices to your Platypush devices. The same developer of Taker has recently developed Join, that allows you among the other things to programmatically send messages over MQTT. You can then create tasks that send messages to Platypush when you get a call, receive an sms, connect to some WiFi network or enter some area. You can also create Join action to send custom commands to your Platypush devices from a tap on your phone.

Pushbullet plugin

Plugin reference

Pushbullet is a quite cool piece of software to keep your devices in sync, exchange messages, synchronize clipboards and sms across devices, access remote files, and so on. You can install it as an Android or iPhone app, as a browser extension, or use it from your browser directly. It can be quite powerful if paired with Platypush - and it has the first backend I have developed as well. You can use the plugin in pair with the backend to do things like:

  • Send URLs, text and Platypush messages to your Android devices
  • Trigger Platypush actions through your Android device, wherever you are
  • Synchronize the clipboards
  • Synchronize your phone notifications to your Raspberry Pi
  • Send and receive pictures
  • ...and so on

Note that you need to enable the Pushbullet backend in order to use this plugin.

Example command to send a file to all of your connected Pushbullet devices:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"pushbullet.send_file", "args": {"filename":"/home/user/myphoto.jpg"}}' \
    http://hostname:8008/execute

Kafka plugin

Plugin reference

Use this plugin if you want to synchronize messages to your devices over a Kafka message instance. Some use cases:

  • Send asynchronous messages to other Kafka nodes
  • Send raw messages to other Platypush devices and build event hooks on them
  • Send directly JSON-formatted requests, responses or events to other Platypush devices

The configuration is quite straightforward:

kafka:
    server: host:9092  # Default hostname and port where the Kafka broker runs. If None (default), then
                       # you will either have to specify on `send_command`, or it will use the Kafka
                       # backend configured server, if the Kafka backend is running

If you want to use Kafka to deliver messages to other Platypush devices keep in mind that their Kafka backends will listen by default on a queue named platypush.<device_id>.

Example to send a text Kafka message:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"kafka.send_message", "args": {"msg":"My first Kafka message over Platypush"}}' \
    http://localhost:8008/execute

IFTTT plugin

Plugin reference

IFTTT is a very versatile cloud service to automate tasks and trigger actions on particular events. IFTTT comes with some channels that may not be available on Platypush (e.g. trigger events on your Android or iOS device, send Telegram messages, create Trello tasks etc.), or you've been an IFTTT user already and you might want to integrate Platypush with your existing IFTTT configuration.

You can use Platypush to trigger IFTTT events using the Maker API.

Steps:

  1. Click on the link above and sign in with your IFTTT account

  2. Click on Documentation and copy the key associated to your account

  3. Configure the Platypush plugin:

ifttt:
    ifttt_key: YOUR_KEY

  1. In this example suppose that you want to automatically send a Telegram message to yourself with some content. Create an IFTTT applet having Webhooks as a trigger channel and specify telegram_send as event_name

  2. Specify Telegram as action channel and select the "Send message" action. Specify your own number and select the ingredient value1 as body

  3. Start Platypush and try to send a message to yourself:

curl -XPOST -H 'Content-Type: application/json' \
    -d '{"type":"request", "target":"hostname", "action":"ifttt.trigger_event", "args": {"event_name":"telegram_send", "values":["IT WORKED"]}}' \
    http://hostname:8008/execute

Adafruit IO plugin

Plugin reference

Adafruit IO is a message-based cloud storage for numerical values. You can use it to store reads from your sensors, see the values on the Adafruit dashboard wherever you are, trigger IFTTT rules if a value goes below or above a threshold and so on.

First create an account on Adafruit and get your key from Adafruit IO. Then configure the Platypush plugin:

adafruit.io:
    username: your_user
    key: your_key

Then you can create a feed on the web interface and configure for instance an event hook that forwards a new read from your temperature sensor to your remote feed:

event.hook.OnSensorData:
    if:
        type: platypush.message.event.sensor.SensorDataChangeEvent
    then:
        action: procedure.OnSensorData

procedure.sync.OnSensorData:
    - if ${'temperature' in data}:
        -
            action: adafruit.io.send
            args:
                feed: temperature
                value: ${data.get('temperature')}

Autoremote plugin

Plugin reference

Tasker is a really powerful app for Android that allows you to automate everything on your system, create tasks and triggers to control app, settings, notifications and so on. Some of its features are quite similar to those offered by Platypush, but it runs on Android while Platypush will likely run on your favourite Linux-based computer or mini-computer :)

It'd be amazing to make those two worlds communicate, for instance by sending notifications to your phone about the media that plays on your Raspberry or triggering an alert on your phone if you're not at home and your Raspberry camera detected some motion.

It's relatively easy to send messages from Tasker to Platypush. Pick your favourite Tasker plugin (Pushbullet, MQTT or Node-Red over Join, any web request plugin...) and you can start creating Tasker routines that send messages to Platypush over the configured channel.

In order to send messages from Platypush to Tasker instead you can leverage AutoRemote, a Tasker plugin that allows you to send custom messages and notifications to an Android device through a multitude of ways (Chrome extension, web API, Tasker integration etc.).

All you need is to install the app on your Android device and follow the steps to register your device. You'll get a unique URL for your device. If you open it you'll notice a key= section in the URL. That's the key you'll need in order to configure the AutoRemote plugin on Platypush:

autoremote:
    devices:
        OnePlus6: AUTOREMOTE_KEY_1
        PixelC: AUTOREMOTE_KEY_2
        Nexus5: AUTOREMOTE_KEY_3

Note that you can install and configure AutoRemote on multiple Android devices and configure the Platypush plugin with their keys and a unique name in order to send messages to them. You can now use the send_message and send_notification to respectively send messages and notifications to your device and build Tasker routines on them.

Kodi plugin

Plugin reference

Kodi is a popular media player and media center. It's compatible with plenty of devices and OSes (including Android, Linux, MacOS, Windows and several embedded players) and there are tons of add-ons available, for anything that goes from media library managemnt to subtitles to radio and tv channels to YouTube.

Kodi also comes with a powerful API, and Platypush can leverage it by allowing you to control your player. You can for instance build a DIY remote control system for your media center by using any IR remote and any IR sensor to navigate the Kodi interface or control the playback status. Or create rules to automatically add to your library and start playing a torrent file when it's done downloading. The plugin reference is quite rich and the available methods should mirror almost at 100% what is provided by the Kodi API.

Torrent plugin

Plugin reference

You can use Platypush to search, download and manage torrents. Example configuration:

torrent:
    download_dir: ~//Downloads   # Torrents download directory
    torrent_ports:               # Pair of ports used by the torrent tracker (default: 6881 and 6891)
        - 6881
        - 6891

Refer to the plugin reference for documentation on the available methods and their interface.

Note also that the download method will generate few types of events and you can build triggers on those, for instance an event hook that automatically starts your favourite player when a movie has done downloading or a notification for the progress of your downloads synced to your mobile device.

Weather plugin

Plugin reference