How to use MaasPower

To use maaspower you will first need to create a configuration file that describes the set of devices that you want to control and the webhooks that will be supplied to control them.

Next launch the webhook server on an appropriate machine.

Finally configure MAAS to talk to the webhook server on behalf of each of the bare metal machines that you are controlling.

Configuration

An example YAML config file is shown below. This configures 1 SmartThings switched power socket and 2 devices connected a switching USB power Hub.

The example power hub is controlled via the uhubctl command line tool (see https://github.com/mvp/uhubctl).

SmartThings are IoT devices which are controlled using a SmartThing api token and SmartThing device ID. Once you have set up a SmartThing and tested it via the associated App you will be able to discover your device ID via the App. You can get your api token by logging in here: https://account.smartthings.com/login.

# yaml-language-server: $schema=maaspower.schema.json
# NOTE: above relative path to a schema file from 'maaspower schema <filename>'

name: my maas power control webhooks
ip_address: 0.0.0.0
port: 5000
username: test_user
password: test_pass

devices:
  # This requires a smartThing compatible switching device and related
  # token, device ID.
  - type: SmartThingDevice
    name: nuc1
    # token and id redacted
    api_token: zzzzzzzz-aaaa-4d46-bcf9-vvvvvvvvvvvv
    device_id: rrrrrrrr-bbbb-4485-9721-rrrrrrrrrrrr
    off: main switch off
    on: main switch on
    query: switch

  # These require that the server is running on a machine with USB
  # connection to a power control USB hub and the uhubctl utility installed.
  - type: CommandLine
    name: pi1
    on: uhubctl -a 1 -p 1
    off: uhubctl -a 0 -p 1
    query: uhubctl -p 1
    query_on_regex: .*power$
    query_off_regex: .*off$

  - type: CommandLine
    name: pi2
    on: uhubctl -a 1 -p 2
    off: uhubctl -a 0 -p 2
    query: uhubctl -p 2
    query_on_regex: .*power$
    query_off_regex: .*off$

Note that the ip_address of 0.0.0.0 tells the server to listen on all interfaces on the machine on which it is running. Instead one could supply the IP of a single NIC or for best security use 127.0.0.1, meaning that only processes on the same machine will have access (in this cases you would run the webhook server on the maas rack server).

SmartThing commands for switch devices will usually take the exact same form as in the above example. Command line devices will just take a command line to execute in the shell.

In all cases the response from the query command is passed through a regex search and will return ‘on’ if the the response matches query_on_regex and ‘off’ it matches query_off_regex. Note that the defaults for these regex are ‘on’ and ‘off’ which is what SmartThing devices will return in the switch status field by default. This is why the nuc1 example is not required to specify query_on_regex, query_off_regex.

Note that the query response which goes to MAAS is converted to MAAS default values and hence no configuration of regex in MAAS itself are required.

Launch the Web Hook server

Once you have the correct configuration you can launch the server from the command line. This assumes you have activated a virtual environment with maaspower installed, see Installation.

It is important to select an appropriate machine to run the Web Hook Server. First if there are any usb controlled hubs or other devices that are not network attached then the Web Server must run on the machine with these devices connected. A good option is to use a rack server and have all the necessary hardware connected to it.

Use this command:

maaspower run <path to configuration file>

This command will validate your config file against the schema and report any issues. Schema validation failure will abort the web server.

If you wish to get assistance with the format of the config file you can generate a schema file and use a schema aware editor which will give you hints and autocompletion. See YAML schema for details.

Configure MAAS to connect to the webhook

For each device configured in the maaspower config file. There needs to be an equivalent configuration of a MAAS controlled machine.

To do this select a Machine in the MAAS Web GUI and go to the configuration tab. Then select Power Configuration -> Edit.

An example configuration that matches the nuc1 device in the above config file is shown below. In this example the Webhook Server has been launched on a machine with IP 192.168.0.1.

Alternative text