hostedpi¶

Python interface to the Mythic Beasts Hosted Pi API, developed by the piwheels team (Ben Nuttall and Dave Jones).

This module provides a Pythonic interface to the API, as well as a command line interface.

The authors of this library are not affiliated with Mythic Beasts, but we use their Pi cloud to power the piwheels project.

Documentation of the API itself can be found at https://www.mythic-beasts.com/support/api/raspberry-pi

Note

Note that the library is currently in beta. The API and CLI are not yet stable and may change. Once the library reaches v1.0, it will be considered stable.

Usage¶

View the information about a Pi from the command line:

$ hostedpi show mypi
Name: mypi
Provision status: live
Model: Raspberry Pi 3B
Disk size: 10GB
Power: on
IPv6 address: 2a00:1098:8:5b::1
IPv6 network: 2a00:1098:8:5b00::/56
Initialised keys: yes
SSH keys: 4
IPv4 SSH port: 5091
Location: MER
URLs:
  http://www.mypi.hostedpi.com
  https://www.mypi.hostedpi.com
SSH commands:
  ssh -p 5091 root@ssh.mypi.hostedpi.com  # IPv4
  ssh root@[2a00:1098:8:5b::1]  # IPv6

Provision a new Pi and view its SSH command (using Python):

>>> from hostedpi import PiCloud
>>> api_id = '8t29hvcux5g9vud8'
>>> secret = 'QNwsvxZY8SxT3OiLt:Vmz-D1mWQuoZ'
>>> cloud = PiCloud(api_id, secret, ssh_key_path='/home/ben/.ssh/id_rsa.pub')
>>> pi = cloud.create_pi('mypi')
>>> print(pi.ssh_command)
ssh -p 5123 root@ssh.mypi.hostedpi.com

See the Getting started page for information on how to authenticate, and see the Command line interface page for information on using the command line interface.

Table of Contents¶

Getting started¶

This page contains a simple tutorial to help you get started by creating a Mythic Beasts account, create an API key, use the command line interface and the Python module.

Create a Mythic Beasts account¶

Sign up: https://www.mythic-beasts.com/user/login

Create an API key¶

Log in to your Mythic Beasts account: https://www.mythic-beasts.com/user/login
Open the API Keys page: https://www.mythic-beasts.com/customer/api-users
Enter a descriptive name for your API key, for your own reference
Check the Raspberry Pi Provisioning box
Click the Create API key button
Make a note of the API ID and Secret. You’ll need them to use this Python module, and you can’t retrieve them after this screen is gone.

Note

If you lose your keys, you can simply reset them or create a new API key.

Install the hostedpi module¶

For a system-wide installation:

$ sudo pip3 install hostedpi

for a user-level installation:

$ pip3 install hostedpi --user

or in a virtual environment:

$ pip install hostedpi

Test your API keys¶

To test your API connection, try running the following commands in a terminal window, with your API ID and secret:

$ HOSTEDPI_ID='YOUR ID' HOSTEDPI_SECRET='YOUR SECRET' hostedpi test
Connected to the Mythic Beasts API

This message means your API credentials were found and a successful connection was made.

Start using the Python module¶

The following Python program will connect to the Mythic Beasts API using your credentials, and print out a list of Pi services in your account:

from hostedpi import PiCloud

cloud = PiCloud(api_id='YOUR API ID', secret='YOUR SECRET')

for name in cloud.pis:
    print(name)

Note

You can either construct PiCloud with your API ID and secret, or set them in environment variables like above.

You can provision a new Pi with the create_pi() method:

from hostedpi import PiCloud

cloud = PiCloud(api_id='YOUR API ID', secret='YOUR SECRET')

pi = cloud.create_pi('mypi3')

The default values are for a Pi 3 with a 10GB disk, but you can request either a Pi 3 or Pi 4 and specify the disk size (which must be a multiple of 10):

from hostedpi import PiCloud

cloud = PiCloud(api_id='YOUR API ID', secret='YOUR SECRET')

pi = cloud.create_pi('mypi4', model=4, disk_size=20)

Note

When requesting a Pi 3, you will either get a model 3B or 3B+. It is not possible to request a particular model beyond 3 or 4. The Pi 4 is the 4GB RAM model.

The return value of this method is a Pi object which you can use to retrieve information about the service, and to manage it. The repr of a Pi object includes the name and model:

>>> pi
<Pi model 4 mypi4>

For example, you can retrieve the SSH command needed to connect to it:

print(pi.ssh_command)

which should print something like:

ssh -p 5123 root@ssh.mypi4.hostedpi.com

Other properties you can read are include:

There are also methods such as reboot():

pi.reboot()

Other methods include:

More¶

See the Command line interface page for details of the possibilities provided by ready-made scripts
See the API documentation for Pi for more information on available properties and methods.
See the Recipes page for more ideas showing what you can do with this module.

Command line interface¶

The hostedpi command is a multi-purpose utility for common actions interacting with the API.

This program requires API keys to be provided using environment variables HOSTEDPI_ID and HOSTEDPI_SECRET.

The following commands are available:

hostedpi add-key¶

Add an SSH key from a public key file to one or more Pis

positional arguments:
  ssh_key_path  The path to an SSH public key file to add to the Pi
  names         The name of the Pis to add keys to

optional arguments:
  -h, --help    show this help message and exit

Usage¶

Add your SSH key to one Pi:

$ hostedpi add-key ~/.ssh/id_rsa.pub mypi
1 key added to mypi

Add your SSH key to multiple Pis:

$ hostedpi add-key ~/.ssh/id_rsa.pub mypi mypi2 pypi3
keys added to mypi
key added to mypi2
key added to mypi3

Note

Keys are counted before and after addition, and de-duplicated, so if the key is already found on the Pi, it will show as not having been added, as above.

hostedpi cancel¶

Cancel one or more Pis in the account

positional arguments:
  names       The names of the Pis to cancel

optional arguments:
  -h, --help  show this help message and exit
  -y, --yes   Proceed without confirmation

Usage¶

Cancel a Pi:

$ hostedpi cancel mypi
Cancelling 1 Pi. Proceed? [Y/n]
mypi cancelled

Note

You can cancel by entering n or interrupting with Ctrl + C.

Note

Unlike other commands, there is no implicit targeting of all Pis. Pis must be listed explicitly to be cancelled.

Cancel multiple Pis:

$ hostedpi cancel mypi mypi2
Cancelling 2 Pis. Proceed? [Y/n]
mypi cancelled
mypi2 cancelled

Cancel a Pi without the confirmation step:

$ hostedpi cancel mypi -y
mypi cancelled

Warning

Be careful!

hostedpi copy-keys¶

Copy all SSH keys from one Pi to one or more others

positional arguments:
  name_src    The name of the Pi to copy keys from
  names_dest  The names of the Pis to copy keys to

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Copy the keys from one Pi to another:

$ hostedpi copy-keys mypi mypi2
2 keys added to mypi2

Copy the keys from one Pi to several others:

$ hostedpi copy-keys mypi mypi2 mypi3 mypi4
keys added to mypi2
keys added to mypi3
keys added to mypi4

Note

Keys are counted before and after addition, and de-duplicated, so if a key is already found on the Pi, it will show as not having been added, as above.

hostedpi count-keys¶

Show the number of SSH keys currently on one or more Pis

positional arguments:
  names       The names of the Pis to get keys for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Show the number of keys on a Pi:

$ hostedpi count-keys mypi
mypi: 4 keys

Show the number of keys on multiple Pis:

$ hostedpi count-keys mypi mypi2
mypi: 4 keys
mypi2: 2 keys

Note

If no names of Pis are given, the key count will be shown for all Pis in the account

hostedpi create¶

Provision a new Pi in the account

positional arguments:
  name                  The name of the new Pi to provision

optional arguments:
  -h, --help            show this help message and exit
  --model [model]       The model of the new Pi to provision (3 or 4)
  --disk [disk]         The disk size in GB
  --image [image]       The operating system image to use
  --ssh-key-path [ssh_key_path]
                        The path to an SSH public key file to add to the Pi

Usage¶

Provision a new Pi using the default settings:

$ hostedpi create mypi
Pi mypi provisioned successfully

Name: mypi
Provision status: provisioning
Model: Raspberry Pi 3
Disk size: 10GB
IPv6 address: 2a00:1098:8:5b::1
IPv6 network: 2a00:1098:8:5b00::/56
SSH port: 5091
Location: MER
URLs:
  http://www.mypi.hostedpi.com
  https://www.mypi.hostedpi.com
SSH commands:
  ssh -p 5091 root@ssh.mypi.hostedpi.com  # IPv4
  ssh root@[2a00:1098:8:5b::1]  # IPv6

Provision a new Pi using custom settings:

$ hostedpi create mypi4 --model 4 --disk 60 --image ubuntu20.04.arm64 --ssh-key-path ~/.ssh/id_rsa.pub
Pi mypi4 provisioned successfully

Name: mypi4
Provision status: provisioning
Model: Raspberry Pi 4
Disk size: 60GB
IPv6 address: 2a00:1098:8:5b::1
IPv6 network: 2a00:1098:8:5b00::/56
SSH port: 5091
Location: MER
URLs:
  http://www.mypi4.hostedpi.com
  https://www.mypi4.hostedpi.com
SSH commands:
  ssh -p 5091 root@ssh.mypi4.hostedpi.com  # IPv4
  ssh root@[2a00:1098:8:5b::1]  # IPv6

Note

Use the hostedpi images command to retrieve the available operating system images for each Pi model.

Note

More information about the Pi will be available with the command hostedpi show once it’s finished provisioning.

hostedpi images¶

Retrieve the list of operating system images available for the given Pi model

positional arguments:
  model       The Pi model number (3 or 4) to get operating systems for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

List the available operating system images for Pi 3 and Pi 4:

Images for Pi 3:
Ubuntu 18.04 (Bionic) : ubuntu-18.04
Ubuntu 16.04 (Xenial) : ubuntu-16.04
Raspbian Buster       : raspbian-buster
Raspbian Jessie       : raspbian-jessie
Raspbian Stretch      : stretch

Images for Pi 4:
Ubuntu 20.04 64 bit (experimental) : ubuntu20.04.arm64
Raspbian Buster                    : raspbian-buster4
Raspberry Pi OS 64 bit             : pios64b

List the available operating system images for Pi 3:

$ hostedpi images 3
Ubuntu 16.04 (Xenial) : ubuntu-16.04
Ubuntu 18.04 (Bionic) : ubuntu-18.04
Raspbian Jessie       : raspbian-jessie
Raspbian Stretch      : stretch
Raspbian Buster       : raspbian-buster

List the available operating system images for Pi 4:

$ hostedpi images 4
Ubuntu 20.04 64 bit (experimental) : ubuntu20.04.arm64
Raspbian Buster                    : raspbian-buster4
Raspberry Pi OS 64 bit             : pios64b
Ubuntu 18.04 (Bionic)              : ubuntu-18.04-rpi4

Note

The right hand column represents the image label which can be used when provisioning a new Pi with hostedpi create and create_pi().

hostedpi keys¶

Show the SSH keys currently on a Pi

positional arguments:
  name        The name of the Pi to get keys for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Show the SSH keys currently on a Pi:

$ hostedpi keys mypi
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDSkT3A1j89RT/540ghIMHXIVwNlAEM3WtmqVG7YN/wYwtsJ8iCszg4/lXQsfLFxYmEVe8L9atgtMGCi5QdYPl4X/c+5YxFfm88Yjfx+2xEgUdOr864eaI22yaNMQ0AlyilmK+PcSyxKP4dzkf6B5Nsw8lhfB5n9F5md6GHLLjOGuBbHYlesKJKnt2cMzzS90BdRk73qW6wJ+MCUWo+cyBFZVGOzrjJGEcHewOCbVs+IJWBFSi6w1enbKGc+RY9KrnzeDKWWqzYnNofiHGVFAuMxrmZOasqlTIKiC2UK3RmLxZicWiQmPnpnjJRo7pL0oYM9r/sIWzD6i2S9szDy6aZ alice@gonzo

Save the output into a file:

$ hostedpi keys mypi > keys.txt

hostedpi list¶

List all Pis in the account

optional arguments:
  -h, --help  show this help message and exit

Usage¶

List all Pis in the account:

$ hostedpi list
mypi
mypi2
mypi3
mypi4

hostedpi off¶

Power off one or more Pis in the account

positional arguments:
  names       The name of the Pi to power off

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Power off a Pi:

$ hostedpi off mypi
mypi powered off

Power off multiple Pis:

$ hostedpi off mypi mypi2
mypi powered off
mypi2 powered off

Note

If no names of Pis are given, all Pis in the account will be powered off

hostedpi on¶

Power on one or more Pis in the account

positional arguments:
  names       The name of the Pi to power on

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Power off a Pi:

$ hostedpi on mypi
mypi powered on

Power off multiple Pis:

$ hostedpi on mypi mypi2
mypi powered on
mypi2 powered on

Note

If no names of Pis are given, all Pis in the account will be powered on

hostedpi power¶

Get the power status for one or more Pis

positional arguments:
  names       The names of the Pis to get the power status for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Get the power status for a Pi:

$ hostedpi power mypi
mypi: powered off

Show the number of keys on multiple Pis:

$ hostedpi power mypi mypi2 mypi3
mypi: powered off
mypi2: powered on
mypi3: powered on

Note

If no names of Pis are given, the power status will be shown for all Pis in the account

hostedpi reboot¶

Reboot one or more Pis in the account

positional arguments:
  names       The name of the Pi to reboot

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Reboot a Pi:

$ hostedpi reboot mypi
mypi rebooted

Reboot multiple Pis:

$ hostedpi reboot mypi mypi2
mypi rebooted
mypi2 rebooted

Note

If no names of Pis are given, all Pis in the account will be rebooted

hostedpi remove-keys¶

Remove all SSH keys from one or more Pis

positional arguments:
  names       The names of the Pis to remove keys from

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Remove all SSH keys from a Pi:

$ hostedpi remove-keys mypi
2 keys removed from mypi

Remove all SSH keys from multiple Pis:

$ hostedpi remove-keys mypi mypi2
2 keys removed from mypi
0 keys removed from mypi2

Note

Unlike other commands, there is no implicit targeting of all Pis. Pis must be listed explicitly to have keys removed.

hostedpi show¶

Show the information about one or more Pis in the account

positional arguments:
  names       The names of the Pis to show information for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Show the information about a Pi:

$ hostedpi show mypi
Name: mypi
Provision status: live
Model: Raspberry Pi 3B
Disk size: 10GB
Power: off
IPv6 address: 2a00:1098:8:5b::1
IPv6 network: 2a00:1098:8:5b00::/56
Initialised keys: yes
SSH keys: 0
IPv4 SSH port: 5091
Location: MER
URLs:
  http://www.mypi.hostedpi.com
  https://www.mypi.hostedpi.com
SSH commands:
  IPv4: ssh -p 5091 root@ssh.mypi.hostedpi.com
  IPv6: ssh root@[2a00:1098:8:5b::1]

Show the number of keys on multiple Pis:

$ hostedpi show mypi mypi2
Name: mypi
Provision status: live
Model: Raspberry Pi 3B
Disk size: 10GB
Power: on
IPv6 address: 2a00:1098:8:5b::1
IPv6 network: 2a00:1098:8:5b00::/56
Initialised keys: yes
SSH keys: 0
IPv4 SSH port: 5091
Location: MER
URLs:
  http://www.mypi.hostedpi.com
  https://www.mypi.hostedpi.com
SSH commands:
  IPv4: ssh -p 5091 root@ssh.mypi.hostedpi.com
  IPv6: ssh root@[2a00:1098:8:5b::1]

Name: mypi2
Provision status: live
Model: Raspberry Pi 4B
Disk size: 40GB
Power: on
IPv6 address: 2a00:1098:8:68::1
IPv6 network: 2a00:1098:8:6800::/56
Initialised keys: yes
SSH keys: 0
IPv4 SSH port: 5072
Location: MER
URLs:
  http://www.mypi2.hostedpi.com
  https://www.mypi2.hostedpi.com
SSH commands:
  IPv4: ssh -p 5072 root@ssh.mypi2.hostedpi.com
  IPv6: ssh root@[2a00:1098:8:68::1]

Note

If no names of Pis are given, information about all Pis will be shown.

hostedpi ssh-command¶

Output the SSH command for one or more Pis in the account

positional arguments:
  names       The names of the Pis to get SSH commands for

optional arguments:
  -h, --help  show this help message and exit
  --ipv6      Show IPv6 command

Usage¶

Output the IPv4 SSH command for a Pi:

$ hostedpi ssh-command mypi
ssh -p 5091 root@ssh.mypi.hostedpi.com

Output the IPv6 SSH command for a Pi:

$ hostedpi ssh-command mypi --ipv6
ssh root@[2a00:1098:8:5b::1]

Show the number of keys on multiple Pis:

$ hostedpi ssh-command mypi mypi2
ssh -p 5091 root@ssh.mypi.hostedpi.com
ssh -p 5091 root@ssh.mypi2.hostedpi.com

Note

If no names of Pis are given, the key count will be shown for all Pis in the account

Execute the SSH command directly:

$ $(hostedpi ssh-command mypi)

Warning

Use with caution

hostedpi ssh-config¶

Output the SSH config for one or more Pis in the account

positional arguments:
  names       The names of the Pis to get SSH config for

optional arguments:
  -h, --help  show this help message and exit
  --ipv6      Show IPv6 command

Usage¶

Output the IPv4 SSH config for a Pi:

$ hostedpi ssh-config mypi
Host mypi
    user root
    port 5224
    hostname ssh.mypi.hostedpi.com

Output the IPv6 SSH config for a Pi:

$ hostedpi ssh-config mypi --ipv6
Host mypi
    user root
    hostname 2a00:1098:8:5b::1

Output the IPv4 SSH config for multiple Pis:

$ hostedpi ssh-config mypi mypi2
Host mypi
    user root
    port 5224
    hostname ssh.mypi.hostedpi.com
Host mypi2
    user root
    port 5072
    hostname ssh.mypi2.hostedpi.com

Note

If no names of Pis are given, the SSH commands will be shown for all Pis in the account

Save (append) the IPv4 SSH config for all Pis in the account into your SSH config file:

$ hostedpi ssh-config >> ~/.ssh/config

Note

Read more about the SSH config file: https://www.ssh.com/ssh/config/

hostedpi ssh-import-id¶

Import SSH keys from GitHub or Launchpad and add them to one or more Pis

positional arguments:
  names                 The names of the Pis to import keys onto

optional arguments:
  -h, --help            show this help message and exit
  --gh [github username]
                        The GitHub username to import keys from
  --lp [launchpad username]
                        The Launchpad username to import keys from

Usage¶

Import keys from GitHub onto a Pi:

$ hostedpi ssh-import-id mypi --gh bennuttall
4 keys retrieved from GitHub

4 keys added to mypi

Import keys from GitHub onto multiple Pis:

$ hostedpi ssh-import-id mypi mypi2 --gh bennuttall
keys retrieved from GitHub

keys added to mypi
keys added to mypi2

Note

If no names of Pis are given, the key count will be shown for all Pis in the account

Note

Keys are counted before and after addition, and de-duplicated, so if a key is already found on the Pi, it will show as not having been added, as above.

Import keys from GitHub and Launchpad onto a Pi:

$ hostedpi ssh-import-id mypi --gh bennuttall --lp bennuttall
keys retrieved from GitHub
key retrieved from Launchpad

key added to mypi

Note

Keys are counted before and after addition, and de-duplicated, so if a key is already found on the Pi, it will show as not having been added, as above.

hostedpi status¶

Get the provision status of one or more Pis

positional arguments:
  names       The names of the Pis to get the provision status for

optional arguments:
  -h, --help  show this help message and exit

Usage¶

Get the provision status of a Pi:

$ hostedpi status mypi
mypi: live

Get the provision status of multiple Pis:

$ hostedpi status mypi mypi2
mypi: live
mypi2: provisioning

Note

If no names of Pis are given, the provision status will be shown for all Pis in the account

hostedpi test¶

Test a connection to the Mythic Beasts API using API ID and secret in environment variables.

optional arguments:
-h, --help  show this help message and exit

Usage¶

Successful test:

$ hostedpi cancel mypi
Connected to the Mythic Beasts API

An error will be shown if the connection fails:

$ hostedpi test
hostedpi error: Failed to authenticate

Note

See the Getting started section for details on how to authenticate

Recipes¶

This page includes some recipes for using the Python library to make custom programs with the utilities provided, perhaps combined with other libraries. See the Python library API page for a full API reference.

Note

You’ll need to create an API key to be able to use these recipes. See the Getting started page to begin. The following examples assume the API keys are set using environment variables, but they can be provided as arguments to the PiCloud class constructor.

Provisioning Pis¶

Provision a Pi¶

from hostedpi import PiCloud

cloud = PiCloud()

pi = cloud.create_pi('mypi', model=3, disk=10)

Provision some Pis¶

from hostedpi import PiCloud

cloud = PiCloud()

pis = [
    cloud.create_pi('mypi{}'.format(n), model=3, disk=10)
    for n in range(10)
]

Push button to provision a Pi¶

from hostedpi import PiCloud
from gpiozero import Button, LED

cloud = PiCloud()
btn = Button(2)
led = LED(3)

def make_pi():
    name = "helloworld"
    cloud.create_pi(name)
    led.on()

btn.when_pressed = make_pi

See a live demo at https://twitter.com/ben_nuttall/status/1300442981779025921

Note

This requires the gpiozero library.

Retrieving data about Pis¶

List all Pis¶

from hostedpi import PiCloud

cloud = PiCloud()

for name in cloud.pis:
    print(name)

List all Pis and their IPv6 address¶

from hostedpi import PiCloud

cloud = PiCloud()

for name, pi in cloud.pis.items():
    print(name, pi.ipv6_address)

Rebooting¶

Reboot all Pis¶

from hostedpi import PiCloud

cloud = PiCloud()

for pi in cloud.pis.values():
    pi.reboot()

Power on/off¶

Boot all Pis powered off¶

from hostedpi import PiCloud

cloud = PiCloud()

for pi in cloud.pis.values():
    if not pi.power:
        pi.on()

SSH¶

List SSH commands for all Pis¶

from hostedpi import PiCloud

cloud = PiCloud()

for pi in cloud.pis.values():
    print(pi.ipv4_ssh_command)

from hostedpi import PiCloud

cloud = PiCloud()

for pi in cloud.pis.values():
    print(pi.ipv6_ssh_command)

Write SSH config to a file¶

from hostedpi import PiCloud

cloud = PiCloud()

with open('config', 'w') as f:
    f.write(cloud.ssh_config)

Web¶

Retrieve the contents of the homepage¶

Note

Note that a web server must be installed on the Pi for the URL to resolve in a web browser, and an SSL certificate must be created for the https URL to resolve.

Print out:

from hostedpi import PiCloud
import requests

cloud = PiCloud()
pi = cloud.pis['somepi']

r = requests.get(pi.url)
print(r.text)

Save to a file:

from hostedpi import PiCloud
import requests

cloud = PiCloud()
pi = cloud.pis['somepi']

r = requests.get(pi.url)
with open('pi.html', 'w') as f:
    f.write(r.text)

Access a particular web location¶

Access data.json from the web server, and print out the message value:

from hostedpi import PiCloud
import requests

cloud = PiCloud()
pi = cloud.pis['somepi']

url = pi.url + '/data.json'
r = requests.get(url)
data = r.json()
print(data['message'])

Python library API¶

This page describes the methods and properties available in the PiCloud and Pi classes and are intended as a useful reference to the functionality provided.

The way to use the module is to import the PiCloud class and initialise it with your API keys. This will allow you to provision new Pi services with the create_pi() method or access existing services from the pis property.

Once you have a connected PiCloud instance and access to newly or previously created Pi instances, the following API documentation should prove useful to show what you can do with the API via the hostedpi module.

You can authenticate by passing your API ID and secret as arguments to the PiCloud constructor:

>>> from hostedpi import PiCloud
>>> cloud = PiCloud('YOUR ID', 'YOUR SECRET')

or set them in environment variables instead:

$ export HOSTEDPI_ID='YOUR ID'
$ export HOSTEDPI_SECRET='YOUR SECRET'

>>> from hostedpi import PiCloud
>>> cloud = PiCloud()

PiCloud¶

class hostedpi.picloud.PiCloud(api_id=None, api_secret=None, *, ssh_keys=None, ssh_key_path=None, ssh_import_github=None, ssh_import_launchpad=None)[source]¶

A connection to the Mythic Beasts Pi Cloud API for creating and managing cloud Pi services.

Set up API keys at https://www.mythic-beasts.com/customer/api-users

Parameters:

api_id (str or None) – Your Mythic Beasts API ID (alternatively, the environment variable HOSTEDPI_ID can be used)
api_secret (str or None) – Your Mythic Beasts API secret (alternatively, the environment variable HOSTEDPI_SECRET can be used)
ssh_keys (list or set or None) – A list/set of SSH key strings (keyword-only argument)
ssh_key_path (str or None) – The path to your SSH public key (keyword-only argument)
ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument)
ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

Note

If any SSH keys are provided on class initialisation, they will be used when creating Pis but are overriden by any passed to the create_pi() method.

All SSH arguments provided will be used in combination.

__str__()[source]¶: String of information about all the Pis in the account

create_pi(name, *, model=3, disk_size=10, os_image=None, ssh_keys=None, ssh_key_path=None, ssh_import_github=None, ssh_import_launchpad=None)[source]¶

Provision a new cloud Pi with the specified name, model, disk size and SSH keys. Return a new Pi instance.

Parameters:

name (str) – A unique identifier for the server. This will form part of the hostname for the server, and must consist only of alphanumeric characters and hyphens.
model (int or None) – The Raspberry Pi model to provision (3 or 4) - defaults to 3 (keyword-only argument)
disk_size (int or None) – The amount of disk space (in GB) attached to the Pi - must be a multiple of 10 - defaults to 10 (keyword-only argument)
os_image (str) – The name of the operating system image to boot from. Defaults to None which falls back to Mythic’s default (Raspbian/PiOS stable). If given, this must be a string which appears as a key in the return value of get_operating_systems() for the relevant Pi model.
ssh_keys (list or set or None) – A list/set of SSH key strings (keyword-only argument)
ssh_key_path (str or None) – The path to your SSH public key (keyword-only argument)
ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument)
ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

Note

If any SSH keys are provided on class initialisation, they will be used here but are overriden by any passed to this method.

Note

When requesting a Pi 3, you will either get a model 3B or 3B+. It is not possible to request a particular model beyond 3 or 4. The Pi 4 is the 4GB RAM model.

get_operating_systems(*, model)[source]¶

Return a dict of operating systems supported by the given Pi model (3 or 4). Dict keys are identifiers (e.g. “raspbian-buster”) which can be used when provisioning a new Pi with create_pi(); dict values are text labels of the OS/distro names (e.g. “Raspbian Buster”).

Parameters:	model (int) – The Raspberry Pi model (3 or 4) to get operating systems for (keyword-only argument)

ipv4_ssh_config¶: A string containing the IPv4 SSH config for all Pis within the account. The contents could be added to an SSH config file for easy access to the Pis in the account.

ipv6_ssh_config¶: A string containing the IPv6 SSH config for all Pis within the account. The contents could be added to an SSH config file for easy access to the Pis in the account.

pis¶: A dictionary of Pi objects keyed by their names.

Pi¶

class hostedpi.pi.Pi[source]¶

The Pi class represents a single Raspberry Pi service in the Mythic Beasts Pi cloud. Initialising a Pi object does not provision a new Pi, rather initialisation is for internal construction only.

There are two ways to get access to a Pi object: retrieval from the pis dictionary; and the return value of create_pi() method.

With a Pi object, you can access data about that particular Pi service, add SSH keys, reboot it, cancel it and more.

Note

The Pi class should not be initialised by the user, only internally within the module.

__str__()[source]¶: A multi-line string of the information about the Pi

cancel()[source]¶: Cancel the Pi service

off()[source]¶: Power the Pi off and return immediately

on(*, wait=False)[source]¶: Power the Pi on. If wait is False (the default), return immediately. If wait is True, wait until the power on request is completed, and return True on success, and False on failure.

reboot(*, wait=False)[source]¶: Reboot the Pi. If wait is False (the default), return None immediately. If wait is True, wait until the reboot request is completed, and return True on success, and False on failure.

Note

Note that if wait is False, you can poll for the boot status while rebooting by inspecting the properties is_booting and boot_progress.

ssh_import_id(*, github=None, launchpad=None)[source]¶

Import SSH keys from GitHub or Launchpad, and add them to the Pi. Return the set of keys added.

Parameters:	ssh_import_github (list or set or None) – A list/set of GitHub usernames to import SSH keys from (keyword-only argument) ssh_import_launchpad (list or set or None) – A list/set of Launchpad usernames to import SSH keys from (keyword-only argument)

boot_progress¶: A string representing the Pi’s boot progress. Can be booted, powered off or a particular stage of the boot process if currently booting.

disk_size¶: The Pi’s disk size in GB

initialised_keys¶: A boolean representing whether or not the Pi has been initialised with SSH keys

ipv4_ssh_command¶: The SSH command required to connect to the Pi over IPv4

ipv4_ssh_config¶: A string containing the IPv4 SSH config for the Pi. The contents could be added to an SSH config file for easy access to the Pi.

ipv4_ssh_port¶: The SSH port to use when connecting via the IPv4 proxy

ipv6_address¶: The Pi’s IPv6 address as an IPv6Address object

ipv6_network¶: The Pi’s IPv6 network as an IPv6Network object

ipv6_ssh_command¶: The SSH command required to connect to the Pi over IPv6

ipv6_ssh_config¶: A string containing the IPv6 SSH config for the Pi. The contents could be added to an SSH config file for easy access to the Pi.

is_booting¶: A boolean representing whether or not the Pi is currently booting

location¶: The Pi’s physical location (data centre)

model¶: The Pi’s model (3 or 4)

model_full¶: The Pi’s model name (3B, 3B+ or 4B)

name¶: The name of the Pi service.

power¶: A boolean representing whether or not the Pi is currently powered on

provision_status¶: A string representing the provision status of the Pi. Can be “provisioning”, “initialising” or “live”.

ssh_keys¶: Retrieve the SSH keys on the Pi, or use assignment to update them. Property value is a set of strings. Assigned value should also be a set of strings.

url¶: The http version of the hostedpi.com URL of the Pi.

Note

Note that a web server must be installed on the Pi for the URL to resolve in a web browser.

url_ssl¶: The https version of the hostedpi.com URL of the Pi.

Note

Note that a web server must be installed on the Pi for the URL to resolve in a web browser, and an SSL certificate must be created. See https://letsencrypt.org/

Development¶

This page contains reference material for those interested in developing and contributing to the hostedpi module.

The project source code is hosted on GitHub at https://github.com/piwheels/hostedpi which also includes the issue tracker.

Setting up for Development¶

Clone the repository and enter the directory:

$ git clone https://github.com/piwheels/hostedpi
$ cd hostedpi

Create a virtual environment e.g. using virtualenvwrapper:
$ mkvirtualenv hostedpi
Install the project for development:
$ make develop

Contributing¶

Source code can be found on GitHub at https://github.com/piwheels/hostedpi
Code and documentation contributions welcome
The issue tracker can be found at https://github.com/piwheels/hostedpi/issues
For issues with the API itself, please contact Mythic Beasts support https://www.mythic-beasts.com/support