4 Writing your own plugins

Fabio Manganiello edited this page 2021-09-17 00:29:26 +02:00

Writing your own platypush plugin, that would execute your own custom logic whenever a bullet with your plugin name is received, is a very simple task.

1. Create your plugin directory under platypush/plugins (e.g. light/batsignal).

2. In the case above, platypush.plugins.light.batsignal will be your package name.

3. Create an __init__.py under platypush/plugins/light/batsignal.

4. If your module is light/batsignal, then its main class should be named LightBatsignalPlugin.

5. The configuration for your module will be read from a section named light.batsignal from your config.yaml. Its values will passed over the plugin constructor arguments.

The __init__.py will look like this:

import batman

# Decorator used to identify class methods to be exposed as plugin actions
from platypush.plugins import action
from platypush.plugins.light import LightPlugin

class LightBatsignalPlugin(LightPlugin):
    def __init__(self, intensity=100):
        super().__init__()
        self.batsignal = batman.Batsignal(intensity)

    @action
    def status(self):
        return {'status': self.batsignal.status()}

    @action
    def on(self, urgent=False):
        if urgent:
            self.batsignal.notify_robin()

        self.batsignal.on()
        return self.status()

    @action
    def off(self):
        self.batsignal.off()
        return self.status()

    @action
    def toggle(self):
        if self.batsignal.status().on:
            self.batsignal.off()
        else:
            self.batsignal.on()

        return self.status()

6. Create a manifest.yaml file in the same directory that defines your plugin. Template:

manifest:
  type: plugin
  package: platypush.plugins.light.batsignal

  # Events launched by the extension
  events:
    platypush.message.event.batsignal.SignalOnEvent: When the signal goes on
    platypush.message.event.batsignal.SignalOffEvent: When the signal goes off

  # Installation requirements
  install:
    # List of system-wide requirements on Debian/Ubuntu and derived
    apt:
      - sudo
    # List of system-wide requirements on Arch Linux and derived
    pacman:
      - sudo
    # List of pip dependencies
    pip:
      - requests
    # Extra commands to run after the dependencies are installed
    exec:
      - sudo systemctl enable my-service

8. Rebuild and reinstall platypush if required and relaunch it.

9. Test your new plugin by sending some requests to it:

• Via cURL:

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

• Via TCP backend:

echo -n '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}' | nc hostname 3333

• Via Redis backend:

echo "RPUSH platypush_bus_mq '{\"type\":\"request\",\"target\":\"turing\",\"action\":\"light.batsignal.on\"}'" | redis-cli

• Via websocket backend:

wscat -w 0 -c 'ws://turing:8765' -x '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}'

Or you can even experiment and connect Node-Red components and flows to trigger your custom action.